SetupErrors

Analyses setup sheets and publishes consistency reports. Validates the dictionary for duplicate variables, missing labels, unknown controls, and formula correctness; inspects choices for unused entries and missing labels; audits exports for missing metadata and dictionary alignment; and reviews translations for missing or duplicate labels. Results are collected as IChecking objects and published to the __checkRep reporting worksheet via CheckingOutput.

Factory

Create #

create

Create and initialise a setup checker instance

Signature:

Public Function Create(ByVal hostBook As Workbook, _
                       Optional ByVal passwordService As IPasswords, _
                       Optional ByVal dictionary As ILLdictionary, _
                       Optional ByVal choices As ILLChoices, _
                       Optional ByVal formulaStore As IFormulaData, _
                       Optional ByVal transManager As ISetupTranslationsTable, _
                       Optional ByVal stateScope As IApplicationState) As ISetupErrors

Factory method on the predeclared instance. Creates a new SetupErrors, calls Initialise with the supplied workbook and optional collaborators, then returns the instance through the ISetupErrors interface.

Parameters:

hostBook: Workbook. The workbook containing setup data.
passwordService: Optional IPasswords. Sheet protection handler.
dictionary: Optional ILLdictionary. Dictionary data accessor.
choices: Optional ILLChoices. Choices data accessor.
formulaStore: Optional IFormulaData. Formula validation handler.
transManager: Optional ISetupTranslationsTable. Translations table accessor.
stateScope: Optional IApplicationState. Application state guard.

Returns: ISetupErrors. A fully initialised instance ready to run checks.

Throws:

ProjectError.ObjectNotInitialized When hostBook is Nothing.

Initialisation

Initialise #

initialise

Bind the checker to a workbook and optional collaborators

Signature:

Public Sub Initialise(ByVal hostBook As Workbook, _
                      Optional ByVal passwordService As IPasswords, _
                      Optional ByVal dictionary As ILLdictionary, _
                      Optional ByVal choices As ILLChoices, _
                      Optional ByVal formulaStore As IFormulaData, _
                      Optional ByVal transManager As ISetupTranslationsTable, _
                      Optional ByVal stateScope As IApplicationState)

Validates the workbook reference, stores it along with optional collaborators, then calls ConfigureDependencies to create any missing default instances and EnsureCheckContainer to prepare the results array.

Parameters:

hostBook: Workbook. The workbook containing setup tables.
passwordService: Optional IPasswords. Sheet protection handler.
dictionary: Optional ILLdictionary. Dictionary data accessor.
choices: Optional ILLChoices. Choices data accessor.
formulaStore: Optional IFormulaData. Formula validation handler.
transManager: Optional ISetupTranslationsTable. Translations table accessor.
stateScope: Optional IApplicationState. Application state guard.

Throws:

ProjectError.ObjectNotInitialized When hostBook is Nothing.

Execution

Run #

run

Execute all setup checks and publish results

Signature:

Public Sub Run()

Suspends Excel UI via EnterBusyState, resets the check container, then runs each checker in sequence: CheckDictionary, CheckChoice, CheckExports, CheckTranslations. On completion, publishes all collected IChecking objects to the reporting worksheet via PrintReport. Restores Excel state even when an error occurs during the checking run.

Results

Checkings #

checkings

Collection of generated checking objects

Signature:

Public Property Get Checkings() As BetterArray

Returns a BetterArray containing the IChecking instances produced by the most recent Run call. Raises when the checker has not been initialised.

Returns: BetterArray. The generated IChecking instances.

Internal members (not exported)

Helper workflow

Self #

self

Current object instance

Signature:

Public Property Get Self() As ISetupErrors

Returns: ISetupErrors. The current instance cast to the interface.

EnsureInitialised #

ensure-initialised

Ensure the checker has been initialised

Signature:

Private Sub EnsureInitialised()

Throws:

ProjectError.ObjectNotInitialized When the workbook reference is Nothing.

ConfigureDependencies #

configure-dependencies

Prepare collaborators when not provided

Signature:

Private Sub ConfigureDependencies()

Creates default instances for any optional collaborator that was not supplied during Initialise: resolves the formula sheet, creates Passwords, LLdictionary, LLChoices, FormulaData, and SetupTranslationsTable instances from the host workbook.

EnsureCheckContainer #

ensure-check-container

Ensure the internal container for checkings exists

Signature:

Private Sub EnsureCheckContainer()

ResetCheckContainer #

reset-check-container

Reset the container prior to running checks

Signature:

Private Sub ResetCheckContainer()

ApplicationScope #

application-scope

Retrieve or create the application state scope

Signature:

Private Function ApplicationScope() As IApplicationState

Returns: IApplicationState. The cached or newly created scope.

EnterBusyState #

enter-busy-state

Suspend Excel UI features while running checks

Signature:

Private Sub EnterBusyState()

LeaveBusyState #

leave-busy-state

Restore Excel UI configuration

Signature:

Private Sub LeaveBusyState(Optional ByVal silent As Boolean = False)

Parameters:

silent: Optional Boolean. When True, suppresses errors during restore. Defaults to False.

ResolveWorksheet #

resolve-worksheet

Resolve a workbook worksheet by name

Signature:

Private Function ResolveWorksheet(ByVal sheetName As String) As Worksheet

Parameters:

sheetName: String. The worksheet name to look up.

Returns: Worksheet. The resolved worksheet.

Throws:

ProjectError.ElementNotFound When the worksheet does not exist.

ValidateWorkbook #

validate-workbook

Validate the incoming workbook reference

Signature:

Private Sub ValidateWorkbook(ByVal hostBook As Workbook)

