The requirements for the caller are:

The caller can include the GTZZTRK macro to get equate symbols for the return and reason codes.

The caller must not have an FRR established.

Before issuing the GTZTRACK 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.

Before issuing the GTZTRACK macro, the caller does not have to place any information into any access register (AR) unless using it in register notation for a particular parameter, or using it as a base register.

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

The GTZTRACK service is designed to keep its synchronously executed code path short. For that purpose part of the request processing is queued to be executed asynchronously in the GTZ address space.

The macro expansion will also ensure a minimal code path and skip the call to the synchronous backend processing, if tracking is not enabled or if the facility is full or too busy for additional requests.

The GTZTRACK macro is written as follows:

The parameters are explained as follows:

name

An optional symbol, starting in column 1, that is the name on the GTZTRACK macro invocation. The name must conform to the rules for an ordinary assembler language symbol.

OWNER=owner

A required input parameter, which specifies the owner of the code issuing GTZTRACK. IBM® recommends that you use your company name, followed by a short component name, for example IBMGRS, as the owner.

Only alphabetic characters (A-Z,a-z), numerics (0-9), national characters (@,$,#), an underscore ('_'), a period (.), a dash (-), a slash (/), and trailing blanks are allowed.

The owner value will be treated case-insensitive in future filter comparisons, but will have its case preserved in any output reports.

To code: Specify the RS-type address, or address in register (2)-(12), of a 16-character field.

,SOURCE=source

,SOURCEPATH=sourcepath

A required input parameter.

,SOURCE=source

A parameter which further identifies the code which is issuing GTZTRACK, as a sub-qualification of the OWNER in form of for example the name of the "(detecting) module" which issued GTZTRACK.

Only alphabetic characters (A-Z,a-z), numerics (0-9), national characters (@,$,#), and trailing blanks are allowed.

The system will convert this value to upper-case and use it this way in future filter comparisons and any output reports.

To code: Specify the RS-type address, or address in register (2)-(12), of an 8-character field.

,SOURCEPATH=sourcepath

A parameter which further identifies a z/OS Unix caller of this service, as a sub-qualification of the OWNER. The length of the SOURCEPATH is given via SOURCEPATHLEN.

Any character is allowed in the source path. It can not be all blanks or all binary zeroes though. IBM recommends to only use printable characters.

Character case and trailing blanks are both preserved and are significant in comparisons.

To code: Specify the RS-type address, or address in register (2)-(12), of a character field.

,SOURCEPATHLEN=sourcepathlen

When SOURCEPATH=sourcepath is specified, a required input parameter, which specifies the length of the SOURCEPATH. SOURCEPATHLEN must be in the range 1 through 1024.

To code: Specify the RS-type address, or address in register (2)-(12), of a halfword field, or specify a literal decimal value. sourcepathlen must be in the range 1 through 1024.

,EVENTDESC=eventdesc

A required input parameter, which describes the tracked instance.

Any character is allowed in the event description, but it can not contain just blanks or just binary zeroes. IBM recommends to only use printable characters.

Character case and trailing blanks are both preserved and are significant in comparisons.

The length of the EVENTDESC field is given via EVENTDESCLEN.

To code: Specify the RS-type address, or address in register (2)-(12), of a character field.

,EVENTDESCLEN=eventdesclen

A required input parameter, which specifies the length of the EVENTDESC field. EVENTDESCLEN must be in the range 1 through 64.

To code: Specify the RS-type address, or address in register (2)-(12), of a halfword field, or specify a literal decimal value. eventdesclen must be in the range 1 through 64.

,EVENTDATA=eventdata

,EVENTDATA=ALLZERO

An optional input parameter, which specifies data associated with this tracked instance. Callers can use it for their own purposes, for example to pass dynamic parameters of a service being tracked. Any display output will format this data as a 16-byte hexadecimal number.

The default is ALLZERO.

To code: Specify the RS-type address, or address in register (2)-(12), of a 16-character field.

,EVENTADDR=eventaddr

,EVENTPSW16=eventpsw16

A required input parameter.

,EVENTADDR=eventaddr

A parameter that contains the address of where the event being tracked occurred. A typical value would be the address to which the code invoking GTZTRACK will return.

This address is assumed to be a 64-bit address. If a 24-bit or 31-bit address is provided, you must ensure that the appropriate high-order bits and bytes of the address are set to zero. For example you should not supply an 8-byte address that is a "pointer-defined" AMODE 31 address, such as 00000000_81234568, which in other circumstances might indicate address 1234568 with the AMODE 31 bit on.

To code: Specify the RS-type address, or address in register (2)-(12), of an eight-byte pointer field.

,EVENTPSW16=eventpsw16

A parameter that contains a z/Arch 16-byte Program Status Word (PSW). It is to provide the address of where the event being tracked occurred via the contained instruction address and to provide information for potential additional GTZPRMxx filtering, for example by program state and authority.

To code: Specify the RS-type address, or address in register (2)-(12), of a 16-character field.

,EVENTPSW8=eventpsw8

When EVENTADDR=eventaddr is specified, a required input parameter that contains the 8-byte Program Status Word (PSW) to be used for potential future use via additional GTZPRMxx filtering, for example by program state and authority.

To code: Specify the RS-type address, or address in register (2)-(12), of an 8-character field.

,EVENTASID=HOME

,EVENTASID=PRIMARY

,EVENTASID=SECONDARY

,EVENTASID=VALUE

A required parameter that specifies which address space to associate with the tracked instance. This is mainly useful for cross-memory cases, where the event occurred in one address space, but the GTZTRACK call in another and the event ASID is different than HOME.

,EVENTASID=HOME

the event occurred in the home address space

,EVENTASID=PRIMARY

the event occurred in the primary address space. Only authorized callers of GTZTRACK are allowed to specify this option.

,EVENTASID=SECONDARY

the event occurred in the secondary address space. Only authorized callers of GTZTRACK are allowed to specify this option.

,EVENTASID=VALUE

the event occurred in the address space identified via EVENTASIDVAL. Only authorized callers of GTZTRACK are allowed to specify this option.

,EVENTASIDVAL=eventasidval

When EVENTASID=VALUE is specified, a required input parameter that specifies the address space id to associate with the tracked instance.

To code: Specify the RS-type address of a 16 bit field.

,NOABEND=NO

,NOABEND=YES

,NOABEND=VALUE

An optional parameter that indicates whether to disallow diagnostic ABENDs for this track request. Some GTZTRACK callers might not be tolerant to ABENDs at all and can specify this as an override for any GTZPRMxx statement which might be matching this GTZTRACK call and which requests an ABEND. The default is NOABEND=NO.

,NOABEND=NO

that indicates diagnostic ABEND E77 is allowed for this track request, if a matching GTZPRMxx statement is found.

,NOABEND=YES

that indicates the tracking facility will never issue ABEND E77 for this track request for diagnostic purposes, even if requested by a matching GTZPRMxx statement.

,NOABEND=VALUE

use the NoAbendVal value.

,NOABENDVAL=noabendval

When NOABEND=VALUE is specified, a required input parameter that indicates whether to disallow diagnostic ABENDs or not. A value of one (1) means 'no abend allowed' and a zero (0) value means 'abends allowed'.

To code: Specify the RS-type address of a one-byte field.

,RETCODE=retcode

An optional output parameter into which the return code is to be copied from GPR 15. If you specify 15, GPR15, REG15, or R15 (within or without parentheses), the value will be left in GPR 15.

To code: Specify the RS-type address of a fullword field, or register (2)-(12) or (15), (GPR15), (REG15), or (R15).

,RSNCODE=rsncode

An optional output parameter into which the reason code is to be copied from GPR 0. If you specify 0, 00, GPR0, GPR00, REG0, REG00, or R0 (within or without parentheses), the value will be left in GPR 0.

To code: Specify the RS-type address of a fullword field, or register (0) or (2)-(12), (00), (GPR0), (GPR00), REG0), (REG00), or (R0).

,PLISTVER=IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=0

An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form. When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are:

• IMPLIED_VERSION, which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
• MAX, if you want the parameter list to be the largest size currently possible. This size might grow from release to release and affect the amount of storage that your program needs.

  If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form, when both are assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.

• 0, if you use the currently available parameters.

To code: Specify one of the following:

• IMPLIED_VERSION
• MAX
• A decimal value of 0

,MF=S

,MF=(L,list addr)

,MF=(L,list addr,attr)

,MF=(L,list addr,0D)

,MF=(E,list addr)

,MF=(E,list addr,COMPLETE)

,MF=(E,list addr,NOCHECK)

,MF=(M,list addr)

,MF=(M,list addr,COMPLETE)

,MF=(M,list addr,NOCHECK)

An optional input parameter that specifies the macro form.

Use MF=S to specify the standard form of the macro, which builds an inline parameter list and generates the macro invocation to transfer control to the service. MF=S is the default.

Use MF=L to specify the list form of the macro. Use the list form together with the execute form of the macro for applications that require reentrant code. The list form defines an area of storage that the execute form uses to store the parameters. Only the PLISTVER parameter may be coded with the list form of the macro.

Use MF=E to specify the execute form of the macro. Use the execute form together with the list form of the macro for applications that require reentrant code. The execute form of the macro stores the parameters into the storage area defined by the list form, and generates the macro invocation to transfer control to the service.

Use MF=M together with the list and execute forms of the macro for service routines that need to provide different options according to user-provided input. Use the list form to define a storage area; use the modify form to set the appropriate options; then use the execute form to call the service.

IBM recommends that you use the modify and execute forms of GTZTRACK in the following order:

• Use GTZTRACK ...MF=(M,list-addr,COMPLETE) specifying appropriate parameters, including all required ones.
• Use GTZTRACK ...MF=(M,list-addr,NOCHECK), specifying the parameters that you want to change.
• Use GTZTRACK ...MF=(E,list-addr,NOCHECK), to execute the macro.

,list addr

The name of a storage area to contain the parameters. For MF=S, MF=E, and MF=M, this can be an RS-type address or an address in register (1)-(12).

,attr

An optional 1- to 60-character input string that you use to force boundary alignment of the parameter list. Use a value of 0F to force the parameter list to a word boundary, or 0D to force the parameter list to a doubleword boundary. If you do not code attr, the system provides a value of 0D.

,COMPLETE

Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.

,NOCHECK

Specifies that the system is not to check for required parameters and is not to supply defaults for omitted optional parameters.

Macro GTZZTRK provides equate symbols for the return and reason codes.

The following table identifies the hexadecimal return and reason codes and the equate symbol associated with each reason code. IBM support personnel may request the entire reason code, including the xxxx value.

None.