GenerationLog

The single owner of a generation run's record. Start opens the run on the designer __check worksheet; Collect and Harvest take Checking bundles, stamp every entry with the flush time, keep the entries in an in-memory record and flush the bundle to the worksheet through CheckingOutput, which appends across renders. Finish writes the closing bundle (outcome and elapsed seconds, plus the sheet and variable counts when the driver knows them), installs the filter handler and shows the worksheet. ExportText writes the whole record to a text file, one line per entry, so the run stays readable outside the workbook.

THE RUN WINDOW

Entries land between Start and Finish. A bundle collected outside that window is ignored, the behaviour every driver leans on: the build core runs the same with or without an open log. The in-memory record stays alive after Finish, which is what a later text re-export reads. Start resets the worksheet, the render marker and the record, so a re-run begins clean.

Depends on: CheckingOutput, Checking, HiddenNames, BetterArray, LinelistSpecs

Factory

Create #

create

Create a log bound to the designer workbook

Signature:

Public Function Create(ByVal designerBook As Workbook) As GenerationLog

The workbook is where the __check worksheet lives. The run itself opens later, through Start.

Parameters:

designerBook: Workbook. The designer workbook.

Returns: GenerationLog. A ready instance.

Throws:

ProjectError.ElementNotFound When designerBook is Nothing.

Run lifecycle

ShowReport #

show-report

Bring the report worksheet to the front

Signature:

Public Function ShowReport() As Boolean

The one owner of showing the report. Finish calls it at the end of a run and the ribbon calls it whenever the user asks for the last report, so a report opened either way opens the same way.

WHY THE WORKBOOK IS ACTIVATED FIRST

Worksheet.Activate raises 1004 when the sheet belongs to a workbook that is not the active one. A generation ends with the built linelist open and in front, so the activation Finish used to do raised every time and its On Error Resume Next swallowed it. That is why the report never appeared at the end of a run.

The sheet is created very hidden and Activate raises on a hidden sheet, so the visibility write comes before it.

An empty sheet is not a report. A designer that has never generated anything carries __check as a blank very hidden sheet, and showing that would leave the user looking at an empty grid with no way back.

Returns: Boolean. True when a report was found and brought to the front.

Internal members (not exported)

Factory

Seal #

seal

Seal the instance against further setup writes

Signature:

Public Sub Seal()

GuardNotSealed #

guard-not-sealed

Guard a setup setter against post-seal mutation

Signature:

Private Sub GuardNotSealed(ByVal propName As String)

Parameters:

propName: String. The name of the property being guarded.

PublicAccessors

DesignerBook #

designer-book

The designer workbook the run writes on

Signature:

Public Property Get DesignerBook() As Workbook

Returns: Workbook. The workbook given at creation.

DesignerBook #

designer-book-set

Assign the designer workbook

Signature:

Public Property Set DesignerBook(ByVal designerBook As Workbook)

Parameters:

designerBook: Workbook. The workbook to store.

RecordLength #

record-length

The number of entries in the in-memory record

Signature:

Public Property Get RecordLength() As Long

Counts every stamped entry the run has collected, the header and closing bundles included. Answers 0 before the first Start.

Returns: Long. The entry count.

RecordLine #

record-line

One record entry as its text line

Signature:

Public Property Get RecordLine(ByVal index As Long) As String

The line shape is the one the text export writes: hh:mm:ss [scope] bundle-title entry-label.

Parameters:

index: Long. The 1-based position of the entry.

Returns: String. The formatted line.

Throws:

ProjectError.ObjectNotInitialized When the run has never started.
ProjectError.InvalidArgument When index is outside the record.

Run lifecycle

Start #

start

Open the run on the __check worksheet

Signature:

Public Sub Start(Optional ByVal setupPath As String = vbNullString, _
                 Optional ByVal linelistName As String = vbNullString)

Resolves the __check worksheet, creating it very hidden when absent, clears it and drops the render marker of the previous run so the writer formats a first render. Opens a fresh writer, resets the in-memory record, starts the wall clock and stamps the run header as the first bundle: the start time and the platform of the run, plus the setup path and the linelist name when the caller knows them.

Parameters:

setupPath: Optional String. The setup file path of the run.
linelistName: Optional String. The output linelist name of the run.

PlatformTag #

platform-tag

The platform of the run, on one tag

Signature:

Private Function PlatformTag() As String

