AUDIT - Control audit mode

General

Application area:	Debugging aids; see "Debugging aids"
Macro type:	Type S, MF format 1: standard/L/D/E form; see "S-type macros"

No symbolic names are generated in the data area in the case of MF=L.

The function harware AUDIT (see below) is only available on /390 servers. On other BS2000 servers the function does return RC=0, but it is not executed.

Macro description

The AUDIT macro offers the user functions for program auditing.

The linkage AUDIT is available in addition to the hardware AUDIT. Both these functions permit tracing of the program run by recording either the addresses of branches performed (hardware AUDIT) or the destination addresses of subprogram branches (linkage AUDIT). The two functions are mutually independent.

The hardware AUDIT enters the source addresses for each branch performed in an AUDIT table, whereas the linkage AUDIT enters the branch destination addresses in the AUDIT table on execution of the BASR, BALR, BASSM and BAKR commands. The linkage AUDIT thus makes it possible to record all the subprograms called within the program run, provided that they were called using one of the above commands.

Separate AUDIT tables are created for the hardware and linkage AUDIT and identified accordingly in the header line on output. An AUDIT table consists of 64 word-length entries for the hardware AUDIT and 1024 entries for the linkage AUDIT and is cyclically overwritten unless specified otherwise. The macro may refer to the entire run of a task or all tasks or be restricted to one process within its own task (e.g. contingency process). The linkage AUDIT may also be processor-local.

It is possible to permit or prohibit the hardware AUDIT and the linkage AUDIT

• For an entire session
  Control is achieved via the system parameter AUDALLOW=YES/NO.
  If any local linkage AUDIT has been activated, it is deactivated if the system parameter AUDALLOW=NO has been set.
  The hardware AUDIT and the linkage AUDIT can only be controlled in combination.

• For a user ID
  Control is performed using the operand HARDWARE-AUDIT or LINKAGE-AUDIT= *UNCHANGED / *NOT-ALLOWED / *ALLOWED in the MODIFY-USER-ATTRIBUTES or ADD-USER command.

• For a task
  Control is performed using the operand HARDWARE-AUDIT or LINKAGE-AUDIT= *UNCHANGED / *NOT-ALLOWED / *ALLOWED in the MODIFY-TEST-OPTIONS command.

The AUDIT macro is rejected with return code X'81003C' if the hardware and linkage AUDITs are not permitted.

Comments on the local linkage AUDIT

The linkage AUDIT is used for the CPU-specific activation of the linkage AUDIT for all the active CPUs or all the logical machines of a server configuration. For each CPU, a trace table is created in privileged class 3 memory and this is maintained throughout the entire session. The linkage AUDIT can be activated or deactivated via the parameter service during the startup phase. System administration can use the /START-LINKAGE-AUDIT/STOP-LINKAGE-AUDIT commands and the AUDIT macro to activate/deactivate the local linkage AUDIT during the session.

Macro format and description of operands

AUDIT

FCT=HWA / LNKA

,SCOPE=TASK / FUNCT / ALLTASK / SIHGLOB / SYSGLOB

,STATE=USER / SYS / PROC

,ACTION={ON [,SAVE=n] / OFF / CONT / DISC / GET [,TABLE=addr]}

[, {TID=tid / TSN=tsn }]

[,PARMOD=31]

,MF=S / L / (E,..) / D

,ID=AUD / pre

The operands are described in alphabetical order below.

ACTION=
Specifies the desired AUDIT operation: activate/deactivate, interrupt, continue or output.

ON
The 64-word (256-byte) or 1024-word (4096-byte) AUDIT table is created (if not already present), and initialized by overwriting any existing entries with binary zero. The current pointer is set to the beginning of the table and AUDIT mode is activated.
If the AUDIT table already exists, the current pointer is set after the last entry or, if the table is already full, to the beginning of the table (cyclic overwriting), and AUDIT mode is activated.

