Artículo técnico

Timestamps de documentos Excel en Delphi: FILETIME y UTC

Un libro generado a las 09:30 en una máquina de build en Shanghái abre en Excel, y File > Info reporta que se creó a las 17:30. La prueba unitaria que produjo el archivo pasó: asignó 09:30, guardó, reabrió y leyó 09:30 directo de vuelta. Ambas lecturas vienen de los mismos bytes. El archivo guarda 09:30 marcado como UTC, Excel honra el marcador y suma ocho horas, y la prueba jamás miró el marcador. Los timestamps de documentos en archivos Excel son UTC en disco, el valor con el que trabaja un programa es hora local, y cada conversión entre ambos tiene que usar las reglas de horario de verano de la fecha del propio stamp

El error de un día que una ida y vuelta no puede ver

En un archivo .xls las horas de creación y guardado son valores FILETIME: un conteo de 64 bits de ticks de 100 nanosegundos desde 1601-01-01 UTC ([MS-DTYP] §2.3.3). Un TDateTime de Delphi cuenta días desde 1899-12-30, el mismo origen serial cubierto en los seriales de fecha Excel en Delphi y los sistemas 1900 vs 1904. Convertir entre ambos necesita una constante, el número de días entre las dos épocas, y ese número es 109205. Hay una forma rápida de verificarlo sin calendario. La época Unix es 25569 como TDateTime y está 134774 días después de la época FILETIME, y 25569 + 109205 = 134774

Cuente los días a mano e incluya ambas fechas finales, y obtiene 109206. Un escritor y un lector construidos sobre esa constante concuerdan perfectamente entre sí. Cada stamp de creación y guardado entra al archivo un día tarde y sale un día temprano, así que una prueba de guardar y reabrir ve exactamente el valor que asignó, mientras Excel, o cualquier lector que use la época correcta, muestra mañana

const
  // días desde la época FILETIME (1601-01-01) a la época TDateTime (1899-12-30)
  // chequeo: 25569 + 109205 = 134774, la época Unix en días FILETIME
  FileTimeDayBias = 109205;

function UtcDateTimeToFileTimeTicks(UtcStamp: TDateTime): Int64;
begin
  // Redondee primero a milisegundos enteros, después escale a ticks de 100 ns.
  // Escalar el Double directo a ticks convierte 04:00 en 03:59:59.9999
  Result := Round((UtcStamp + FileTimeDayBias) * 86400000.0) * 10000;
end;
Cronología de HotXLS de la época FILETIME 1601-01-01, la época TDateTime 1899-12-30 y la época Unix de 1970, mostrando el sesgo de 109205 días detrás de UtcDateTimeToFileTimeTicks y cómo un sesgo de 109206 escribiría cada stamp de CreatedDate un día tarde y lo leería un día temprano
El boceto de UtcDateTimeToFileTimeTicks deja el sesgo donde una constante equivocada se cancela a sí misma — una prueba simétrica de guardar y reabrir ve el valor que asignó mientras el panel Info de Excel muestra mañana

El comentario de redondeo en ese boceto también importa. Una fracción de TDateTime es un Double binario, y multiplicarla directo por 864,000,000,000 ticks por día empuja el error de representación a los dígitos bajos, así que un stamp de exactamente 04:00 se lee de vuelta como 03:59:59.9999 y se muestra como 03:59. HotXLS redondea primero a milisegundos enteros y solo entonces escala a ticks. Los valores en punto sobreviven. El boceto toma una entrada UTC a propósito; el paso de zona horaria viene después y es la mitad más difícil

¿Qué property IDs de SummaryInformation guardan las fechas?

