GTRACE DATA

The DATA function of the GTRACE macro records system or problem program data in the GTF trace buffers. GTRACE DATA can trace up to 8192 bytes of data.

Data is written only if you requested the event qualifier (through the USRP option) when you started GTF. Therefore, you can issue the GTRACE DATA without issuing a GTRACE TEST.

In earlier releases, GTRACE DATA writes the record to the GTF data set even if the record's event ID (EID) is excluded from a USRP list in the GTF trace options. Therefore, you need to issue a GTRACE TEST before you issue GTRACE DATA to determine if data is to be collected for the event qualifier.

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; all data and parameters must reside in the home address space.
AMODE:	24- or 31- or 64-bit. The caller must be in 31-bit mode for GTRACE to record data above 16 megabytes.
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

Programming requirements

None.

Restrictions

None.

Input register information

Before issuing the GTRACE DATA 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-14: Unchanged
15: Return code

Performance implications

None.

Syntax

The standard form of the DATA 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.

DATA=`addr`	`addr`: RX address or register (2) - (12).
DATA64=`addr`

,LNG=`nbr`	`nbr`: Symbol, decimal number, hexadecimal number, or register (2) - (12).

,ID=`id`	`id`: Symbol, decimal number, or hexadecimal number.

,FID=`fidname`	`fidname`: Symbol, decimal number, hexadecimal number, or register (2) - (12).

,PAGEIN=NO	Default: PAGEIN=NO
,PAGEIN=YES

Parameters

The parameters are explained as follows:

DATA=addr

DATA64=addr

Specifies the virtual storage address of the data that is to be recorded.

Note: DATA64 can be specified only when running in 64-bit address mode (AMODE).

,LNG=nbr

Specifies the number of data bytes (1 through 8192) to be recorded from the address specified by the DATA parameter. You can specify the number in decimal or in hexadecimal. If the number is hexadecimal, use the expression X'nbr' to specify the number.

Note: When you specify LNG, the trace record contains the number of bytes that you specify plus 12 bytes, which is the size of the trace record header. The header consists of a 4-byte ASCB address followed by an 8-byte jobname. Thus, if you specify LNG=8192, the trace record has 8204 (8192+12) bytes.

,ID=id

Specifies the event ID that is to be recorded with the data bytes. 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.

,FID=fidname

Specifies the format appendage that controls the formatting of this record. Formatting occurs when the trace output is processed by GTF trace. The format appendage name is formed by appending the 2-digit FID value to the names AMDUSR, HMDUSR, and IMDUSR. Assign FID values as follows:

X'00': The record is to be dumped in hexadecimal.
X'01' to X'50': The record contains user format identifiers.

Note: If you code FID without any fidname, or if you omit the FID parameter, the system supplies a default fidname of zero.

,PAGEIN=NO

,PAGEIN=YES

Specifies that paged-out user data is to be processed (YES) or not to be processed (NO). To ensure that all user data is traced, specify YES.

ABEND codes

None.

Return codes

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

Table 1. Return Codes for the GTRACE DATA Macro
Hexadecimal Return Code	Meaning and Action
00	Meaning: GTF is active. The data was recorded in GTF trace buffers. Action: None.
04	Meaning: GTF is not active or not active for this particular event ID. No data was recorded. Action: None.
08	Meaning: Program error. The value of the LNG keyword is not valid. It must be a number from 1 through 8192. No data was recorded. Action: Reissue the macro, specifying a valid amount of trace data to be recorded.
0C	Meaning: Program error. The value of the DATA keyword is not valid. It does not represent an area of storage that the calling program can refer to. No data was recorded. Action: Correct the problem and reissue the macro.
10	Meaning: Program error. The value of the FID keyword is not valid. It must be a number from X'0' through X'FF'. No data was recorded. Action: Correct the problem and reissue the macro.
18	Meaning: Environmental condition. All GTF buffers are full. No data was recorded. Action: None.
1C	Meaning: Program error. The address of the parameter list for GTF is not valid. The parameter list is not in storage that the caller can refer to, or its format is not valid. No data was recorded. Action: Correct the problem and reissue the macro.
20	Meaning: Program error. Some of the data to be recorded was paged out. No data was recorded. This return code is not valid with PAGEIN=YES. Action: Page-fix the storage containing the data to be recorded or modify the macro invocation to specify the PAGEIN=YES option.

Example

Use GTRACE to record 200 bytes of user data plus 12 bytes for the trace record header. The user data is found at symbolic address AREA. Use an event identifier of 37. Use the formatting appendage named IMDUSR40 to control the formatting.

GTRACE DATA=AREA,LNG=200,ID=37,FID=X'40'