Zewnętrzne odwołania do skoroszytu

Przegląd

Modele arkuszy kalkulacyjnych często pobierają dane z pomocniczych skoroszytów przy użyciu formuł odwołań wzajemnych; HotXLS obsługuje analizowanie, zapisywanie i zachowywanie zewnętrznych odwołań do skoroszytów zarówno w dokumentach BIFF8 (klasyczny XLS), jak i OpenXML (XLSX)

Obszar roboczy żywych skoroszytów

TXLSWorkbookWorkspace w lxWorkbookWorkspace to współdzielony rdzeń tożsamości i rejestracji żywych skoroszytów zewnętrznych; zarówno TXLSWorkbook, jak i TXLSXWorkbook udostępniają CreateWorkspaceWorkbook i posiadają ExternalWorkspace używany przez ich ewaluatory formuł, natomiast skoroszyt ODS otwarty przez TXLSXWorkbook zgłasza rodzaj silnika OpenDocument przez ten sam 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;

Klasyczne skoroszyty używają tych samych metod zgodności z celami TXLSWorkbook; RegisterExternalWorkbook i UnregisterExternalWorkbook zarządzają wyłącznie mapowaniem nazw na poziomie fasady, natomiast ExternalWorkspace.Remove i Clear cofają same rejestracje obszaru roboczego. Wywołujący z różnych silników dodają dowolny adapter Classic, XLSX lub ODS bezpośrednio do ExternalWorkspace

• Normalizacja tożsamości jest leksykalna i ignoruje wielkość liter, zachowuje ścieżki i rozszerzenia, rozwiązuje cele względne względem źródłowej tożsamości właściciela, redukuje segmenty kropek i nie wykonuje żadnego dostępu do systemu plików ani sieci
• Dokładne tożsamości i jawne aliasy są rozwiązywane w pierwszej kolejności; wyszukiwanie wyłącznie po nazwie podstawowej pliku kończy się sukcesem tylko wtedy, gdy pasuje dokładnie jedna połączona rejestracja, w przeciwnym razie Resolve zwraca xlswrsConflict
• Add odrzuca kolizje dokładnego klucza, aliasu i zduplikowanego skoroszytu; różne pełne ścieżki i różne rozszerzenia mogą współistnieć
• Remove i Clear cofają rejestracje, natomiast bezpośrednie zniszczenie celu Classic lub XLSX rozłącza jego adapter i czeka na aktywnych czytelników, zanim model zostanie zwolniony
• Zewnętrzne arkusze są rozwiązywane najpierw po zadeklarowanej nazwie, a dopiero potem według pozycji liczonej od jedynki, więc kolejność arkuszy skoroszytu docelowego nie musi odpowiadać katalogowi łączy źródłowych
• Ewaluator formuł najpierw czyta rozwiązany żywy skoroszyt, a dopiero potem sięga do typowanej pamięci podręcznej pliku hosta; hosty Classic XLS dekodują rzadkie wartości XCT i CRN, a hosty XLSX używają pamięci podręcznej łączy zewnętrznych już utrzymywanej przez model pakietu
• OnLoadWorkbook to opcjonalne, kontrolowane żądanie zasobu; jego wartością domyślną jest nil, więc przeliczanie nadal nie wykonuje żadnego dostępu do systemu plików ani sieci, chyba że kod aplikacji jawnie dostarczy taką politykę
• Każda znormalizowana tożsamość wywołuje loader co najwyżej raz do momentu ResetLoadAttempts; równoczesne żądania najwyższego poziomu współdzielą wynik będący w toku, łącznie z typowanymi wynikami „nie znaleziono" i błędami, zamiast otwierać ten sam zasób wielokrotnie
• MaxLoadDepth ma domyślnie wartość 16, a MaxWorkbookCount — 64; ponowne wejście dla tej samej tożsamości, zagnieżdżone zależności od tożsamości już przetwarzanej, wyczerpanie głębokości i wyczerpanie licznika skoroszytów zwracają typowaną diagnostykę bez blokowania w cyklu ładowania
• IRI zewnętrznych źródeł ODF pozostają pełnymi tożsamościami leksykalnymi, łącznie ze schematami URI i znakami w cudzysłowach, ale nigdy nie autoryzują niejawnego dostępu do plików ani sieci
• Konflikt tożsamości pozostaje jako #REF!, więc nieaktualne dane z pamięci podręcznej nie mogą ukryć niejednoznacznego routingu; brakująca komórka w pamięci podręcznej jest wartością pustą tylko wtedy, gdy plik deklaruje prawidłową pamięć podręczną dla tego arkusza