El conjunto de propiedades \005SummaryInformation definido por [MS-OLEPS] guarda la hora de creación bajo el property ID $0C (PIDSI_CREATE_DTM), la última hora de guardado bajo $0D (PIDSI_LASTSAVE_DTM) y el tiempo total de edición bajo $0A (PIDSI_EDITTIME). El ID justo después del stamp de guardado, $0E, es PIDSI_PAGECOUNT. Ponga ahí una hora de guardado y Excel se queda sin fecha de guardado que mostrar, más una propiedad de conteo de páginas cargando un FILETIME. HotXLS escribe el stamp de guardado bajo $0D, y cuando lee un archivo donde $0D falta pero $0E carga un VT_FILETIME, toma ese valor como la última hora de guardado. Una cadena o cualquier otro tipo sentado bajo uno de estos IDs en un archivo malformado se salta en vez de leerse mal como fecha. Para ver los streams crudos mismos, consulte leer archivos compuestos OLE2 en Delphi sin COM IStorage

PIDSI_EDITTIME es el caso raro. Está tipeado VT_FILETIME pero carga una duración: el conteo crudo de ticks de 100 ns transcurridos, sin época sumada. Trátelo como los otros dos, convierta EditTimeMinutes / 1440 por la aritmética de época, y 125 minutos de edición se convierten en un valor de unos 299 años de largo. HotXLS escribe el conteo de ticks simple (minutos × 600,000,000). En Windows el lector también atrapa la codificación con forma de fecha por su tamaño, ya que ninguna sesión de edición real atraviesa tres siglos: cualquier tiempo de edición de 109206 días o más tiene ese offset restado antes de llenar EditTimeMinutes

Mapa de HotXLS del conjunto de propiedades 005SummaryInformation donde PIDSI_CREATE_DTM en $0C guarda la hora de creación, PIDSI_LASTSAVE_DTM en $0D el stamp de guardado, PIDSI_EDITTIME en $0A una duración cruda en vez de una fecha, y $0E PIDSI_PAGECOUNT, una ranura de conteo de páginas que no debe cargar timestamps
PIDSI_EDITTIME es la trampa dentro de la trampa — tipeado VT_FILETIME pero cargando ticks transcurridos sin época, así que tratarlo como fecha convierte 125 minutos de edición en unos 299 años, lo que una revisión del lector por tamaño puede reconocer

Asignar timestamps .xls con TXLSWorkbook

TXLSWorkbook.CreatedDate y TXLSWorkbook.LastSavedDate toman valores TDateTime locales, y HotXLS los convierte a FILETIMEs UTC cuando el libro se guarda. RevisionNumber y EditTimeMinutes viven en el mismo stream. Un valor cero significa «deje esta propiedad fuera», que también es como usted elimina las cuatro: límpielas y el siguiente guardado no escribe ninguna. HotXLS no estampa Now en LastSavedDate por su cuenta. Lo que usted asigne es lo que va al archivo, y ese es el default correcto para una biblioteca. Un trabajo por lotes que regenera los reportes del año pasado normalmente quiere las fechas del año pasado, y un estampado automático las sobrescribiría en silencio

var
  Book: TXLSWorkbook;
begin
  Book := TXLSWorkbook.Create;
  try
    Book.Title := 'Q3 settlement';
    // los valores de la API son hora local; el archivo guarda FILETIMEs UTC
    Book.CreatedDate := EncodeDate(2026, 1, 15) + EncodeTime(9, 30, 0, 0);
    Book.LastSavedDate := Now;     // se escribe como se asignó, jamás se estampa solo
    Book.RevisionNumber := 7;
    Book.EditTimeMinutes := 125;   // una duración, guardada como ticks crudos
    if Book.SaveAs('settlement.xls') <> 1 then
      raise Exception.Create('Save failed');
  finally
    Book.Free;
  end;
end;

Abrir un archivo llena las mismas cuatro propiedades de vuelta, convertidas a la hora local de la máquina que lee. Un servicio corriendo en UTC y un escritorio en Tokio reportarán valores CreatedDate distintos para el mismo libro, nueve horas aparte, y ambos son correctos. Si dos sistemas necesitan comparar stamps, convierta a UTC de su lado antes de la comparación, o guarde el valor UTC junto al otro

