The requirements for the caller are:

For Assembler, include the GTZZQRY macro to get a mapping for the answer area and to get equate symbols for related constants as well as return and reason codes.

For (METAL-) C use include file gtzhqry.h instead of GTZZQRY.

The caller must not have a functional recovery routine (FRR) established.

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

None.

The GTZQUERY 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 GTZQUERY macro invocation. The name must conform to the rules for an ordinary assembler language symbol.

REQUEST=STATUS

REQUEST=EXCLUDE

REQUEST=DEBUG

REQUEST=TRACKDATA

A required parameter, which identifies the type of request.

REQUEST=STATUS

Get general status information for the tracking facility and an overview of current configuration settings and accumulated tracking data.

REQUEST=EXCLUDE

Retrieve detail information about currently active exclusion filters. Compare for example the SETGTZ EXCLUDE command.

REQUEST=DEBUG

Retrieve detail information about currently active debug action filters. Compare for example the SETGTZ DEBUG command.

REQUEST=TRACKDATA

Retrieve individual unique tracked instances, as created by GTZTRACK calls, and their associated statistics as currently stored by the tracking facility.

,OWNER=owner

,OWNER=*

When REQUEST=TRACKDATA is specified, an optional input parameter, which requests to return only such tracked instances which have a matching OWNER value, as specified on the GTZTRACK invocations that recorded the tracked instances.

If OWNER is specified, the owner value

