외부 통합 문서 참조

개요

스프레드시트 모델은 종종 상호 참조 수식을 사용하여 보조 통합 문서에서 데이터를 가져옵니다. HotXLS는 BIFF8(클래식 XLS) 및 OpenXML (XLSX) 문서 모두에서 외부 통합 문서 참조의 구문 분석, 작성, 보존을 지원합니다

라이브 통합 문서 워크스페이스

lxWorkbookWorkspace의 TXLSWorkbookWorkspace는 라이브 외부 통합 문서를 위한 공유 식별자 및 등록 코어입니다. TXLSWorkbook과 TXLSXWorkbook 모두 CreateWorkspaceWorkbook을 노출하고 자신의 수식 평가기가 사용하는 ExternalWorkspace를 소유하며, TXLSXWorkbook을 통해 열린 ODS 통합 문서는 동일한 어댑터를 통해 OpenDocument 엔진 종류를 보고합니다

var
  Host, Target: TXLSXWorkbook;
begin
  Host.ExternalWorkspace.Add(
    '..\Data\Target.xlsx',
    '..\Data\Target.xlsx',
    'C:\Models\Host.xlsx',
    Target.CreateWorkspaceWorkbook);

  // The compatibility facade maps an unambiguous name to the
  // relationship target already stored in Host.ExternalLinks
  Host.RegisterExternalWorkbook('Target.xlsx', Target);

  // The matching call revokes a facade-level registration
  Host.UnregisterExternalWorkbook('Target.xlsx');
end;

클래식 통합 문서도 TXLSWorkbook 대상에 대해 동일한 호환성 메서드를 사용합니다. RegisterExternalWorkbook과 UnregisterExternalWorkbook은 파사드 수준의 이름 매핑만 관리하는 반면, ExternalWorkspace.Remove와 Clear는 워크스페이스 등록 자체를 해제합니다. 크로스 엔진 호출자는 클래식, XLSX 또는 ODS 어댑터를 ExternalWorkspace에 직접 추가할 수 있습니다

• 식별자 정규화는 어휘적이며 대소문자를 구분하지 않고, 경로와 확장자를 보존하고, 소유자 소스 식별자를 기준으로 상대 대상을 해석하고, 도트 세그먼트를 축소하며, 파일 시스템이나 네트워크 접근을 수행하지 않습니다
• 정확한 식별자와 명시적 별칭이 먼저 해석됩니다. basename만으로 조회하는 것은 정확히 하나의 연결된 등록이 일치할 때만 성공하고, 그 외의 경우 Resolve는 xlswrsConflict를 반환합니다
• Add는 동일 키, 별칭, 중복 통합 문서 충돌을 거부합니다. 서로 다른 전체 경로와 서로 다른 확장자는 공존할 수 있습니다
• Remove와 Clear는 등록을 해제하며, 클래식 또는 XLSX 대상을 직접 파괴하면 해당 어댑터의 연결이 끊기고 모델이 해제되기 전에 활성 리더를 기다립니다
• 외부 워크시트는 1기반 위치 폴백보다 선언된 이름으로 먼저 해석되므로, 대상 통합 문서의 시트 순서가 소스 링크 디렉터리와 일치할 필요가 없습니다
• 수식 평가기는 해석된 라이브 통합 문서를 먼저 읽고, 그다음 호스트 파일의 형식화된 캐시로 폴백합니다. 클래식 XLS 호스트는 스파스한 XCT 및 CRN 값을 디코드하고, XLSX 호스트는 패키지 모델이 이미 보유한 외부 링크 캐시를 사용합니다
• OnLoadWorkbook는 선택적인 제어된 리소스 요청입니다. 기본값은 nil이므로, 애플리케이션 코드가 해당 정책을 명시적으로 제공하지 않는 한 재계산은 파일 시스템이나 네트워크 접근을 수행하지 않습니다
• 정규화된 식별자마다 ResetLoadAttempts까지 로더를 최대 한 번만 호출합니다. 동시 최상위 요청은 형식화된 not-found 및 오류 결과를 포함해 진행 중인 결과를 공유하므로 같은 리소스를 반복해서 열지 않습니다
• MaxLoadDepth는 기본값이 16이고 MaxWorkbookCount는 기본값이 64입니다. 동일 식별자 재진입, 이미 진행 중인 식별자에 대한 중첩 종속, 깊이 소진, 통합 문서 수 소진은 로드 주기를 차단하지 않고 형식화된 진단을 반환합니다
• ODF 외부 소스 IRI는 URI 스킴과 따옴표로 묶인 문자를 포함해 완전한 어휘 식별자로 유지되지만, 암시적인 파일 또는 네트워크 접근을 허가하지 않습니다
• 식별자 충돌은 #REF!로 유지되어 오래된 캐시 데이터가 모호한 라우팅을 숨길 수 없습니다. 캐시된 셀이 없는 경우는 파일이 해당 시트에 유효한 캐시를 선언한 경우에 한해 빈 값이 됩니다

