Dokumentasi HotXLS

Referensi Buku Kerja Eksternal

Ringkasan

Model lembar kerja sering mengambil data dari buku kerja sekunder menggunakan rumus referensi silang; HotXLS mendukung penguraian, penulisan, dan pelestarian referensi buku kerja eksternal baik dalam dokumen BIFF8 (XLS klasik) maupun OpenXML (XLSX)

Workspace buku kerja live

TXLSWorkbookWorkspace di lxWorkbookWorkspace adalah inti identitas dan registrasi bersama untuk buku kerja eksternal yang live; TXLSWorkbook maupun TXLSXWorkbook mengekspos CreateWorkspaceWorkbook dan memiliki ExternalWorkspace yang dipakai oleh evaluator rumusnya, sementara buku kerja ODS yang dibuka lewat TXLSXWorkbook melaporkan jenis engine OpenDocument melalui adapter yang sama

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;

Buku kerja klasik memakai method kompatibilitas yang sama dengan target TXLSWorkbook; RegisterExternalWorkbook dan UnregisterExternalWorkbook hanya mengelola pemetaan nama di level facade, sedangkan ExternalWorkspace.Remove dan Clear mencabut registrasi workspace-nya sendiri. Caller lintas engine bisa menambahkan adapter Classic, XLSX, atau ODS apa pun langsung ke ExternalWorkspace

  • Normalisasi identitas bersifat leksikal dan tidak peka huruf besar-kecil, mempertahankan path dan ekstensi, menyelesaikan target relatif terhadap identitas sumber pemiliknya, merapatkan dot segment, dan tidak melakukan akses file system maupun jaringan
  • Identitas persis dan alias eksplisit di-resolve lebih dulu; lookup berbasis basename saja hanya berhasil bila tepat satu registrasi yang terhubung cocok, selain itu Resolve mengembalikan xlswrsConflict
  • Add menolak tabrakan exact-key, alias, dan buku kerja duplikat; path lengkap yang berbeda dan ekstensi yang berbeda bisa hidup berdampingan
  • Remove dan Clear mencabut registrasi, sedangkan penghancuran langsung target Classic atau XLSX memutus adapter-nya dan menunggu pembaca aktif selesai sebelum model dilepas
  • Lembar kerja eksternal di-resolve berdasarkan nama yang dideklarasikan sebelum Fallback posisi one-based, sehingga urutan lembar kerja buku kerja target tidak harus cocok dengan direktori tautan sumber
  • Evaluator rumus membaca buku kerja live yang berhasil di-resolve lebih dulu, lalu Fallback ke cache bertipe milik file host; host Classic XLS mendekode nilai XCT dan CRN yang sparse, sedangkan host XLSX memakai cache external-link yang sudah dipegang oleh model paket
  • OnLoadWorkbook adalah permintaan resource terkontrol yang bersifat opsional; nilai defaultnya nil, jadi perhitungan ulang tetap tidak melakukan akses file system atau jaringan kecuali kode aplikasi secara eksplisit menyediakan policy tersebut
  • Setiap identitas ternormalisasi memanggil loader paling banyak sekali sampai ResetLoadAttempts; permintaan top-level yang terjadi bersamaan berbagi hasil in-flight, termasuk outcome not-found dan error yang bertipe, alih-alih membuka resource yang sama berulang kali
  • MaxLoadDepth default-nya 16 dan MaxWorkbookCount default-nya 64; re-entry dengan identitas sama, dependensi bersarang pada identitas yang sedang in-flight, depth yang habis, dan jumlah buku kerja yang melampaui batas mengembalikan diagnostik bertipe tanpa memblokir siklus load
  • IRI sumber eksternal ODF tetap berupa identitas leksikal yang lengkap, termasuk skema URI dan karakter yang di-quote, tetapi tidak pernah mengizinkan akses file atau jaringan secara implisit
  • Konflik identitas tetap menghasilkan #REF! agar data cache basi tidak dapat menyembunyikan routing yang ambigu; sel cache yang absen baru dianggap nilai kosong bila file mendeklarasikan cache yang valid untuk lembar kerja tersebut

Resolve melakukan lookup pada registrasi lalu load terkontrol yang opsional; hasilnya berupa TXLSWorkspaceResolveStatus (xlswrsResolved, xlswrsNotFound, xlswrsConflict, xlswrsDisconnected, xlswrsLoadNotFound, xlswrsLoadLimit, xlswrsLoadLoop, atau xlswrsLoadError), dan ResolveWithLoader juga mengembalikan TXLSWorkspaceLoadDiagnostic yang memasangkan TXLSWorkspaceLoadDiagnosticCode dengan TXLSWorkspaceLoadResponseStatus (xlswlrsNotFound, xlswlrsResolved, xlswlrsError) untuk membedakan outcome tidak ditemukan, error loader, hasil terputus, batas depth atau jumlah buku kerja, re-entry identitas, dependensi konkuren, dan konflik registrasi. Callback loader menerima TXLSWorkspaceLoadRequest (identitas, depth, jumlah registrasi, limit) dan menjawab dengan TXLSWorkspaceLoadResponse

