기술 문서

Delphi Excel 문서 타임스탬프: FILETIME, UTC, DST

상하이의 빌드 머신에서 09:30에 생성한 통합 문서를 Excel에서 열면 File > Info가 생성 시각 17:30을 보여 줍니다. 그 파일을 만든 단위 테스트는 통과했습니다. 09:30을 대입하고 저장한 뒤 다시 열어 09:30을 그대로 읽었으니까요. 두 값은 같은 바이트에서 나왔습니다. 파일에는 09:30이 UTC로 표시되어 있고 Excel은 그 표시를 존중해 8시간을 더하며, 테스트는 그 표시를 전혀 들여다보지 않았습니다. Excel 파일의 문서 타임스탬프는 디스크에는 UTC이고 프로그램이 다루는 값은 현지 시간이며, 둘 사이의 모든 변환은 타임스탬프 날짜 자신의 서머타임 규칙을 따라야 합니다

왕복 테스트가 봐주지 못하는 하루짜리 오류

.xls 파일에서 생성·저장 시각은 FILETIME 값입니다. 1601-01-01 UTC 이후의 100나노초 틱 수를 담는 64비트 정수입니다([MS-DTYP] §2.3.3). Delphi의 TDateTime은 1899-12-30부터의 날짜 수를 세는데, Delphi의 Excel 날짜 시리얼과 1900 vs 1904 체계에서 다룬 것과 같은 기준점입니다. 둘 사이의 변환에는 두 기원 사이의 날짜 수라는 상수 하나가 필요하고, 그 수는 109205입니다. 달력 없이 검산하는 방법도 있습니다. Unix 기원은 TDateTime으로 25569이고 FILETIME 기원으로는 134774일 뒤인데, 25569 + 109205 = 134774입니다

양 끝 날짜를 모두 세어 손으로 세면 109206이 나옵니다. 그 상수로 만든 작성기와 읽기는 서로 완벽히 일치합니다. 모든 생성·저장 스탬프는 하루 늦게 파일에 들어가고 하루 일찍 돌아오므로, 저장 후 다시 열기 테스트는 자신이 대입한 값과 정확히 같은 값을 보는 반면, Excel이나 올바른 기원을 쓰는 어떤 읽기든 내일을 보여 줍니다

const
  // FILETIME 기원(1601-01-01)부터 TDateTime 기원(1899-12-30)까지의 날짜 수
  // 검산: 25569 + 109205 = 134774, Unix 기원의 FILETIME 날짜 수
  FileTimeDayBias = 109205;

function UtcDateTimeToFileTimeTicks(UtcStamp: TDateTime): Int64;
begin
  // 먼저 정수 밀리초로 반올림한 뒤 100ns 틱으로 환산합니다.
  // Double을 틱으로 곧바로 환산하면 04:00이 03:59:59.9999가 됩니다
  Result := Round((UtcStamp + FileTimeDayBias) * 86400000.0) * 10000;
end;
HotXLS 타임라인: FILETIME 기원 1601-01-01, TDateTime 기원 1899-12-30, Unix 기원 1970-01-01이 109205일과 25569일 상수로 이어지는 모습
109205일짜리 상수 하나가 FILETIME 틱과 TDateTime 날짜 사이를 오갑니다. 검산은 25569 + 109205 = 134774입니다

그 스케치의 반올림 주석도 중요합니다. TDateTime의 소수부는 이진 Double이어서, 하루 864,000,000,000 틱으로 곧바로 곱하면 표현 오차가 낮은 자릿수로 밀려납니다. 그래서 정확히 04:00인 스탬프가 03:59:59.9999로 읽히고 03:59로 표시됩니다. HotXLS는 먼저 정수 밀리초로 반올림한 뒤에야 틱으로 환산합니다. 정시 값은 살아남습니다. 스케치가 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인데 담고 있는 것은 기간입니다. 기원이 더해지지 않은, 경과한 100ns 틱의 숫자 그 자체입니다. 다른 둘처럼 취급해 EditTimeMinutes / 1440을 기원 산술로 돌리면 125분의 편집이 대략 299년짜리 값으로 변합니다. HotXLS는 맨 틱 수(분 × 600,000,000)를 기록합니다. Windows에서 읽는 쪽은 크기로 날짜 모양 인코딩도 잡아냅니다. 실제 편집 세션이 세 세기를 넘을 수 없으므로, 109206일 이상의 편집 시간은 EditTimeMinutes를 채우기 전에 그 오프셋을 뺍니다

