Riferimenti esterni alla cartella di lavoro

Panoramica

I modelli di foglio di lavoro spesso ricavano dati da cartelle di lavoro secondarie utilizzando formule di riferimento incrociato; HotXLS supporta l'analisi, la scrittura e la conservazione dei riferimenti esterni alla cartella di lavoro sia nei documenti BIFF8 (XLS classico) sia in quelli OpenXML (XLSX)

Workspace dei workbook live

Il TXLSWorkbookWorkspace in lxWorkbookWorkspace è il nucleo condiviso di identità e registrazione per i workbook esterni live; sia TXLSWorkbook sia TXLSXWorkbook espongono CreateWorkspaceWorkbook e possiedono un ExternalWorkspace usato dai rispettivi valutatori di formule, mentre un workbook ODS aperto tramite TXLSXWorkbook riporta il tipo di motore OpenDocument attraverso lo stesso adapter

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;

I workbook classici usano gli stessi metodi di compatibilità con target TXLSWorkbook; RegisterExternalWorkbook e UnregisterExternalWorkbook gestiscono solo la mappatura dei nomi a livello di facade, mentre ExternalWorkspace.Remove e Clear revocano le registrazioni del workspace vere e proprie. I chiamanti cross-engine aggiungono qualsiasi adapter Classic, XLSX o ODS direttamente a ExternalWorkspace

• La normalizzazione delle identità è lessicale e case-insensitive: preserva percorsi ed estensioni, risolve i target relativi rispetto all'identità di origine del proprietario, comprime i segmenti dot e non esegue alcun accesso al file system o alla rete
• Le identità esatte e gli alias espliciti vengono risolti per primi; la ricerca solo per basename riesce soltanto quando corrisponde esattamente una registrazione connessa, altrimenti Resolve restituisce xlswrsConflict
• Add rifiuta le collisioni su chiave esatta, su alias e su workbook duplicati; percorsi completi distinti ed estensioni distinte possono coesistere
• Remove e Clear revocano le registrazioni, mentre la distruzione diretta di un target Classic o XLSX disconnette il suo adapter e attende i lettori attivi prima di rilasciare il modello
• I fogli di lavoro esterni vengono risolti per nome dichiarato prima del fallback posizionale a base uno, quindi l'ordine dei fogli del workbook di destinazione non deve corrispondere alla directory dei collegamenti di origine
• Il valutatore di formule legge prima un workbook live risolto e poi ricade nella cache tipizzata del file host; gli host XLS classici decodificano i valori sparsi XCT e CRN, mentre gli host XLSX usano la cache dei collegamenti esterni già detenuta dal modello del pacchetto
• OnLoadWorkbook è una richiesta di risorsa controllata facoltativa; il suo valore predefinito è nil, quindi il ricalcolo non esegue comunque accessi al file system o alla rete a meno che il codice applicativo non fornisca esplicitamente tale criterio
• Ogni identità normalizzata invoca il loader al massimo una volta finché non arriva ResetLoadAttempts; le richieste top-level concorrenti condividono il risultato in corso, compresi gli esiti tipizzati not-found ed errore, invece di aprire ripetutamente la stessa risorsa
• MaxLoadDepth vale 16 per impostazione predefinita e MaxWorkbookCount 64; il rientro sulla stessa identità, le dipendenze annidate su un'identità già in corso, l'esaurimento della profondità e quello del conteggio dei workbook restituiscono diagnostica tipizzata senza bloccarsi in un ciclo di caricamento
• Le IRI delle origini esterne ODF restano identità lessicali complete, schemi URI e caratteri quotati compresi, ma non autorizzano mai accessi impliciti a file o alla rete
• Un conflitto di identità resta #REF!, così dati in cache non aggiornati non possono nascondere un instradamento ambiguo; una cella assente in cache è un valore vuoto solo quando il file dichiara una cache valida per quel foglio

Resolve esegue la ricerca tra le registrazioni e poi il caricamento controllato facoltativo; il suo esito è un TXLSWorkspaceResolveStatus (xlswrsResolved, xlswrsNotFound, xlswrsConflict, xlswrsDisconnected, xlswrsLoadNotFound, xlswrsLoadLimit, xlswrsLoadLoop oppure xlswrsLoadError), e ResolveWithLoader restituisce anche un TXLSWorkspaceLoadDiagnostic che accoppia un TXLSWorkspaceLoadDiagnosticCode a un TXLSWorkspaceLoadResponseStatus (xlswlrsNotFound, xlswlrsResolved, xlswlrsError) per distinguere gli esiti non trovato, errore del loader, risultato disconnesso, limite di profondità o di workbook, rientro di identità, dipendenza concorrente e conflitto di registrazione. Il callback del loader riceve un TXLSWorkspaceLoadRequest (identità, profondità, numero di registrazioni, limiti) e risponde con un TXLSWorkspaceLoadResponse