Resolve wykonuje wyszukiwanie w rejestrze, a następnie opcjonalne kontrolowane ładowanie; jego wynikiem jest TXLSWorkspaceResolveStatus (xlswrsResolved, xlswrsNotFound, xlswrsConflict, xlswrsDisconnected, xlswrsLoadNotFound, xlswrsLoadLimit, xlswrsLoadLoop lub xlswrsLoadError), a ResolveWithLoader zwraca dodatkowo TXLSWorkspaceLoadDiagnostic łączący TXLSWorkspaceLoadDiagnosticCode z TXLSWorkspaceLoadResponseStatus (xlswlrsNotFound, xlswlrsResolved, xlswlrsError), co pozwala odróżnić wyniki: nie znaleziono, błąd loadera, wynik rozłączony, limit głębokości lub liczby skoroszytów, ponowne wejście dla tożsamości, równoległa zależność i konflikt rejestracji. Wywołanie zwrotne loadera otrzymuje TXLSWorkspaceLoadRequest (tożsamość, głębokość, liczba zarejestrowanych, limity) i odpowiada TXLSWorkspaceLoadResponse

Recalculate zgłasza TXLSWorkspaceRecalcStatus, opcjonalnie z rozbiciem w TXLSWorkspaceRecalcResult, a ewaluator zapisuje pochodzenie każdej komórki jako TXLSWorkspaceRuntimeLookup (xlswrlInactive, xlswrlResolved, xlswrlFallbackCache lub xlswrlError), dzięki czemu diagnostyka odróżni odczyt żywy od sięgnięcia do pamięci podręcznej

Adapter IXLSWorkspaceWorkbook udostępnia EngineKind (typ TXLSWorkspaceEngineKind: xlsweClassic, xlsweOpenXml lub xlsweOpenDocument), SourceIdentity, InstanceIdentity i Generation, sprawdza żywotność przez IsConnected, odczytuje pojedynczą komórkę przez TryGetCellValue (zwracający typowany TXLSWorkspaceCellStatus: wartość, brak, nieprawidłowe odwołanie, rozłączony lub błąd, plus flagę wyjścia poza używany zakres), odświeża model przez Recalculate i odłącza się od modelu skoroszytu przez Disconnect

Rejestr dodaje AddAlias dla dodatkowych nazw powiązanych z jedną zarejestrowaną tożsamością, TryResolve jako wariant wyszukiwania bez wyjątków oraz BaseNameMatchCount do podglądu, ile połączonych rejestracji dzieli nazwę podstawową, zanim wybierze się jednoznaczny cel

Graf zależności między skoroszytami

BuildDependencyGraph tworzy migawkę każdego zarejestrowanego adaptera skoroszytu i wyodrębnia węzły formuł z modeli Classic XLS, XLSX i ODS do jednego TXLSWorkspaceDepGraph; metoda zwraca False i żadnego częściowego grafu, gdy dowolny zarejestrowany adapter nie potrafi dostarczyć metadanych zależności

