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 se abre en Excel, y Archivo > Info informa de que se creó a las 17:30. El test unitario que produjo el archivo pasó: asignó 09:30, guardó, reabrió y leyó 09:30 directamente. Las dos lecturas salen de los mismos bytes. El archivo guarda 09:30 marcado como UTC, Excel honra la marca y añade ocho horas, y el test nunca miró la marca. Los timestamps de documentos en archivos Excel son UTC en disco, el valor con el que trabaja un programa es la hora local, y cada conversión entre ambos tiene que usar las reglas de horario de verano de la fecha del propio sello

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

En un archivo .xls las horas de creación y guardado son valores FILETIME: un recuento de 64 bits de ticks de 100 nanosegundos desde el 1601-01-01 UTC ([MS-DTYP] §2.3.3). Un TDateTime de Delphi cuenta días desde el 1899-12-30, el mismo origen serial cubierto en seriales de fecha Excel en Delphi y los sistemas 1900 frente a 1904. Convertir entre ellos 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 comprobarlo sin calendario. La época Unix es 25569 como TDateTime y 134774 días después de la época FILETIME, y 25569 + 109205 = 134774

Contad los días a mano incluyendo las dos fechas de los extremos y os salen 109206. Un escritor y un lector construidos sobre esa constante se entienden perfectamente entre sí. Cada sello de creación y guardado entra en el archivo un día tarde y sale un día temprano, así que un test de guardar y reabrir ve exactamente el valor que asignó, mientras que Excel, o cualquier lector que use la época correcta, muestra mañana

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

function UtcDateTimeToFileTimeTicks(UtcStamp: TDateTime): Int64;
begin
  // Redondea primero a milisegundos enteros, luego escala 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 sello CreatedDate un día tarde y lo leería un día temprano
El esbozo UtcDateTimeToFileTimeTicks deja el sesgo donde una constante equivocada se cancela a sí misma — un test simétrico de guardar y reabrir ve el valor que asignó mientras el panel Info de Excel muestra mañana

El comentario sobre el redondeo en ese esbozo también importa. La fracción de un TDateTime es un Double binario, y multiplicarla directamente por 864.000.000.000 ticks por día empuja el error de representación a los dígitos bajos, así que un sello de exactamente 04:00 se lee 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 esbozo toma una entrada UTC a propósito; el paso de zona horaria viene después y es la mitad difícil

¿Qué IDs de propiedad de SummaryInformation guardan las fechas?

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

PIDSI_EDITTIME es el caso raro. Está tipado VT_FILETIME y aun así guarda una duración: el recuento crudo de ticks de 100 ns transcurridos, sin época añadida. Tratadlo como los otros dos, convertid EditTimeMinutes / 1440 con la aritmética de épocas, y 125 minutos de edición se convierten en un valor de unos 299 años de largo. HotXLS escribe el recuento de ticks plano (minutos × 600.000.000). En Windows el lector además caza la codificación con forma de fecha por su tamaño, ya que ninguna sesión de edición real abarca tres siglos: a cualquier tiempo de edición de 109206 días o más se le resta ese sesgo antes de rellenar 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 sello de guardado, PIDSI_EDITTIME en $0A una duración cruda en vez de una fecha, y $0E PIDSI_PAGECOUNT, una casilla de recuento de páginas que no debe guardar timestamps
PIDSI_EDITTIME es la trampa dentro de la trampa — tipado VT_FILETIME pero guardando ticks transcurridos sin época, así que tratarlo como una fecha convierte 125 minutos de edición en unos 299 años, cosa que una comprobación por tamaño del lector puede reconocer

Fijar 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 flujo. Un valor cero significa "dejar esta propiedad fuera", que es también cómo elimináis las cuatro: limpiadlas y el siguiente guardado no escribe ninguna. HotXLS no estampa Now por su cuenta en LastSavedDate. Lo que asignéis es lo que entra en el archivo, y ese es el comportamiento correcto por defecto para una biblioteca. Un trabajo por lotes que regenera los informes del año pasado normalmente quiere las fechas del año pasado, y un sello 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 tal cual se asignó, nunca 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 rellena 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 informarán de valores CreatedDate distintos para el mismo libro, nueve horas de diferencia, y ambos tienen razón. Si dos sistemas tienen que comparar sellos, convertid a UTC en vuestro lado antes de la comparación, o guardad el valor UTC al lado

¿Por qué las fechas XLSX se desvían exactamente el offset de zona?

Las fechas XLSX salen desviadas 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 añadir 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 las tres rutas antes de escribir: TXLSXWorkbook.Created, TXLSXWorkbook.Modified y las fechas añadidas por CustomProperties.AddDate son locales en el 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. Convertid un sello de enero en julio en cualquier zona con horario de verano y aterriza desviado 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 fijar de cero pasa intacto en ambas direcciones, así que una propiedad vacía nunca se convierte en una fecha de 30 de diciembre de 1899 desplazada unas horas

Caminos de conversión local a UTC de HotXLS para un sello de enero 17:00 CET guardado en julio: LocalFileTimeToFileTime aplica el offset de verano de hoy y aterriza una hora desviado en 15:00Z, mientras TzSpecificLocalTimeToSystemTime escoge el offset de la fecha propia del sello y escribe el 16:00Z correcto
El offset de zona pertenece a la fecha propia del sello, no a las reglas actuales de la máquina — una API de Windows escoge el lado correcto de un cambio de horario de verano, la otra desplaza en silencio una hora los sellos 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 central europea, core.xml ahora guarda
    // <dcterms:created xsi:type="dcterms:W3CDTF">2026-07-01T07:30:00Z</dcterms:created>
    // (UTC+2 en julio), mientras que 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 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 sellos W3CDTF escritos por otros generadores

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

El único caso que las especificaciones dejan abierto es una hora sin marcador de zona alguno, como 2026-07-01T09:30:00. El perfil W3CDTF exige un designador de zona siempre que hay una hora, y ECMA-376 Parte 2 no da regla para un sello que la 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 sello sin zona es una herramienta que escribió hora local y se dejó la marca, y desplazar esos valores movería todos los timestamps de esa herramienta el offset de zona entero

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

Probar contra bytes que vuestro código no escribió

Cada trampa de arriba pasa una comprobación de guardar y reabrir, porque un error simétrico es invisible para un test simétrico. La referencia tiene que venir de otro sitio. Para .xlsx, descomprimid el archivo guardado y verificad el texto literal de dcterms:created; para .xls, el paquete olefile de Python lee el flujo SummaryInformation de forma independiente con get_metadata(), informa el tiempo de edición en segundos y trata $0E como un recuento de páginas, lo que deja visibles las dos trampas de .xls a la vez. La otra dirección es un libro guardado por el propio Excel, leído por la API y comparado con lo que muestra Archivo > Info

uses
  System.SysUtils, System.DateUtils;

procedure CheckExcelReference;
var
  Book: TXLSXWorkbook;
  Expected: TDateTime;
begin
  // El valor que Archivo > Info de Excel muestra para este archivo en la máquina de test
  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');
    // Comprobación vuestra, no una API de HotXLS: permite 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;

Ejecutad esa batería en una máquina en una zona bien alejada de UTC, con una fecha de test 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 única fecha de verano esconde el de LocalFileTimeToFileTime; el 20 de enero y el 1 de julio en hora central europea cazan los dos

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