ACMSGEN commands allow you to change ACMS system parameters to define lower limits, quotas, process names, user names, proxy accounts, and priorities for components of ACMS. Table 11-4 lists the ACMSGEN commands and qualifiers and provides a brief description of each ACMSGEN command. For detailed information about ACMSGEN commands and qualifiers, see Chapter 22.

Table 11-4 Summary of ACMSGEN Commands

Commands and Qualifiers	Description
EXIT	Ends the ACMSGEN session and returns you to the DCL prompt.
HELP	Displays help information about ACMSGEN commands, parameters, and qualifiers.
SET	Places a new parameter value in the ACMSGEN work area.
SHOW /ACC /ALL /CP /EXC /MSS /QTI /TSC	Displays the value in the work area, the default value, the minimum value, the maximum value, the unit of measure, and the dynamic/fixed status for ACMS system parameters.
USE	Initializes the ACMSGEN work area with values from a work file.
USE ACTIVE	Initializes the ACMSGEN work area with active values for all parameters from an ACMS system global section.
USE CURRENT	Initializes the ACMSGEN work area with current values for all parameters from the SYS$SYSTEM:ACMSPAR.ACM parameter file.
USE DEFAULT	Initializes the ACMSGEN work area with ACMS default values for all ACMS parameters.
WRITE	Writes values from the ACMSGEN work area to a work file, creating a new version of the file.
WRITE ACTIVE	Changes active values for dynamic parameters by writing values from the ACMSGEN work area to an ACMS system global section.
WRITE CURRENT	Changes current values by writing values from the ACMSGEN work area to the SYS$SYSTEM:ACMSPAR.ACMS file.

This chapter explains how to use the Audit Trail Logger (ATL) and the Audit Trail Report (ATR) Utility to monitor the use and misuse of your application. See Section 12.9 for a summary of ATR commands and qualifiers. For reference information on the commands described in this chapter, refer to Chapter 23.

12.1 Understanding the Audit Trail Logger

The Audit Trail Logger records application and user activity in the audit trail log. The Audit Trail Logger records:

• ACMS system starts and stops
• ACMS application starts and stops
• User sign-ins and sign-outs
• What tasks users run and where they encounter errors
• What activities are taking place on distributed ACMS systems
• User errors
• Modifications to application, task, and server attributes
• Server process dumps
• Queued Task Initiator (QTI) process events
• Server image replacement
• Other significant events

The Audit Trail Logger is automatically started with the ACMS system. Disable the Audit Trail Logger by using the /NOAUDIT qualifier either on the ACMS/START SYSTEM command or the ACMS/SET SYSTEM command. When the Audit Trail Logger is disabled, it only records file opens and closes. Use the /AUDIT qualifier with either of these commands to reenable auditing.

Use the ATR Utility to display audit trail records or write them to an output file.

12.2 Using the Audit Trail Log File

Each time the ACMS system starts, it creates a new version of the audit trail log file. ACMS writes Audit Trail Logger information to the file SYS$ERRORLOG:ACMSAUDIT.LOG by default. The default protection for the audit trail log file is (S:RD,O:RWED,G:R). The Audit Trail Logger must have write access to the audit trail log file for you to start your ACMS system.

The Audit Trail Logger attempts to translate the following logical names, which you can define, and uses the values of the logical names for file allocation when ACMS creates the audit trail log file:

• ACMS$ATL_DEQ_BLOCKS --- The default extension quantity (DEQ) specifies the number of blocks to be added when the file is extended. Valid values are 0 through 65535.
• ACMS$ATL_ALQ_BLOCKS --- The allocation quantity (ALQ) specifies the number of blocks to be initially allocated when the log is created. Valid values are 0 through 4,294,967,295.

See the OpenVMS Record Management Services Reference Manual for additional information about these fields.

