Зовнішні посилання на книги

Огляд

Табличні моделі часто отримують дані з вторинних книг за допомогою перехресних формул посилань; HotXLS підтримує розбір, запис та збереження зовнішніх посилань на книги в документах BIFF8 (класичний XLS) та OpenXML (XLSX)

Робочий простір активних книг

TXLSWorkbookWorkspace у lxWorkbookWorkspace — це спільне ядро ідентичності та реєстрації для активних зовнішніх книг; і TXLSWorkbook, і TXLSXWorkbook відкривають CreateWorkspaceWorkbook та володіють ExternalWorkspace, яку використовують їхні оцінювачі формул, а книга ODS, відкрита через TXLSXWorkbook, повідомляє вид рушія 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 відкликають самі реєстрації робочого простору. Викликачі з різними рушіями додають будь-який адаптер Classic, XLSX чи ODS безпосередньо до ExternalWorkspace

• Нормалізація ідентичності є лексичною та незалежною від регістру, зберігає шляхи й розширення, розв'язує відносні цілі відносно вихідної ідентичності власника, згортає сегменти «.» і не виконує жодного доступу до файлової системи чи мережі
• Першими розв'язуються точні ідентичності та явні псевдоніми; пошук лише за іменем файлу успішний, тільки коли збігається рівно одна активна реєстрація, інакше Resolve повертає xlswrsConflict
• Add відхиляє колізії за точним ключем, псевдонімом і дублікатом книги; різні повні шляхи та різні розширення можуть співіснувати
• Remove і Clear відкликають реєстрації, а безпосереднє знищення цілі Classic чи XLSX від'єднує її адаптер і чекає активних читачів, перш ніж модель буде звільнено
• Зовнішні аркуші розв'язуються за оголошеним ім'ям перед позиційним резервним варіантом з базою одиниця, тому порядок аркушів цільової книги не мусить збігатися з каталогом вихідних посилань
• Оцінювач формул спершу читає розв'язану активну книгу, а потім повертається до типізованого кешу файлу-господаря; господарі Classic XLS декодують розріджені значення XCT і CRN, а господарі XLSX використовують кеш зовнішніх посилань, який уже є в моделі пакета
• OnLoadWorkbook — це необов'язковий контрольований запит ресурсу; його типовим значенням є nil, тож перерахування як і раніше не виконує доступу до файлової системи чи мережі, якщо код застосунку явно не надасть таку політику
• Кожна нормалізована ідентичність викликає завантажувач щонайбільше один раз до ResetLoadAttempts; одночасні запити верхнього рівня спільно використовують результат, що вже виконується, включно з типізованими результатами «не знайдено» та помилками, замість того, щоб відкривати той самий ресурс знову і знову
• MaxLoadDepth типово дорівнює 16, а MaxWorkbookCount — 64; повторний вхід з тією самою ідентичністю, вкладені залежності від ідентичності, що вже обробляється, вичерпання глибини та вичерпання кількості книг повертають типізовані діагностики без блокування в циклі завантаження
• IRI зовнішніх джерел ODF залишаються повними лексичними ідентичностями, включно зі схемами URI та символами в лапках, але ніколи не дозволяють неявний доступ до файлів чи мережі
• Конфлікт ідентичностей залишається #REF!, щоб застарілі кешовані дані не могли приховати неоднозначну маршрутизацію; відсутня кешована комірка є порожнім значенням лише тоді, коли файл оголошує чинний кеш для цього аркуша

Resolve виконує пошук серед зареєстрованих, а потім необов'язкове контрольоване завантаження; її результат — це TXLSWorkspaceResolveStatus (xlswrsResolved, xlswrsNotFound, xlswrsConflict, xlswrsDisconnected, xlswrsLoadNotFound, xlswrsLoadLimit, xlswrsLoadLoop або xlswrsLoadError), а ResolveWithLoader додатково повертає TXLSWorkspaceLoadDiagnostic, що поєднує TXLSWorkspaceLoadDiagnosticCode з TXLSWorkspaceLoadResponseStatus (xlswlrsNotFound, xlswlrsResolved, xlswlrsError), щоб розрізняти результати: не знайдено, помилка завантажувача, від'єднаний результат, ліміт глибини чи кількості книг, повторний вхід за ідентичністю, паралельна залежність і конфлікт реєстрації. Зворотний виклик завантажувача отримує 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 як варіант пошуку без винятків і BaseNameMatchCount, щоб заздалегідь дізнатися, скільки активних реєстрацій мають те саме ім'я файлу, перш ніж обирати однозначну ціль

Граф залежностей між книгами

