The TEST function of the GTRACE macro indicates whether the operator requested a particular user event in response to the USRP option. The system returns the test result as a return code in register 15.
By issuing GTRACE TEST and checking the return code, you can determine whether you need to subsequently issue GTRACE DATA to write the record. If the return code indicates that tracing has been requested by USRP for the specified user event, then issue GTRACE DATA.
Issuing GTRACE TEST before issuing GTRACE DATA is not necessary but you might find it useful to do so if the processing of your code can benefit from learning whether processing is active for the record type you want to record to the generalized trace facility (GTF) before requesting to do that recording.
When the operator requests GTF prompting for specific event identifiers with the USRP option and your program issues GTRACE DATA, the system records the user trace record only when the event identifier specified on GTRACE DATA was also requested with the USRP option. However, the TEST function is still supported for compatibility with existing programs.
The requirements for the caller are:
Environmental factor | Requirement |
---|---|
Minimum authorization: | Problem state, any PSW key |
Dispatchable unit mode: | Task or SRB |
Cross memory mode: | Any PASN, any HASN, any SASN |
AMODE: | 24- or 31- or 64-bit |
ASC mode: | Primary |
Interrupt status: | Enabled or disabled for I/O and external interrupts |
Locks: | No requirement |
Control parameters: | Must be in the primary address space and all data must reside in primary address space. |
None.
Before issuing the GTRACE TEST macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
None.
The TEST function of the GTRACE macro is coded as follows:
Syntax | Description |
---|---|
name | name: Symbol. Begin name in column 1. |
␢ | One or more blanks must precede GTRACE. |
GTRACE | |
␢ | One or more blanks must follow GTRACE. |
TEST=YES | |
,ID=id | id: Symbol, decimal digit, or hexadecimal number. |
The parameters are explained as follows:
None.
When GTRACE TEST macro returns control to your program, GPR 15 contains a return code.
Hexadecimal Return Code | Meaning and Action |
---|---|
00 | Meaning: Tracing has not been requested
by USRP for the specified user event. Action: Do not issue a GTRACE DATA request to create your trace record for the specified user event ID. |
04 | Meaning: Tracing has been requested by
USRP for the specified user event. Action: You may issue a GTRACE DATA request to create your trace record for the specified user event ID. |