COMOS VBScript Report Object: Open, OpenReadOnly, and Close Methods

Siemens COMOS exposes a COM-scriptable automation layer that lets integrators and administrators drive the engineering database, P&ID drawings, and report generators from VBScript. The Document.Report interface is one of the most frequently used sub-objects because nearly every plant documentation deliverable (P&ID, datasheets, loop diagrams, materials reports) is generated as a Report. This reference covers the documented and field-verified methods on the Report object, how to detect an already-open report, how to close it cleanly, and the well-known OpenReadOnly licensing behavior that catches many first-time scripterers.

1. Overview of the COMOS Automation Object Model

COMOS scripts run inside the COMOS action catalog and are interpreted by the embedded VBScript engine bound to the COMOS type library. The top-level automation hierarchy from script perspective is:

Most automation code paths follow the pattern:

Dim oDoc, oReport
Set oDoc = COMOS.Project.Workset.GetObjectByNavigatorPath("P&ID\Unit_100\Reactor_R-101")
Set oReport = oDoc.Report
' ... use oReport methods ...
oReport.Close

The VBScript host runs in a STA (single-threaded apartment) and is synchronous. Long-running report operations (e.g. generating a 200-page P&ID) must be wrapped in COMOS.UI.ProcessEvents calls to keep the UI responsive.

2. Document.Report.Open — Edit Mode

Document.Report.Open opens the report for editing. The method takes an optional Boolean parameter controlling whether the document is brought to the foreground (default behavior depends on the calling context: from a navigator action, the report is usually focused; from a background script, it is opened in the current MDI frame).

Signature variants observed in the Class_Documentation_COMOS_dll_enUS.pdf reference:

' Parameterless variant
oReport.Open

' Variant with focus flag
oReport.Open True     ' bring to front

' Variant with mode flag (1 = edit, 2 = read-only with locking)
oReport.Open 1

2.1 Return Value and Error Behavior

Open returns a Boolean. True indicates the report was opened successfully. A return of False typically indicates one of:

• The report is already opened in write mode by another user (lock conflict).
• The current user does not have the report layer/attribute permission set.
• The report reference is to a deleted or uncommitted base object.
• A license check failed (most common with P&ID-specific reports; see section 6).

3. Document.Report.OpenReadOnly — Read-Only Mode

Document.Report.OpenReadOnly opens the report without acquiring a write lock. It is the recommended path for scripts that need to read attributes, traverse report pages, or extract data without modifying the document.

' Basic read-only open
Dim bOk
bOk = oReport.OpenReadOnly()
If Not bOk Then
    ' handle error
End If

' Open with foreground focus
bOk = oReport.OpenReadOnly(True)

3.1 Parameter Contract

The class documentation lists a single Boolean Focus parameter. Field experience (and the original COMOS development note referenced in the field report) confirms that calling OpenReadOnly with True as the focus flag is a supported pattern. Some sample scripts in the COMOS knowledge base pass the constant vbTrue for clarity.

3.2 What "Read-Only" Means in COMOS

Despite the name, OpenReadOnly does not open the document in a hardened view-only mode. The user can still edit the report in the UI. The "read-only" part refers to the database lock: no exclusive write lock is taken, so other users can continue to save. This is the source of a common operational confusion, especially around P&ID licensing (see section 6).

4. Document.Report.Close — Releasing the Report

Document.Report.Close closes the report. It accepts an optional Boolean that controls whether unsaved changes are silently discarded (False, the default in most observed sample scripts) or whether the user is prompted to save (True).

' Unconditional close (discard unsaved changes if present)
oReport.Close

' Close and prompt the user to save if dirty
oReport.Close True

4.1 Closing Sequence Best Practice

Always close reports in a deterministic order to avoid orphaned database connections. The recommended sequence is:

1. Call oReport.Save if changes were made.
2. Call oReport.Close (no parameter, or True if the user must be prompted).
3. Set the reference to Nothing: Set oReport = Nothing.

Skipping the Set ... = Nothing assignment is the most common cause of "ghost lock" symptoms in COMOS, where the database still considers the report locked even though no UI window is visible.

5. Detecting Whether a Report Is Already Open

COMOS does not expose a public IsOpen property on the Document object. Two field-verified techniques exist for detecting the open state from VBScript:

5.1 State-Enumeration Technique (preferred)

Every COMOS report carries an internal state flag that can be inspected through the Document.State property. The numeric value is > 0 when the document is currently opened in any mode (write, read-only, or background).

Function IsReportOpen(oDoc) 'As Boolean
    If IsNull(oDoc) Or IsEmpty(oDoc) Then
        IsReportOpen = False
        Exit Function
    End If

    Dim lState
    lState = CLng(oDoc.State)
    IsReportOpen = (lState > 0)
End Function

' --- usage ---
If IsReportOpen(oDoc) Then
    ' skip open attempt, or close first
    oDoc.Report.Close
Else
    oDoc.Report.Open
End If

5.2 Try-Open with Error Capture

