مراجع کتاب کار خارجی

نمای کلی

مدل‌های صفحه گستر اغلب با استفاده از فرمول‌های مرجع متقاطع داده‌ها را از کتاب‌های کار ثانویه استخراج می‌کنند؛ 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 فقط نگاشت نام در سطح Facade را مدیریت می‌کنند، در حالی که ExternalWorkspace.Remove و Clear خود ثبت‌های فضای کاری را لغو می‌کنند. فراخوان‌های چندموتوره می‌توانند هر آداپتور Classic، XLSX یا ODS را مستقیماً به ExternalWorkspace بیفزایند

• نرمال‌سازی هویت لغوی و بدون حساسیت به بزرگی/کوچکی حروف است، مسیرها و پسوندها را حفظ می‌کند، هدف‌های نسبی را نسبت به هویت مبدأ مالک حل می‌کند، قطعه‌های نقطه‌دار را فرومی‌پاشد و هیچ دسترسی به فایل‌سیستم یا شبکه انجام نمی‌دهد
• هویت‌های دقیق و نام‌های مستعار صریح نخست حل می‌شوند؛ جست‌وجوی فقط-نام‌پایه تنها زمانی موفق می‌شود که دقیقاً یک ثبت متصل مطابقت داشته باشد، در غیر این صورت Resolve مقدار xlswrsConflict را برمی‌گرداند
• Add برخوردهای کلید دقیق، نام مستعار و کتاب کار تکراری را رد می‌کند؛ مسیرهای کامل متمایز و پسوندهای متمایز می‌توانند هم‌زمان وجود داشته باشند
• Remove و Clear ثبت‌ها را لغو می‌کنند و تخریب مستقیم یک هدف Classic یا XLSX آداپتور آن را قطع می‌کند و پیش از آزادشدن مدل منتظر خواننده‌های فعال می‌ماند
• کاربرگ‌های خارجی پیش از Fallback مکانی با اندیس یک-مبنا، با نام اعلام‌شده حل می‌شوند؛ بنابراین ترتیب کاربرگ‌های کتاب کار هدف لازم نیست با دایرکتوری پیوند مبدأ مطابقت داشته باشد
• ارزیاب فرمول نخست کتاب کار زنده حل‌شده را می‌خواند و سپس به Fallback روی حافظه پنهان نوع‌دار فایل میزبان متوسل می‌شود؛ میزبان‌های Classic XLS مقادیر خلوت XCT و CRN را رمزگشایی می‌کنند و میزبان‌های XLSX از حافظه پنهان پیوند خارجی که مدل بسته از قبل در اختیار دارد استفاده می‌کنند
• OnLoadWorkbook یک درخواست منبع کنترل‌شده و اختیاری است؛ مقدار پیش‌فرض آن nil است، بنابراین بازمحاسبه همچنان هیچ دسترسی به فایل‌سیستم یا شبکه انجام نمی‌دهد مگر آنکه کد برنامه چنین سیاستی را صریحاً فراهم کند
• هر هویت نرمال‌شده تا ResetLoadAttempts حداکثر یک‌بار بارگذار را فرامی‌خواند؛ درخواست‌های هم‌زمان سطح بالا نتیجه در جریان را به اشتراک می‌گذارند — از جمله پیامدهای نوع‌دار نیافت‌شده و خطا — به‌جای آنکه همان منبع را بارها باز کنند
• MaxLoadDepth به‌طور پیش‌فرض 16 و MaxWorkbookCount به‌طور پیش‌فرض 64 است؛ ورود مجدد با هویت یکسان، وابستگی‌های تودرتو به هویتی که از قبل در جریان است، اتمام عمق و اتمام شمار کتاب کار، تشخیص‌های نوع‌دار برمی‌گردانند و در چرخه بارگذاری مسدود نمی‌شوند
• IRIهای منبع خارجی ODF هویت‌های لغوی کامل می‌مانند، شامل schemeهای 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) تا تشخیص‌ها بتوانند خواندن زنده را از Fallback روی حافظه پنهان بازشناسند

آداپتور 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 شمار بررسی‌های دقیق مستطیل را برای راستی‌آزمایی کارایی در معرض می‌گذارند
• استخراج فرمول تحت مجوزهای خواندن کتاب کار انجام می‌شود و فقط اشیای فرمول عینی‌سازی‌شده را اسکن می‌کند؛ در نتیجه ذخیره‌سازی فشرده مقادیر فشرده می‌ماند و ساخت گراف نسل‌های کتاب کار را تغییر نمی‌دهد

بازمحاسبه زمان‌بندی‌شده

Recalculate گراف مشترک را نگه می‌دارد و فقط زمانی بازسازی‌اش می‌کند که ثبت فضای کاری یا نسل وابستگی فرمول یک کتاب کار تغییر کند؛ نسل‌های مقدار آغازگر یک پاس کهنگی تازه هستند و کهنگی از طریق یال‌های وابسته میان‌کتابی منتشر می‌شود

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

