Compiled reporting API

The lxReport unit compiles placeholders and structural report bands once, then applies caller-owned data through bounded cursors without rescanning generated workbook objects

Table and cursor contracts

Controlled query providers

IXLSReportQueryExecutor.ExecuteReadOnly keeps query execution host-owned and accepts only definitions registered by application code

TXLSReportQueryParameter, TXLSReportQueryParameters, and TXLSReportQueryDefinition expose Name, CommandText, TimeoutMS, ParameterCount, Parameters, SetParameter, and ClearParameters

TXLSReportQueryProvider uses RegisterQuery, RemoveQuery, Clear, and TryGetTable, with Count, Definitions, and MaximumTimeoutMS exposing the whitelist and timeout ceiling

Per-run data sessions

IXLSReportDataSession is the isolated lazy cache behind one report run: DeclareRequest registers a TXLSReportDataRequest (kind TXLSReportDataRequestKind: xrdrkNamed or xrdrkUser) whose TXLSReportDataSource (kind TXLSReportDataSourceKind: unspecified, cell, range band, table band, or expression) and TXLSReportDataParameter list describe the source and its values, and whose RunControl is the host's IXLSReportRunControl cancellation handle; HasResolver tests a provider key, TryGetTable and RequireTable read cached aliases, TryResolveTable and RequireResolvedTable resolve on demand into a TXLSReportDataResolveResult (status TXLSReportDataResolveStatus: xrdrsUnhandled, xrdrsResolved, xrdrsNotFound, or xrdrsDataError), and TryGetState reports a TXLSReportDataSessionState of loading, resolved, not found, or data error, while CachedAliasCount and ResolvedAliasCount expose session size

IXLSReportDataView.TryGetValue looks up one named value without raising, complementing the indexed Count, Names, and Values accessors

Relations and lazy table combinators

TXLSReportRowIndexes and TXLSReportRelationIndex retain child row numbers in compound-key buckets; use FindChildRows or CreateChildCursor and inspect BucketCount or IndexedRowCount

TXLSReportAggregateKind, TXLSReportAggregate, and TXLSReportJoinKind configure TXLSReportTableFactory, whose row filters compare through TXLSReportFilterOperator (xrfoEqual, xrfoNotEqual, xrfoGreater, xrfoGreaterEqual, xrfoLess, xrfoLessEqual, xrfoContains, xrfoStartsWith, xrfoEndsWith)

Named and explicit range bands

TXLSReportBandKind selects row, column, or cross-tab expansion, and TXLSReportBandState reports ready, running, completed, completed-with-errors, canceled, or failed lifecycle state

TXLSCompiledReportBand accepts an exact-scope defined name or CreateForRange, then expands through the Run overloads; DefinedName, ScopeSheetIndex, Kind, Sheet, SheetIndex, FirstRow, FirstCol, LastRow, LastCol, TargetCount, and State expose the compiled plan

EmptyBandPolicy (type TXLSEmptyBandPolicy) controls what the band does with its template rows when the data set is empty — xreKeepTemplate leaves the rows untouched, xreClearTemplate clears the band cells including placeholders, and xreDeleteTemplate deletes the template rows — and DeleteLastRow removes the final BandHeight rows of the expanded block after its copies land, so trailing X-range separator rows collapse

FixedBand makes row bands overwrite the rows below the template instead of inserting new ones, which keeps surrounding content at a fixed position

TXLSCompiledTableReportBand.Run expands one Excel table data-template row while preserving table metadata; inspect TableName, Sheet, SheetIndex, ExcelTable, TemplateRow, and State, and configure the same V2 image properties exposed by range bands

Range and Excel-table bands share ErrorMode, StrictDataAccess, RuntimeLimits, and immutable LastResult snapshots; xremWriteAndContinue writes only explicit recoverable cell failures as literal diagnostics, records the source BandInputRow and actual output coordinates, and continues later targets and rows, while structural, cancellation, resource-limit, callback, and rollback failures remain fatal

TXLSCompiledSheetReportBand.Run creates per-record sheets using NameColumn, NamePrefix, and DeleteTemplateAfterRun; TXLSCompiledOverflowReportBand.Run creates continuation sheets using NamePrefix and DeleteTemplateAfterRun

Whole-workbook templates

TXLSReportTemplateTarget and TXLSReportTemplateTargets select cells, comments, hyperlinks, shapes, headers and footers, sheet names, defined names, and document properties

TXLSCompiledReportTemplate.Compile captures targets and expressions, Analyze returns addressed TXLSReportIssues, the Run overloads apply values, and WriteDiagnostics writes issues to a worksheet; TargetAreas, TargetCount, and UserTableCount describe the compiled surface and registered user tables

