Eksterne projektmappe-referencer

Oversigt

Regnearksmodeller henter ofte data fra sekundære projektmapper via krydsreference-formler; HotXLS understøtter parsing, skrivning og bevarelse af eksterne projektmappe-referencer i både BIFF8 (klassisk XLS)- og OpenXML (XLSX)-dokumenter

Workspace til live-projektmapper

TXLSXWorkbookWorkspace i lxWorkbookWorkspace er det fælles identitets- og registreringscenter for live eksterne projektmapper; både TXLSWorkbook og TXLSXWorkbook eksponerer CreateWorkspaceWorkbook og ejer en ExternalWorkspace, som deres formelevaluatorer bruger, mens en ODS-projektmappe, der åbnes via TXLSXWorkbook, rapporterer OpenDocument-motortypen gennem samme 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;

Klassiske projektmapper bruger de samme kompatibilitetsmetoder med TXLSWorkbook-mål; RegisterExternalWorkbook og UnregisterExternalWorkbook styrer kun navneafbildningen på facadeniveau, mens ExternalWorkspace.Remove og Clear tilbagekalder selve workspace-registreringerne. Kald på tværs af motorer tilføjer vilkårlige Classic-, XLSX- eller ODS-adaptere direkte til ExternalWorkspace

• Identitetsnormaliseringen er leksikalsk og case-insensitiv, bevarer stier og filendelser, opløser relative mål mod ejerens kildeidentitet, kollapser dot-segmenter og udfører ingen filsystem- eller netværksadgang
• Eksakte identiteter og eksplicitte aliasser opløses først; opslag på kun basenavn lykkes kun, når præcis én tilsluttet registrering matcher, ellers returnerer Resolve xlswrsConflict
• Add afviser kollisioner på eksakt nøgle, alias og duplikeret projektmappe; forskellige fulde stier og forskellige filendelser kan eksistere side om side
• Remove og Clear tilbagekalder registreringer, mens direkte destruktion af et Classic- eller XLSX-mål frakobler dets adapter og venter på aktive læsere, før modellen frigives
• Eksterne regneark opløses efter deres deklarerede navn, før den 1-baserede positions-fallback, så arkrækkefølgen i målprojektmappen ikke behøver at matche kildens linkmappe
• Formelevaluatoren læser først en opløst live-projektmappe og falder derefter tilbage til værtsfilens typede cache; Classic XLS-værter dekoder sparse XCT- og CRN-værdier, mens XLSX-værter bruger den eksterne link-cache, som pakkemodellen allerede holder
• OnLoadWorkbook er en valgfri, kontrolleret ressourceanmodning; dens standardværdi er nil, så genberegning stadig ikke udfører filsystem- eller netværksadgang, medmindre applikationskoden eksplicit leverer den politik
• Hver normaliseret identitet kalder loaderen højst én gang, indtil ResetLoadAttempts; samtidige topniveau-anmodninger deler in-flight-resultatet, herunder typede not-found- og fejlresultater, i stedet for at åbne samme ressource gentagne gange
• MaxLoadDepth er som standard 16, og MaxWorkbookCount er som standard 64; genindtræden med samme identitet, nestede afhængigheder af en identitet, der allerede er in flight, opbrugt dybde og opbrugt projektmappeantal returnerer typet diagnostik uden at blokere i en load-cyklus
• ODF'ens eksterne kilde-IRI'er forbliver komplette leksikalske identiteter, herunder URI-skemaer og anførte tegn, men godkender aldrig implicit fil- eller netværksadgang
• En identitetskonflikt forbliver #REF!, så forældede cachede data ikke kan skjule tvetydig routing; en manglende cached celle er kun en tom værdi, når filen deklarerer en gyldig cache for det ark

Resolve udfører registreret opslag og derefter den valgfrie kontrollerede load; resultatet er en TXLSWorkspaceResolveStatus (xlswrsResolved, xlswrsNotFound, xlswrsConflict, xlswrsDisconnected, xlswrsLoadNotFound, xlswrsLoadLimit, xlswrsLoadLoop eller xlswrsLoadError), og ResolveWithLoader returnerer desuden en TXLSWorkspaceLoadDiagnostic, der kombinerer en TXLSWorkspaceLoadDiagnosticCode med en TXLSWorkspaceLoadResponseStatus (xlswlrsNotFound, xlswlrsResolved, xlswlrsError) og derved adskiller not found-, loaderfejl-, frakoblet-, dybde- eller projektmappegrænse-, identitetsgenindtrædnings- og registreringskonflikt-resultater. Loader-callbacket modtager en TXLSWorkspaceLoadRequest (identitet, dybde, registreret antal, grænser) og svarer med en TXLSWorkspaceLoadResponse