• مؤلفه‌های قویاً همبند روی سلول‌های فرمول محاسبه می‌شوند؛ بنابراین کتاب‌های کار می‌توانند در هر دو جهت به هم پیوند بخورند و در عین حال بدون چرخه بمانند، تا زمانی که مسیرهای وابستگی در سطح سلول حلقه نسازند
• اعضای واقعی چرخه و نسل‌های کهنه‌ای که توسط چرخه مسدود شده‌اند باطل می‌شوند و از ترتیب توپولوژیک کنار می‌روند تا مقادیر کهنه حافظه پنهان به‌عنوان نتیجه موفق عرضه نشوند
• ارجاع‌های فرّار یا حل‌نشده به‌صورت ایستا، رفتار محافظه‌کارانه کهنگیِ لازم برای درستی را تحمیل می‌کنند، در حالی که گراف‌های پایدار از کار وابستگی پیشین دوباره استفاده می‌کنند
• خواندن‌های خارجی درون یک پاس از حافظه پنهان دقیق نمونه کتاب کار، کاربرگ، سطر و ستون استفاده می‌کنند؛ فرمول زمان‌بندی‌شده پیش از ارزیابی، محدوده خروجی خود را باطل می‌کند تا وابسته‌های بعدی مقدار تازه را ببینند
• حافظه پنهان محلیِ پاس هرگز اختیار منبع نمی‌دهد؛ کتاب‌های کار ثبت‌شده و بارگذار اختیاریِ کنترل‌شده توسط فراخوان، تنها منابع حل زنده می‌مانند و پس از آن‌ها حافظه‌های پنهان نوع‌دار فایل و #REF! قرار دارند
• TXLSWorkspaceRecalcResult در معرض می‌گذارد که آیا گراف بازسازی شده است، به‌همراه شمار کهنه‌ها، ارزیابی‌شده‌ها، باطل‌شده‌ها، چرخه‌ها، مسدودشده‌ها، Cache hit و Cache miss
• وضعیت، موفقیت، آداپتورهای پشتیبانی‌نشده، کتاب‌های کار قطع‌شده، ارجاع‌های حلقوی، خطاهای محاسبه و تغییر فضای کاری در طول پاس را از هم تفکیک می‌کند
• فراخوانی‌های 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 از جایگاه‌های عددی کتاب کارِ آگاه از نحو و به ترتیب سند روابط استفاده می‌کند و فقط بخش‌های external-link کتاب کار را می‌پذیرد؛ DDE، OLE، جایگاه‌های حل‌نشده، ارجاع‌های جدول و متن داخل کروشه در رشته‌ها کنار گذاشته می‌شوند
• همه جایگزینی‌ها پیش از نخستین تغییر آماده و به‌صورت یک عملیات نوشتن واحد اعمال می‌شوند؛ فراخوانی دوم idempotent است
• متن نام، دامنه کتاب کار یا کاربرگ، نمایانی، کامنت‌ها، پرچم‌های ماکرو و داخلی، ویژگی‌های ناشناخته XLSX و دایرکتوری پیوند خارجی پس از تبدیل و رفت‌وبرگشت در دسترس می‌مانند
• تعریف‌های بدشکل و پشتیبانی‌نشده تا جای ممکن بایت‌محفوظ یا متن‌محفوظ می‌مانند و به‌جای حدس زدن، تشخیص xlsDiagnosticDefinedNameConversionSkipped می‌افزایند
• فرمول‌های وابسته به مقدار خطای متناظر Excel بازمحاسبه می‌شوند، در حالی که نتیجه معتبر حافظه پنهان برای یک فرمول خارجی مستقیم معمولی، حتی اگر کتاب کار زنده بعداً قطع شود، همچنان در دسترس می‌ماند
• این عملیات مختص Excel است و معناشناسی فرمول-نام OpenDocument را بازتفسیر نمی‌کند

مراجع خارجی XLS کلاسیک

در کتاب‌های کار XLS کلاسیک، پیوندهای خارجی در بلک دایرکتوری سراسری با استفاده از رکوردهای EXTERNALBOOK و EXTERNNAME ذخیره می‌شوند؛ HotXLS این دایرکتوری‌ها را در طول چرخه‌های خواندن/نوشتن فایل حفظ می‌کند و تضمین می‌کند که مراجع بازه دوردست در حلقه‌های تغییر دوام می‌آورند

روابط خارجی XLSX

برای کتاب‌های کار OOXML، نگاشت پیوند خارجی از طریق بخش‌های رابطه مدیریت می‌شود؛ جزئیات رابط‌های پشتیبان زیر را بررسی کنید

• کلاس TXLSXExternalLinks — API برای فهرست‌کردن و به‌روزرسانی پیوندهای خارجی صفحه گستر
• رابط IXLSWorkbook — ویژگی‌های سطح بالای کتاب کار
• ویژگی IXLSRange.Formula — خواندن و نوشتن فرمول‌های میان‌کتابی