BuildDependencyGraph робить знімок кожного зареєстрованого адаптера книги та витягує вузли формул з моделей Classic XLS, XLSX і ODS в один TXLSWorkspaceDepGraph; метод повертає False і не повертає часткового графа, якщо будь-який зареєстрований адаптер не може надати метадані залежностей

• Кожен вузол формули зберігає канонічну ідентичність книги, ім'я та позицію аркуша з базою одиниця, позицію комірки з нульовою базою, прямокутник виводу масиву, волатильність і стан нерозв'язаних посилань
• Посилання на комірки та прямокутні діапазони зберігають канонічні ідентичності цільової книги й аркуша; посилання на цілі стовпці, рядки та весь аркуш залишаються одним інтервалом, а не розгортаються в мільйони комірок
• Локальні іменовані діапазони залишаються доступними для запитів як символьні залежності, а також розгортаються у свої конкретні коміркові чи діапазонні залежності, якщо визначення можна розв'язати статично
• Зовнішні іменовані діапазони зберігають слот зовнішнього посилання, оголошене ім'я, необов'язкову область аркуша та канонічну ідентичність цілі, не трактуючи метадані DDE, OLE чи користувацьких функцій як імена книг
• FindDependentsOfCell і побудова ребер графа використовують дерева рядкових інтервалів з відсіканням за максимальним кінцем; LastRangeCandidateChecks і EdgeCandidateChecks відкривають кількість точних перевірок прямокутників для верифікації продуктивності
• Витяг формул виконується в межах виділених читань книги (lease) і сканує лише матеріалізовані об'єкти формул, тож упаковане сховище значень залишається упакованим, а створення графа не змінює покоління книги

Заплановане перерахування

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 замість розіменування вилученої реєстрації
• Знищення робочого простору чекає завершення його активного проходу, а знищення зареєстрованої книги від'єднує її адаптер і робить подальше розв'язання безпечним відмовом
• Відмови завантажувача та результати «не знайдено» кешуються один раз на нормалізовану ідентичність до ResetLoadAttempts, а невдале обчислення зберігає локальний «брудний» стан для явного повтору
• Утримуваний граф робить незмінений повторний прохід пропорційним до кількості зареєстрованих книг, а не до кількості формул; нерекурсивний аналіз компонентів і компактні ребра діапазонів утримують глибокі й широкі моделі в межах метаданих матеріалізованих формул

Від'єднання зовнішніх іменованих діапазонів

ConvertExternalDefinedNamesToRefErrors надає ту саму публічну операцію на TXLSWorkbook і TXLSXWorkbook; вона повертає кількість визначень рівня книги та рівня аркуша, замінених рідним #REF!

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

• Вибір у Classic XLS використовує скомпільовані BIFF-токени посилань та ідентичність допоміжної книги XTI, тож тривимірні посилання в межах однієї книги і невизначені потоки токенів залишаються без змін
• Вибір у XLSX використовує синтаксично обізнані числові слоти книг у порядку документів зв'язків і приймає лише частини зовнішніх посилань книг, виключаючи DDE, OLE, нерозв'язані слоти, посилання на таблиці та текст у дужках усередині рядків
• Усі заміни готуються до першої мутації та застосовуються однією операцією запису; повторний виклик є ідемпотентним
• Текст імені, область книги чи аркуша, видимість, коментарі, прапорці макросів та вбудованих імен, невідомі атрибути XLSX і каталог зовнішніх посилань залишаються доступними після перетворення та Roundtrip
• Некоректні та непідтримувані визначення зберігаються побайтово чи текстово, наскільки можливо, і додають діагностику xlsDiagnosticDefinedNameConversionSkipped замість здогадок
• Залежні формули перераховуються до відповідного значення помилки Excel, тоді як чинний кешований результат для звичайної прямої зовнішньої формули залишається доступним, якщо її активна книга згодом від'єднається
• Операція специфічна для Excel і не переінтерпретує семантику імен-формул OpenDocument

Зовнішні посилання класичного XLS

У класичних книгах XLS зовнішні посилання зберігаються в глобальному блоці каталогу за допомогою записів EXTERNALBOOK та EXTERNNAME; HotXLS підтримує ці каталоги під час циклів читання/запису файлів, забезпечуючи збереження віддалених посилань на діапазони після модифікацій

Зовнішні зв'язки XLSX

Для книг OOXML відображення зовнішніх посилань керується через частини зв'язків; перевірте деталі підтримуючого інтерфейсу нижче

• Клас TXLSXExternalLinks — API для переліку та оновлення зовнішніх посилань таблиці
• Інтерфейс IXLSWorkbook — Властивості книги верхнього рівня
• Властивість IXLSRange.Formula — Читання та запис формул між книгами