To write audit trail information to a different file on a disk or on a magnetic tape volume set, define the system logical name ACMS$AUDIT_LOG to point to that file. If you omit any parts of the file specification in defining the logical name, missing parts are supplied from SYS$ERRORLOG:ACMSAUDIT.LOG. For example, the following command defines the audit trail log file as ACMSAUDIT.LOG in the directory [ACMS.AUDIT] on SYS$DISK. The file name and file type are supplied by default.

$ DEFINE/SYSTEM ACMS$AUDIT_LOG SYS$DISK:[ACMS.AUDIT]

Note the logical must be a system logical so that the Audit Trail Logger has access to it.

If you write audit trail information to a file on disk, take the steps needed to process audit trail log files as ACMS creates them. For example, you can purge audit trail log files or store them on a separate volume.

If the Audit Trail Logger runs out of space for audit trail information on disk, the audit trail logs the error in the software event log (generated by SWL), and the Audit Trail Logger process stops. ACMS sends a message to ACMS operator terminals. Restart the Audit Trail Logger process with the ACMS/SET SYSTEM /AUDIT command or the ACMS/RESET AUDIT command.

If you write audit trail information to a magnetic tape volume set, define the logical name ACMS$AUDIT_LOG to point to a file specification of the form:

MTxn:name.ext

The components of this file specification are:

• MT --- Device type for a magnetic tape drive
• x --- Controller code for the tape drive
• n --- Unit number of the tape drive
• name --- File name for the log file
• ext --- File type for the log file

The following command defines ACMS$AUDIT_LOG to point to ACMSAUDIT.LOG on the magnetic tape mounted on the MTA0 device:

$ DEFINE /SYSTEM ACMS$AUDIT_LOG MTA0:

The default file name and file type are taken from the file specification SYS$ERRORLOG:ACMSAUDIT.LOG.

If you write audit trail information to magnetic tape, load and initialize the magnetic tape before you start the ACMS system. If you do not, the ACMS/START SYSTEM command can time out before the initialization is complete. Initialize the magnetic tape with a volume name the same as the first six characters of the file name for the audit trail log file. For example:

$ INIT MTA0: ACMSAU

If the file name is longer than six characters, the Audit Trail Logger truncates the volume name to six characters. Do not use the MOUNT command after initializing the tape. ACMS logically mounts the magnetic tape when it starts the Audit Trail Logger. If the tape is already mounted, ACMS returns a fatal error on the ACMS/START SYSTEM command.

If the Audit Trail Logger is logging information to magnetic tape, and the end of volume is encountered, OpenVMS sends a message to OpenVMS operator terminals asking the operator to mount the next volume in the volume set. The operator loads the tape on the drive, initializes and mounts the volume, and responds to the operator request with a DCL REPLY command. The Audit Trail Logger then logs information to the new volume.

For information about magnetic tapes, see OpenVMS System Manager's Manual: Essentials. For information about the REPLY command, see the OpenVMS DCL Dictionary.

12.3 Events Recorded by the Audit Trail Logger

The Audit Trail Logger logs the following types of events:

• Flagged events --- Events flagged when auditing is enabled using the application-level AUDIT clause or subclause, or with the AUDIT keyword in ACMS operator commands.
• Default events --- Events that the Audit Trail Logger logs regardless of application definition or operator command. Table 12-1 marks default events in the "When Recorded" column with the word "Always".

Table 12-1 shows the events logged by the Audit Trail Logger, an explanation of recorded events, and the conditions under which events are recorded.

Table 12-1 Events Logged by the Audit Trail Logger