HotXLS의 005SummaryInformation 속성 집합 지도: $0C의 PIDSI_CREATE_DTM은 생성 시각, $0D의 PIDSI_LASTSAVE_DTM은 저장 스탬프, $0A의 PIDSI_EDITTIME은 날짜가 아닌 맨 기간, $0E는 PIDSI_PAGECOUNT로서 타임스탬프를 담아서는 안 되는 자리
PIDSI_EDITTIME은 함정 속의 함정입니다. VT_FILETIME 타입에 기원 없는 경과 틱을 담으므로 날짜처럼 취급하면 125분의 편집이 약 299년이 되고, 크기 기반 읽기 검사가 이를 알아볼 수 있습니다

TXLSWorkbook으로 .xls 타임스탬프 설정하기

TXLSWorkbook.CreatedDate와 TXLSWorkbook.LastSavedDate는 현지 TDateTime 값을 받고, HotXLS는 통합 문서를 저장할 때 이를 UTC FILETIME으로 변환합니다. RevisionNumber와 EditTimeMinutes는 같은 스트림에 있습니다. 0 값은 "이 속성은 빼고 싶다"는 뜻이며 넷을 모두 벗기는 방법이기도 합니다. 값을 지우면 다음 저장에 아무것도 기록되지 않습니다. HotXLS는 LastSavedDate에 제 임의로 Now를 찍지 않습니다. 대입한 것이 그대로 파일에 들어가고, 라이브러리 입장에서 그것이 옳은 기본값입니다. 지난해 보고서를 다시 찍어 내는 배치 작업은 보통 지난해 날짜를 원하고, 자동 스탬프는 그것을 조용히 덮어쓰니까요

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;   // 기간이므로 맨 틱으로 저장
    if Book.SaveAs('settlement.xls') <> 1 then
      raise Exception.Create('Save failed');
  finally
    Book.Free;
  end;
end;

파일을 열면 같은 네 속성이 읽는 쪽 머신의 현지 시간으로 변환되어 채워집니다. UTC에서 돌아가는 서비스와 도쿄의 데스크톱은 같은 통합 문서에 대해 9시간 차이 나는 CreatedDate를 보고하고, 둘 다 맞습니다. 두 시스템이 스탬프를 비교해야 한다면 비교 전에 자기 쪽에서 UTC로 변환하거나 UTC 값을 함께 저장하세요

XLSX 날짜가 정확히 시간대 오프셋만큼 틀어지는 이유

작성기가 현지 시간을 찍고 UTC라고 표시하면 XLSX 날짜는 시간대 오프셋만큼 틀어져 나옵니다. docProps/core.xml의 dcterms:created와 dcterms:modified는 ECMA-376 Part 2의 핵심 속성 모델 아래 W3CDTF 값이고, 평범한 형태는 Z로 끝납니다. Now를 포맷해 Z를 붙이는 것이 자명해 보이는 한 줄입니다. UTC+8 머신에서 그 한 줄은 09:30을 09:30:00Z로 만들고, 같은 머신의 Excel은 17:30을 보여 줍니다. 바로 서두의 예제 그 자체입니다. vt:filetime으로 저장되는 사용자 정의 날짜 속성도 같은 규칙을 따르고, .xls의 이진 FILETIME도 마찬가지입니다. HotXLS는 세 경로 모두에서 기록 전에 변환합니다. TXLSXWorkbook.Created, TXLSXWorkbook.Modified, CustomProperties.AddDate로 넣은 날짜는 API 쪽에서 현지 시간이고 파일에서는 Z가 붙은 UTC입니다

