# Compaq ACMS for OpenVMS
Managing Applications

Previous | Contents | Index

1. ACMS Log Report
   The name of the report.

2. Date and time
   The starting date and time for processing the report.
3. The criteria for selecting the records in the report. An asterisk (*) indicates that you did not use a criterion to select records. "ALL" indicates that you did not select records by record type.
4. File
   The information included to identify the source file, including the file name or file specification.
5. Type
   A listing of all records that meet your selection criteria. If you do not use qualifiers to select records for the report, the report contains all records in the input file.
6. End Report
   The time report processing concluded.

# 12.6 Selecting Audit Trail Records

Use LIST command qualifiers to select records from the Audit Trail Logger. Which qualifier or qualifiers you use depends on the kind of application or task information you want or on how much information you want.

The /SINCE and /BEFORE qualifiers let you select records by time range. The /APPLICATION, /IDENTIFICATION, /SUBMITTER, /TASK, /TERMINAL, /TYPE, and /USERNAME qualifiers each select records containing the information you include on the qualifier. For example, the /APPLICATION qualifier selects records containing the application name you include. Combinations of qualifiers further restrict the information in the report.

## 12.6.1 Selecting Records by Submitter and Task Identification Code

Every submitter that signs in to ACMS receives a submitter identification code, or submitter ID, that ACMS associates with the submitter until the submitter signs out. Every submitter ID is unique. Similarly, each task instance receives a task identification code, or task ID, that is also unique.

Use submitter and task IDs with operator commands and with the ATR LIST command. Submitter and task IDs on command qualifiers limit the scope of the command you use. For example, a submitter ID on the /SUBMITTER qualifier of the LIST command defines which audit trail records are extracted from the audit trail log.

Both a submitter ID and a task ID have the following format:

`<node::><local-id>--<sequence-no>--<boot-time1>--<boot-time2>`

A called task ID has the following format:

`<node::><local-id>--<sequence-no>--<boot-time1>--<boot-time2>--task-call`

For example, this is a submitter ID:

    CARAT::0455002C-00000000-F7B46260-008DEB44

This is a task ID:

    MYOHMY::0001002F-00000017-F7B46260-008DEB44

This is the task ID of a called task:

    MYOHMY::0001002F-00000017-F7B46260-008DEB44-00000001

The sequence number in a submitter ID is always zero. A dash (--) separates boot-time fields for readability, but both fields are considered one field. A task ID is the same as the task submitter's submitter ID, except that the sequence number field contains a hexadecimal number that is incremented for each task selection.

If a task is a called task (that is, a task called by another task) the task ID contains an additional field called the task-call field. The task call field is a hexadecimal number that is incremented each time a task calls another task. This field is only displayed for tasks called by other tasks.

Because the boot-time field is useful mainly in the Audit Trail Logger, ACMS does not display this field when you use ACMS operator commands. Because the sequence number field of a submitter ID is always zero, ACMS does not display the sequence number field either. The ACMS operator command display formats of the IDs are:

- Submitter ID display format:

  `<node::><local-id>`

  For example:

      NODE1::0455002C

- Task ID display format:

  `node::local-id--sequence-number--task-call`

  For example:

      NODE1::0455002C-0000001A-00000001

When you specify a submitter or task ID with an operator or ATR Utility command, any of the fields that you do not specify are implicitly wildcarded. A dash (--) separates fields, such as local-id and sequence-no, to allow you to omit leading fields. You can omit leading zeros in any of the fields, except the node field.

To see all current task instances submitted by task submitters on node ROW that are executing on your node, specify just the node name on the /SUBMITTER qualifier of the ACMS/SHOW TASK command. For example:

    $ ACMS/SHOW TASK/SUBMITTER=ROW::

To see what the first task selection was for each submitter in an Audit Trail Logger, specify only the sequence number field on the /IDENTIFIER qualifier of the LIST command. Because you are not specifying the local ID field, indicate that you are omitting that leading field by using a dash. For example:

    ATR> LIST/IDENTIFIER=-1

When you specify a full task ID, the report only contains records generated by that particular task.

## 12.6.2 Selecting Application Information

Use the /APPLICATION qualifier to create an audit log report of only application information.

## 12.6.3 Selecting Task Information

These qualifiers return information about ACMS tasks:

- /APPLICATION
- /BEFORE
- /IDENTIFICATION
- /SINCE
- /TYPE