OFF
Deactivates AUDIT mode and releases the AUDIT table and the save table, if present. If the AUDIT table was copied via the GET operand to a memory area designated by the user, this area is retained until the program is terminated. The SCOPE=FUNCT operand may not be specified; the SAVE operand is ignored.

CONT
Reactivates the AUDIT following a preceding ACTION=DISC call. Auditing to the AUDIT table is resumed from the point at which it was interrupted by the ACTION=DISC call. If a save table is present it continues to be used for saving the AUDIT tables.

This operand can only be specified in conjunction with SCOPE=TASK. If no AUDIT is active at the time of the CONTINUE call, it is activated for the specified processor state (USER or SYS) for the entire task. The operands TID and TSN may not be specified. The SAVE operand is ignored.

DISC
Deactivates AUDIT mode while retaining the AUDIT table and the save table, if present. The DISCONTINUE function can be used only for the entire run of the user's own task (SCOPE=TASK); the operands TID and TSN may not be specified; the SAVE operand is ignored.

GET
Only permitted if SCOPE=TASK; the SAVE operand is ignored

For FCT=HWA:
The 64-word hardware AUDIT table (excluding the save table) is copied to the memory area designated by the user by means of the virtual address specified in the TABLE operand.
Unlike the SHOW command, the contents of the AUDIT table are read in in unchanged chronological order.

For FCT=LNKA:
All the linkage AUDIT trace information (AUDIT and save table) is copied to the memory area designated by the user in the linkage AUDIT data area by means of the virtual address audTAB and the length audLBUF The last AUDIT table entry appears at the beginning of the output.

In the linkage AUDIT, the address and length of the transfer buffer must be stored in the audTAB or audLBUF fields. Note that the address and length of the transfer buffer cannot be specified directly in the macro; instead they must be entered in the parameter list using the L form. In addition to the AUDIT table, the address of the next free entry in the transfer buffer is returned in the audTABE field. If the buffer is full, the end address of the buffer is returned. If the interface is called with ACTION=GET and the value
X'00000000' in the audTAB field, the buffer size for a subsequent GET call is returned in the audLBUF field. If the transfer buffer specified in the audTAB field is too small, the request will only be partially carried out. The linkage AUDIT table is transferred only with the length specified in the audLBUF field. The return code X'400020' is returned in addition.

FCT=
This operand specifies the AUDIT function to which the following parameters refer.

HWA
The AUDIT macro refers to the hardware AUDIT.

LNKA
The AUDIT macro refers to the linkage AUDIT.

MF=
For a general description of the MF operand, its operand values and any subsequent operands (e.g. for a prefix), see "S-type macros". The valid MF values are given at the start of the macro description under “Macro type” and are included in the macro format.
If MF=D or MF=L, a prefix ID (pre = 1..3 letters) can be specified, as shown in the macro format.

PARMOD=
This parameter is unnecessary and is still supported for compatibility reasons only. In general only the 31-bit interface is generated regardless of the operand specified.

Note: 24-bit coding that has already been generated will, of course, remain executable.

SAVE=
Creates a save area (save table) for the AUDIT table in the privileged class 5 memory of that task which is to be monitored with AUDIT (with TU), or in the privileged class 3 memory (with TPR). This save area accepts the contents of the AUDIT table before it is cyclically overwritten. This increases the requestable amount of AUDIT information.
This operand is effective only if specified in conjunction with ACTION=ON and only if no AUDIT table is yet available (e.g. after ACTION=OFF).

n
Specifies the number of 4K pages for the save area.
With nonprivileged logging of the processor state TU, integer values of 0 <= n <= 16 may be specified for n. A maximum of 64K can be requested for the save area, corresponding to the size of 256 hardware AUDIT trace tables or 16 linkage AUDIT trace tables.

With privileged logging of the processor state TPR using the hardware AUDIT, only the values 0 and 1 are meaningful for n; greater values (n > 1) are replaced by the value 1. A maximum of 4KB can therefore be requested for the save area for TPR in the hardware AUDIT, corresponding to the size of 16 AUDIT trace tables.
This operand may not be specified for privileged logging of the processor state TPR using the linkage AUDIT or if SCOPE=SIHGLOB/SYSGLOB is specified.