Events Recorded	Explanation	When Recorded
Abnormal terminations of applications	Stopping of applications for any reason other than ACMS/STOP SYSTEM or ACMS/STOP APPLICATION commands	Always
Abnormal terminations of server processes	Stopping of server processes due to error	Always
ACMS errors	ACMS system internal errors	Always
Application starts and stops	Each use of ACMS/START APPLICATION and ACMS/STOP APPLICATION commands	Always
Application modifications	Each use of the ACMS/MODIFY APPLICATION command	Application auditing enabled
Open new audit trail log file	Each use of an ACMS/RESET AUDIT command	Always
Enabling and disabling of the Audit Trail Logger	Each use of the ACMS/SET SYSTEM, ACMS/START SYSTEM, or ACMS/STOP SYSTEM command to enable or disable the Audit Trail Logger	Always
Enabling and disabling of ACMS operator terminals	Each use of the ACMS/SET SYSTEM command to enable or disable ACMS operator terminal	Always
Error allocating ACMS-controlled terminals	Why an ACMS-controlled terminal was unable to be allocated by the ACMS terminal subsystem controller	Always
Errors returned or signaled by cancel handling procedures	Each error encountered by user-written cancel handlers	Always
Errors returned or signaled on initialization and termination procedures	Each error encountered by user-written initialization and termination procedures	Always
Errors signaled by processing steps	Each error signaled during a processing step	Always
Failure to start a server process	Why a server process failed to start	Always
Sign-ins and sign-outs	Who signed in to or out of ACMS and at what time	Always
Queue starts and stops	Each use of the ACMS/START QUEUE, or ACMS/STOP QUEUE commands	Always
Queue modifications	Each use of the ACMS/SET QUEUE command	Always
Queued task failures	Each error that caused the task invocation to fail	Always
Server replacement	Each use of the ACMS/REPLACE SERVER command	Always
System starts and stops	Each use of ACMS/START SYSTEM or ACMS/STOP SYSTEM command	Always
Task calls	Tasks called by other tasks	Task subclause
Task chains	Tasks chained to from another task	Task auditing enabled
Task cancellations	Tasks canceled by any method	Task auditing enabled
Composed task transaction aborts	When a composed task transaction was aborted	Always
Task completions	Completed tasks, who completed each task, and when	Always
Task selections	Each task selected by a user	Task auditing enabled
User errors not elsewhere reported	User errors, including errors ACMS cannot report back to the user	Always
Submitter authentications in remote applications	As a security measure, when a submitter first selects a task in a remote application, the submitter is authenticated by the application execution controller (ACC) on the submitter node	Always

Use ATR commands to read the events recorded in the audit trail log file or to produce a report that lists the events. The following sections describe how to run the ATR Utility and use ATR commands.

12.4 Running the ATR Utility

Use either of the following commands to run ATR:

$ RUN SYS$SYSTEM:ACMSATR ATR>

or

$ MCR ACMSATR ATR>

You can also enter ATR Utility commands from DCL level by defining ATR as a DCL foreign command. For example:

$ ATR:==$SYS$SYSTEM:ACMSATR

Place this command in your login command file to permanently define this foreign command. Once you define ATR as a DCL foreign command, you can use ATR commands from DCL. For example:

$ ATR LIST /APPLICATION=EXEX_APPL /BEFORE=14-JAN-1991

When you see the ATR> prompt, enter ATR commands. Use the LIST command to display or list audit trail records. Use the HELP command to get information about ATR commands. For example:

ATR> HELP LIST

Instead of typing ATR commands, you can use keypad keys to enter commands. Press [PF1] and [PF2] for access to the ATR keypad. Press [Ctrl/B] to recall the last 20 ATR commands you enter (one at a time).

When you are finished using the ATR Utility, type EXIT or press [Ctrl/Z] to return to DCL:

ATR> EXIT $

In DCL, get help information about the ATR Utility by using the following HELP command:

$ HELP @ACMSATR

12.5 Creating Log Reports

The ATR Utility LIST command generates an ACMS log report consisting of records from the Audit Trail Logger. Include a file specification with the LIST command to identify a concatenated file containing several audit trail log files, or omit the file specification altogether. If you omit the file specification, ATR searches for a translation for the logical ACMS$AUDIT_LOG. If ACMS$AUDIT_LOG is not defined, ATR uses the default file specification, SYS$ERRORLOG:ACMSAUDIT.LOG.

12.5.1 Creating Full Log Reports