The LIST command with the /TYPE=TASK qualifier causes the ATR Utility to display information about all tasks. Use the /IDENTIFICATION qualifier to display information about a particular task by specifying the task ID. See Section 12.6.1 for information on specifying a task ID. You can use more than one of these qualifiers on the LIST command to select information. For example, the /TASK qualifier and the /BEFORE and /SINCE qualifiers return information about tasks in a time range.

Example 12-3 provides output from the LIST/TYPE=TASK command. It includes records about two different tasks: DBMS_SINGLE_TASK is a task in the TESTB application and TSK0101R is a task in the TESTB application.

Example 12-3 Using the LIST/TYPE =TASK Command to Display Task Information

    ATR> LIST/TYPE=TASK

    (1)    ACMS Log Report   4_JAN_1991    (2)  16:05:08.02
        Type   : TASK
        Since  : *
        Before : *
        Appl   : *
        Task   : *            (3)
        ID     : *
        User   : *
        Sub    : *
        Term   : *
    (4)   File   : SYS$SYSROOT:[SYSERR]ACMSAUDIT.LOG;3
        ************************************************************
    (5)    Type   : TASK     (6) Time   :  1-JAN-1991 13:50:59.58
    (7)    Appl   : TESTB
    (8)    Task   : DBMS_SINGLE_TASK
    (9)    User   : LTUSER28
    (10)   ID     : CARAT::00010045-0000000A-38A21C80-008DDDE5
    (11)   Sub    : CARAT::00010045-00000000-38A21C80-008DDDE5
    (12)   Text   : Task started
        ************************************************************
        Type   : TASK         Time   :  1-JAN-1991 13:51:34.88
        Appl   : TESTB
        Task   : TSK0101R
        User   : LTUSER46
        ID     : CARAT::0001005B-00000013-38A21C80-008DDDE5
        Sub    : CARAT::0001005B-00000000-38A21C80-008DDDE5
        Text   : Task started
        ************************************************************
        Type   : TASK         Time   :  1-JAN-1991 13:50:59.58
        Appl   : TESTB
        Task   : DBMS_SINGLE_TASK
        User   : LTUSER28
        ID     : CARAT::00010045-0000000A-38A21C80-008DDDE5
        Sub    : CARAT::00010045-00000000-38A21C80-008DDDE5
        Text   : Task end
    (13)  Task completion status: Task completed normally
        ************************************************************
        Type   : TASK         Time   :  1-JAN-1991 13:51:34.88
        Appl   : TESTB
        Task   : TSK0101R
        User   : LTUSER46
        ID     : CARAT::0001005B-00000013-38A21C80-008DDDE5
        Sub    : CARAT::0001005B-00000000-38A21C80-008DDDE5
        Text   : Task end
        Task completion status: Task completed normally
        ************************************************************
        End Report  1-JAN-1991 14:10:40.27

1. ACMS Log Report
   The name of the report.
2. Date and time
   The date and starting time for processing the report.
3. The criteria for selecting the records in the report. An asterisk (*) indicates that you did not use a criterion to select records. "ALL" indicates that you did not select records by record type.
4. File
   The information you included to identify the source file, including the file name or file specification.
5. Type
   Type of audit record.
6. Time
   Date and time the record was written.
7. Appl
   Application name.
8. Task
   Task name.
9. User
   User name of the task submitter.
10. ID
    Task ID.
11. Sub
    Submitter ID.
12. Text
    Message text.
13. Task completion status
    Additional status text.

Use the /TASK qualifier to list information about particular tasks. The following command lists information about all tasks with the name DBMS_SINGLE_TASK:

    ATR> LIST/TASK=DBMS_SINGLE_TASK

If more than one application has a task with the name TSK0101R, use the /APPLICATION qualifier with the /TASK qualifier to return information about only one of these tasks. For example:

    ATR> LIST/TASK=TSK0101R /APPLICATION=TESTB

To return records involving only a particular task instance, use the /IDENTIFICATION qualifier. You only have to enter the node name and the first two long words to uniquely identify a task instance. This example uses the task identification code for the DBMS_SINGLE_TASK task from Example 12-3:

    ATR> LIST/IDENTIFICATION=CARAT::10045-A

This example shows how you can drop leading and trailing zeros from task identification codes; however, do not drop significant digits.

## 12.6.4 Selecting User Information

These qualifiers return information about ACMS users:

- /SUBMITTER
- /TERMINAL
- /TYPE=LOGIN
- /USERNAME

You can use more than one qualifier on a LIST command to return information. For example, to return information about sign-ins and sign-outs under one user name, use the /USERNAME qualifier and the /TYPE qualifier with the LOGIN keyword. Example 12-4 shows some sample output from a LIST command with these qualifiers.

