vb6-trace-pattern

VB6 Trace Pattern

VB6 has no native call stack accessible to user code. When an error fires in production, Err.Description tells you what but not where in the chain of calls. This pattern solves that by maintaining a manual stack in a module-level array, pushed by EnterMethod on entry and popped by ExitMethod on exit.

The pattern is one of the most useful additions you can make to a long-lived VB6 codebase. The cost is one line at the top and one line in each exit path of every instrumented procedure.

1. When to instrument

Every non-trivial new procedure gets EnterMethod/ExitMethod. "Non-trivial" means any of:

• More than ~5 lines of logic
• Has On Error GoTo (CSEH style)
• Accesses database, file, or network
• Called from more than one place

Skip for:

• Trivial getters/setters (Property Get/Let that just reads/assigns a field)
• One-line utility functions
• Stateless pure helpers (string formatting, math)

When in doubt, instrument. The overhead is negligible compared to the diagnostic value when something fails in production.

2. Canonical placement

The pattern is paired with the CSEH error-handling pattern:

'CSEH: ErrRaise
Public Function GetActiveCustomer(ByVal lngCustomerID As Long) As Object

        '<EhHeader>
        On Error GoTo GetActiveCustomer_Err

        EnterMethod "modDB", "GetActiveCustomer"
        '</EhHeader>

        ' ... body ...

    '<EhFooter>
        On Error GoTo 0

GetActiveCustomer_Exit:
        ' cleanup
        ExitMethod "modDB", "GetActiveCustomer"
        Exit Function

GetActiveCustomer_Err:
        Dim sGetActiveCustomer_Err As String
        sGetActiveCustomer_Err = "Error: " & Err.Number & " - " & Err.Description & " (" & Erl & ")"

        ' cleanup
        ExitMethod "modDB", "GetActiveCustomer"

        Err.Raise vbObjectError + 100, "SampleApp.modDB.GetActiveCustomer", sGetActiveCustomer_Err
    '</EhFooter>
End Function

Critical: ExitMethod is called on both the success path (_Exit) and the error path (_Err). Skipping ExitMethod in _Err leaves the function "open" on the stack — every subsequent trace shows that function still as a caller, which is wrong.

3. EnterMethod with parameters (optional)

When the parameter values would help diagnose a future failure, pass them to EnterMethod after the module and procedure names:

EnterMethod "modDB", "GetActiveCustomer", lngCustomerID, blnIncludeInactive

EnterMethod accepts a ParamArray and serializes each parameter:

• Primitives — converted via CStr
• Objects — "Object:" followed by a property/field dump, or "Nothing"
• Recordsets — fast dump via GetString
• Arrays — element-by-element serialization
• Empty / Null — literal strings

Resulting log line: Enter: modDB::GetActiveCustomer( 1234, False )

Performance caveat: serializing a populated Recordset is expensive. Inside hot loops (thousands of iterations), do not pass heavy parameters. Pass scalar identifiers (IDs, counts) only.

4. TraceMethod() in error handlers

TraceMethod() returns the current stack as a formatted string. Embed it in the error message when the error is going to surface to the UI or be sent externally (email, ticket):

GetActiveCustomer_Err:
        Dim sGetActiveCustomer_Err As String
        sGetActiveCustomer_Err = "Error: " & Err.Number & " - " & Err.Description & " (" & Erl & ")"
        sGetActiveCustomer_Err = sGetActiveCustomer_Err & vbCrLf & TraceMethod()

        ExitMethod "modDB", "GetActiveCustomer"
        Err.Raise vbObjectError + 100, "SampleApp.modDB.GetActiveCustomer", sGetActiveCustomer_Err

Do not embed TraceMethod() in every handler. In re-raise chains (function A calls function B which raises; A catches and re-raises), the stack is implicit in the chain of qualified source strings. Duplicating it in every message bloats the log. Use TraceMethod() at the boundary where the error becomes user-visible.

5. Log activation

Logging only writes when gblnRegisterLog = True. The flag is set by RegisterLog (called automatically by LogMsg) based on three signals:

1. The IDE is active (fg_InIDE returns True) — always log in dev
2. A file named debug.txt exists in App.Path — sysadmin enables logging by creating this file on the client machine
3. An explicit code-level toggle (e.g., a config flag)