Recalculate rapporterer en TXLSWorkspaceRecalcStatus, eventuelt med en TXLSWorkspaceRecalcResult-opdeling, og evaluatoren registrerer pr. celle, hvor værdien kom fra, som en TXLSWorkspaceRuntimeLookup (xlswrlInactive, xlswrlResolved, xlswrlFallbackCache eller xlswrlError), så diagnostikken kan skelne en live-læsning fra en cached fallback

IXLSWorkspaceWorkbook-adapteren eksponerer EngineKind (typen TXLSWorkspaceEngineKind: xlsweClassic, xlsweOpenXml eller xlsweOpenDocument), SourceIdentity, InstanceIdentity og Generation, tester liv med IsConnected, læser én celle via TryGetCellValue (returnerer en typet TXLSWorkspaceCellStatus: værdi, manglende, ugyldig reference, frakoblet eller fejl plus et flag for udenfor det brugte område), opfrisker modellen med Recalculate og frakobler fra projektmappemodellen med Disconnect

Registret tilføjer AddAlias til ekstra navne bundet til én registreret identitet, TryResolve som opslagsvarianten uden exceptions og BaseNameMatchCount til at se, hvor mange tilsluttede registreringer der deler et basenavn, før man vælger et entydigt mål

Afhængighedsgraf på tværs af projektmapper

BuildDependencyGraph tager et snapshot af alle registrerede projektmappeadaptere og udtrækker formelknuder fra Classic XLS-, XLSX- og ODS-modellerne i én TXLSWorkspaceDepGraph; metoden returnerer False og ingen delvis graf, når en registreret adapter ikke kan levere afhængighedsmetadata

• Hver formelknude bevarer sin kanoniske projektmappeidentitet, sit arkenavn og sin 1-baserede arkposition, sin 0-baserede celleposition, sit array-outputrektangel, sin volatilitet og sin tilstand for uopløste referencer
• Celle- og rektangulære område-referencer bevarer kanoniske målprojektmappe- og arksidentiteter; helkolonne-, helrække- og helark-referencer forbliver ét interval i stedet for at blive udvidet til millioner af celler
• Lokale definerede navne forbliver forespørgselbare som symbolske afhængigheder og udvides også til deres konkrete celle- eller områdeafhængigheder, når definitionen kan opløses statisk
• Eksterne definerede navne bevarer external-link-slottet, det deklarerede navn, det valgfrie regnearksomfang og den kanoniske målidentitet uden at behandle DDE-, OLE- eller user-function-metadata som projektmappenavne
• FindDependentsOfCell og opbygningen af grafkanter bruger rækkeintervaltræer med maximum-end-beskæring; LastRangeCandidateChecks og EdgeCandidateChecks eksponerer antallet af eksakte rektangeltjek til performanceverifikation
• Formelekstraktionen kører under projektmappens læselåne og scanner kun materialiserede formelobjekter, så det pakkede værdilager forbliver pakket, og oprettelsen af grafen ikke ændrer projektmappens generationer

Planlagt genberegning

Recalculate beholder den delte graf og genopbygger den kun, når workspace-registreringen eller en projektmappes formelafhængighedsgeneration ændres; værdigenerationer starter et nyt dirty-gennemløb, og dirtiness udbredes gennem afhængighedskanterne på tværs af projektmapper

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