Example 12-4 ATR LIST/USERNAME/TYPE Command

    ATR> LIST/USERNAME=PERSONNEL/TYPE=LOGIN

    (1)   ACMS Log Report   4_JAN_1991 (2) 15:24:49.88
        Type   : LOGIN
        Since  : *
        Before : *
        Appl   : *
        Task   : *              (3)
        ID     : *
        User   : PERSONNEL
        Sub    : *
        Term   : *
    (4)   File   : SYS$SYSROOT:[SYSERR]ACMSAUDIT.LOG;3
        ************************************************************
    (5)   Type   : LOGIN       (6)   Time   :  1-JAN-1991 13:04:50.16
    (7)   User   : PERSONNEL   (8)   Term   : TTA4:
    (9)   Sub    : ALLDAY::00020036-00000000-BCC34BC0-008DDDE4
    (10)  Text   : Login request
        ************************************************************
        Type   : LOGIN             Time   :  1-JAN-1991 13:04:55.95
        User   : PERSONNEL         Term   : TTA5:
        Sub    : ALLDAY::00270001-00000000-BCC34BC0-008DDDE4
        Text   : Login request
        ************************************************************
        Type   : LOGIN             Time   :  1-JAN-1991 13:05:19.05
        User   : PERSONNEL         Term   : TTA4:
        Sub    : ALLDAY::00020036-00000000-BCC34BC0-008DDDE4
        Text   : Successful login
        ************************************************************
        Type   : LOGIN             Time   :  1-JAN-1991 13:05:25.25
        User   : PERSONNEL         Term   : TTA5:
        Sub    : ALLDAY::00270001-00000000-BCC34BC0-008DDDE4
        Text   : Successful login
        ************************************************************
    (11)    End Report   4-JAN-1991 15:32:35.86

1. ACMS Log Report
   Name of the report.
2. Date and time
   The date and starting time for processing the report.
3. Criteria for selecting the records in the report. An asterisk (*) indicates that you did not use a criterion to select records. "ALL" indicates that you did not select records by record type.
4. File
   Information you included to identify the source file, including the file name or file specification.
5. Type
   Type of audit record.
6. Time
   Date and time the record was written.
7. User
   User name of the task submitter.
8. Term
   Device name.
9. Sub
   Submitter ID.
10. Text
    Message text.
11. End Report
    Date and time report processing concluded.

The display contains all records of sign-ins or sign-outs involving the user name PERSONNEL from the current version of the Audit Trail Logger.

Qualifiers let you find a small number of user records in the Audit Trail Logger containing the task submitter identification code from that session.

Example 12-4 contains two task submitter identification codes:

- ALLDAY::00020036-00000000-BCC34BC0-008DDDE4
- ALLDAY::00270001-00000000-BCC34BC0-008DDDE4

To display all records involving the user session identified by this submitter identification, use the following command:

    ATR> LIST/SUBMITTER=ALLDAY::20036

You have to type only the node name and the first longword to uniquely identify a submitter. You can even omit leading zeros from the first long word to make entry easier.

Example 12-4 contains records of sign-ins at two terminals: TTA4 and TTA5. To list sign-ins and sign-outs at the ACMS-controlled terminal TTA4, use the following command:

    ATR> LIST/TERMINAL=TTA4:

## 12.6.5 Creating an Audit Trail Record for the QTI Process

The Audit Trail Logger audits all ACMS operator commands that start, stop, or set the QTI or ACMS task queues. In addition, the Audit Trail Logger records all task invocations which fail. The audit trail record of failed task invocations shows the following:

- The error that caused the task invocation to fail
- What the QTI has done with the queued task element

Example 12-5 shows a sample QTI audit entry.

Example 12-5 QTI Audit Entry

    *****************************************************************************
    Type   : ERROR     Time   :  6-APR-1991 13:04:31.81
    Queue  : KEV_QUE
    ErrQue :
    Text   : Error processing queued task
    -ACMSQUE-E-ERRREADQ, Error reading the queue file
    -SYSTEM-F-ACCVIO, access violation, reason mask=00, virtual address=010E0007,
    PC=000009B0, PSL=5F56454B
    *****************************************************************************
    Type   : ERROR     Time   :  6-APR-1991 13:04:36.44
    Queue  : KEV_QUE
    ErrQue :
    Appl   : SWISS
    Task   : CHEESE
    User   : MCCARTHY
    Elem Id: 218001A3-00000002-D9F83F60-00910F15
    Text   : Error processing queued task
    -ACMSQUE-E-ERRGETPROC, Error returned from ACMS$GET_PROCEDURE_INFO
    -ACMS-E-NOSUCH_PKG, There is no such package defined
    -ACMSQUE-I-QTRETRY, Queued task will be retried later
    ****************************************************************************

