Skip to content

Batch log and status message writing

clsBatchBase gives batch applications a small set of output methods so status and error text goes to the correct destination — standard output, standard error, or one of up to five environment-variable-configured log files — without each application managing StreamWriter instances itself.

Field Value
Operation ID OP-CA-004
Trigger Downstream batch application code calls WriteStatusMsg, WriteErrorMsg, or one of the WriteAppLogMsg overloads
Inputs Message text (String); optionally a BatchStreams target (StandardFile, File0…File4)
Outputs Text written to Console.Out, Console.Error, or an open file stream; for file streams, an opened/updated System.IO.StreamWriter tracked in the instance's internal log table
Primary components clsBatchBase.WriteStatusMsg, clsBatchBase.WriteErrorMsg, clsBatchBase.WriteAppLogMsg (both overloads)
Entry point Presentation\SAIF.Presentation.ConsoleApplication\clsBatchBase.vb

Steps

  1. Write a status message (WriteStatusMsg). Writes the given text to Console.Out via Console.WriteLine. Used internally by WriteBatchHeader/WriteBatchFooter as part of the console application execution lifecycle.
  2. Write an error message (WriteErrorMsg). Writes the given text to Console.Error via Console.Error.WriteLine.
  3. Write a console-only application-log message (WriteAppLogMsg(AppLogMsg)). Writes the given text directly to Console.Out; no file or stream is involved.
  4. Write a stream-targeted application-log message (WriteAppLogMsg(AppLogMsg, LogFile)). Resolves the target from the BatchStreams enum value's upper-cased name (LogNo):
  5. If LogNo = "STANDARDFILE": unconditionally opens a new IO.StreamWriter at {CurrentDirectory}\{AppName}.log, replacing any previously tracked writer for this stream, then writes and flushes the message (BR-006).
  6. If LogNo is any other stream name (File0…File4):
    • Reads the environment variable named LogNo.
    • If that environment variable is empty/unset: throws Exception("Log stream " & LogNo & " is not a valid environment variable or file.") (BR-001).
    • On failure: the exception propagates uncaught out of WriteAppLogMsg (the internal Try/Catch re-throws via a bare Throw).
    • If the environment variable is set and no StreamWriter has been opened yet for this stream (the tracked value is still its placeholder empty string): opens a new IO.StreamWriter at the path named by the environment variable and tracks it.
    • If a StreamWriter was already opened for this stream in a prior call: reuses it without reopening.
    • Writes the message to the resolved StreamWriter and flushes it immediately.
  7. Streams remain open until teardown. Any StreamWriter opened by step 4 stays open (to allow further appends) until clsBatchBase.Uninitialize() flushes and closes it as part of the console application execution lifecycle.

Process flow

The following diagram visualizes how WriteAppLogMsg(AppLogMsg, LogFile) resolves and writes to its target stream.

flowchart TD
    Start([WriteAppLogMsg called<br>with message and LogFile]) --> IsStd{LogFile is<br>StandardFile?}
    IsStd -->|Yes| NewStd[Always open a new StreamWriter<br>at CurrentDirectory AppName.log]
    IsStd -->|No| EnvCheck{Environment variable<br>for stream is set?}
    EnvCheck -->|No| ThrowErr([Throw: not a valid<br>environment variable or file])
    EnvCheck -->|Yes| Opened{StreamWriter already<br>opened for this stream?}
    Opened -->|No| NewNamed[Open new StreamWriter<br>at env-var path]
    Opened -->|Yes| ReuseNamed[Reuse existing StreamWriter]
    NewStd --> Write[Write line and flush]
    NewNamed --> Write
    ReuseNamed --> Write
    Write --> End([Stream stays open<br>until Uninitialize])

Failure and edge-case behavior

  • Writing to a non-StandardFile batch log stream whose environment variable is unset or empty throws an exception rather than silently discarding the message (BR-001).
  • Repeated writes to the StandardFile stream each open a brand-new StreamWriter over the same path instead of reusing the one from the previous call, unlike the named (File0…File4) streams, which are opened once and reused (BR-006).
  • WriteErrorMsg writes to Console.Error only — it never writes to a file-backed stream, even when the application also has batch log streams configured.
  • The internal log table only tracks streams that were pre-registered during Initialize() (names matching FILE?) or the StandardFile slot; a BatchStreams value with no corresponding pre-registered environment variable still throws per BR-001 when first written to.*

Note: Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts.

Sources

  • Presentation\SAIF.Presentation.ConsoleApplication\clsBatchBase.vb