技術記事

DelphiのExcelドキュメントタイムスタンプ:FILETIMEとUTCとDST

上海のビルドマシンで09:30に生成されたワークブックをExcelで開くと、ファイル > 情報には17:30の作成と表示されます。ファイルを生んだユニットテストは合格しています。09:30を代入し、保存し、開き直して09:30をそのまま読み返したのです。どちらの読みも同じバイトから来ています。ファイルは09:30をUTCとして印付きで保持し、Excelはその印を尊重して8時間加え、テストは印をまったく見ていなかったのです。Excelファイルのドキュメントタイムスタンプはディスク上ではUTC、プログラムが扱う値はローカル時刻で、両者の間のすべての変換はスタンプ自身の日付のサマータイム規則に従わなければなりません

往復テストでは見えない1日ずれ

.xlsファイルでは作成時刻と保存時刻はFILETIME値です。1601-01-01 UTCからの100ナノ秒tickの64ビットカウントです([MS-DTYP] §2.3.3)。DelphiのTDateTimeは1899-12-30からの日数を数え、これはDelphiのExcel日付シリアルと1900対1904方式で扱ったのと同じシリアル原点です。両者の変換に必要な定数は2つのエポック間の日数1つだけで、その数は109205です。カレンダーなしで確かめる手があります。UnixエポックはTDateTimeでは25569、FILETIMEエポックからは134774日後で、25569 + 109205 = 134774となるのです

手で日数を数えて両端の日を含めると、109206になります。その定数の上に組まれたライターとリーダーは互いに完全に一致します。すべての作成スタンプと保存スタンプは1日遅れてファイルに入り、1日早く出てくるため、保存して開き直すテストは代入した値をそのまま見る一方で、Excelや正しいエポックを使う他のリーダーは明日を表示します

const
  // FILETIMEのエポック(1601-01-01)からTDateTimeのエポック(1899-12-30)までの日数
  // 検算:25569 + 109205 = 134774、FILETIME日数で数えたUnixエポック
  FileTimeDayBias = 109205;

function UtcDateTimeToFileTimeTicks(UtcStamp: TDateTime): Int64;
begin
  // まずミリ秒単位に丸めてから100ナノ秒tickへ拡大する
  // Doubleを直接tickへ拡大すると04:00が03:59:59.9999になる
  Result := Round((UtcStamp + FileTimeDayBias) * 86400000.0) * 10000;
end;
FILETIMEのエポック1601-01-01、TDateTimeのエポック1899-12-30、1970年のUnixエポックを並べたHotXLSのタイムライン図。UtcDateTimeToFileTimeTicksの背後にある109205日のバイアスと、バイアスが109206だとCreatedDateスタンプが1日遅く書かれ1日早く読み戻される様子
UtcDateTimeToFileTimeTicks のスケッチは、誤った定数が自己打消しする位置にバイアスを置きます。対称な保存と開き直しのテストは代入値を見て満足し、Excel の情報ペインだけが明日を表示します

このスケッチの丸めに関するコメントも重要です。TDateTimeの小数部はバイナリのDoubleで、1日あたり864,000,000,000 tickを直接掛けると表現誤差が下位の桁に押し込まれ、ちょうど04:00のスタンプが03:59:59.9999と読み戻され、03:59と表示されます。HotXLSはまずミリ秒単位に丸めてからtickへ拡大します。ちょうどの時刻の値は生き残ります。このスケッチが意図的にUTC入力を受け取るのは、タイムゾーンのステップが後であり、しかも難しい側だからです

日付を保持するSummaryInformationのプロパティIDはどれか

[MS-OLEPS]が定義する\005SummaryInformationプロパティセットは、作成時刻をプロパティID $0C(PIDSI_CREATE_DTM)に、最終保存時刻を$0D(PIDSI_LASTSAVE_DTM)に、合計編集時間を$0A(PIDSI_EDITTIME)に保持します。保存スタンプの直後のID $0EはPIDSI_PAGECOUNTです。そこに保存時刻を書くと、Excelは表示すべき保存日付を失い、FILETIMEを持つページ数プロパティを手にします。HotXLSは保存スタンプを$0Dに書き、$0Dがなくて$0EがVT_FILETIMEを運ぶファイルを読むときは、その値を最終保存時刻として扱います。不正なファイルでこれらのIDの下に文字列などの別の型があれば、日付と誤読せずに読み飛ばします。生のストリームそのものを見たいなら、COM IStorageなしでDelphiのOLE2複合ファイルを読むを参照してください

PIDSI_EDITTIMEは一風変わっています。型はVT_FILETIMEなのに、収めているのは期間です。エポックを加算しない、経過100ナノ秒tickの生のカウントです。他の2つと同じ扱いでEditTimeMinutes / 1440をエポック計算に通すと、125分の編集が約299年ぶんの値になります。HotXLSは素のtickカウントを書きます(分 × 600,000,000)。Windowsでは読み手がさらに、サイズによって日付型の符号化を捕捉します。実際の編集セッションが3世紀に及ぶことはないからです。109206日以上の編集時間には、EditTimeMinutesに収める前にそのオフセットを差し引きます

