CNZTRKR — Tracking interface macro

Description

The CNZTRKR macro can be used to invoke the tracking facility. IBM® recommends to use macro GTZTRACK instead. This service allows programmers to record events of interest. For more information about the tracking facility, see z/OS MVS Diagnosis: Tools and Service Aids.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state and any PSW key.
Dispatchable unit mode:	Task
Cross memory mode:	Any PASN, any HASN, any SASN
AMODE:	24- or 31-bit
ASC mode:	Primary
Interrupt status:	Enabled for I/O and external interrupts
Locks:	No locks held
Control parameters:	Control parameters must be in the primary address space.

Programming requirements

Before issuing the CNZTRKR macro, do the following:

Include the CNZTRPL mapping macro in your program.
Obtain storage for the CNZTRKR parameter list. TRPL_LEN in CNZTRPL contains the length of the parameter list. The parameter list can be in any type of storage.
Clear the entire parameter list by setting it to zeros.

Initialize fields in the parameter list mapped by macro CNZTRPL. You must initialize the following fields:

Field	Description
TRPL_Acro	The TRPL acronym
TRPL_Version	The current version level of the parameter list. The CNZTRPL mapping macro contains the current version level in TRPL_K_Curr_Version.
TRPL_Track_Info	Text that describes the occurrence of this instance. This text can be from 1 to 28 characters in length. Any EBCDIC value is allowed though you should use displayable characters because undisplayable characters may be changed to blanks when displayed on an operator's console or in the hardcopy log. The text cannot be all blank or all hexadecimal zeros.
TRPL_Track_Data	Four bytes of data associated with this track instance. Zero is a valid value. The DISPLAY OPDATA operator command will display this value as a hexadecimal number.
TRPL_Violators_Addr	While optional, this field should contain the address of where the event being tracked occurred (perhaps the address to which the service invoking CNZTRKR will return). If set to zero, the tracking facility will attempt to determine the address of the event, but may not be able to determine the exact location. This address is assumed to be a 31-bit address. If a 24-bit address is provided, you must ensure that the high-order byte of the address is zero.

Restrictions

The caller must not have functional recovery routines (FRRs) established.

Input register information

Before issuing the CNZTRKR 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: Reason code
1: Used as a work register by the system
2-13: Unchanged
14: Used as a work register by the system
15: Return code

When control returns to the caller, the access registers (ARs) contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14-15: Used as work registers by the system

Syntax

The CNZTRKR macro is written as follows:

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede CNZTRKR.

CNZTRKR

␢	One or more blanks must follow CNZTRKR.


`register`	`register`: General purpose register (2) - (12).
or
`list name`	`list name`: RX-type address.

Parameters

The parameters are explained as follows:

register
list name: Contains the address (register) or the name (list name) of the TRPL parameter list.

ABEND codes

If the installation has requested to ABEND the program that invokes the tracking service, the task will be ABENDed with an ABEND code of X'E77' and a user defined reason code. See the SETGTZ DEBUG operator command for further details.

Return and reason codes

When the CNZTRKR macro returns control to your program, register 15 contains the return code and register 0 contains a reason code, if the return code is not zero. Mapping macro CNZTRPL provides names for the return and reason codes. Refer to GTZTRACK macro — GTZ Track for codes that are not listed in CNZTRPL.

Hexadecimal Return Code	Hexadecimal Reason Code	Meaning and Action
00	00	Meaning: The recording of an instance completed successfully. Action: None.
04	04	Meaning: The request was to record an instance but the maximum number of recorded instances has been reached. Action: See the description of message GTZ0004E.
04	08	Meaning: The request was to record an instance but the tracking facility is not active. Action: See the description of reason code xxxx0401 of macro service GTZTRACK.
0C	`xx`	Meaning: There was an error with the TRPL parameter list. Action: None.
0C	04	Meaning: The acronym in the parameter list was not valid (it must be “TRPL”) or the version level was not supported. Action: Correct the acronym or version level in the parameter list and issue CNZTRKR again.
0C	08	Meaning: The track information provided in the TRPL parameter list was all blank or all hexadecimal zeros. Action: Make any necessary corrections to your code and issue CNZTRKR again.
0C	0C	Meaning: There was an error attempting to access the TRPL parameter list. The TRPL address you provided may not have been valid or pointed to storage that the CNZTRKR service could not access. Action: Make any necessary corrections to your code and issue CNZTRKR again.
10	`xx`	Meaning: This return code is for IBM diagnostic purposes only. Action: Record the return and reason codes and supply them to the appropriate IBM support personnel.
10	04	Meaning: A recovery environment could not be established. Action: Record the return and reason codes and supply them to the appropriate IBM support personnel.
10	08	Meaning: A serialization environment could not be established. Action: If this instance is important to be recorded, you can reissue the request. Serialization may now be able to be obtained.
10	0C	Meaning: An ABEND occurred in the CNZTRKR service during the processing of your request. Action: Notify your system programmer.
10	10	Meaning: GTZTRACK rejected the tracking request. Action: Notify your system programmer.