In production, the absence of debug.txt means logging is off and the overhead of EnterMethod/ExitMethod is reduced to a couple of array operations and an early-exit check.

6. Force-log for critical events

LogMsg accepts a Force parameter:

LogMsg "Database connection failed", True

Force = True writes regardless of gblnRegisterLog. Use sparingly — reserve for events that must always reach the log file:

• Critical error dialogs (the project's MsgBoxCritical wrapper does this)
• App startup/shutdown
• Failed connection attempts
• Schema migration steps

7. Automatic process dump on automation errors

LogMsg scans the message for "failed" and "automation error". When either is found, it triggers DumpProcesses (via WMI) which logs every running process on the machine. This is invaluable when COM/automation errors appear sporadically and you need to know what else was running — competing processes, antivirus interference, stale instances of the app itself, etc.

The dump fires only once per LogMsg call (guarded by bDumping flag) and is best-effort (On Error Resume Next throughout).

8. Log file layout

Default layout for a single-tier log:

App.Path\
  log\
    app-2026-05-23.txt       ' general log, rotated daily
    app-2026-05-22.txt
    ...

LogMsg opens the daily file in append mode, writes a single line with Format(Now, "hh:nn:ss") & " < " & msg & " >", and closes the handle. File handles do not stay open between messages — the cost of FreeFile/Open/Close is acceptable in exchange for not losing entries on crash.

Old logs are pruned automatically by CleanupOldLogs, called once per session on first log entry. Default retention: 30 days (DEF_LOG_DAYS constant).

9. ExitMethod modes

ExitMethod supports two signatures:

ExitMethod "modDB", "GetActiveCustomer"     ' specific (paired with EnterMethod)
ExitMethod "modDB"                          ' bulk (pop all frames for this module)

The specific form pops one frame. The bulk form pops every frame at the top of the stack whose object matches — useful in form Unload handlers where multiple methods of the same form may still be on the stack due to exceptional early returns.

Prefer the specific form. The bulk form exists as a safety net but indicates that some ExitMethod was missed elsewhere.

10. Anti-patterns

Anti-pattern	Why it breaks
EnterMethod without paired ExitMethod	Stack grows unbounded; every trace is wrong from that point forward
ExitMethod only in _Exit, not in _Err	After an error, the function stays "open" on the stack
Instrumenting trivial getters/setters	Pollutes the log; cost > benefit
Passing a populated Recordset to EnterMethod in a loop	Each iteration serializes the entire recordset; massive log spam
Calling ExitMethod before fully cleaning up resources	Trace looks clean but resources leak silently
Using TraceMethod() in every re-raise handler	The qualified source string already carries the path; duplicates inflate log
Initializing msMethods() mid-session via Stop/restart	Stack becomes inconsistent; trace shows phantom frames until next entry

11. Migration notes for existing code

Adding the trace pattern to an existing codebase is incremental:

1. Drop in modLog.bas (from reference/)
2. Add Microsoft Scripting Runtime reference (for Dictionary and FileSystemObject)
3. Define fg_InIDE in any module (the helper that detects IDE vs compiled execution)
4. Start instrumenting new code immediately
5. Add to existing code opportunistically — every procedure you touch for another reason gets EnterMethod/ExitMethod

There is no requirement to instrument everything at once. Partial coverage is useful: the trace shows what is instrumented, and uninstrumented procedures appear as "missing levels" in the trace, which itself is a hint about where to add coverage.

12. Reference module

reference/modLog.bas is a complete, self-contained implementation of the pattern. Copy it into a new project and it works after referencing Microsoft Scripting Runtime and providing a fg_InIDE function.

The reference module includes:

• LogMsg — write a line to the daily log file, with optional Force
• EnterMethod — push a method onto the stack with optional parameter serialization
• ExitMethod — pop a method (specific or bulk)
• TraceMethod — return the current stack as a formatted string
• DumpProcesses — WMI-based process listing, auto-invoked on automation-error patterns
• CleanupOldLogs — daily-log retention
• SerializeMethod — diagnostic helper for serializing arbitrary parameter arrays