¿Por qué las fechas XLSX están corridas exactamente el offset de zona?

Las fechas XLSX salen corridas por el offset de zona cuando un escritor estampa hora local y la etiqueta como UTC. En docProps/core.xml, dcterms:created y dcterms:modified son valores W3CDTF bajo el modelo de propiedades core de ECMA-376 Parte 2, y la forma habitual termina en Z. Formatear Now y agregar Z es el one-liner obvio. En una máquina UTC+8 convierte 09:30 en 09:30:00Z, y Excel en esa misma máquina muestra 17:30 — el ejemplo inicial, exacto. Las propiedades de fecha personalizadas guardadas como vt:filetime siguen la misma regla, igual que los FILETIME binarios en .xls. HotXLS convierte en los tres caminos antes de escribir: TXLSXWorkbook.Created, TXLSXWorkbook.Modified y las fechas agregadas mediante CustomProperties.AddDate son locales del lado de la API y UTC con Z en el archivo

Qué función de Windows hace la conversión resulta importar más de lo que la gente espera. LocalFileTimeToFileTime aplica el offset vigente ahora mismo. Convierta un stamp de enero en julio en cualquier zona con horario de verano y aterriza corrido una hora. HotXLS usa TzSpecificLocalTimeToSystemTime al escribir y SystemTimeToTzSpecificLocalTime al leer, y ambos eligen hora estándar o de verano a partir de la fecha que se convierte, no de hoy. Un valor sin asignar de cero pasa intacto en ambas direcciones, así que una propiedad vacía jamás se convierte en una fecha 30 de diciembre de 1899 corrida unas horas

Caminos de conversión local a UTC de HotXLS para un stamp de enero 17:00 CET guardado en julio: LocalFileTimeToFileTime aplica el offset de verano de hoy y aterriza una hora corrido en 15:00Z, mientras TzSpecificLocalTimeToSystemTime elige el offset de la propia fecha del stamp y escribe el correcto 16:00Z
El offset de zona pertenece a la fecha propia del stamp, no a las reglas actuales de la máquina — un Windows API elige el lado correcto de un cambio de horario de verano, el otro corre en silencio una hora los stamps de enero convertidos en julio
var
  Book: TXLSXWorkbook;
begin
  Book := TXLSXWorkbook.Create;
  try
    if Book.Open('report-template.xlsx') <> 1 then
      raise Exception.Create('Template not available');
    Book.Created := EncodeDate(2026, 7, 1) + EncodeTime(9, 30, 0, 0);
    Book.Modified := Now;
    Book.CustomProperties.AddDate('ApprovedOn',
      EncodeDate(2026, 1, 20) + EncodeTime(17, 0, 0, 0));
    if Book.SaveAs('report.xlsx') <> 1 then
      raise Exception.Create('Save failed');
    // En una máquina en Hora de Europa Central, core.xml ahora carga
    // <dcterms:created xsi:type="dcterms:W3CDTF">2026-07-01T07:30:00Z</dcterms:created>
    // (UTC+2 en julio), mientras ApprovedOn se escribe como 16:00Z (UTC+1 en enero)
  finally
    Book.Free;
  end;
end;

Fuera de Windows la misma conversión pasa por el soporte de zonas horarias de la RTL. En Delphi eso es TTimeZone.Local, y las dos horas incómodas del año reciben ahí una respuesta fija: una hora local dentro del hueco de primavera no existe, así que se escribe sin cambios, y una hora de otoño que ocurre dos veces se toma como la ocurrencia de hora estándar

Leer stamps W3CDTF escritos por otros generadores