The LIST command with the /OUTPUT qualifier writes full Audit Trail Logger reports to a listing file. If you do not use the /OUTPUT qualifier, the ATR Utility displays information on the terminal.

Example 12-1 provides an sample log report containing a full version of each record in the audit trail log file. Instead of displaying the entire log file on your terminal as shown here, use the /OUTPUT qualifier to send the output to a listing file.

Example 12-1 ATR LIST Command

ATR> LIST (1) ACMS Log Report 5_JAN_1991 (2)10:08:08.83 Type : ALL 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 12:16:55.00 (7) Appl : TEST (8) Task : TSK1M2 (9) User : LTUSER2 (10) ID : CARAT::00010036-00000001-47E6F8C0-008DDDDE (11) Sub : CARAT::00010036-00000000-47E6F8C0-008DDDDE (12) Text : Task started ************************************************************) Type : TASK Time : 1-JAN-1991 12:17:19.06 Appl : TEST Task : TSK1M2 User : LTUSER2 ID : CARAT::00010036-00000001-47E6F8C0-008DDDDE Sub : CARAT::00010036-00000000-47E6F8C0-008DDDDE Text : Task end Task completion status: Task completed normally ************************************************************ (13) End Report 1-JAN-1991 13:09:01.41

The following is a description of the numbered items in Example 12-1.

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 included to identify the source file, including the file name or file specification.
5. Type
   The type of information in the record.
6. Time
   The time the record was created.
7. Appl
   The application name for an active task.
8. Task
   The name of the active task.
9. User
   The OpenVMS user name of the user who submitted the task.
10. ID
    The ACMS task identification code for one task instance.
11. Sub
    The ACMS task submitter identification code for an ACMS user running a task.
12. Text
    A description of the event recorded.
13. End Report
    The date and time that report processing concluded.

The /BRIEF qualifier limits how much information is included in the report. Each record in a brief report contains the time of the entry in the Audit Trail Logger and the type of information in the entry. For information about record types, see the description of the /TYPE qualifier. The default is to include full records in the report. Example 12-2 provides an example of an ACMS log report containing a brief version of each record in the Audit Trail Logger.

Example 12-2 ATR LIST/BRIEF Command

ATR> LIST/BRIEF (1) ACMS Log Report 5_JAN_1991 (2) 10:01:02.74 Type : ALL Since : * Before : * Appl : * Task : * (3) ID : * User : * Sub : * Term : * (4) File : SYS$ERRORLOG:RWGAUDIT.LOG;3 ************************************************************ Type : OTHER Time : 1-JAN-1991 11:57:35.03 Type : COMMAND Time : 1-JAN-1991 11:57:42.97 Type : COMMAND Time : 1-JAN-1991 11:59:05.42 Type : LOGIN Time : 1-JAN-1991 11:59:34.61 Type : LOGIN Time : 1-JAN-1991 11:59:35.63 Type : LOGIN Time : 1-JAN-1991 11:59:42.04 Type : LOGIN Time : 1-JAN-1991 11:59:43.05 Type : TASK Time : 1-JAN-1991 12:00:55.00 Type : TASK Time : 1-JAN-1991 12:00:55.92 (5) Type : TASK Time : 1-JAN-1991 12:01:06.52 Type : TASK Time : 1-JAN-1991 12:01:09.39 Type : LOGIN Time : 1-JAN-1991 12:02:15.76 Type : TASK Time : 1-JAN-1991 12:02:16.53 Type : TASK Time : 1-JAN-1991 12:02:18.22 Type : LOGIN Time : 1-JAN-1991 12:02:19.82 Type : TASK Time : 1-JAN-1991 12:02:19.87 Type : LOGIN Time : 1-JAN-1991 12:02:19.98 Type : TASK Time : 1-JAN-1991 12:02:20.81 Type : TASK Time : 1-JAN-1991 12:02:22.15 (6) End Report 5-JAN-1991 10:01:58.42

A brief log report consists of a header and one or more records. The following is a description of the numbered items in Example 12-2.