See Chapter 8 for information about the operator commands which control the QTI and ACMS task queues. See Chapter 5 for information about managing task queues and queued task elements.

## 12.6.6 Creating an Audit Trail Record for Application Modification

When you enable application-level auditing and use the ACMS/MODIFY APPLICATION command, the audit trail records any application modifications you make in the Audit Trail Logger. As described in Chapter 9, you can use the ACMS/MODIFY APPLICATION command to modify task, application, or server attributes in active applications. Example 12-6 contains an audit trail record recording a change in the maximum number of task instances allowed in application AIR_REGISTER.

Example 12-6 Application Modification Audit Entry

    *******************************************************************
    Type   : COMMAND   Time   : 26-JAN-1991 16:52:38.00
    Appl   : AIR_REGISTER
    User   : KINK
    Text   : Attributes for application AIR_REGISTER have been modified
    Maximum number of task instances has been changed to 5
    *******************************************************************

See Chapter 9 for information about the ACMS/MODIFY APPLICATION command.

## 12.6.7 Creating an Audit Trail Record for Server Process Dump

If server process dumps have been enabled in the application definition and the server process stops unexpectedly, an OpenVMS process dump is generated and the event is recorded in an audit trail record. Example 12-7 is an example of an audit trail record containing server process dump information.

Example 12-7 Server Process Dump Audit Entry

    **************************************************************
    Type   : ERROR     Time   : 27-JAN-1991 09:46:04.95
    Appl   : SANDAPPL
    Text   : Server process death has generated a VMS process dump
    Process dump for server PROC_DUMP_SRV is
        DISK1$:[TWEP.TEST]PROC_DUMP_SRV.DMP;
    **************************************************************

Example 12-8 contains an example of an audit trail record generated when the attempt to generate a server process dump failed.

Example 12-8 Server Process Dump Failure Audit Entry

    **************************************************************
    Type   : ERROR     Time   : 27-JAN-1991 09:48:26.95
    Appl   : SANDAPPL
    Text   : Server process death has generated a VMS process dump
    Error writing process dump for server PROC_DUMP_SRV to
        SYS$SYSROOT:[SYSERR]PROC_DUMP_SRV.DMP;
    Insufficient privilege or file protection violation
    **************************************************************

See Compaq ACMS for OpenVMS Writing Applications for information about enabling server process dumps.

## 12.6.8 Audit Trail Record for Server Replacement

When you use the ACMS/REPLACE SERVER command to replace a server image in an application with a new version of that image, the event is recorded in the Audit Trail Logger. Example 12-9 is an example of an audit report generated by a server replacement.

Example 12-9 Server Replacement Audit Entry

    ************************************************************
    Type   : COMMAND   Time   : 26-JAN-1991 14:58:53.52
    Appl   : RULES_REGS
    User   : SANDY
    Text   : Replace Server
    Replace server command issued for RULES_REGS
    ************************************************************

For more information on the ACMS/REPLACE SERVER command, see Chapter 9.

## 12.6.9 Creating an Audit Trail Record for Insufficient Workspace Pool

If a user initiates a task, but the application execution controller (EXC) is unable to allocate sufficient memory for the task, the user receives an error and the event is recorded in the Audit Trail Logger. Example 12-10 shows an example of an audit trail record generated by insufficient workspace space.

Example 12-10 Insufficient Workspace Audit Entry

    ******************************************************************************
    Type   : TASK Time   : 26-JAN-1991 14:58:53.52
    Appl   : ORDER_ENTRY
    Task   : ORDER_ENTRY_TASK
    User   : OPER_42
    ID     : NODEA::00050021-00000002-3D208320-009113BE
    Sub    : NODEA::00050021-00000000-3D208320-009113BE
    Text   : Task start failed during initialization
    Error starting task: Unable to allocate workspace resources, please try later
    %ACMSWSP-E-ERRCTLPOO, Error allocating 132 bytes in TWSC pool 3 for workspaces
    %ACMSPOO-E-POOL_EXHAUSTED, Insufficient free memory available for request
    ******************************************************************************

See Chapter 11 for information about the causes of workspace pool allocation failures and how to correct such errors.

Previous | Next | Contents | Index