• Każdy węzeł formuły zachowuje kanoniczną tożsamość skoroszytu, nazwę arkusza i pozycję arkusza liczoną od jedynki, pozycję komórki liczoną od zera, prostokąt wyjściowy tablicy, zmienność oraz stan nierozwiązanych odwołań
• Odwołania do komórek i prostokątnych zakresów zachowują kanoniczne tożsamości skoroszytu i arkusza docelowego; odwołania do całych kolumn, całych wierszy i całych arkuszy pozostają jednym przedziałem zamiast rozszerzać się do milionów komórek
• Lokalne nazwy zdefiniowane pozostają odpytywalne jako zależności symboliczne, a gdy definicję da się rozwiązać statycznie, rozszerzają się również do konkretnych zależności komórkowych lub zakresowych
• Zewnętrzne nazwy zdefiniowane zachowują slot łącza zewnętrznego, zadeklarowaną nazwę, opcjonalny zakres arkusza i kanoniczną tożsamość celu, bez traktowania metadanych DDE, OLE ani funkcji użytkownika jako nazw skoroszytów
• FindDependentsOfCell i budowanie krawędzi grafu używają drzew przedziałów wierszy z przycinaniem po maksymalnym końcu; LastRangeCandidateChecks i EdgeCandidateChecks ujawniają liczbę dokładnych sprawdzeń prostokątów dla weryfikacji wydajności
• Wyodrębnianie formuł działa w ramach dzierżaw odczytu skoroszytu i skanuje wyłącznie zmaterializowane obiekty formuł, więc spakowany magazyn wartości pozostaje spakowany, a tworzenie grafu nie modyfikuje generacji skoroszytu

Zaplanowane przeliczanie

Recalculate zachowuje współdzielony graf i przebudowuje go tylko wtedy, gdy zmienia się rejestracja obszaru roboczego albo generacja zależności formuł skoroszytu; generacje wartości inicjują nowy przebieg przetwarzania nieświeżych komórek, a nieświeżość propaguje się przez krawędzie zależności między skoroszytami

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

• Silnie spójne składowe są wyliczane na komórkach z formułami, więc skoroszyty mogą łączyć się w obu kierunkach i pozostawać acykliczne, dopóki ich komórkowe ścieżki zależności nie tworzą pętli
• Prawdziwe elementy cykli oraz nieświeży potomkowie zablokowani przez cykl są unieważniani i wyłączani z porządku topologicznego, dzięki czemu nieaktualne wartości z pamięci podręcznej nie zostaną pokazane jako poprawne wyniki
• Odwołania zmienne albo statycznie nierozwiązywalne wymuszają konserwatywne zachowanie dla nieświeżych danych wymagane dla poprawności, a stabilne grafy ponownie używają wcześniejszej pracy nad zależnościami
• Odczyty zewnętrzne w ramach przebiegu używają dokładnej pamięci podręcznej instancji skoroszytu, arkusza, wiersza i kolumny; zaplanowana formuła unieważnia swój zakres wyjściowy przed obliczeniem, więc późniejsi zależni widzą nową wartość
• Pamięć podręczna lokalna dla przebiegu nigdy nie nadaje uprawnień do zasobów; zarejestrowane skoroszyty i opcjonalny loader kontrolowany przez wywołującego pozostają jedynymi żywymi źródłami rozwiązywania, a za nimi następują typowane pamięci podręczne plików i #REF!
• TXLSWorkspaceRecalcResult ujawnia, czy graf został przebudowany, oraz liczniki: nieświeżych, obliczonych, unieważnionych, cykli, zablokowanych, trafień i chybień w pamięci podręcznej
• Status rozróżnia sukces, nieobsługiwane adaptery, rozłączone skoroszyty, odwołania cykliczne, błędy obliczeń i modyfikację obszaru roboczego w trakcie przebiegu
• Wywołania Recalculate na tym samym obszarze roboczym są serializowane, więc dwie sesje obliczeń nigdy nie modyfikują współdzielonego grafu ani pamięci podręcznych skoroszytów równocześnie
• Remove lub Clear mogą działać, gdy przebieg jest aktywny; przebieg trzyma bezpieczne migawki adapterów i zwraca xlswrcWorkspaceChanged zamiast dereferencjonować usuniętą rejestrację
• Niszczenie obszaru roboczego czeka na zakończenie aktywnego przebiegu, a zniszczenie zarejestrowanego skoroszytu rozłącza jego adapter i sprawia, że późniejsze rozwiązywanie kończy się bezpiecznym błędem
• Błędy loadera i wyniki „nie znaleziono" pozostają w pamięci podręcznej raz na znormalizowaną tożsamość do momentu ResetLoadAttempts, a nieudane obliczenie zachowuje lokalny stan nieświeżości na potrzeby jawnego ponowienia
• Przechowany graf sprawia, że kolejny przebieg bez zmian w modelu kosztuje proporcjonalnie do liczby zarejestrowanych skoroszytów, a nie do liczby formuł; nierekurencyjna analiza składowych i zwięzłe krawędzie zakresów utrzymują głębokie i szerokie modele w granicach wyznaczonych przez zmaterializowane metadane formuł