Resolve는 등록된 조회를 수행한 다음 선택적인 제어 로드를 수행합니다. 그 결과는 TXLSWorkspaceResolveStatus(xlswrsResolved, xlswrsNotFound, xlswrsConflict, xlswrsDisconnected, xlswrsLoadNotFound, xlswrsLoadLimit, xlswrsLoadLoop 또는 xlswrsLoadError)이고, ResolveWithLoader는 추가로 TXLSWorkspaceLoadDiagnostic을 반환합니다. 이는 TXLSWorkspaceLoadDiagnosticCode와 TXLSWorkspaceLoadResponseStatus(xlswlrsNotFound, xlswlrsResolved, xlswlrsError)를 짝지어 not found, 로더 오류, 연결 끊김 결과, 깊이 또는 통합 문서 한도, 식별자 재진입, 동시 종속, 등록 충돌 결과를 구분합니다. 로더 콜백은 TXLSWorkspaceLoadRequest(식별자, 깊이, 등록 수, 한도)를 받고 TXLSWorkspaceLoadResponse로 응답합니다

Recalculate는 TXLSWorkspaceRecalcStatus를 보고하며, 선택적으로 TXLSWorkspaceRecalcResult 상세 내역을 함께 제공합니다. 평가기는 셀별 출처를 TXLSWorkspaceRuntimeLookup(xlswrlInactive, xlswrlResolved, xlswrlFallbackCache 또는 xlswrlError)로 기록하므로 진단이 라이브 읽기와 캐시 폴백을 구분할 수 있습니다

IXLSWorkspaceWorkbook 어댑터는 EngineKind(타입 TXLSWorkspaceEngineKind: xlsweClassic, xlsweOpenXml 또는 xlsweOpenDocument), SourceIdentity, InstanceIdentity, Generation을 노출하고, IsConnected로 생존 여부를 검사하며, TryGetCellValue로 셀 하나를 읽고(값, 누락, 잘못된 참조, 연결 끊김, 오류와 사용 범위 밖 플래그를 담는 형식화된 TXLSWorkspaceCellStatus 반환), Recalculate로 모델을 새로 고치고, Disconnect로 통합 문서 모델에서 분리합니다

레지스트리는 하나의 등록된 식별자에 추가 이름을 바인딩하는 AddAlias, 예외 없는 조회 변형인 TryResolve, 모호하지 않은 대상을 고르기 전에 동일한 basename을 공유하는 연결된 등록 수를 미리 보는 BaseNameMatchCount를 제공합니다

통합 문서 간 종속성 그래프

BuildDependencyGraph는 등록된 모든 통합 문서 어댑터의 스냅샷을 만들고 클래식 XLS, XLSX, ODS 모델에서 수식 노드를 추출해 하나의 TXLSWorkspaceDepGraph로 만듭니다. 등록된 어댑터 중 하나라도 종속성 메타데이터를 제공할 수 없으면 메서드는 False를 반환하고 부분 그래프도 만들지 않습니다