Recalculate riporta un TXLSWorkspaceRecalcStatus, facoltativamente con un dettaglio TXLSWorkspaceRecalcResult, e il valutatore registra la provenienza cella per cella come TXLSWorkspaceRuntimeLookup (xlswrlInactive, xlswrlResolved, xlswrlFallbackCache oppure xlswrlError), così la diagnostica può distinguere una lettura live da un fallback sulla cache

L'adapter IXLSWorkspaceWorkbook espone EngineKind (di tipo TXLSWorkspaceEngineKind: xlsweClassic, xlsweOpenXml oppure xlsweOpenDocument), SourceIdentity, InstanceIdentity e Generation, verifica la connessione con IsConnected, legge una cella tramite TryGetCellValue (restituendo un TXLSWorkspaceCellStatus tipizzato: valore, mancante, riferimento non valido, disconnesso o errore, più un flag fuori dall'used range), aggiorna il modello con Recalculate e si stacca dal modello del workbook con Disconnect

Il registro aggiunge AddAlias per nomi aggiuntivi legati a una identità registrata, TryResolve come variante di ricerca senza eccezioni, e BaseNameMatchCount per vedere in anticipo quante registrazioni connesse condividono uno stesso basename prima di scegliere un target non ambiguo

Grafo delle dipendenze tra workbook

BuildDependencyGraph scatta uno snapshot di ogni adapter di workbook registrato ed estrae i nodi formula dai modelli Classic XLS, XLSX e ODS in un unico TXLSWorkspaceDepGraph; il metodo restituisce False e nessun grafo parziale quando un adapter registrato non riesce a fornire i metadati delle dipendenze

• Ogni nodo formula conserva la propria identità canonica di workbook, nome e posizione a base uno del foglio di lavoro, posizione della cella a base zero, rettangolo di output della formula matrice, volatilità e stato dei riferimenti non risolti
• I riferimenti a celle e a intervalli rettangolari conservano le identità canoniche di workbook e foglio di destinazione; i riferimenti a intera colonna, intera riga e intero foglio restano un unico intervallo invece di espandersi in milioni di celle
• I nomi definiti locali restano interrogabili come dipendenze simboliche e si espandono anche alle loro dipendenze concrete di cella o intervallo quando la definizione può essere risolta staticamente
• I nomi definiti esterni preservano lo slot del collegamento esterno, il nome dichiarato, l'ambito facoltativo sul foglio di lavoro e l'identità canonica del target, senza trattare i metadati DDE, OLE o di funzioni utente come nomi di workbook
• FindDependentsOfCell e la costruzione degli archi del grafo usano alberi di intervalli di righe con potatura dell'estremo massimo; LastRangeCandidateChecks e EdgeCandidateChecks espongono il numero di controlli esatti sui rettangoli per la verifica delle prestazioni
• L'estrazione delle formule gira sotto lease di lettura del workbook e scandisce solo gli oggetti formula materializzati, così l'archiviazione compatta dei valori resta compatta e la creazione del grafo non modifica le generazioni del workbook

Ricalcolo pianificato

Recalculate conserva il grafo condiviso e lo ricostruisce solo quando cambia la registrazione del workspace o la generazione delle dipendenze delle formule di un workbook; le generazioni dei valori avviano un nuovo passaggio dirty, e lo stato dirty si propaga attraverso gli archi di dipendenza tra workbook

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