• can contain wildcards anywhere in the string: An asterisk (*) will match any character sequence of zero or more characters and a question mark (?) will match a single arbitrary character.
• will be compared case-insensitive and will have trailing blanks ignored in comparisons.
• can only contain alphabetic characters (A-Z,a-z), numerics (0-9), national characters (@,$,#), the underscore ('_'), a period (.), a dash (-), a slash (/), wildcards, or trailing blanks.

The default is * which indicates, as a single wildcard asterisk, to match any tracked instance’s OWNER value.

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

,SOURCETYPE=ALL

,SOURCETYPE=NOPATH

,SOURCETYPE=PATH

When REQUEST=TRACKDATA is specified, an optional parameter, which identifies what type of tracked instance source values to match. The default is SOURCETYPE=ALL.

,SOURCETYPE=ALL

Match any source value, regardless if the tracked instance has a SOURCE or SOURCEPATH asociated with it.

,SOURCETYPE=NOPATH

Match only tracked instances which have a matching SOURCE value. Tracked instances with a SOURCEPATH value will not be matched.

,SOURCETYPE=PATH

Match only tracked instances which have a matching SOURCEPATH value. Tracked instances with a SOURCE value will not be matched.

,SOURCE=source

,SOURCE=*

When SOURCETYPE=NOPATH and REQUEST=TRACKDATA are specified, an optional input parameter, which requests to return only such tracked instances which have a matching SOURCE value.

The source value here:

• can contain wildcards anywhere in the string: An asterisk (*) will match any character sequence of zero or more characters and a question mark (?) will match a single arbitrary character.
• can only contain alphabetic characters (A-Z,a-z), numerics (0-9), national characters (@,$,#), wildcards, or trailing blanks.
• will be converted to upper-case for comparisons and will have trailing blanks ignored in comparisons.

The default is * , a single wildcard asterisk, which indicates to match all tracked instances with a SOURCE value.

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

,SOURCEPATHLEN=sourcepathlen

,SOURCEPATHLEN=0

When SOURCEPATH=PATH and REQUEST=TRACKDATA are specified, an optional input parameter, which specifies the length of the SOURCEPATH to match. SOURCEPATHLEN must be in the range of 0 through 1024.

The default is 0, which indicates to match any SOURCEPATH value.

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 0 through 1024.

,SOURCEPATH=sourcepath

When SOURCEPATHLEN=sourcepathlen, SOURCETYPE=PATH and REQUEST=TRACKDATA are specified, a required input parameter, which requests to return only such tracked instances which have a matching SOURCEPATH value with a length as specified by SOURCEPATHLEN.

The source path value here:

• can contain wildcards anywhere in the string: An asterisk (*) will match any character sequence of zero or more characters and a question mark (?) will match a single arbitrary character.
• can contain any EBCDIC character, but not just blanks or just binary zeroes. IBM® recommends you only use printable characters.
• will not have its alphabetic characters folded to upper-case and will be compared case-sensitive.
• will not have its trailing blanks removed for comparisons.

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

,EVENTDESCLEN=eventdesclen

,EVENTDESCLEN=0

When REQUEST=TRACKDATA is specified, an optional input parameter, which specifies the length of the event description (EVENTDESC) to match. EVENTDESCLEN must be in the range 0 through 64.

The default is 0 which indicates to match any EVENTDESC value.

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 0 through 64.

,EVENTDESC=eventdesc

When EVENTDESCLEN=eventdesclen and REQUEST=TRACKDATA are specified, a required input parameter, which requests to return only such tracked instances which have a matching event description (EVENTDESC) value with a length as specified by EVENTDESCLEN.

The EVENTDESC value:

• can contain wildcards anywhere in the string: An asterisk (*) will match any character sequence of zero or more characters and a question mark (?) will match a single arbitrary character.
• can contain any EBCDIC character, but not just blanks or just binary zeroes. IBM recommends to only use printable characters.
• will not have its alphabetic characters folded to upper-case and will be compared case-sensitive.
• will not have its trailing blanks removed.

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

,EVENTDATA=eventdata

,EVENTDATA=ALL

When REQUEST=TRACKDATA is specified, an optional input parameter, which requests to return only such tracking instances which have a matching EVENTDATA value as specified on the GTZTRACK invocations that recorded the tracked instances.

The default is ALL which indicates to match all EVENTDATA values.

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

,EVENTASID=eventasid

,EVENTASID=ALL

When REQUEST=TRACKDATA is specified, an optional input parameter, which requests to return only such tracked instances which have a matching EVENTASID value as specified on the GTZTRACK invocations that recorded the tracked instances. (address space identifier)

The default is ALL which indicates to match all EVENTASID values.

To code: Specify the RS-type address, or address in register (2)-(12), of a halfword field, or specify a literal decimal value.

,EVENTJOB=eventjob

,EVENTJOB=*

When REQUEST=TRACKDATA is specified, an optional input parameter, which requests to return only such tracking instances which were associated with a matching job name of the address space identified by the EVENTASID value specified on the GTZTRACK invocations that recorded the tracked instances.

If EVENTJOB is specified, the eventjob value

• can contain wildcards anywhere in the string: An asterisk (*) will match any character sequence of zero or more characters and a question mark (?) will match a single arbitrary character.
• can only contain alphabetic characters (A-Z,a-z), numerics (0-9), national characters (@,$,#), wildcards, or trailing blanks.
• will be converted to upper-case for comparisons and will have trailing blanks ignored in comparisons.

The default is * which indicates, as a single wildcard asterisk, to match. any tracked instance's EVENTJOB value.

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

PROGRAMTYPE=ALL

PROGRAMTYPE=NOPATH

PROGRAMTYPE=PATH

When REQUEST=TRACKDATA is specified, an optional parameter, which identifies what type of tracked instance program values, as derived from the EVENTADDR value specified on the GTZTRACK invocations that recorded the tracked instance, to match. A tracked instance is associated with a PROGRAMPATH value if the derived program is a z/OS Unix program, otherwise the tracked instance is associated with a PROGRAM value. The default is PROGRAMTYPE=ALL.

PROGRAMTYPE=ALL

Match any program value, regardless if the tracked instance has a PROGRAM or PROGRAMPATH associated with it.

,PROGRAMTYPE=NOPATH

Match only tracked instances which have a matching PROGRAM value. Tracked instances with a PROGRAMPATH value will not be matched.

,PROGRAMTYPE=PATH

Match only tracked instances which have a matching PROGRAMPATH value. Tracked instances with a PROGRAM value will not be matched.

,PROGRAM=program

,PROGRAM=*

When PROGRAMTYPE=NOPATH and REQUEST=TRACKDATA are specified, an optional input parameter, which requests to return only such tracked instances which have a matching PROGRAM value.

The program value here:

• can contain wildcards anywhere in the string: An asterisk (*) will match any character sequence of zero or more characters and a question mark (?) will match a single arbitrary character.
• can only contain alphabetic characters (A-Z,a-z), numerics (0-9), national characters (@,$,#), wildcards, or trailing blanks.
• will be converted to upper-case for comparisons and will have trailing blanks ignored in comparisons.

The default is * , a single wildcard asterisk, which indicates to match all tracked instances with a PROGRAM value.

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

,PROGRAMPATHLEN=programpathlen

,PROGRAMPATHLEN=0

When PROGRAMTYPE=PATH and REQUEST=TRACKDATA are specified, an optional input parameter, which specifies the length of the PROGRAMPATH to match. PROGRAMPATHLEN must be in the range 0 through 1024.

The default is 0, which indicates to match any PROGRAMPATH value.

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

,PROGRAMPATH=programpath

When PROGRAMPATHLEN=programpathlen, PROGRAMTYPE=PATH and REQUEST=TRACKDATA are specified, a required input parameter, which requests to return only such tracked instances which have a matching PROGRAMPATH value with a length as specified by PROGRAMPATHLEN.

The program path value here:

• can contain wildcards anywhere in the string: An asterisk (*) will match any character sequence of zero or more characters and a question mark (?) will match a single arbitrary character.
• can contain any EBCDIC character, but not just blanks or just binary zeroes. IBM recommends to only use printable characters.
• will not have its alphabetic characters folded to upper-case and will be compared case-sensitive.
• will not have its trailing blanks removed for comparisons.

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

,PROGRAMOFFSET=programoffset

,PROGRAMOFFSET=ALL

When REQUEST=TRACKDATA is specified, an optional input parameter, which requests to return only such tracked instances which were associated with a matching program offset as derived from the EVENTADDR value specified on the GTZTRACK invocations that recorded the tracked instances.

The default is ALL which indicates to match all PROGRAMOFFSET values.

To code: Specify the RS-type address of a doubleword field, or specify a literal decimal value.

,HOMEASID=homeasid

,HOMEASID=ALL

When REQUEST=TRACKDATA is specified, an optional input parameter, which requests to return only such tracked instances which were associated with a matching ASID of the HOME address space at the time of the GTZTRACK invocations that recorded the tracked instances.

The default is ALL which indicates to match all HOME ASID values.

To code: Specify the RS-type address, or address in register (2)-(12), of a halfword field, or specify a literal decimal value.

,HOMEJOB=homejob

,HOMEJOB=*

When REQUEST=TRACKDATA is specified, an optional input parameter, which requests to return only such tracked instances which were associated with a matching job name of the HOME address space at the time of the GTZTRACK invocations that recorded the tracked instances.

If HOMEJOB is specified, the homejob value:

• can contain wildcards anywhere in the string: An asterisk (*) will match any character sequence of zero or more characters and a question mark (?) will match a single arbitrary character.
• can only contain alphabetic characters (A-Z,a-z), numerics (0-9), national characters (@,$,#), wildcards, or trailing blanks.
• will be converted to upper-case for comparisons and will have trailing blanks ignored in comparisons.

The default is * which indicates, as a single wildcard asterisk, to match. any tracked instance's HOMEJOB value.

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

,ANSAREA=ansarea

A required output parameter. A parameter which is to contain the returned information. The length of ANSAREA is given via ANSLEN. The answer area is mapped by macro GTZZQRY and has to start at a double-word boundary.

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

,ANSLEN=anslen

A required input parameter, which contains the length of the provided answer area in bytes. The length must be at least of value GtzQuaaMinAnsLen, which is defined in macro GTZZQRY.

To code: Specify the RS-type address, or address in register (2)-(12), of a doubleword field, or specify a literal decimal value.

,SECCHECK=UNAUTH

,SECCHECK=ALL

An optional parameter that indicates whether to do RACF security checks based on profile(s) GTZ.sysname.QUERY. If RACF does not grant authority, the request is rejected. The default is SECCHECK=UNAUTH.

,SECCHECK=UNAUTH

that indicates to do RACF security checks only when the caller is unauthorized (not supervisor state, not system key, not APF-authorized).

,SECCHECK=ALL

that indicates to do RACF security checks in all cases.

,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 GTZQUERY in the following order:

• Use GTZQUERY ...MF=(M,list-addr,COMPLETE) specifying appropriate parameters, including all required ones.
• Use GTZQUERY ...MF=(M,list-addr,NOCHECK), specifying the parameters that you want to change.
• Use GTZQUERY ...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 GTZZQRY 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.

See the sample health check GTZSHCK in SYS1.SAMPLIB for sample GTZQUERY invocations.