ProcessStructuralDirectives (default True) makes a template Run execute the structural {{#delete}} and {{#format}} directives after value targets are applied — the TXLSReportDirectiveProcessor behind it parses the ranges, applies them, and reports how many it handled through AppliedCount — and CreateEncrypted opens an encrypted template with its password and compiles it while keeping the workbook reachable through the Workbook property

TXLSReportIssueKind, TXLSReportIssue, and TXLSReportIssues identify malformed, missing, invalid, unknown, or cyclic placeholder content with target and cell coordinates

Includes, images, and formatting

IXLSReportIncludeResolver.Resolve supplies named fragments and its Immutable flag permits safe reuse; TXLSReportIncludeLibrary provides Add, Remove, Clear, Freeze, Resolve, Count, and Immutable

IXLSReportImageProvider.TryGetImage returns a TXLSReportImageValue configured by TXLSReportImageFit; TXLSReportMissingImagePolicy controls missing resources, while TXLSReportImageBinder.Apply, ApplyTarget, MissingPolicy, and ClearDirectiveCell update exact image directives

TXLSReportImageBinder.ApplyTargetV2 binds one directive cell through the V2 provider contract and forwards a TXLSReportTransformImageEvent that can rewrite the resolved payload before it lands; the resolved placeholder itself is a TXLSReportEvaluatedTarget whose TXLSReportEvaluatedTargetKind distinguishes xretNone, xretText, xretValue, and xretFormula; IXLSReportImageCancellation.IsCancellationRequested lets long-running providers observe a cooperative cancel

IXLSReportImageDataProviderV2.GetImage receives TXLSReportImageRequest with stable worksheet identity, compiled target, band and table names, logical and cursor rows, a read-only current-row view, directive and anchor cells, target dimensions and offsets in EMU, and IXLSReportImageCancellation

TXLSReportImageResult carries a TXLSReportImagePayload whose Kind (TXLSReportImagePayloadKind) selects xripMissing, bytes, or a stream, with the stream's lifetime declared by TXLSReportImageStreamOwnership: xrisoBorrowed streams remain caller-owned and restore their position when seekable, while xrisoTransferred streams are released exactly once; optional SourceWidth, SourceHeight, SourceDpiX, and SourceDpiY assert or override physical source geometry

xrifNatural uses the source physical size, xrifContain scales and centres within the target box, xrifCover fills the box with symmetric source cropping, and xrifStretch fills it without preserving aspect ratio; PNG, JPEG, GIF, BMP, EMF, and WMF geometry is read from bounded headers without decoding pixels

OnTransformImage runs after provider data is snapshotted and before worksheet mutation; MaximumImageBytes defaults to 64 MiB and payload signatures, geometry headers, dimension and DPI pairs, raster side and pixel limits, anchors, and grid coordinates are validated before binding

TXLSXImage.OffsetXEMU and OffsetYEMU retain an image's position inside its cell or absolute anchor through XLSX and ODS round trips

TXLSReportDynamicFormat and TXLSReportFormatEvent let a runner apply number formats, row heights, and column widths per target

Reusable execution

TXLSReportRunPhase, TXLSReportRunState, TXLSReportRunProgress, and TXLSReportRunProgressEvent describe progress and cancellation boundaries

TXLSCompiledReportRunner exposes Run, RunToStream, RunToFile, RunToEncryptedFile, and Cancel, with ReportTemplate, State, Progress, OnProgress, and OnFormat controlling reusable execution; failed validation raises EXLSReportData before deterministic writes

ErrorMode (type TXLSReportErrorMode) defaults to xremStop; xremWriteAndContinue handles only explicit EXLSReportRecoverableData failures and resolver DataError results, records ordered immutable issues in LastResult (an IXLSReportRunResult exposing State, AppliedCount, IssueCount, indexed Issues, and the FailureClassName / FailureMessage of a fatal failure) whose TXLSReportRuntimeIssue snapshots expose their Category (a TXLSReportRuntimeIssueCategory: xrricDataAccess, xrricProvider, or xrricExpression) and report TargetIndex, SheetName, Col, and whether the issue was already WasWritten into the output, and finishes as xrrsCompletedWithErrors

TXLSReportRuntimeLimits.Defaults allows 100,000 retained issues, 512 characters per sanitized message, and 16 MiB of issue memory; assign a positive custom RuntimeLimits record before a run, and leave RuntimeDiagnosticsSheetName empty unless one structured diagnostics worksheet is required

Recoverable cell values and formulas become literal [Report error CODE] message text, safe non-cell targets retain their original value, and an optional diagnostics worksheet marks those structured issues as written; worksheet-name and defined-name-formula failures always stop because they can change workbook structure

Resolver-declared data errors, expression division by zero, and invalid regular expressions use stable provider or expression categories; thrown resolver exceptions and all callback, cancellation, resource-limit, rollback, serialization, security, and structural failures remain fatal

RunToStream, RunToFile, and RunToEncryptedFile stage serialization inside the same run and data-session lifetime, then publish once; any fatal, canceled, serialization, partial stream-write, or destination-replacement failure preserves the complete prior destination and releases temporary storage before returning

A nonempty output stream must be readable, writable, sizable, and seekable so rollback can restore its original bytes, size, and position; snapshots up to 8 MiB remain in memory and larger snapshots use managed temporary storage, while a successful commit leaves the stream positioned at zero

Unencrypted output uses the generated workbook's source format, so an ODS template produces an ODS stream or file with its required package metadata; encrypted output continues to use the encrypted Office container

ImageProvider preserves the original compatibility contract; ImageProviderV2, OnTransformImage, MaximumImageBytes, MissingImagePolicy, and ClearImageDirectiveCell let a runner, generator, range band, or Excel-table band consume precompiled {{#image Key}} targets directly; omitting both providers leaves those directive cells unchanged

AutofitMode (type TXLSReportAutofitMode) selects a whole-sheet autofit (xramNone, xramRows, xramColumns, or xramBoth) applied once after all targets run, and AutofitAdjustment is an extra headroom factor (1.0 = none, 1.1 = 10% taller rows)

Generation lifecycle and template sources

TXLSReportLifecyclePhase identifies template-read, workbook-generation, and worksheet-generation boundaries, while TXLSReportLifecycleOutcome distinguishes entered, completed, canceled, and failed callbacks

TXLSReportLifecycleContext supplies the active workbook and worksheet, stable worksheet identity, original and current coordinates, a read-only IXLSReportDataView, target count, and first-failure details; every entered before event receives a paired after event even when generation is canceled or fails

TXLSCompiledReportRunner.BeforeGenerateWorkbook, AfterGenerateWorkbook, BeforeGenerateSheet, and AfterGenerateSheet observe a frozen set of original worksheets; callback-driven structure changes trigger compilation refresh without adding newly created sheets to the current run

TXLSReportGenerator accepts a workbook, file name, caller-owned stream, or encrypted file and adds BeforeReadTemplate plus AfterReadTemplate to the generation events; TXLSReportModificationMode selects compatible in-place mutation or isolated atomic-clone generation. Read-only SourceKind (type TXLSReportTemplateSourceKind: xrtsWorkbook, xrtsFile, xrtsStream, or xrtsEncryptedFile) and TemplateWorkbook report the configured template source, while ModificationMode and IncludeResolver are settable before a run

File and stream templates default to xrmAtomicClone; seekable input streams restore their original position, forward-only streams are consumed in bounded blocks, caller streams remain open, and output streams or files are replaced only after successful completion

Planning, checking, and migration

TXLSReportPaginationPlanner provides KeepTogether, SplitRows, MergeSimilar, and BalanceColumns plans for fixed-footers and balanced output

TXLSReportTemplateChecker provides Check, CheckBand, and CheckTableBand; TXLSReportTemplateMigrator provides MigrateText and MigrateWorkbook for supported legacy placeholder forms

Delphi example

Context := TXLSReportDataContext.Create;
Table := TXLSReportMemoryTable.Create('Orders', ['Customer', 'Amount']);
Table.AddRow(['A. Datum', 1200]);
Context.RegisterTable(Table);
Template := TXLSCompiledReportTemplate.Create(Workbook);
Template.DataContext := Context;
Runner := TXLSCompiledReportRunner.Create(Template);
try
  Runner.StrictDataAccess := True;
  Runner.ErrorMode := xremWriteAndContinue;
  Runner.RuntimeDiagnosticsSheetName := 'Report Diagnostics';
  Runner.RunToFile(Values, OutputFileName);
  RunResult := Runner.LastResult;
finally
  Runner.Free;
  Template.Free;
  Context.Free;
end;

C++Builder example

Lxreport::TXLSReportMemoryTable *tableObject =
  new Lxreport::TXLSReportMemoryTable(L"Orders", columns, 1);
Lxreport::_di_IXLSReportTable table;
tableObject->GetInterface(table);
tableObject->AddRow(row, 1);
context->RegisterTable(table);

Lxreport::TXLSCompiledReportTemplate *reportTemplate =
  new Lxreport::TXLSCompiledReportTemplate(workbook);
reportTemplate->DataContext = context;
Lxreport::TXLSCompiledReportRunner *runner =
  new Lxreport::TXLSCompiledReportRunner(reportTemplate);
runner->StrictDataAccess = true;
runner->ErrorMode = Lxreport::xremWriteAndContinue;
runner->RuntimeDiagnosticsSheetName = L"Report Diagnostics";
runner->RunToFile(values, outputFileName);
Lxreport::_di_IXLSReportRunResult runResult = runner->LastResult;

The Delphi FeatureShowcase and C++Builder XlsxFeatureGallery contain complete runnable versions that verify the completed-with-errors state and issue count before releasing the runner

See also

• Advanced workbook workflows
• TXLSXWorkbook
• TXLSPaginationModel