• 각 수식 노드는 정규화된 통합 문서 식별자, 워크시트 이름과 1기반 워크시트 위치, 0기반 셀 위치, 배열 출력 사각형, 휘발성, 미해결 참조 상태를 유지합니다
• 셀 및 사각형 범위 참조는 정규화된 대상 통합 문서 및 워크시트 식별자를 유지합니다. 전체 열, 전체 행, 전체 시트 참조는 수백만 개의 셀로 확장되지 않고 하나의 구간으로 유지됩니다
• 로컬 정의 이름은 기호 종속성으로 조회할 수 있을 뿐 아니라, 정의를 정적으로 해석할 수 있을 때는 구체적인 셀 또는 범위 종속성으로도 확장됩니다
• 외부 정의 이름은 DDE, OLE, 사용자 함수 메타데이터를 통합 문서 이름으로 취급하지 않고 외부 링크 슬롯, 선언된 이름, 선택적 워크시트 범위, 정규화된 대상 식별자를 보존합니다
• FindDependentsOfCell과 그래프 엣지 구성은 최대 끝값 가지치기가 적용된 행 구간 트리를 사용합니다. LastRangeCandidateChecks와 EdgeCandidateChecks는 성능 검증을 위해 정확한 사각형 검사 횟수를 노출합니다
• 수식 추출은 통합 문서 읽기 리스 아래에서 실행되고 구체화된 수식 개체만 스캔하므로, 압축된 값 저장소는 압축된 상태로 유지되고 그래프 생성은 통합 문서 세대를 변경하지 않습니다

예약된 재계산

Recalculate는 공유 그래프를 유지하며 워크스페이스 등록이나 통합 문서의 수식 종속성 세대가 변경될 때만 다시 빌드합니다. 값 세대는 새 더티 패스를 시드하고, 더티 상태는 통합 문서 간 종속 엣지를 따라 전파됩니다

var
  RecalcInfo: TXLSWorkspaceRecalcResult;
  Status: TXLSWorkspaceRecalcStatus;
begin
  Status := Workspace.Recalculate(RecalcInfo);
  if Status <> xlswrcOk then
    HandleWorkspaceCalculation(Status, RecalcInfo);
end;

• 강연결 요소는 수식 셀을 대상으로 계산되므로, 셀 수준 종속 경로가 루프를 이루지 않는 한 통합 문서가 양방향으로 링크되어도 비순환 상태를 유지합니다
• 실제 사이클 구성원과 사이클에 막힌 더티 자손은 무효화되고 위상 순서에서 제외되어, 오래된 캐시 값이 성공적인 결과로 표시되는 것을 막습니다
• 휘발성 참조나 정적으로 해석되지 않는 참조는 정확성에 필요한 보수적인 더티 동작을 강제하며, 안정적인 그래프는 이전 종속성 작업을 재사용합니다
• 한 패스 안의 외부 읽기는 정확한 통합 문서 인스턴스, 워크시트, 행, 열 캐시를 사용합니다. 예약된 수식은 평가 전에 출력 범위를 무효화하므로 이후 종속 항목은 새 값을 관찰합니다
• 패스 로컬 캐시는 리소스 권한을 부여하지 않습니다. 등록된 통합 문서와 호출자가 제어하는 선택적 로더가 유일한 라이브 해석 소스이며, 그다음으로 형식화된 파일 캐시와 #REF!가 이어집니다
• TXLSWorkspaceRecalcResult는 그래프 재빌드 여부와 더티, 평가됨, 무효화됨, 사이클, 차단됨, 캐시 히트, 캐시 미스 수를 노출합니다
• 상태는 성공, 지원하지 않는 어댑터, 연결이 끊긴 통합 문서, 순환 참조, 계산 오류, 패스 중 워크스페이스 변경을 구분합니다
• 동일한 워크스페이스에 대한 Recalculate 호출은 직렬화되므로 두 계산 세션이 공유 그래프나 통합 문서 캐시를 동시에 수정하는 일은 없습니다
• 패스가 진행되는 동안에도 Remove나 Clear가 실행될 수 있습니다. 패스는 안전한 어댑터 스냅샷을 유지하고 제거된 등록을 역참조하는 대신 xlswrcWorkspaceChanged를 반환합니다
• 워크스페이스를 파괴하면 활성 패스가 끝나기를 기다리며, 등록된 통합 문서를 파괴하면 해당 어댑터의 연결이 끊겨 이후 해석이 안전하게 실패합니다
• 로더 실패와 not-found 결과는 ResetLoadAttempts까지 정규화된 식별자별로 한 번만 캐시되고, 실패한 계산은 명시적 재시도를 위해 로컬 더티 상태를 유지합니다
• 유지된 그래프 덕분에 변경되지 않은 후속 패스는 수식 수가 아닌 등록된 통합 문서 수에 비례합니다. 비재귀 컴포넌트 분석과 압축된 범위 엣지는 깊고 넓은 모델도 구체화된 수식 메타데이터 범위 안에 머무르게 합니다