Odłączanie zewnętrznych nazw zdefiniowanych

ConvertExternalDefinedNamesToRefErrors zapewnia tę samą publiczną operację na TXLSWorkbook i TXLSXWorkbook; zwraca liczbę definicji o zakresie skoroszytu i zakresie arkusza zastąpionych natywnym #REF!

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

• Wybór w klasycznym XLS używa skompilowanych tokenów odwołań BIFF i tożsamości skoroszytu pomocniczego XTI, więc trójwymiarowe odwołania w obrębie tego samego skoroszytu i niepewne strumienie tokenów pozostają niezmienione
• Wybór w XLSX używa numerycznych slotów skoroszytów świadomych składni w kolejności dokumentu relacji i akceptuje wyłącznie części łączy zewnętrznych skoroszytu, wykluczając DDE, OLE, nierozwiązane sloty, odwołania do tabel i tekst w nawiasach wewnątrz ciągów
• Wszystkie zamiany są przygotowywane przed pierwszą modyfikacją i zatwierdzane jako jedna operacja zapisu; drugie wywołanie jest idempotentne
• Tekst nazwy, zakres skoroszytu lub arkusza, widoczność, komentarze, flagi makr i flagi nazw wbudowanych, nieznane atrybuty XLSX oraz katalog łączy zewnętrznych pozostają dostępne po konwersji i przebiegu zapisu
• Wadliwe i nieobsługiwane definicje pozostają — o ile to możliwe — zachowane bajt po bajcie lub jako tekst i dodają diagnostykę xlsDiagnosticDefinedNameConversionSkipped zamiast być zgadywane
• Formuły zależne przeliczają się do odpowiedniej wartości błędu Excela, natomiast prawidłowy wynik z pamięci podręcznej dla zwykłej bezpośredniej formuły zewnętrznej pozostaje dostępny, jeśli jej żywy skoroszyt rozłączy się później
• Operacja jest specyficzna dla Excela i nie reinterpretuje semantyki formuł nazw OpenDocument

Klasyczne odwołania zewnętrzne XLS

W klasycznych skoroszytach XLS linki zewnętrzne są przechowywane w globalnym bloku katalogu przy użyciu rekordów EXTERNALBOOK i EXTERNNAME; HotXLS utrzymuje te katalogi podczas cykli odczytu/zapisu plików, zapewniając, że zdalne odwołania do zakresów przetrwają pętle modyfikacji

Relacje zewnętrzne XLSX

W przypadku skoroszytów OOXML mapowanie linków zewnętrznych jest zarządzane poprzez części relacji; sprawdź szczegóły obsługiwanego interfejsu poniżej

• Klasa TXLSXExternalLinks — API do listowania i aktualizowania linków zewnętrznych arkusza kalkulacyjnego
• Interfejs IXLSWorkbook — Właściwości skoroszytu najwyższego poziomu
• Właściwość IXLSRange.Formula — Odczyt i zapis formuł między skoroszytami