• Le componenti fortemente connesse vengono calcolate sulle celle formula, quindi i workbook possono collegarsi in entrambe le direzioni restando aciclici quando i loro percorsi di dipendenza a livello di cella non formano un ciclo
• I membri reali di un ciclo e i discendenti dirty bloccati da un ciclo vengono invalidati ed esclusi dall'ordine topologico, impedendo che valori in cache non aggiornati vengano presentati come risultati riusciti
• I riferimenti volatili o non risolti staticamente impongono il comportamento dirty conservativo richiesto per la correttezza, mentre i grafi stabili riutilizzano il lavoro sulle dipendenze già svolto
• Le letture esterne all'interno di un passaggio usano una cache esatta per istanza di workbook, foglio di lavoro, riga e colonna; una formula pianificata invalida il proprio intervallo di output prima della valutazione, così i dipendenti successivi osservano il nuovo valore
• La cache locale al passaggio non concede mai autorità sulle risorse; i workbook registrati e il loader facoltativo controllato dal chiamante restano le uniche fonti di risoluzione live, seguite dalle cache tipizzate dei file e da #REF!
• TXLSWorkspaceRecalcResult espone se il grafo è stato ricostruito più i conteggi di nodi dirty, valutati, invalidati, cicli, bloccati, cache-hit e cache-miss
• Lo stato distingue successo, adapter non supportati, workbook disconnessi, riferimenti circolari, errori di calcolo e mutazione del workspace durante il passaggio
• Le chiamate a Recalculate sullo stesso workspace vengono serializzate, così due sessioni di calcolo non modificano mai concorrentemente il grafo condiviso o le cache dei workbook
• Remove o Clear possono girare mentre un passaggio è attivo; il passaggio conserva snapshot sicuri degli adapter e restituisce xlswrcWorkspaceChanged invece di dereferenziare una registrazione rimossa
• La distruzione di un workspace attende che il suo passaggio attivo sia finito, mentre la distruzione di un workbook registrato disconnette il suo adapter e fa fallire in sicurezza le risoluzioni successive
• I fallimenti del loader e i risultati not-found restano in cache una sola volta per identità normalizzata finché non arriva ResetLoadAttempts, e un calcolo fallito conserva lo stato dirty locale per un tentativo esplicito
• Il grafo conservato rende un passaggio successivo senza cambiamenti proporzionale ai workbook registrati invece che al numero di formule; l'analisi non ricorsiva delle componenti e gli archi compatti di intervallo tengono i modelli profondi e larghi limitati dai metadati delle formule materializzate

Scollega i nomi definiti esterni

ConvertExternalDefinedNamesToRefErrors offre la stessa operazione pubblica su TXLSWorkbook e TXLSXWorkbook; restituisce il numero di definizioni con ambito workbook e con ambito foglio di lavoro sostituite con #REF! nativo

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

• La selezione per XLS classico usa i token di riferimento BIFF compilati e l'identità XTI del workbook di supporto, quindi i riferimenti tridimensionali nello stesso workbook e i flussi di token incerti restano invariati
• La selezione per XLSX usa slot numerici dei workbook consapevoli della sintassi nell'ordine del documento delle relazioni e accetta solo le parti di collegamento esterno del workbook, escludendo DDE, OLE, slot non risolti, riferimenti a tabelle e testo tra parentesi quadre dentro le stringhe
• Tutte le sostituzioni vengono preparate prima della prima mutazione e commesse come un'unica operazione di scrittura; una seconda chiamata è idempotente
• Il testo del nome, l'ambito workbook o foglio di lavoro, la visibilità, i commenti, i flag macro e incorporati, gli attributi XLSX sconosciuti e la directory dei collegamenti esterni restano disponibili dopo la conversione e il round-trip
• Le definizioni malformate e non supportate restano preservate a livello di byte o di testo dove possibile e aggiungono diagnostica xlsDiagnosticDefinedNameConversionSkipped invece di essere indovinate
• Le formule dipendenti si ricalcolano nel corrispondente valore di errore di Excel, mentre un risultato valido in cache per una formula esterna diretta ordinaria resta disponibile se il suo workbook live si disconnette in seguito
• L'operazione è specifica di Excel e non reinterpreta la semantica nome-formula di OpenDocument

Riferimenti esterni XLS classico

Nelle cartelle di lavoro XLS classiche, i collegamenti esterni sono memorizzati nel blocco della directory globale utilizzando i record EXTERNALBOOK e EXTERNNAME; HotXLS mantiene queste directory durante i cicli di lettura/scrittura dei file, assicurando che i riferimenti di intervallo remoti sopravvivano ai cicli di modifica

Relazioni esterne XLSX

Per le cartelle di lavoro OOXML, la mappatura dei collegamenti esterni è gestita tramite le parti di relazione; controlla i dettagli delle interfacce di supporto di seguito

• Classe TXLSXExternalLinks — API per elencare e aggiornare i collegamenti esterni del foglio di calcolo
• Interfaccia IXLSWorkbook — Proprietà della cartella di lavoro di livello superiore
• Proprietà IXLSRange.Formula — Leggi e scrivi formule tra cartelle di lavoro