005SummaryInformationプロパティセットのHotXLSマップ。$0CのPIDSI_CREATE_DTMが作成時刻を、$0DのPIDSI_LASTSAVE_DTMが保存スタンプを保持し、$0AのPIDSI_EDITTIMEは日付ではなく生の期間、$0EのPIDSI_PAGECOUNTはタイムスタンプを保持してはならないページ数スロット
PIDSI_EDITTIME は罠の中の罠です。型は VT_FILETIME なのにエポックなしの経過 tick を収めるため、日付として扱うと 125 分の編集が約 299 年になります。サイズによる読み手側の検査がこれを見抜けます

TXLSWorkbookで.xlsのタイムスタンプを設定する

TXLSWorkbook.CreatedDateとTXLSWorkbook.LastSavedDateはローカルのTDateTime値を受け取り、HotXLSはワークブックの保存時にUTCのFILETIMEへ変換します。RevisionNumberとEditTimeMinutesは同じストリームに住んでいます。ゼロの値は「このプロパティを書き出さない」の意味で、4つすべてを剥がすのも同じ方法です。クリアすれば次の保存は何も書きません。HotXLSが自分の判断でNowをLastSavedDateに押し込むことはありません。代入したものがそのままファイルに入ります。ライブラリとして正しいデフォルトです。昨年のレポートを再生成するバッチジョブは普通、昨年の日付を望んでおり、自動スタンプはそれを黙って上書きしてしまいます

var
  Book: TXLSWorkbook;
begin
  Book := TXLSWorkbook.Create;
  try
    Book.Title := 'Q3 settlement';
    // API の値はローカル時刻。ファイルには UTC の FILETIME が収まる
    Book.CreatedDate := EncodeDate(2026, 1, 15) + EncodeTime(9, 30, 0, 0);
    Book.LastSavedDate := Now;     // 代入値のまま書かれる。自動スタンプはされない
    Book.RevisionNumber := 7;
    Book.EditTimeMinutes := 125;   // 期間。生の tick で保存される
    if Book.SaveAs('settlement.xls') <> 1 then
      raise Exception.Create('Save failed');
  finally
    Book.Free;
  end;
end;

ファイルを開くと同じ4つのプロパティが、読みを行うマシンのローカル時刻に変換されて戻ってきます。UTCで動くサービスと東京のデスクトップは、同じワークブックに対して9時間違うCreatedDateを報告しますが、どちらも正しいのです。2つのシステムがスタンプを比較する必要があるなら、比較の前にこちら側でUTCへ変換するか、UTC値を併せて保存してください

XLSXの日付がちょうどタイムゾーンオフセットぶんずれる理由

XLSXの日付がゾーンオフセットぶんずれるのは、ライターがローカル時刻にUTCの印を付けて書くからです。ECMA-376 Part 2のコアプロパティモデルの下で、docProps/core.xmlのdcterms:createdとdcterms:modifiedはW3CDTF値であり、通常の形はZで終わります。Nowを整形してZを付けるのがいかにもな1行です。UTC+8のマシンでは09:30が09:30:00Zになり、同じマシンのExcelは17:30を表示します。冒頭の例のそっくりそのままです。vt:filetimeとして保存されるカスタム日付プロパティも同じ規則に従い、.xlsのバイナリFILETIMEも同様です。HotXLSは3つの経路すべてで書き込み前に変換します。TXLSXWorkbook.Created、TXLSXWorkbook.Modified、CustomProperties.AddDateで追加される日付は、API側ではローカル、ファイル内ではZ付きのUTCです

変換にどのWindows関数を使うかは、人が思うより重要です。LocalFileTimeToFileTimeは今この瞬間に有効なオフセットを適用します。サマータイムのあるどのゾーンでも、7月に1月のスタンプを変換すると1時間ずれます。HotXLSは書き込みにTzSpecificLocalTimeToSystemTime、読み込みにSystemTimeToTzSpecificLocalTimeを使い、どちらも今日ではなく変換対象の日付から標準時かサマータイムかを選びます。未設定値のゼロはどちらの方向でもそのまま通るため、空のプロパティが数時間ずれた1899年12月30日になることはありません