SCOPE=
Specifies the program area to be logged.

Note
An AUDIT job of a very large program area or a higher PCB replaces that of a smaller program area or a lower PCB (e.g. TASK replaces FUNCT), but not vice versa.

TASK
The requesting task or the task specified in the TID or TSN operand is to be logged.

FUNCT
The PCB-specific function to be logged is that function which refers to the highest interrupted PCB of the processor state specified in the STATE operand. FUNC is permitted for the user's own task only and if ACTION=ON is specified. The operands TID and TSN may not be specified.

ALLTASK
All branch addresses belonging to the processor state TPR are to be logged with all tasks. If the TID or TSN operands are listed at the same time this leads to an error message. The SAVE=n entry is ignored if FCT=HWA is specified. SAVE=n may not be specified if FCT=LNKA (see SAVE operand). If necessary, ALLTASK first switches off an active task-wide hardware audit in every task and then switches it back on without the save table.
If the task-wide TPR linkage AUDIT is already switched on for a task, it is not changed by the ALLTASK function.
If a task-wide hardware audit is inactive, it is not switched off and the save table is retained. If new tasks are added, the AUDIT is generally activated for these without the save table.
This value can only be entered under the system administration ID (TSOS).

SIHGLOB
All branch addresses of the processor state SIH are logged in a processor-local AUDIT table. This specification is permitted only in conjunction with FCT=LNKA,
STATE=PROC and ACTION=ON/OFF. The operands TID, TSN and SAVE may not be specified.
This value can only be entered under the system administration ID (TSOS).

SYSGLOB

All branch addresses of the processor states SIH and TPR are logged in a processorlocal AUDIT table. SCOPE=SYSGLOB may only be used if no privileged linkage AUDIT is activated in any task throughout the system or no TPR linkage AUDIT is in the 'DISCONTINUE' state. This specification is permitted only in conjunction with FCT=LNKA, STATE=PROC and ACTION=ON/OFF. The operands TID, TSN and SAVE may not be specified.
This value can only be entered under the system administration ID (TSOS).

STATE=
Processor state (TU, TPR or SIH) to which the scope specified in the SCOPE operand refers. If more than one processor state is to be logged simultaneously, the macro must be called a number of times.

USER
The scope specified in the SCOPE operand refers to the processor state TU (USER). The operand value P1 is still supported for reasons of compatibility and for the hardware AUDIT only. Default for SCOPE=FUNCT and SCOPE=TASK.

SYS
The scope specified in the SCOPE operand refers to the processor state TPR (SYS). The operand value P2 is still supported for reasons of compatibility and for the hardware AUDIT only. Default and mandatory for SCOPE=ALLTASK.
This value can only be specified under the system administration ID (TSOS).

PROC
The scope specified in the SCOPE operand is processor-local and refers to the SIH processor state or SIH and TPR. This specification is permitted only in conjunction with FCT=LNKA. Default and mandatory for SCOPE=SIHGLOB/SYSGLOB.
This value can only be specified under the system administration ID (TSOS).

TABLE=
Specifies the address to which the contents of the hardware AUDIT table are to be written. This may only be specified for hardware AUDIT and in conjunction with ACTION=GET.

addr
Virtual memory address which must point to a previously assigned memory area with write access authorization. Address 0 must not be specified.
(addr can be specified by 1 to 8 hexadecimal digits or by the appropriate number of decimal digits).

It is helpful to enter only a dummy value for the TABLE operand and then to overwrite the audTAB with the appropriate address dynamically in the program.

In the linkage AUDIT the transfer of AUDIT trace information to a user area is controlled exclusively by the GET operand.

TID=
Specifies the task which is to be monitored with AUDIT by its internal task number. The operand may only be specified together with SCOPE=TASK (see also the note for the TSN operand).

tid
Internal task number; can be specified in the followinf form:

h[hhhhhhh]:

