GTRACE TEST

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.

Environment

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.

Programming requirements

Include the CVT and the MCHEAD mapping macros.
When you code the CVT mapping macro, you must not specify PREFIX=YES.

Restrictions

None.

Input register information

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.

Output register information

When control returns to the caller, the general purpose registers (GPRs) contain:

Register: Contents
0: Unchanged
1: Used as a work register by the system
2-13: Unchanged
14: Used as a work register by the system
15: Return code

Performance implications

None.

Syntax

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.

Parameters

The parameters are explained as follows:

TEST=YES: Specifies the test function of the GTRACE macro.
,ID=id: Specifies the event ID for the user event that is to be tested. Decimal event IDs 0 through 1023 (X'3FF') are available for user events. You can specify the ID in decimal or in hexadecimal. Use the expression X'id' to specify a hexadecimal number.

ABEND codes

None.

Return codes

When GTRACE TEST macro returns control to your program, GPR 15 contains a return code.

Table 1. Return Codes for the GTRACE TEST Macro
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.