A generation report is read on another machine and long after the run, and the two platforms do not behave the same: a geobase export Windows accepts has refused on a Mac. The name and the bitness come from the compile constants, so they are the build that is running and cannot be misread. The Excel version comes from the application.

Returns: String. Something of the shape "mac-64 excel-16.90".

Collect #

collect

Take one Checking bundle into the run

Signature:

Public Sub Collect(ByVal checks As Checking, _
                   Optional ByVal recordOnly As Boolean = False)

Stamps every entry of the bundle with the flush time, appends the entries to the in-memory record and flushes the bundle to the worksheet. A Nothing or empty bundle is skipped, and so is any bundle arriving outside the run window (before Start or after Finish).

THE RECORD-ONLY PATH

recordOnly keeps a bundle out of the worksheet and puts it in the in-memory record alone, so it reaches the text file and nothing else. It carries the detail bundles: one entry per variable written is a few hundred entries on a normal linelist, and CheckingOutput ends every row it writes with an EntireColumn.AutoFit. The worksheet keeps the sheet, section and analysis milestones plus every fault, which is what a reader opens it for.

Parameters:

checks: Checking. The bundle to take.
recordOnly: Optional Boolean. True keeps the bundle off the worksheet.

Harvest #

harvest

Collect the bundles of the specification collaborators

Signature:

Public Sub Harvest(ByVal specs As LinelistSpecs)

Pulls the checkings of the dictionary, the choices, the exports, the analysis, the passwords, the format and the specifications themselves, in that order. The pull runs after LinelistSpecs.Prepare, when the collaborators have filed their entries.

Parameters:

specs: LinelistSpecs. The specifications after Prepare.

Throws:

ProjectError.InvalidArgument When specs is Nothing.

Finish #

finish

Close the run and show the worksheet

Signature:

Public Sub Finish(ByVal outcome As String, _
                  Optional ByVal sheetCount As Long = -1, _
                  Optional ByVal variableCount As Long = -1)

Writes the closing bundle (the outcome, the elapsed seconds, and the sheet and variable counts when the driver passes them), installs the worksheet filter handler, makes the worksheet visible and brings it to the front, then releases the writer. A workbook that refuses the code injection the filter needs gets a warning entry in the closing bundle and the run still closes whole. The record stays alive for the text export. A log that never started, or already finished, ignores the call.

Parameters:

outcome: String. The outcome text of the run.
sheetCount: Optional Long. Data entry sheets built. A value below 0 skips the entry.
variableCount: Optional Long. Variables written. A value below 0 skips the entry.

ExportText #

export-text

Write the whole record to a text file

Signature:

Public Function ExportText(ByVal folderPath As String, ByVal baseName As String) As String

One line per entry, in the order the run collected them: hh:mm:ss [scope] bundle-title entry-label. The file lands in the given folder as -generation.txt, which puts it beside the generated linelist when the caller passes the output folder and the linelist name.

Parameters:

folderPath: String. The folder taking the file.
baseName: String. The file name without its suffix.

Returns: String. The full path of the written file.

Throws:

ProjectError.ObjectNotInitialized When the run has never started.

Internal helpers

ResolveCheckingSheet #

resolve-checking-sheet

Resolve the __check worksheet, creating it when absent

Signature:

Private Function ResolveCheckingSheet() As Worksheet

A created worksheet lands very hidden at the end of the workbook. Finish makes it visible once the run closes.

Returns: Worksheet. The resolved or newly created worksheet.

ScopeText #

scope-text

The plain scope word of one entry

Signature:

Private Function ScopeText(ByVal checks As Checking, ByVal keyName As String) As String

Reads the type descriptor of the entry and strips the icon characters, leaving Error, Warning, Info, Note or Success for the record and the text lines.

Parameters:

checks: Checking. The bundle holding the entry.
keyName: String. The entry key.

Returns: String. The plain scope word.

ErrorHandling

ThrowError #

throw-error

Raise a ProjectError-coded runtime error

Signature:

Private Sub ThrowError(ByVal errNumb As Long, ByVal errorMessage As String)

Parameters:

errNumb: Long. ProjectError enumeration value.
errorMessage: String. Human-readable description.

Throws:

ProjectError. Always raises the specified error.

Used in (8 file(s))

CodeTransfer.cls
LinelistSpecs.cls
LLLog.cls
EventsDesignerAdvanced.bas
EventsDesignerMulti.bas
InitTransfer.bas
HeadlessBuild.bas
TestGenerationLog.bas