Start hardware AUDIT mode
Component: | BS2000 |
Functional area: | AUDIT mode control |
Domain: | PROGRAM |
Privileges: | STD-PROCESSING |
Function
The START-HARDWARE-AUDIT command controls the AUDIT mode for the processor state TU (task unprivileged) or TPR (task privileged). The branch instruction addresses are entered into the AUDIT table.
Hardware AUDIT mode is terminated with the STOP-HARDWARE-AUDIT command. The hardware AUDIT table is then no longer available.
Hardware AUDIT mode may be interrupted with the HOLD-HARDWARE-AUDIT command. When hardware AUDIT mode is resumed with RESUME-HARDWARE-AUDIT, it continues the hardware AUDIT table used previously. The contents of the hardware AUDIT table can be output with the SHOW-HARDWARE-AUDIT command as long as hardware AUDIT mode has not yet been terminated.
Availability of the AUDIT function
Hardware AUDIT is not available on systems with /390 architecture.
Systems support staff can make the AUDIT function globally available with the parameter service (AUDALLOW=YES). Via the user entry, systems support controls whether a user is authorized to start the hardware AUDIT mode.
Each user can prohibit or allow the hardware AUDIT mode within his or her task by means of the MODIFY-TEST-OPTIONS command (effective only if the authorization in the user entry allows it).
Privileged functions
Systems support (TSOS privilege) can start the AUDIT mode for each task and also control it for the TPR processor state.
If the AUDIT function is activated for recording all branch instructions on the job level (SCOPE=*OWN-JOB/*ALL-JOBS/*TID/*TSN), SCOPE=*PROGRAM-LEVEL is rejected. If a PCB-specific AUDIT is activated at a lower PCB, the new request is accepted additionally. Activation of ALL-JOBS-AUDIT results in deactivation of the AUDIT function on the job level in each job and subsequent activation of ALL-JOBS-AUDIT without retention of the earlier AUDIT table. See also the “Diagnostics Handbook” [8].
Format
START-HARDWARE-AUDIT | ||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||
Operands
SCOPE =
Scope of the hardware AUDIT function.
SCOPE = *OWN-JOB
The request applies to actions (processor state TU) in the user’s own task (in which the command was issued).
SCOPE = *PROGRAM-LEVEL
The request applies to the PCB-specific function relating to the highest interrupted PCB of the processor state TU. It is allowed only for the user’s own job (see TID, TSN operands). If a task-wide hardware AUDIT is activated (SCOPE=*OWN-JOB), a PCB-specific hardware AUDIT request is refused. If a PCB-specific hardware AUDIT at a lower PCB is activated, the new request is accepted in addition.
SCOPE = *ALL-JOBS
All jobs currently in the system are to be monitored with AUDIT.
This operand value may only be entered in conjunction with the operand STATE=*SYSTEM.
SCOPE = *TID(...)
AUDIT is to monitor only one task, identified by its internal task identifier (TID). Nonprivileged users can only specify tasks running under their own user ID.
TID = <alphanum-name 1..8>
TID of the task.
SCOPE = TSN(...)
AUDIT is to monitor only one task, identified by its task sequence number (TSN). Nonprivileged users can only specify tasks running under their own user ID.
TSN = <alphanum-name 1..4> / <c-string 1..4>
TSN of the task.
BUFFER-SIZE = 0 / <integer 0..16 4Kbyte>
Number of 4-KB pages additionally requested in TU for the hardware AUDIT table to allow it to be saved to this area before cyclic overwriting. In TPR, the maximum possible size of the backup table is 4 KB. It replaces the 256-byte hardware AUDIT table. In TPR, BUFFER-SIZE can only be assigned the value 0 (no backup table) or 1 (backup table 4 KB).
Any value > 1 entered is replaced by 1.
STATE =
Processor state for which AUDIT is to be active.
STATE = *USER
The hardware AUDIT is to be started for the nonprivileged processor state TU.
STATE = *SYSTEM
Only privileged users are allowed to select this operand value.
The hardware AUDIT is to be started for the privileged processor state TPR.
Return codes
(SC2) | SC1 | Maincode | Meaning |
|---|---|---|---|
0 | CMD0001 | Command executed without error | |
1 | 0 | CMD0001 | Hardware AUDIT already underway |
2 | 0 | IDA0009 | BUFFER-SIZE invalid |
1 | CMD2201 | Invalid operand combination, specified task or PCB does not exist | |
64 | CMD0216 | User does not have required authorization | |
64 | IDA0003 | No hardware AUDIT table created | |
64 | IDA0004 | Hardware AUDIT running with SCOPE=*OWN-JOB; SCOPE=*PROGRAM-LEVEL rejected | |
64 | IDA0006 | BUFFER-SIZE operand ignored | |
64 | IDA0011 | Privilege error | |
64 | IDA0020 | Hardware AUDIT not available on this system (HSI) | |
64 | IDA0023 | Hardware AUDIT not available because user entry does not contain authorization | |
64 | IDA0024 | Hardware AUDIT not available due to the current test option settings for the active task | |
130 | IDA0017 | Out of memory; hardware AUDIT disabled for all tasks | |
130 | IDA0019 | START command rejected because a STOP command is still being processed |