7月に保存した1月の17:00 CETスタンプに対するHotXLSのローカルからUTCへの変換経路の図。LocalFileTimeToFileTimeは今日のサマータイムオフセットを適用して1時間ずれた15:00Zに着地しますが、TzSpecificLocalTimeToSystemTimeはスタンプ自身の日付からオフセットを選び、正しい16:00Zを書き込みます
ゾーンオフセットはスタンプ自身の日付に属し、マシンの現在の規則には属しません。あるWindows APIはサマータイム切替の正しい側を選び、もう片方は7月に変換した1月のスタンプを黙って1時間ずらします
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');
    // 中欧時刻に設定したマシンでは、core.xml は次を保持する
    // <dcterms:created xsi:type="dcterms:W3CDTF">2026-07-01T07:30:00Z</dcterms:created>
    // (7月はUTC+2)。一方 ApprovedOn は 16:00Z(1月はUTC+1)として書かれる
  finally
    Book.Free;
  end;
end;

Windowsの外では同じ変換はRTLのタイムゾーンサポートを通ります。DelphiならTTimeZone.Localで、年に2つの厄介な時間にも固定の答えが用意されています。春に時計が進む隙間の中のローカル時刻は存在しないため、そのまま書かれ、秋に2度起こる時間は標準時の側として扱われます

他のジェネレーターが書いたW3CDTFスタンプを読む

ExcelはZを書きますが、他のジェネレーターはそうとは限らず、20文字目のZだけを見るリーダーはよくある2つの形を読み誤ります。2026-07-01T01:30:00.5Zは小数部が間に入り、2026-07-01T09:30:00+08:00は明示的なオフセットを持ちます。素朴なパーサはどちらも調整なしのローカル時刻として読みます。Created、Modified、日付値のカスタムプロパティ向けのHotXLSリーダーは、任意の長さの小数秒、Z、+hh:mm / -hh:mmオフセットを受け付け、瞬間を指定のオフセットからUTCへ、さらにローカル時刻へ変換します。2026-07-01のような日付だけのスタンプはその日の深夜0時として読まれ、まったく解析に失敗するスタンプはゼロとして返ります

仕様が空白のままにしているのが、2026-07-01T09:30:00のようなゾーン標識を一切持たない時刻です。W3CDTFプロファイルは時刻が存在すれば必ずゾーン標識を要求し、ECMA-376 Part 2はそれを省くスタンプについて規則を与えません。HotXLSはそのような値をローカル時刻として、変更せずに読みます。UTCとして扱うのも紙の上では同等に正当ですが、ゾーンなしスタンプの最有力の出所はローカル時刻を書いて印を付け忘れたツールであり、その値をずらすとそのツールのタイムスタンプ全部がゾーンオフセットぶん動いてしまいます

逆の間違いを救えるリーダーはありません。ローカル時刻として書かれZを着たスタンプは正しいものと見分けが付かないため、HotXLSもExcelも形式に従う他のリーダーも、ゾーンオフセットぶんずらします。読み手が検出できる署名を持つのは、.xlsの編集時間の符号化と$0Eの置き場所だけです

自分のコードが書いていないバイトに対してテストする

上に挙げた罠はどれも保存して開き直す検査を通ります。対称な間違いは対称なテストには見えないからです。基準はどこか別の場所から来なければなりません。.xlsxなら、保存したファイルをunzipしてdcterms:createdのリテラルテキストを表明します。.xlsなら、PythonのolefileパッケージがSummaryInformationストリームを独立に読め、get_metadata()は編集時間を秒で報告し$0Eをページ数として扱うので、.xlsの2つの罠が一度に見えます。もう1つの方向は、Excel自身が保存したワークブックをAPI経由で読み、ファイル > 情報の表示と比較することです

uses
  System.SysUtils, System.DateUtils;

procedure CheckExcelReference;
var
  Book: TXLSXWorkbook;
  Expected: TDateTime;
begin
  // テストマシンで Excel のファイル > 情報がこのファイルについて表示する値
  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');
    // HotXLS の API ではなく自分のチェック。丸め込みで 1 秒を許容
    if Abs(Book.Created - Expected) > OneSecond then
      raise Exception.CreateFmt('Created reads as %s',
        [DateTimeToStr(Book.Created)]);
  finally
    Book.Free;
  end;
end;

このスイートをUTCから十分離れたゾーンに設定したマシンで走らせ、テスト日付をサマータイム切替の両側に1つずつ置いてください。UTCのまま放置されたビルドエージェントはゾーンオフセットの誤りを完全に隠し、夏だけのテスト日付はLocalFileTimeToFileTimeの誤りを隠します。中欧時刻の1月20日と7月1日なら両方とも捕まります

記録管理システム、検索インデックス、監査証跡はこれらのスタンプで並べ替えます。1日や8時間ずれた日付は、欠けている日付より有害です。誰も疑わないからです。HotXLS Delphiスプレッドシートコンポーネントでは、エポック定数、プロパティID、サマータイムを考慮したUTC変換が.xlsと.xlsxの両方で処理され、アプリケーションコードは通常のローカルなTDateTime値を代入し読むだけですみます。タイトルや作成者からカスタムプロパティまで、プロパティセットの残りについては、DelphiでExcelドキュメントプロパティを設定するの解説が残りのフィールドをカバーします