외부 정의 이름 분리

ConvertExternalDefinedNamesToRefErrors는 TXLSWorkbook과 TXLSXWorkbook에서 동일한 공용 작업을 제공하며, 통합 문서 범위 및 워크시트 범위 정의 중 네이티브 #REF!로 대체된 정의 수를 반환합니다

var
  Converted: Integer;
begin
  Converted := Workbook.ConvertExternalDefinedNamesToRefErrors;
  // External-link parts and ordinary cell formulas remain intact
end;

• 클래식 XLS 선택은 컴파일된 BIFF 참조 토큰과 XTI 지원 통합 문서 식별자를 사용하므로, 동일 통합 문서 3차원 참조와 불확실한 토큰 스트림은 변경되지 않습니다
• XLSX 선택은 관계 문서 순서대로 구문 인식 숫자 통합 문서 슬롯을 사용하고 통합 문서 외부 링크 파트만 받아들이며, DDE, OLE, 미해결 슬롯, 테이블 참조, 문자열 안의 대괄호 텍스트는 제외합니다
• 모든 대체는 첫 변경 전에 준비되고 하나의 쓰기 작업으로 커밋됩니다. 두 번째 호출은 멱등적입니다
• 이름 텍스트, 통합 문서 또는 워크시트 범위, 가시성, 주석, 매크로 및 기본 제공 플래그, 알 수 없는 XLSX 특성, 외부 링크 디렉터리는 변환 후에도 남아 Roundtrip을 거칩니다
• 잘못되었거나 지원되지 않는 정의는 가능한 한 바이트 또는 텍스트를 보존하고 추측하는 대신 xlsDiagnosticDefinedNameConversionSkipped 진단을 추가합니다
• 종속 수식은 해당 Excel 오류 값으로 재계산되며, 일반 직접 외부 수식의 유효한 캐시 결과는 라이브 통합 문서가 나중에 연결이 끊겨도 계속 사용할 수 있습니다
• 이 작업은 Excel 전용이며 OpenDocument 이름-수식 의미를 재해석하지 않습니다

클래식 XLS 외부 참조

클래식 XLS 통합 문서에서 외부 링크는 EXTERNALBOOK 및 EXTERNNAME 레코드를 사용하여 전역 디렉터리 블록에 저장됩니다. HotXLS는 파일 읽기/쓰기 주기 동안 이러한 디렉터리를 유지하여 원격 범위 참조가 수정 루프를 거쳐도 보존되도록 합니다

XLSX 외부 관계

OOXML 통합 문서의 경우 외부 링크 매핑은 관계 파트를 통해 관리됩니다. 아래의 지원 인터페이스 세부 정보를 확인하십시오

• TXLSXExternalLinks 클래스 — 스프레드시트 외부 링크를 나열하고 업데이트하는 API
• IXLSWorkbook 인터페이스 — 최상위 통합 문서 속성
• IXLSRange.Formula 속성 — 통합 문서 간 수식을 읽고 씁니다