Excel escribe Z, otros generadores no siempre lo hacen, y un lector que solo revisa Z en el carácter 20 se equivoca con dos formas comunes. 2026-07-01T01:30:00.5Z trae una fracción en medio, y 2026-07-01T09:30:00+08:00 trae un offset explícito. Un parser ingenuo lee ambos como hora local sin ajuste. El lector de HotXLS para Created, Modified y propiedades personalizadas con fecha acepta fracciones de segundo de cualquier largo, Z, y offsets +hh:mm / -hh:mm; convierte el instante desde el offset dado a UTC y luego a hora local. Un stamp de solo fecha como 2026-07-01 se lee como esa fecha a medianoche, y un stamp que no parsea en absoluto regresa como cero

El único caso que las especificaciones dejan abierto es una hora sin marcador de zona en absoluto, como 2026-07-01T09:30:00. El perfil W3CDTF exige un designador de zona siempre que haya una hora, y ECMA-376 Parte 2 no da regla para un stamp que lo omite. HotXLS lee semejante valor como hora local, sin cambios. Tratarlo como UTC habría sido igual de defendible sobre el papel, pero la fuente más probable de un stamp sin zona es una herramienta que escribió hora local y dejó el marcador fuera, y desplazar esos valores movería cada timestamp de esa herramienta por el offset de zona

Ningún lector puede rescatar el error contrario. Un stamp escrito como hora local y luciendo una Z se ve exactamente como uno correcto, así que HotXLS, Excel y cualquier otro lector que siga el formato lo desplaza por el offset de zona. Solo la codificación de tiempo de edición y la colocación en $0E en .xls tienen una firma que un lector puede detectar

Probar contra bytes que su propio código no escribió

Cada trampa de arriba pasa una revisión de guardar y reabrir, porque un error simétrico es invisible para una prueba simétrica. La referencia tiene que venir de otro lado. Para .xlsx, descomprima el archivo guardado y afirme el texto literal de dcterms:created; para .xls, el paquete olefile de Python lee el stream SummaryInformation de forma independiente con get_metadata(), reporta el tiempo de edición en segundos y trata $0E como conteo de páginas, lo que vuelve visibles ambas trampas de .xls de una vez. La otra dirección es un libro guardado por el propio Excel, leído por la API y cotejado contra lo que File > Info muestra

uses
  System.SysUtils, System.DateUtils;

procedure CheckExcelReference;
var
  Book: TXLSXWorkbook;
  Expected: TDateTime;
begin
  // El valor que File > Info de Excel muestra para este archivo en la máquina de prueba
  Expected := EncodeDate(2026, 1, 20) + EncodeTime(17, 0, 0, 0);
  Book := TXLSXWorkbook.Create;
  try
    if Book.Open('excel-saved-reference.xlsx') <> 1 then
      raise Exception.Create('Reference file missing');
    // Verificación propia, no una API de HotXLS: permita un segundo por redondeo
    if Abs(Book.Created - Expected) > OneSecond then
      raise Exception.CreateFmt('Created reads as %s',
        [DateTimeToStr(Book.Created)]);
  finally
    Book.Free;
  end;
end;

Corra esa batería en una máquina puesta en una zona bien lejos de UTC, con una fecha de prueba a cada lado de un cambio de horario de verano. Un agente de build dejado en UTC esconde por completo el error de offset de zona, y una sola fecha de prueba de verano esconde el de LocalFileTimeToFileTime; el 20 de enero y el 1 de julio en Hora de Europa Central atrapan ambos

Los sistemas de archivos históricos, los índices de búsqueda y las pistas de auditoría ordenan por estos stamps, y una fecha corrida un día u ocho horas hace más daño que una faltante, porque nadie la cuestiona. Con el componente de hojas de cálculo HotXLS para Delphi, la constante de época, los property IDs y la conversión UTC consciente del horario de verano quedan resueltos para .xls y .xlsx, así el código de la aplicación asigna y lee valores TDateTime locales ordinarios. Para el resto del conjunto de propiedades, del título y autor a las propiedades personalizadas, la pieza compañera sobre asignar propiedades de documentos Excel en Delphi cubre los campos restantes