1-8 hexadecimal digits, which the system pads out to 8 places with leading zeros as necessary.

TSN=
Specifies the task which is to be monitored with AUDIT by its job number.

tsn
Job number (TSN); can be specified as follows:

n[nnn]:	1-4 digits, which the system pads out with leading zeros to 4 places as necessary
a[aaa]:	1-4 alphanumeric characters, which the system pads out with leading zeros to 4 places as necessary
c'a[aaa]':	1-4 characters, which the system pads out with leading zeros to 4 places as necessary (user-specified blanks are retained)

Notes

• If neither of the two operands TID or TSN is specified, the AUDIT request applies to the requesting task itself.
  The TID or TSN operand may be specified only in conjunction with SCOPE=TASK. The ACTION=DISC and ACTION=CONT operands are not permitted in conjunction with the TID or TSN operand.

Return information and error flags

R15:

+---------------+
|   |   |   |   |
|0|0|a|a|a|a|a|a|
+---------------+

A return code relating to the execution of the AUDIT macro is transferred in register R15.

X'aaaaaa'	Meaning
X'000000'	a) The requested action was accepted b) The requested action was ignored because AUDIT is already running (ACTION=ON) c) The requested action was ignored because AUDIT is not running (ACTION=DISC) d) The requested action was ignored because no AUDIT table has been allocated (ACTION=OFF) e) The requested action with SCOPE=FUNCT was ignored because AUDIT has already been activated for SCOPE=TASK f) The requested action was ignored because the hardware AUDIT is not available onthis hardware. g) A SAVE- or TABLE-operand may have been ignored.
X'000004'	Operand error. The generated data area contains illegal operand combinations, or the user or the program is not privileged for the action requested
X'000008'	The address of the data area is invalid, or the data area is not aligned on a word boundary, or an internal error occurred
X'00000C'	The address in the TABLE operand (table transfer area) is invalid or the area is readonly
X'000010'	Insufficient memory is available for either class 3 original tables, class 4 management areas, class 5 save tables or class 5 management areas. The AUDIT action cannot be executed
X'000014'	The task with the specified TID or TSN does not exist
X'000018'	The PCB addressed by SCOPE=FUNCT does not exist
X'01FFFF'	The UNIT or FUNCTION number specified in the standard header is invalid. Processing is aborted
X'03FFFF'	Invalid version number in the standard header
X'400020'	The table transfer area for the linkage AUDIT table (ACTION=GET) is too small. Execution of the function was incomplete
X'400024'	The function could not be executed because a)a processor-local linkage AUDIT is running (STATE=SYS) or b)a linkage AUDIT is running in the TPR processor state (STATE=PROC) or c)a processor-local SIH linkage AUDIT is running (SCOPE=SYSGLOBE) or d)a processor-local SIH and TPR linkage AUDIT is running (SCOPE=SIHGLOB)
X'400028'	The TU save table is not contained in the transfer buffer due to an internal AUDIT error.
X'40002C'	The task identified by means of its TID or TSN is terminating. The job was rejected.
X'810030'	The macro call sequence AUDIT FCT=HWA,ACTION=ON/-OFF/-ON for an external task in TPR always produces this return code in the second ACTION=ON if the external task has not been executed in the meantime. This means that the second macro call with ACTION=ON must be repeated later because the macro call with ACTION=OFF is still in a queue.
X'810034'	Macro call AUDIT FCT=HWA/LNKA,STATE=U System administration has locked the hardware or linkage AUDIT for the active user ID using the /MODIFY-USER-ATTRIBUTES command.
X'810038'	Macro call AUDIT FCT=HWA/LNKA,STATE=U The user has locked the hardware or linkage AUDIT for the active task using the /MODIFY-TEST-OPTIONS command.
X'81003C'	Macro call AUDIT FCT=HWA/LNKA System administration has prohibited all AUDIT macro calls for the current session by specifying the parameter AUDALLOW=NO in the startup parameter service.
X'81FFFF'	The central linkage AUDIT management is currently locked (please wait and repeat the job at a later time).