Recalculate melaporkan TXLSWorkspaceRecalcStatus, opsional dengan rincian TXLSWorkspaceRecalcResult, dan evaluator mencatat provenance per sel sebagai TXLSWorkspaceRuntimeLookup (xlswrlInactive, xlswrlResolved, xlswrlFallbackCache, atau xlswrlError) sehingga diagnostik bisa membedakan pembacaan live dari Fallback cache

Adapter IXLSWorkspaceWorkbook mengekspos EngineKind (tipe TXLSWorkspaceEngineKind: xlsweClassic, xlsweOpenXml, atau xlsweOpenDocument), SourceIdentity, InstanceIdentity, dan Generation, menguji keaktifan dengan IsConnected, membaca satu sel melalui TryGetCellValue (mengembalikan TXLSWorkspaceCellStatus bertipe berupa nilai, missing, referensi tidak valid, terputus, atau error ditambah flag di luar used range), menyegarkan model dengan Recalculate, dan melepaskan diri dari model buku kerja dengan Disconnect

Registry menambahkan AddAlias untuk nama tambahan yang terikat pada satu identitas terdaftar, TryResolve sebagai varian lookup tanpa exception, dan BaseNameMatchCount untuk melihat dulu berapa banyak registrasi yang terhubung berbagi sebuah basename sebelum memilih target yang tidak ambigu

Graf dependensi lintas buku kerja

BuildDependencyGraph mengambil snapshot semua adapter buku kerja yang terdaftar dan mengekstrak node rumus dari model Classic XLS, XLSX, dan ODS ke dalam satu TXLSWorkspaceDepGraph; method ini mengembalikan False tanpa graf parsial bila ada adapter terdaftar yang tidak bisa menyediakan metadata dependensi

  • Setiap node rumus menyimpan identitas kanonik buku kerja, nama lembar kerja dan posisi lembar kerja berbasis satu, posisi sel berbasis nol, persegi output array, volatilitas, dan status referensi yang belum ter-resolve
  • Referensi sel dan rentang persegi panjang menyimpan identitas kanonik buku kerja target dan lembar kerja; referensi satu kolom penuh, satu baris penuh, dan satu lembar penuh tetap berupa satu interval alih-alih mengembang menjadi jutaan sel
  • Defined name lokal tetap bisa di-query sebagai dependensi simbolik dan juga mengembang ke dependensi sel atau rentang konkretnya bila definisinya bisa di-resolve secara statis
  • Defined name eksternal mempertahankan slot external-link, nama yang dideklarasikan, scope lembar kerja opsional, dan identitas target kanonik, tanpa memperlakukan metadata DDE, OLE, atau user-function sebagai nama buku kerja
  • FindDependentsOfCell dan konstruksi edge graf memakai tree interval baris dengan pruning maximum-end; LastRangeCandidateChecks dan EdgeCandidateChecks mengekspos jumlah pemeriksaan persegi eksak untuk verifikasi performa
  • Ekstraksi rumus berjalan di bawah read lease buku kerja dan hanya memindai objek rumus yang termaterialisasi, sehingga penyimpanan nilai packed tetap packed dan pembuatan graf tidak mengubah generation buku kerja

Perhitungan ulang terjadwal

Recalculate mempertahankan graf bersama dan membangunnya ulang hanya bila registrasi workspace atau generation dependensi-rumus sebuah buku kerja berubah; generation nilai memicu pass dirty baru, dan status dirty merambat melalui edge dependen lintas buku kerja

var
  RecalcInfo: TXLSWorkspaceRecalcResult;
  Status: TXLSWorkspaceRecalcStatus;
begin
  Status := Workspace.Recalculate(RecalcInfo);
  if Status <> xlswrcOk then
    HandleWorkspaceCalculation(Status, RecalcInfo);