• Stærkt sammenhængende komponenter beregnes på formelceller, så projektmapper godt kan linke i begge retninger og forblive acykliske, når deres afhængighedsstier på celleniveau ikke danner en loop
• Ægte cykelmedlemmer og dirty-efterkommere, der blokeres af en cykel, invalidiseres og udelades fra den topologiske rækkefølge, så forældede cachede værdier ikke præsenteres som succesfulde resultater
• Volatile eller statisk uopløste referencer tvinger den konservative dirty-adfærd frem, som kræves for korrekthed, mens stabile grafer genbruger tidligere afhængighedsarbejde
• Eksterne læsninger i et gennemløb bruger en eksakt cache på projektmappeinstans, ark, række og kolonne; en planlagt formel invalidiserer sit outputområde før evaluering, så senere afhængige ser den nye værdi
• Gennemløbets lokale cache giver aldrig ressourceautoritet; registrerede projektmapper og den valgfrie kalder-styrede loader forbliver de eneste live-opløsningskilder, efterfulgt af typede fil-cacher og #REF!
• TXLSWorkspaceRecalcResult eksponerer, om grafen blev genopbygget, plus optællinger af dirty, evaluerede, invalidiserede, cykler, blokerede, cache-hit og cache-miss
• Statussen adskiller succes, ikke-understøttede adaptere, frakoblede projektmapper, cirkulære referencer, beregningsfejl og workspace-mutation under gennemløbet
• Kald til Recalculate på samme workspace serialiseres, så to beregningssessioner aldrig ændrer den delte graf eller projektmappe-cacherne samtidig
• Remove eller Clear kan køre, mens et gennemløb er aktivt; gennemløbet beholder sikre adapter-snapshots og returnerer xlswrcWorkspaceChanged i stedet for at dereferere en fjernet registrering
• Destruktion af et workspace venter på, at dets aktive gennemløb afsluttes, mens destruktion af en registreret projektmappe frakobler dens adapter og får senere opløsning til at fejle sikkert
• Loader-fejl og not-found-resultater forbliver cached én gang pr. normaliseret identitet, indtil ResetLoadAttempts, og en fejlslået beregning beholder den lokale dirty-tilstand til et eksplicit retry
• Den tilbageholdte graf gør et uændret efterfølgende gennemløb proportionalt med antallet af registrerede projektmapper frem for formelantallet; ikke-rekursiv komponentanalyse og kompakte områdekanter holder dybe og brede modeller afgrænset af materialiseret formelmetadata

Frakobl eksterne definerede navne

ConvertExternalDefinedNamesToRefErrors leverer samme offentlige operation på TXLSWorkbook og TXLSXWorkbook; den returnerer antallet af projektmappe- og regnearksomfangsdefinitioner, der er erstattet med native #REF!

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

• Classic XLS-udvælgelsen bruger kompilerede BIFF-referencetokens og XTI'ens understøttende projektmappeidentitet, så tredimensionelle referencer inden for samme projektmappe og usikre tokenstrømme forbliver uændrede
• XLSX-udvælgelsen bruger syntaksbevidste numeriske projektmappe-slots i dokumentordenen for relationerne og accepterer kun projektmappens external-link-dele, hvilket udelader DDE, OLE, uopløste slots, tabelreferencer og klammadskrift inde i strenge
• Alle erstatninger forberedes før den første mutation og committes som én skriveoperation; et andet kald er idempotent
• Navnetekst, projektmappe- eller regnearksomfang, synlighed, kommentarer, makro- og indbyggede flag, ukendte XLSX-attributter og external-link-mappen forbliver tilgængelige efter konvertering og roundtrip
• Misdannede og ikke-understøttede definitioner forbliver byte- eller tekstbevarende, hvor det er muligt, og tilføjer xlsDiagnosticDefinedNameConversionSkipped-diagnostik i stedet for at blive gættet
• Afhængige formler genberegnes til den tilsvarende Excel-fejlværdi, mens et gyldigt cached resultat for en almindelig direkte ekstern formel forbliver tilgængeligt, hvis dens live-projektmappe senere frakobles
• Operationen er Excel-specifik og genfortolker ikke OpenDocuments navneformel-semantik

Klassiske XLS-eksterne referencer

I klassiske XLS-projektmapper gemmes eksterne referencer i det globale mappe-blok via EXTERNALBOOK- og EXTERNNAME-poster; HotXLS bevarer disse mapper under filens læse-/skrivecyklusser og sikrer, at eksterne områdereferencer overlever ændringsløkker

Eksterne XLSX-relationer

Ved OOXML-projektmapper styres tilknytning af eksterne referencer via relationsdele; se de understøttende grænsefladedetaljer nedenfor

• Klassen TXLSXExternalLinks — API til at vise og opdatere eksterne regnearksreferencer
• Grænsefladen IXLSWorkbook — Projektmappe-egenskaber på øverste niveau
• Egenskaben IXLSRange.Formula — Læs og skriv formler på tværs af projektmapper