When a pre-check is not possible, attempt the open and trap the COM error. This is slower but more robust because it covers lock conflicts that the State property does not surface (e.g. another workstation's lock):

Function TryOpenReport(oDoc) 'As Boolean
    On Error Resume Next
    Dim bOk
    bOk = oDoc.Report.Open()
    If Err.Number <> 0 Then
        TryOpenReport = False
        Err.Clear
    Else
        TryOpenReport = bOk
    End If
    On Error Goto 0
End Function

Error codes most frequently returned by Open when the report is already in use:

6. The OpenReadOnly / P&ID License Anomaly

The single most common operational problem reported when scripting Document.Report.OpenReadOnly against a P&ID is that the report opens in read/write mode and consumes a P&ID license token. The expected behavior is a license-free, read-only session.

6.1 Root Cause

The P&ID license is a workstation-scoped floating token managed by the Siemens License Server (SLS, formerly FLEXLM). COMOS requests the token the moment a P&ID report is loaded into the editor — regardless of the lock state — because the editing engine itself is licensed. OpenReadOnly in COMOS controls the database write lock, not the editor engine license. The two concepts are independent:

• Database write lock: Open acquires it; OpenReadOnly does not.
• P&ID editor engine license: any path that loads the report into the in-process editor requests it.

Therefore, a script calling OpenReadOnly on a P&ID document does check out a P&ID license token on the workstation running the script, even though the report is technically opened in a non-locking mode.

6.2 Workarounds

For headless batch operations that do not need the editor UI, use the database-only access path instead of the editor path. This bypasses the license check entirely.

' Read P&ID attributes without consuming a P&ID license
Function ReadPIDAttributes(oDoc, sAttrName)
    Dim oAttr
    Set oAttr = oDoc.Attributes(sAttrName)
    If Not oAttr Is Nothing Then
        ReadPIDAttributes = oAttr.Value
    Else
        ReadPIDAttributes = ""
    End If
End Function

For automation that does require the editor (page enumeration, layer visibility, dimension extraction), the only reliable workaround is to ensure the workstation running the script holds a P&ID license, or to centralize such scripts on a dedicated P&ID-enabled batch server.

6.3 Verifying License Behavior

Use the Siemens License Server web UI to confirm token checkout/release. The comos.log file in the workstation's %LOCALAPPDATA%\Siemens\Automation\COMOS\<version>\ directory records every license request with timestamps. Filter the log for the string PID-License to correlate with script activity.

7. Report Object Methods — Field-Verified Catalog

Beyond Open, OpenReadOnly, and Close, the COMOS automation type library exposes the following methods on the Document.Report object. They are not all enumerated in the public class documentation PDF; the table below combines the documented surface with field-verified behavior observed by integrators.

8. End-to-End Sample Script

The script below combines the techniques from sections 2–5 into a reusable subroutine. It is designed to be placed in a COMOS action (e.g. @C > Scripts > Utilities > Reopen Report) and run against a navigator selection.

Option Explicit

' ---- ReopenReport.vbs ----
' Reloads the currently selected report by:
'   1. Detecting if it is already open
'   2. Closing it safely (prompt for save)
'   3. Reopening it in write mode
'   4. Releasing the COM reference

Sub ReopenReport()
    Dim oSel, oDoc, oReport, lState, bOk

    Set oSel = COMOS.UI.Selection
    If oSel Is Nothing Then
        MsgBox "No navigator object selected.", vbExclamation
        Exit Sub
    End If

    Set oDoc = oSel.Item(0)
    If oDoc Is Nothing Then
        MsgBox "Selected object is not a document.", vbExclamation
        Exit Sub
    End If

    Set oReport = oDoc.Report
    If oReport Is Nothing Then
        MsgBox "Selected object has no Report interface.", vbExclamation
        Exit Sub
    End If

    ' 1. Detect open state
    lState = CLng(oDoc.State)
    If lState > 0 Then
        ' 2. Close with save prompt
        If Not oReport.Close(True) Then
            MsgBox "User cancelled close.", vbInformation
            Exit Sub
        End If
    End If

    ' 3. Reopen in write mode
    bOk = oReport.Open(True)
    If Not bOk Then
        MsgBox "Open failed. Check locks and licenses.", vbCritical
        Exit Sub
    End If

    ' 4. Release reference
    Set oReport = Nothing
    Set oDoc = Nothing

    MsgBox "Report reopened successfully.", vbInformation
End Sub

This script is intentionally defensive: it checks the State field, prompts before discarding work, surfaces COM errors to the user, and releases all object references. It is a good template for any COMOS automation that touches the Report object.

9. Cross-Reference With Statistical and Document Reporting

VBScript as an automation host is used not only inside COMOS but also in adjacent reporting contexts. The general pattern of open object → read/manipulate → close object → release is identical to the pattern used when VBScript drives a statistical report generator (for example, the technique described in Using VBScript For Perfecting Statistical Report). The shared discipline of pairing every Open with a deterministic Close and an explicit Set ... = Nothing release applies in both domains and is the most reliable way to avoid resource leaks.

10. Troubleshooting Matrix

11. Verification Checklist

After any change to a COMOS automation script that touches the Report object, run the following verification sequence before promoting the change to a production action:

1. Lock verification. Open the target report in a second COMOS client (read-only) and confirm that after the script closes, the second client can take a write lock without errors.
2. State verification. In the script, after Close, log oDoc.State and confirm it returns 0.
3. License verification. If the report is a P&ID, confirm the SLS shows the token released within one polling interval after the script completes.
4. Reference release. Confirm that no COMOS process retains a handle to the report (e.g. via Sysinternals Handle or the COMOS diagnostic view).
5. Error path verification. Re-run the script with the report already open in another session and confirm the expected error code is returned and handled.
6. Regression run. Re-run the script against a non-P&ID report (e.g. a datasheet) to confirm the same logic works across report types.

12. FAQ