end;
  • Strongly connected component dihitung pada sel-sel rumus, sehingga buku kerja boleh saling bertaut dua arah dan tetap acyclic selama jalur dependensi level selnya tidak membentuk loop
  • Anggota cycle yang nyata dan keturunan dirty yang terblokir oleh cycle dibatalkan validitasnya dan dikeluarkan dari urutan topologis, mencegah nilai cache basi disajikan sebagai hasil sukses
  • Referensi volatile atau yang belum ter-resolve secara statis memaksa perilaku dirty konservatif yang dipersyaratkan untuk kebenaran hasil, sementara graf yang stabil memakai ulang pekerjaan dependensi sebelumnya
  • Pembacaan eksternal dalam satu pass memakai cache workbook-instance, lembar kerja, baris, dan kolom yang eksak; rumus terjadwal membatalkan validitas rentang outputnya sebelum evaluasi sehingga dependen berikutnya melihat nilai baru
  • Cache lokal per-pass tidak pernah memberi otoritas resource; buku kerja terdaftar dan loader opsional yang dikendalikan caller tetap menjadi satu-satunya sumber resolusi live, disusul cache file bertipe dan #REF!
  • TXLSWorkspaceRecalcResult mengekspos apakah graf dibangun ulang, ditambah hitungan dirty, evaluated, invalidated, cycle, blocked, cache-hit, dan cache-miss
  • Status membedakan sukses, adapter yang tidak didukung, buku kerja terputus, referensi sirkular, error kalkulasi, dan mutasi workspace selama pass berjalan
  • Pemanggilan Recalculate pada workspace yang sama diserialisasi, sehingga dua sesi kalkulasi tidak pernah memodifikasi graf bersama atau cache buku kerja secara konkuren
  • Remove atau Clear boleh berjalan saat sebuah pass aktif; pass menyimpan snapshot adapter yang aman dan mengembalikan xlswrcWorkspaceChanged alih-alih melakukan dereference pada registrasi yang sudah dihapus
  • Menghancurkan workspace menunggu pass aktifnya selesai, sedangkan menghancurkan buku kerja terdaftar memutus adapter-nya dan membuat resolusi berikutnya gagal dengan aman
  • Kegagalan loader dan hasil not-found tetap di-cache sekali per identitas ternormalisasi sampai ResetLoadAttempts, dan kalkulasi yang gagal mempertahankan state dirty lokal untuk retry eksplisit
  • Graf yang dipertahankan membuat pass lanjutan tanpa perubahan berbiaya proporsional terhadap jumlah buku kerja terdaftar, bukan jumlah rumus; analisis komponen non-rekursif dan edge rentang yang kompak menjaga model yang dalam maupun lebar tetap terbatas oleh metadata rumus termaterialisasi

Melepas defined name eksternal

ConvertExternalDefinedNamesToRefErrors menyediakan operasi publik yang sama pada TXLSWorkbook dan TXLSXWorkbook; method ini mengembalikan jumlah definisi ber-scope buku kerja dan ber-scope lembar kerja yang diganti dengan #REF! native

var
  Converted: Integer;
begin
  Converted := Workbook.ConvertExternalDefinedNamesToRefErrors;
  // External-link parts and ordinary cell formulas remain intact
end;
  • Seleksi Classic XLS memakai token referensi BIFF yang telah dikompilasi dan identitas supporting-workbook XTI, sehingga referensi tiga dimensi dalam buku kerja yang sama dan aliran token yang tidak pasti tetap tidak diubah
  • Seleksi XLSX memakai slot buku kerja numerik yang sadar-sintaks dalam urutan dokumen relasi dan hanya menerima bagian external-link buku kerja, tidak termasuk DDE, OLE, slot yang belum ter-resolve, referensi tabel, dan teks dalam kurung di dalam string
  • Semua penggantian disiapkan sebelum mutasi pertama dan di-commit sebagai satu operasi tulis; pemanggilan kedua bersifat idempoten
  • Teks nama, scope buku kerja atau lembar kerja, visibilitas, komentar, flag macro dan built-in, atribut XLSX yang tidak dikenal, serta direktori external-link tetap tersedia setelah konversi dan Roundtrip
  • Definisi yang malformed dan tidak didukung dipertahankan sebisanya per byte atau per teks dan menambahkan diagnostik xlsDiagnosticDefinedNameConversionSkipped alih-alih ditebak
  • Rumus dependen dihitung ulang menjadi nilai error Excel yang sesuai, sedangkan hasil cache yang valid untuk rumus eksternal langsung yang biasa tetap tersedia bila buku kerja livenya nanti terputus
  • Operasi ini spesifik Excel dan tidak menafsirkan ulang semantik name-formula OpenDocument

Referensi Eksternal XLS Klasik

Pada buku kerja XLS klasik, tautan eksternal disimpan dalam blok direktori global menggunakan rekaman EXTERNALBOOK dan EXTERNNAME; HotXLS memelihara direktori ini selama siklus baca/tulis file, memastikan bahwa referensi rentang jarak jauh bertahan dari loop modifikasi

Relasi Eksternal XLSX

Untuk buku kerja OOXML, pemetaan tautan eksternal dikelola melalui bagian relasi; periksa detail antarmuka pendukung di bawah ini

Copyright © 2010-2026 losLab Software