audit(1) — Commands
Digital
NAME
AUDIT − statement in a task that posts information to the event log server
SYNOPSIS
[ <label-name>: ] AUDIT <audit-information> [, ...]
PARAMETER
•label-name
An internal unqualified identifier associated with the statement, for use in flow control operations.
•audit-information
A workspace name, workspace field, or literal string.
DESCRIPTION
If the AUDIT statement refers to any transactional workspace fields in a noncomposable task, it must be enclosed by a transaction block
The ACMSxp system posts audit information independently of the transaction.
To extract from the TPsystem system log information generated by the AUDIT statement and generate a file with the audit information, use the acmslog -f stdl -o command. The STDL data type definition format for the audit information is:
TYPE audit RECORD
event-time TEXT SIZE 17;
source INTEGER;
procedure TEXT SIZE 32;
interface TEXT SIZE 32;
tp-system TEXT SIZE 256;
device TEXT SIZE 256;
data-length INTEGER;
data-buffer ARRAY SIZE 0 to 32768 DEPENDING ON data-length OF OCTET;
END RECORD;
The following are the details for the fields in the audit event data type definition.
event-time17-character text field representing the time at which the audited event occurred. The format is:
yyyymmddhhmmssmmm
where:
yyyy is the year, with a value of 0000 through 9999
mm is the month, with a value of 01 through 12
dd is the day, with a value of 01 through 31
hh is the hour, with a value of 00 through 23
mm is the minute, with a value of 00 through 59
ss is the second, with a value from 00 through 59
mmm is the millisecond from 000 to 999
sourceInteger indicating where the audit record was generated:
0 indicates that the ACMSxp system generated the audit record
1 indicates that the task generated the audit record, containing application audit information
task-name32-character text field containing the name of the task that produced the audit record. Taken from the SYSTEM-INFO-WORKSPACE for the current task.
task-group-name32-character text field containing the name of the task group that produced the audit record. Taken from the SYSTEM-INFO-WORKSPACE for the current task.
tp-system-name256-character text field containing the symbolic address for the system that produced the audit record. Taken from the SYSTEM-INFO-WORKSPACE for the current task.
default-device256-character text field containing the display name for the submitter’s device. Taken from the SYSTEM-INFO-WORKSPACE for the current task.
data-lengthInteger field containing the length of the optional data associated with the audit record. For the application audit records generated by the AUDIT statement, the length represents the total length of all workspaces, workspace fields, and literals specified in the AUDIT statement.
audit-dataVariable-length array of octets containing the optional data associated with the audit record.
The normal execution flow for an AUDIT statement is to write to the event log and to complete with default flow control. The write operation to the audit log is nontransactional.
Deviations from the normal execution flow occur when one of the conditions listed in the Exceptions section occurs. The AUDIT statement completes with that exception. A write to the event log file may or may not occur.
In the ACMSxp system, an event filter on application servers controls the type of information logged. When a server is created, by default, the event filter is set to record audit events. If the event filter on the application server does not have audit set, no audit information is logged.
The ACMSxp software tries to avoid losing event records. If there is a problem communicating with the event log server, the application server writes the event data directly to the TPsystem event log file. If there is still a problem, the server writes the event data to a standard output log file.
See the acmslog man page for information about the command to access log files and extract audit event records.
EXCEPTIONS
The AUDIT statement can generate the exception classes described in the following sections. The sections describe the conditions leading to the exception class and suggest actions to take.
AP-EXECUTION-FAULT
The AP-EXECUTION-FAULT exception class indicates one of the following error conditions:
oThe subscript used to refer to an element in a fixed-length array is invalid (referring to A(n) where n is less than one or n is greater than the maximum size of array).
oThe subscript used to refer to an element in a variable-length array is invalid (referring to A(n) where n is less than one or n is greater than the value of the DEPENDING ON field).
oThe value of the DEPENDING ON field used when referring to an element of a variable-length array is invalid.
The DEPENDING ON field value is less than the minimum size of the array or is greater than the maximum size of the array.
oThe value of the DEPENDING ON field was invalid when referring to a workspace name or workspace field containing a variable-length array.
ENV-EXECUTION-FAULT
The ACMSxp system in which the task is executing is unable to write the audit information to the event log file.
EXAMPLES
The following example shows the use of the AUDIT statement.
AUDIT SYSTEM-INFO-WORKSPACE.TASK-NAME;
AUDIT SYSTEM-INFO-WORKSPACE.TASK-GROUP-NAME;
AUDIT SYSTEM-INFO-WORKSPACE.TP-SYSTEM-NAME;
AUDIT SYSTEM-INFO-WORKSPACE.DISPLAY-NAME;
AUDIT SYSTEM-INFO-WORKSPACE.DISPLAY-TP-SYSTEM;
AUDIT SYSTEM-INFO-WORKSPACE.ACTIVATION-TIME;
These statements log information from the ACMSxp system workspace SYSTEM-INFO-WORKSPACE.
RELATED INFORMATION
Command: acmslog(1)
Syntax: statement(1), transaction_block(1), workspace(1)