변환을 어느 Windows 함수로 하느냐가 사람들이 생각하는 것보다 훨씬 중요합니다. LocalFileTimeToFileTime은 지금 이 순간 유효한 오프셋을 적용합니다. 서머타임이 있는 어느 시간대든 7월에 1월 스탬프를 변환하면 한 시간 틀린 곳에 떨어집니다. HotXLS는 쓰기에 TzSpecificLocalTimeToSystemTime을, 읽기에 SystemTimeToTzSpecificLocalTime을 쓰며, 둘 다 표준시와 서머타임을 오늘이 아니라 변환 대상 날짜로 고릅니다. 설정되지 않은 0 값은 양방향 모두 손대지 않고 통과하므로, 빈 속성이 몇 시간 어긋난 1899년 12월 30일 날짜로 변하는 일은 없습니다

HotXLS의 현지 시간-UTC 변환 경로 비교: 7월에 저장한 1월 17:00 CET 스탬프를 LocalFileTimeToFileTime은 오늘의 서머타임 오프셋을 적용해 15:00Z로 한 시간 틀리게 착지하고, TzSpecificLocalTimeToSystemTime은 스탬프 날짜의 오프셋을 골라 올바른 16:00Z를 기록
시간대 오프셋은 기계의 현재 규칙이 아니라 스탬프 자신의 날짜에 속합니다. 한 Windows API는 서머타임 전환의 올바른 쪽을 고르고, 다른 하나는 7월에 변환한 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이고, 1년 중 곤란한 두 시간에는 고정된 답을 둡니다. 봄에 시계가 앞으로 뛰는 구간 안의 현지 시간은 존재하지 않으므로 그대로 기록되고, 가을에 두 번 일어나는 시각은 표준시 발생으로 받아들입니다

다른 생성기가 쓴 W3CDTF 스탬프 읽기

Excel은 Z를 쓰지만 다른 생성기는 항상 그렇지 않고, 20번째 문자의 Z만 검사하는 읽기는 흔한 두 형태를 틀리게 읽습니다. 2026-07-01T01:30:00.5Z는 소수부가 가로막고 있고, 2026-07-01T09:30:00+08:00는 명시적 오프셋을 갖고 있습니다. 순진한 파서는 둘 다 조정 없는 현지 시간으로 읽습니다. HotXLS의 Created, Modified, 날짜 값 사용자 정의 속성 읽기는 임의 길이의 소수 초와 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라면 저장된 파일의 압축을 풀어 dcterms:created의 문자 그대로의 텍스트를 단언하고, .xls라면 Python의 olefile 패키지가 get_metadata()로 SummaryInformation 스트림을 독립적으로 읽어 주며, 편집 시간을 초 단위로 보고하고 $0E를 페이지 수로 취급하므로 .xls의 두 함정이 한꺼번에 드러납니다. 반대 방향은 Excel 자신이 저장한 통합 문서를 API로 읽어 File > Info가 보여 주는 것과 비교하는 것입니다

uses
  System.SysUtils, System.DateUtils;

procedure CheckExcelReference;
var
  Book: TXLSXWorkbook;
  Expected: TDateTime;
begin
  // 테스트 머신에서 이 파일에 대해 Excel의 File > Info가 보여 주는 값
  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에서 충분히 먼 시간대로 설정된 머신에서, 서머타임 전환의 양쪽에 하나씩 테스트 날짜를 두고 돌리세요. UTC로 놓인 빌드 에이전트는 시간대 오프셋 오류를 완전히 숨기고, 여름 날짜 하나뿐인 테스트는 LocalFileTimeToFileTime 오류를 숨깁니다. 중부 유럽 시간의 1월 20일과 7월 1일이 둘 다 잡아냅니다

기록 시스템과 검색 색인, 감사 추적은 이 스탬프들을 기준으로 정렬하며, 하루나 8시간 어긋난 날짜는 없는 날짜보다 더 큰 피해를 남깁니다. 아무도 의심하지 않기 때문입니다. HotXLS Delphi 스프레드시트 컴포넌트를 쓰면 기원 상수와 속성 ID, 서머타임을 인식하는 UTC 변환이 .xls와 .xlsx 양쪽에서 처리되고, 애플리케이션 코드는 평범한 현지 TDateTime 값만 대입하고 읽습니다. 제목과 작성자부터 사용자 정의 속성까지 속성 집합의 나머지는 자매 글인 Delphi에서 Excel 문서 속성 설정하기가 남은 필드들을 다룹니다