Parameters:

hostBook: Workbook. The workbook to validate.

Throws:

ProjectError.ObjectNotInitialized When hostBook is Nothing.

Core checking routines

CheckDictionary #

check-dictionary

Validate dictionary sheet for structure, duplicates, and formulas

Signature:

Private Sub CheckDictionary()

Unprotects the dictionary, exports, and choices sheets, then iterates bottom-up through the dictionary rows checking for: duplicate variable names, short variable names, missing main labels, missing sheet names, unknown controls, choice formula mismatches, formula validity, min/max validation types, format/type consistency, and export column alignment. Collects all findings into a single IChecking object and re-protects sheets on exit.

CheckChoice #

check-choice

Inspect choices sheet for unused or inconsistent entries

Signature:

Private Sub CheckChoice()

Unprotects the choices sheet, builds a list of choice names actually referenced in dictionary controls, then flags unused choices, missing list names, missing ordering values, and missing labels. Collects all findings into a single IChecking object and re-protects on exit.

CheckExports #

check-exports

Audit exports sheet for missing metadata and dictionary alignment

Signature:

Private Sub CheckExports()

Iterates over each export row, checking active exports for missing label, password, metadata, format, filename, and header values. Also validates that the corresponding dictionary column exists and is not empty, checks password/identifier consistency, and validates filename variable references.

CheckTranslations #

check-translations

Review translations table for missing and duplicate labels

Signature:

Private Sub CheckTranslations()

Unprotects the translations sheet, updates the translations manager from the registry, then queries for missing and duplicate labels. Collects findings into a single IChecking object and re-protects on exit.

CheckAnalysis #

check-analysis

Run analysis table checks across all sections

Signature:

Private Sub CheckAnalysis()

Resolves the analysis worksheet, removes empty rows via Analysis.RemoveRows, then delegates to CheckTable for each of the seven analysis sections. Caches the worksheet and WorksheetFunction references and passes them to CheckTable to avoid repeated lookups.

CheckTable #

Evaluate a specific analysis section for structural errors.

Signature:

Private Sub CheckTable(ByVal partName As String, _
                       ByVal analysisSheet As Worksheet, _
                       ByVal workFun As WorksheetFunction)

Parameters:

partName: String. The section display name (e.g. "Global summary").
analysisSheet: Worksheet. The cached analysis worksheet.
workFun: WorksheetFunction. The cached worksheet function object.

PrintReport #

print-report

Publish all collected checkings to the reporting worksheet

Signature:

Private Sub PrintReport()

Resolves the __checkRep worksheet, clears its content, creates a CheckingOutput helper, and prints all collected IChecking objects. Installs the worksheet change handler for filtering support and activates the report sheet.

Message helpers

FormatMessage #

format-message

Format an error message by replacing numbered placeholders

Signature:

Private Function FormatMessage(ByVal messageTag As String, _
                               Optional ByVal valueOne As String = vbNullString, _
                               Optional ByVal valueTwo As String = vbNullString, _
                               Optional ByVal valueThree As String = vbNullString, _
                               Optional ByVal valueFour As String = vbNullString) As String

Parameters:

messageTag: String. The message template with %1..%4 placeholders.
valueOne: Optional String. Replacement for %1.
valueTwo: Optional String. Replacement for %2.
valueThree: Optional String. Replacement for %3.
valueFour: Optional String. Replacement for %4.

Returns: String. The formatted message.

FormulaMessage #

formula-message

Validate a formula string and return a formatted error when invalid

Signature:

Private Function FormulaMessage(ByVal formValue As String, _
                                ByVal messageTag As String, _
                                Optional ByVal valueOne As String = vbNullString, _
                                Optional ByVal valueTwo As String = vbNullString, _
                                Optional ByVal formulaType As String = "linelist") As String

Parameters:

formValue: String. The formula expression to validate.
messageTag: String. The message template to use on failure.
valueOne: Optional String. Replacement for %1.
valueTwo: Optional String. Replacement for %2.
formulaType: Optional String. Formula type ("linelist" or "analysis"). Defaults to "linelist".

Returns: String. The formatted error message, or empty when the formula is valid.

ReplacePlaceholder #

replace-placeholder

Replace a single placeholder token in a template string

Signature:

Private Function ReplacePlaceholder(ByVal template As String, _
                                    ByVal placeholder As String, _
                                    ByVal replacement As String) As String

Parameters:

template: String. The template containing the placeholder.
placeholder: String. The token to replace (e.g. "%1").
replacement: String. The value to substitute.

Returns: String. The template with the placeholder replaced.

Interface implementation

ISetupErrors_Initialise #

Signature:

Private Sub ISetupErrors_Initialise(ByVal hostBook As Workbook, _
                                    Optional ByVal passwordService As IPasswords, _
                                    Optional ByVal dictionary As ILLdictionary, _
                                    Optional ByVal choices As ILLChoices, _
                                    Optional ByVal formulaStore As IFormulaData, _
                                    Optional ByVal transManager As ISetupTranslationsTable, _
                                    Optional ByVal stateScope As IApplicationState)

Delegated members satisfying the ISetupErrors contract. See the corresponding Public members above for full documentation.

ThrowError #

throw-error

Raise a ProjectError-based exception

Signature:

Private Sub ThrowError(ByVal errNumber As ProjectError, ByVal errorMessage As String)

Wrapper around Err.Raise that standardises the source to CLASS_NAME, providing a consistent stack trace across all methods in this class.

Parameters:

errNumber: ProjectError. The error code to raise.
errorMessage: String. Human-readable description of the failure.

Throws:

ProjectError Always raises the specified error.

Used in (4 file(s))