ATRQUERY — Obtain RRS Information

The ATRQUERY macro allows callers to:
  • Retrieve information about resource managers that are involved with RRS processing
  • Retrieve information about units of recovery (URs)
  • Retrieve information about resource manager metadata.

Environment

The requirements for the caller are:

If your installation uses the RACF component of SecureWay for z/OS to control access to RRS information, ATRQUERY requires READ access to one of two RACF resources in the FACILITY class.

To view URs on other systems in a sysplex, ATRQUERY requires READ access to the MVSADMIN.RRS.COMMANDS.gname.sysname resource in the FACILITY class, where gname is the target logging group name, and sysname is the target system name. You may create a RACF profile to permit access to multiple logging groups and systems by including RACF valid generic characters (**, *, and %) in gname and sysname. See the z/OS Security Server RACF Security Administrator's Guide and z/OS Security Server RACF Command Language Reference for more information about using these RACF generic characters and defining RACF profiles. By permitting READ access through this profile, you can allow users to view RRS information on any number of systems in the sysplex.

If you are running RRS on a single system, ATRQUERY requires READ access to either the MVSADMIN.RRS.COMMANDS.gname.sysname resource or the MVSADMIN.RRS.COMMANDS resource in the FACILITY class. The MVSADMIN.RRS.COMMANDS resource only allows access to RRS system management functions on the current system. You cannot use the MVSADMIN.RRS.COMMANDS resource to allow or disallow use of RRS on another system.

ATRQUERY does not check the SYSSTATE global variable or the SPLEVEL global variable.

Programming requirements

ATRQUERY callers must include the following mapping macros: ATRFZQRY, CVT, IHAECVT

To use the ATR_* constants referenced in the keyword descriptions, ATRQUERY callers must include the ATRRASM mapping macro.

Restrictions

None.

Input register information

Before issuing the ATRQUERY 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 GPRs contain:
Register
Contents
0
Contains the reason code
1-13
Unchanged
14
Used as a work register by the system.
15
Contains the return code

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.

Performance implications

None.

Syntax

The ATRQUERY macro is written as follows:
Note: Keywords prefaced with a vertical bar (|) are mutually exclusive.

Parameters

The parameters are explained as follows:
name
An optional symbol, starting in column 1, that is the name on the ATRQUERY macro invocation. The name must conform to the rules for an ordinary assembler language symbol.
REQUEST=RMINFO
REQUEST=WMINFO
REQUEST=SYSINFO
REQUEST=URINFO
A required parameter that specifies the requested ATRQUERY function.
You must provide a storage area for the returned information. The AREAADDR, AREALEN, and AREAALET parameters define the storage area. If the storage area is not large enough to hold all the information to be returned, a warning return code is set, along with a reason code to identify the problem. The number of entries is returned in the COUNT field.
REQUEST=RMINFO
Retrieves information about resource managers that are involved with RRS processing. The information includes resource managers that are:
  • Currently active with RRS on any systems in the sysplex that match all of the specified filters
  • Currently not active with RRS on any system but were logged as last active with RRS on a system and match all of the specified filters
Note: Resource managers that are currently active with RRS/MVS are ones that have exits set with RRS.

When you specify REQUEST=RMINFO, DSECT ATRFZRM in mapping macro ATRFZQRY maps the storage area.

ATRQUERY returns this information sorted alphanumerically with a primary ascending sort key of logging group name and a secondary ascending sort key of system name.

REQUEST=WMINFO
Retrieves information about work managers that are involved with RRS/MVS processing. The information includes work managers that:
  • Own contexts that have incomplete units of recovery on this system; or,
  • Own or owned contexts that have incomplete units of recovery which are currently not active with RRS on any system, but were last active on this system.
Note: If a native context has an incomplete unit of recovery, the work manager name reported by RRS is reported as the following concatenated string:
  • SystemName
  • Period (.)
  • JobName of the native context address space
  • Period (.)
  • ASID
  • Blanks (padded to 32–bytes)

When you specify REQUEST=WMINFO, DSECT ATRFZWM in mapping macro ATRFZQRY maps the storage area.

REQUEST=SYSINFO
Retrieves information about RRS itself.

When you specify REQUEST=SYSINFO, DSECT ATRFZSI in mapping macro ATRFZQRY maps the storage area.

ATRQUERY returns this information sorted alphanumerically with a primary ascending sort key of logging group name and a secondary ascending sort key of system name.

REQUEST=URINFO
Retrieves information about units of recovery (URs) that are active on systems in the sysplex that match all of the specified filters.

When you specify REQUEST=URINFO, DSECTs ATRFZUR and ATRFZURI in mapping macro ATRFZQRY map the storage area.

,RMNAME=rmname
With REQUEST=RMINFO or REQUEST=URINFO, an optional parameter that contains the resource manager name.
Note: The character string you specify may include wildcard characters. An asterisk (*) represents any string having a length of zero or more characters. A question mark (?) represents a position which may contain any single character.
When you specify RMINFO and RMNAME, the system uses the specified value as a filter on the returned information, only returning information about the resource managers matching the pattern you specify for this or any other filters. These resource managers must be:
  • Currently active on this system; or,
  • Currently inactive, but were active on this system in the past.

When you specify URINFO and RMNAME, the system returns information about the URs associated with the resource manager you name. When you specify URINFO without RMNAME, the system returns information about all currently active resource managers.

To code: Specify the RS-type address, or address in register (2)-(12), of a 32-character field that contains a resource manager name. The name can consist of the following printable characters:
  • Alphanumeric characters: A-Z and 0-9.
  • National characters: $ (X'5B'), # (X'7B'), @ (X'7C').
  • The period (.).
  • The underscore (_).
  • The trailing blank characters needed to fill the 32-byte field.
  • The wildcard characters: * and ?.

The name may not start with a blank or contain embedded blanks. Lower case characters are folded to upper case characters.

,WMNAME=wmname
With REQUEST=WMINFO or REQUEST=URINFO, an optional parameter that contains the work manager name.
Note: The character string you specify may include wildcard characters. An asterisk (*) represents any string having a length of zero or more characters. A question mark (?) represents a position which may contain any single character.
When you specify WMNAME, the system returns information about the work managers matching the pattern you specify. These work managers must be managing currently incomplete units of recovery that:
  • Are currently active on this system; or,
  • Were last active on this system.
When you omit WMNAME, the system returns information about all work managers that are managing currently incomplete units of recovery that:
  • Are currently active on this system; or,
  • Were last active on this system.

When you specify URINFO and WMNAME, the system returns information about the URs associated with the work manager you name. When you specify URINFO without WMNAME, the system returns information about all currently active work managers.

To code: Specify the RS-type address, or address in register (2)-(12), of a 32-character field that contains a work manager name. The name can consist of the following printable characters:
  • Alphanumeric characters: A-Z and 0-9.
  • National characters: $ (X'5B'), # (X'7B'), @ (X'7C').
  • The period (.).
  • The underscore (_).
  • The trailing blank characters needed to fill the 32-byte field.
  • The wildcard characters: * and ?.

The name may not start with a blank or contain embedded blanks. Lower case characters are folded to upper case characters.

,GNAME=gname
With REQUEST=RMINFO, REQUEST=WMINFO, REQUEST=SYSINFO or REQUEST=URINFO, an optional parameter that contains the logging group name.
Note: The character string you specify may include wildcard characters. An asterisk (*) represents any string having a length of zero or more characters. A question mark (?) represents a position which may contain any single character.

When you specify GNAME, the system uses the specified value as a filter on the returned information, only returning information matching the pattern you specify.

When you omit GNAME, ATRQUERY uses the current system's logging group name as a filter on the information returned. To obtain information for all the systems in a sysplex, specify an asterisk (*) for both GNAME and SYSNAME. To obtain information for all the systems in a specific logging group, specify the logging group name for GNAME and specify an asterisk (*) for SYSNAME.

To code: Specify the RS-type address, or address in register (2)-(12), of a 8-character field that contains a logging group name. The name can consist of the following printable characters:
  • Alphanumeric characters: A-Z and 0-9.
  • National characters: $ (X'5B'), # (X'7B'), @ (X'7C').
  • The period (.).
  • The underscore (_).
  • The trailing blank characters needed to fill the 8-byte field.
  • The wildcard characters: * and ?.

The name may not start with a blank or contain embedded blanks. Lower case characters are folded to upper case characters.

,SYSNAME=sysname
With REQUEST=RMINFO, REQUEST=WMINFO, REQUEST=SYSINFO or REQUEST=URINFO, an optional parameter that contains the system name.
Note: The character string you specify may include wildcard characters. An asterisk (*) represents any string having a length of zero or more characters. A question mark (?) represents a position which may contain any single character.

When you specify SYSNAME, the system uses the specified value as a filter on the returned information, only returning information matching the pattern you specify.

When you omit SYSNAME, ATRQUERY uses the current system's system name as a filter on the information returned. To obtain information for all the systems in a sysplex, specify an asterisk (*) for both GNAME and SYSNAME.

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

,METADATA
With REQUEST=RMINFO, an optional keyword that indicates that if the resource manager has stored Meta Data, it will be returned as part of the resource manager's information. When you omit METADATA, no Meta Data information will be returned.
,ASID=asid
When you specify REQUEST=URINFO, an optional input parameter that contains the address space identifier (ASID) of the address space where the application you are interested in is running. The system returns information about URs associated with this address space.
Note: This parameter is left for compatibility with previous releases. IBM® recommends the usage of WMNAME instead of this parameter.

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

,URID=urid
When you specify REQUEST=URINFO, an optional parameter that contains the identifier of the specific UR for which information is to be returned. (To obtain the UR identifier, call the Express_UR_Interest service.)
Note: URID and URIDSTR are mutually exclusive.

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

,URIDSTR=uridstr
When you specify REQUEST=URINFO, an optional parameter that contains the EBCDIC representation of the 16–character identifier of the specific UR for which information is to be returned.
Note: The character string you specify may include wildcard characters. An asterisk (*) represents any string having a length of zero or more characters. A question mark (?) represents a position which may contain any single character.
Note: URID and URIDSTR are mutually exclusive.

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

,SURID=surid
When you specify REQUEST=URINFO, an optional parameter that contains the sysplex UR identifier of the specific cascaded UR family for which information is to be returned. You can obtain a sysplex UR identifier from a log entry in the Restart, Main, or Delayed log stream or from a prior ATRQUERY URINFO macro invocation.
Note: SURID and SURIDSTR are mutually exclusive.

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

,SURIDSTR=suridstr
When you specify REQUEST=URINFO, an optional parameter that contains the EBCDIC representation of the 32–character sysplex UR identifier of the specific cascaded UR family for which information is to be returned.
Note: The character string you specify may include wildcard characters. An asterisk (*) represents any string having a length of zero or more characters. A question mark (?) represents a position which may contain any single character.
Note: SURID and SURIDSTR are mutually exclusive.

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

,URTYPE=urtype
When you specify REQUEST=URINFO, an optional input parameter that contains the type of UR for which information is to be returned.
Use one of the following constants:
ATR_NOFILTER
The UR type will not be used to filter the returned information.
ATR_PROTECTED
The system will return all URs in which at least one resource manager has a protected interest.
ATR_UNPROTECTED
The system will return all URs in which no resource manager has a protected interest.

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

,URSTATE=urstate
When you specify REQUEST=URINFO, an optional parameter that specifies the state that a given UR or interest in a given UR must be in to be returned.
Note: URSTATE and URSTMASK are mutually exclusive keywords.
Use one of the following values:
ATR_NOFILTER
The UR state will not be used to filter the returned information.
ATR_IN_FLIGHT
In-Flight URs only.
ATR_IN_STATE_CHECK
In-State_Check URs only.
ATR_IN_PREPARE
In-Prepare URs only.
ATR_IN_DOUBT
In-Doubt URs only.
ATR_IN_COMMIT
In-Commit URs only.
ATR_IN_BACKOUT
In-Backout URs only.
ATR_IN_END
In-End URs only.
ATR_COMPLETE
Complete URs only.
Note: This parameter is left for compatibility. IBM recommends the usage of the ATR_IN_COMPLETION parameter.
ATR_IN_COMPLETION
In-Completion URs only.
ATR_IN_ONLY_AGENT
In-Only-Agent URs only.
ATR_IN_FORGET
In-Forget URs only.

To code: Specify the value, or register (2)-(12) that contains the value.

,URSTMASK=urstmask
When you specify REQUEST=URINFO, an optional parameter that specifies a 32–bit mask identifying one or more states of the URs or interests in the URs to be returned.
Note: URSTATE and URSTMASK are mutually exclusive keywords.
The following bit constants can be used to create the fullword bit mask:
ATR_NOFILTER_MASK (X'00000000')
The UR state will not be used to filter the returned information.
ATR_IN_FLIGHT_MASK (X'80000000')
Include In-Flight URs.
ATR_IN_STATE_CHECK_MASK (X'40000000')
Include In-State_Check URs.
ATR_IN_PREPARE_MASK (X'20000000')
Include In-Prepare URs.
ATR_IN_DOUBT_MASK (X'1000000')
Include In-Doubt URs.
ATR_IN_COMMIT_MASK (X'08000000')
Include In-Commit URs.
ATR_IN_BACKOUT_MASK (X'04000000')
Include In-Backout URs.
ATR_IN_END_MASK (X'02000000')
Include In-End URs.
ATR_IN_COMPLETION_MASK (X'01000000')
Include In-Completion URs.
ATR_IN_ONLY_AGENT_MASK (X'00800000')
Include In-Only-Agent URs.
ATR_IN_FORGET_MASK (X'00400000')
Include In-Forget URs.
To code: Specify the value, or register (2)-(12) that contains the value. For example, if the value passed via this parameter is X'0C000000', both the ATR_IN_COMMIT_MASK and the ATR_IN_BACKOUT_MASK are specified. URs that are in commit or backout are returned. This definition might be specified: 
CMT_AND_BAK    EQU(ATR_IN_COMMIT_MASK+ATR_IN_BACKOUT_MASK)
,LUWID=luwid
When you specify REQUEST=URINFO, an optional input parameter that specifies the logical unit of work identifier (LUWID) to be used to filter the returned information.
Note: LUWID and LUWIDSTR are mutually exclusive keywords.
To code: Specify the RS-type address, or address in register (2)-(12), of a 26-character field. A LUWID has the following format: 
     netid.luname.instnum.seqnum
The fields are as follows:
netid.luname
1-17 character identifier of the network and LU, preceded by a 1-byte length field
instnum
6-byte TP instance
seqnum
2-byte sequence number

If LUWID and LUWIDSTR are left unspecified, then the LUWID will not be used as a filter. If LUWIDSTR is specified, but the instnum or the seqnum (or both) is left unspecified, then that unspecified portion of the LUWID is not used as a filter.

,LUWIDSTR=luwidstr
When you specify REQUEST=URINFO, the address of an optional 35–character EBCDIC representation of the LUWID with commas or blanks used to delimit the netid.luname, instnum, and seqnum fields.
Note: The netid.luname string you specify may include wildcard characters. An asterisk (*) represents any string having a length of zero or more characters. A question mark (?) represents a position which may contain any single character. The instnum and seqnum are optional. However, if the seqnum is specified without the instnum, the delimiter between instnum and seqnum is still required. For example: ABC.LUNAME,,12
Here are some more examples of valid LUWIDSTR pattern specifications: 
*.*,99,12
ABC.*
ABC.*,12
ABC.*,,12
A?C.LUNA??
If LUWID and LUWIDSTR are left unspecified, then the LUWID will not be used as a filter. If LUWIDSTR is specified, but the instnum or the seqnum (or both) is left unspecified, then that unspecified portion of the LUWID is not used as a filter.
Note: LUWID and LUWIDSTR are mutually exclusive keywords.

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

,TID=tid
When you specify REQUEST=URINFO, an optional input parameter that contains the transaction identifier (TID) to be used to filter the returned information. If you specify TID=ATR_NOFILTER, this keyword is ignored.
Note: TID may not be specified if either TIDLOW or TIDHIGH is specified.
To code: Specify the RS-type address, or address in register (2)-(12), of a 4-byte field that contains the TID part of the Enterprise identifier (EID). An EID has the following format: 
     tidgtid
,TIDLOW=tidlow
When you specify REQUEST=URINFO, an optional input parameter that specifies that URs having transaction identifiers (TID) that are equal to or higher than one specified are returned. The low range indicator is set by default to be a value lower than, or equal to, all transaction identifiers. If TIDLOW and TIDHIGH are both specified, URs that have transaction identifiers that are between the TIDLOW and TIDHIGH values, inclusive, are returned.
Note: TID may not be specified if either TIDLOW or TIDHIGH is specified.
To code: Specify the RS-type address, or address in register (2)-(12), of a 4-byte field that contains the lowest desired TID part of the Enterprise identifier (EID). An EID has the following format: 
     tidgtid
,TIDHIGH=tidhigh
When you specify REQUEST=URINFO, an optional input parameter that specifies that URs having transaction identifiers (TID) that are equal to or lower than one specified are returned. The high range indicator is set by default to be a value higher than, or equal to, all transaction identifiers. If TIDLOW and TIDHIGH are both specified, URs that have transaction identifiers that are between the TIDLOW and TIDHIGH values, inclusive, are returned.
Note: TID may not be specified if either TIDLOW or TIDHIGH is specified.
To code: Specify the RS-type address, or address in register (2)-(12), of a 4-byte field that contains the highest desired TID part of the Enterprise identifier (EID). An EID has the following format: 
     tidgtid
,GTID=gtid
When you specify REQUEST=URINFO, an optional input parameter that contains the global transaction identifier (GTID) to be used to filter the returned information. If you specify GTID=ATR_NOFILTER, this keyword is ignored.
Note: GTID and GTIDSTR are mutually exclusive keywords.
To code: Specify the RS-type address, or address in register (2)-(12), of a 40-byte field that contains the GTID part of the Enterprise identifier (EID). An EID has the following format: 
     tidgtid
,GTIDSTR=gtidstr
When you specify REQUEST=URINFO, the address of an optional 80–character input that contains the EBCDIC representation of the 40–character GTID used to filter the returned information.
Note: The character string you specify may include wildcard characters. An asterisk (*) represents any string having a length of zero or more characters. A question mark (?) represents a position which may contain any single character.
Note: GTID and GTIDSTR are mutually exclusive keywords.
To code: Specify the RS-type address, or address in register (2)-(12), of an 80-byte field that contains the EBCDIC representation of the GTID part of the Enterprise identifier (EID). An EID has the following format: 
     tidgtid
,XID=xid
When you specify REQUEST=URINFO, the address of an optional 140–character input that contains the X/Open Identifier (XID) used to filter the returned information.

The default is 0. The XID will not be used to filter the returned information.

Note: XID may not be specified if either XIDFORMATID, XIDGTRIDSTR, or XIDBQUALSTR is specified.
To code: Specify the RS-type address, or address in register (2)-(12), of a 140-byte field that contains the X/Open Identifier (XID). An XID has the following format: 
     FormatIDGtrid_lengthBqual_lengthID
,XIDFORMATIDSTR=xidformatidstr
When you specify REQUEST=URINFO, the address of the EBCDIC representation of an optional 8–character input that contains the 4–character FormatID portion of the X/Open Identifier (XID) used to filter the returned information.

The default is 0. The XIDFORMATIDSTR will not be used to filter the returned information.

Note:
  1. The character string you specify may include wildcard characters. An asterisk (*) represents any string having a length of zero or more characters. A question mark (?) represents a position which may contain any single character.
  2. XID may not be specified if either XIDFORMATID, XIDGTRIDSTR, or XIDBQUALSTR is specified.

To code: Specify the RS-type address, or address in register (2)-(12), of the EBCDIC representation of a 4-byte field that contains the FormatID portion of the X/Open Identifier (XID).

,XIDGTRIDSTR=xidgtridstr
When you specify REQUEST=URINFO, the address of the EBCDIC representation of an optional 128–character input that contains the 64–character GTRID portion of the X/Open Identifier (XID) used to filter the returned information.

The default is 0. The XIDGTRIDSTR will not be used to filter the returned information.

Note:
  1. The character string you specify may include wildcard characters. An asterisk (*) represents any string having a length of zero or more characters. A question mark (?) represents a position which may contain any single character.
  2. XID may not be specified if either XIDFORMATID, XIDGTRIDSTR, or XIDBQUALSTR is specified.

To code: Specify the RS-type address, or address in register (2)-(12), of the EBCDIC representation of a 64-byte field that contains the GTRID portion of the X/Open Identifier (XID).

,XIDBQUALSTR=xidbqualstr
When you specify REQUEST=URINFO, the address of the EBCDIC representation of an optional 128–character input that contains the 64–character BQUAL portion of the X/Open Identifier (XID) used to filter the returned information.

The default is 0. The XIDBQUALSTR will not be used to filter the returned information.

Note:
  1. The character string you specify may include wildcard characters. An asterisk (*) represents any string having a length of zero or more characters. A question mark (?) represents a position which may contain any single character.
  2. XID may not be specified if either XIDFORMATID, XIDGTRIDSTR, or XIDBQUALSTR is specified.

To code: Specify the RS-type address, or address in register (2)-(12), of the EBCDIC representation of a 64-byte field that contains the BQUAL portion of the X/Open Identifier (XID).

,TODBEG=todbeg
When you specify REQUEST=URINFO, an optional 8–byte begin range time of day (UTC) value used to filter the returned information. URs which were created at the same time or later than the time specified by this parameter will be returned. If this parameter is not specified, the starting TOD range is set to the UTC time of the oldest UR.
Note: If TODBEG and TODEND are both specified, URs that have create times that are between the TODBEG and TODEND values, inclusive, are returned.

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

,TODEND=todend
When you specify REQUEST=URINFO, an optional 8–byte end range time of day (UTC) value used to filter the returned information. URs which were created at the same time or earlier than the time specified by this parameter will be returned. If this parameter is not specified, the ending TOD range is set to the current UTC time.
Note: If TODBEG and TODEND are both specified, URs that have create times that are between the TODBEG and TODEND values, inclusive, are returned.

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

,CURDUR=curdur
When you specify REQUEST=URINFO, an optional 13–byte field character string in the format hh:mm:ss.ssss containing the minimum duration that a given UR has been in its current state. If this parameter is not specified, URs will be returned regardless of how long they have been in their current state.

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

,DEFURONLY=defuronly
When you specify REQUEST=URINFO, an optional 3–character string used to determine if only the URs that are marked deferred should be returned. There are two possible strings:
  • NO — All URs will be returned, including those marked deferred.
  • YES — Only URs marked deferred will be returned.
The default is NO .
Note: This parameter is left for compatibility. IBM recommends the usage of the EXCLMASK parameter. DEFURONLY and EXCLMASK are mutually exclusive.

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

,EXCLMASK=exclmask
When you specify REQUEST=URINFO, an optional parameter that specifies the address of a fullword containing the 32–bit mask identifying one or more conditions that identify URs to be excluded from the returned information.
Note: DEFURONLY and EXCLMASK are mutually exclusive keywords.
The following bit constants can be used to create the fullword bit mask:
ATR_NOEXCLUSION_MASK (X'00000000')
No exclusion conditions will be used to filter the returned information.
ATR_UR_IN_RESTART_MASK (X'80000000')
URs that are read from the Restart log will be excluded from the returned information.
ATR_RESTART_REQUIRED_MASK (X'40000000')
URs that contain interests whose resource managers are required to restart with RRS will be excluded from the returned information.
ATR_NONDEFERRED_UR_MASK (X'20000000')
URs that are not deferred from an RRS server task will be excluded from the returned information. This specification is equivalent to specifying the DEFURONLY keyword.
ATR_CASCADED_UR_MASK (X'10000000')
URs that are included only because they are part of a cascaded UR family will be excluded from the returned information.
ATR_LOCAL_UR_MASK (X'08000000')
URs in local transaction mode will be excluded from the returned information.
ATR_GLOBAL_UR_MASK (X'04000000')
URs in global transaction mode or hybrid-global transaction mode will be excluded from the returned information.
ATR_RRS_MANAGED_UR_MASK (X'02000000')
URs whose current work manager is RRS will be excluded from the returned information. RRS is a work manager for restart URs and for URs associated with contexts delegated to RRS.
ATR_NONRRS_MANAGED_UR_MASK (X'01000000')
URs whose current work manager is not RRS will be excluded from the returned information.
To code: Specify the RS-type address, or address in register (2)-(12), of a fullword field. For example, if the address passed via this parameter points to a fullword that contains a value of X'C0000000', both the ATR_RESTART_LOG_MASK and the ATR_RESTART_REQUIRED_MASK are specified. Neither URs that are read from the Restart log nor URs that contain interests that have RMs that are required to restart will be returned. This definition might be specified: 
REST_AND_RQRD    DC  AL4(ATR_UR_IN_RESTART_MASK+ATR_RESTART_REQUIRED_MASK)
,EXINFOMASK=exinfomask
When you specify REQUEST=URINFO, an optional parameter that specifies the address of a fullword containing the 32–bit mask identifying which types of extended information will be returned for the returned units of recovery.
The following bit constants can be used to create the fullword bit mask:
ATR_NOXINFO_MASK (X'00000000')
No extended information will be returned.
ATR_XINFO_TIMESTAMP_MASK (X'80000000')
Timestamp information for each unit of recovery as well as each interest in each unit of recovery will be added to the returned information.
ATR_XINFO_CASCADED_MASK (X'40000000')
Cascaded family information for each unit of recovery will be added to the returned information. If any UR in a cascaded UR family is returned, all of the URs in the family will be returned, unless EXCLUDEURMASK indicates that they should be excluded.
ATR_XINFO_PID_MASK (X'20000000')
Persistent Interest Data for each unit of recovery interest will be added to the returned information.

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

,SORTTAB=sorttab
When you specify REQUEST=URINFO, an optional row-major sort table array. Each element in the table is comprised of a fullword sort key selector and a 32–bit sort options field. Each element in the table represents a sort key; therefore, a table with multiple elements specifies a multiple key sort of the returned information. The position of a given sort element in the sort table array specifies its sort priority. The first element in the table specifies the primary sort key. The second element specifies the secondary sort key. The third specifies the tertiary sort key, and so on. A mapping of the element format is provided in the ATRFZQRY mapping macro.
Note: If SORTTAB is specified, SORTNUM must also be specified.
Example table:
Table 1. ATRQUERY — SORTTAB Parameter
Sort order Sort key Sort option
Primary sort key DC F(ATR_SORT_WM_NAME) DC F(ATR_SORTOPT_ASCENDING)
Secondary sort key DC F(ATR_SORT_CREATE_TIME) DC F(ATR_SORTOPT_DESCENDING)
Tertiary sort key DC F(ATR_SORT_URID) DC F(ATR_SORTOPT_ASCENDING)
The SORTNUM for this table would be 3.
Sort Key Selector Values:
ATR_SORT_WM_NAME (X'00000001')
Sort returned information based on Work Manager Name.
ATR_SORT_URID (X'00000002')
Sort returned information based on UR Identifier.
ATR_SORT_CREATE_TIME (X'00000003')
Sort returned information based on the create time of the UR.
ATR_SORT_UR_STATE (X'00000004')
Sort returned information based on the UR state.
ATR_SORT_LUWID (X'00000005')
Sort returned information based on the Logical Unit Work Identifier.
Note: ATR_SORT_LUWID is really a three key sort, with the primary key being the luname.netid, the secondary key being the instnum, and the tertiary key being the seqnum. The luname.netid is padded to 17 bytes with blanks on the right before comparing the IDs for sort order.
ATR_SORT_TID (X'00000006')
Sort returned information based on the Transaction Identifier.
ATR_SORT_GTID (X'00000007')
Sort returned information based on the Global Transaction Identifier.
ATR_SORT_XID (X'00000008')
Sort returned information based on the X/Open Identifier.
Note: ATR_SORT_XID is really a three key sort, with the primary key being the FormatID, the secondary key being the Global Transaction ID, and the tertiary key being the BQUAL.
ATR_SORT_GNAME (X'00000009')
Sort returned information based on the logging group name.
ATR_SORT_SYSNAME (X'0000000A')
Sort returned information based on the system name.
ATR_SORT_SURID (X'0000000B')
Sort returned information based on the sysplex UR identifier.
Sort Option Values:
ATR_SORTOPT_ASCENDING (X'0nnnnnnn')
Sort returned information in ascending order using the sort key.
ATR_SORTOPT_DESCENDING (X'8nnnnnnn')
Sort returned information in descending order using the sort key.
Note: Bits 1–31 are reserved, and must contain binary zeros.

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

,SORTNUM=sortnum
When you specify REQUEST=URINFO, an optional fullword unsigned integer value containing the number of elements in the sort table passed via the SORTTAB parameter. The number of elements that can be passed in the sort table is limited to the number of possible sort fields.
Note: SORTNUM must be specified if SORTTAB is specified.

To code: Specify the RS-type address, or address in register (2)-(12), of a fullword unsigned integer value.

,AREAADDR=areaaddr
A required input parameter that contains the address of the storage area to contain the returned information. Specify the length of the area in AREALEN.

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

,AREALEN=arealen
A required input parameter that contains the length of the area to contain the returned information. Specify the address of the area in AREAADDR.

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

,AREAALET=areaalet
An optional input parameter that contains the ALET of an entry on the DU Access List that will be used to address the area to contain the returned information. Specify the address of the area in AREAADDR.
Note: ALETs of access list entries on the PASN access list and the special ALET value of 1 (secondary) are not valid.

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

,AREAOPT=areaopt
An optional input parameter that specifies the type of addressing used in the control structures returned in the area specified by AREAADDR.
To code: Specify either:
AREAOPT=BYADDR
Complete addresses are to be returned in the control structures.
AREAOPT=BYOFFSET
Offsets from the beginning of the storage area are to be returned in the control structures.
The default is BYADDR.
,COUNT=count
A required output parameter that, upon return from the service, will contain the number of entries that match your request.

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

,RCTABLE=rctable
An optional 4–byte input parameter that contains the address of a "2304" area to contain the return code and reason code from each system and logging group queried. The area consists of up to 64 36–byte entries. DSECT ATRFZRCA in mapping macro ATRFZQRY maps the storage area. The number of entries will be returned in the RCNUM parameter. The table will only contain valid information if the reason code returned to you is ATRSRV_REMOTE_WARNING or ATRSRV_REMOTE_ERROR.

The default is RCTABLE=0. No return code table is desired.

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

,RCNUM=rcnum
When using RCTABLE, a required output parameter that will contain the number of entries in the RCTABLE area.

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

,RETCODE=retcode
An optional output parameter into which the system copies the return code from GPR 15.

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

,RSNCODE=rsncode
An optional output parameter into which the system copies the reason code from GPR 0.

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

,PLISTVER=IMPLIED_VERSION
,PLISTVER=MAX
,PLISTVER=1
,PLISTVER=2
,PLISTVER=3
,PLISTVER=4
,PLISTVER=5
,PLISTVER=6
,PLISTVER=7
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; in this way, MAX ensures that the parameter list does not overwrite nearby storage.

  • 1, if you use the following parameters:
    • AREAADDR
    • AREALEN
    • ASID
    • COUNT
    • GTID
    • LUWID
    • REQUEST
    • RMNAME
    • TID
    • URID
    • URSTATE
    • URTYPE
  • 2, if you use the parameters from PLISTVER=1 plus the following parameters:
    • DEFURONLY
  • 3, if you use the parameters from PLISTVER=2 plus the following parameters:
    • CURDUR
    • EXCLMASK
    • EXINFOMASK
    • GTIDSTR
    • LUWIDSTR
    • SORTNUM
    • SORTTAB
    • TIDHIGH
    • TIDLOW
    • TODBEG
    • TODEND
    • URIDSTR
    • URSTMASK
  • 4, if you use the parameters from PLISTVER=3 plus the following parameters:
    • AREAALET
    • AREAOPT
    • GNAME
    • RCNUM
    • RCTABLE
    • SYSNAME
  • 5, if you use the parameters from PLISTVER=4 plus the following parameters:
    • XID
    • XIDFORMATIDSTR
    • XIDGTRIDSTR
    • XIDBQUALSTR
  • 6, if you use the parameters from PLISTVER=5 plus the following parameters:
    • SURID
    • SURIDSTR
  • 7, if you use the parameters from PLISTVER=6 plus the following parameters:
    • ATRxinfo
    • PID_Mask
  • 8, if you use the parameters from PLISTVER=7 plus the following parameters:
    • METADATA
To code: Specify one of the following:
  • IMPLIED_VERSION
  • MAX
  • A decimal value of 1
  • A decimal value of 2
  • A decimal value of 3
  • A decimal value of 4
  • A decimal value of 5
  • A decimal value of 6
  • A decimal value of 7
,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)
An optional input parameter that specifies the macro form.

Use MF=S to specify the standard form of the macro, which builds an in-line 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.
,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, which can contain any value that is valid on an assembler DS pseudo-op. You can use this parameter to force boundary alignment of the parameter list. If you do not code attr, the system provides a value of 0D, which forces the parameter list to a doubleword boundary.
,COMPLETE
Specifies that the system is to check for required parameters and supply defaults for omitted optional parameters.
Note: Declarations for Bit constants are provided in the ATRFZQRY mapping macro interface.

ABEND codes

None.

Return and reason codes

When the ATRQUERY macro returns control to your program:
  • GPR 15 (and retcode, if you coded RETCODE) contains a return code:
    0
    ATRQUERY_SUCCESS — request completed successfully
    4
    ATRQUERY_WARNING — request completed with a warning condition
    8
    ATRQUERY_FAILURE — request failed
  • When the value in GPR 15 is not zero, GPR 0 (and rsncode, if you coded RSNCODE) contains a reason code. The return and reason codes are shown in the following table. The ATRFZQRY mapping macro provides the equate symbols for the return and reason codes.
Return code in: hexadecimal Reason code in: hexadecimal Meaning and action
4 3 Equate symbol: ATRQUERY_AREA_FULL

Meaning: The return area is too small to hold all the information to be returned.

Action: Increase the size of the return area and retry the request.
4 17 Equate symbol: ATRQUERY_REMOTE_WARNING

Meaning: Errors occurred while querying data on at least one system. Some information may not have been returned. If you have been provided with an RCTABLE, it will contain detailed error information for each system involved in your request.

Action: Fix the errors noted in the RCTABLE and retry the request.
4 29 Equate symbol: ATRQUERY_RMMETADATALOGUNAVAILABLE

Meaning: The RM Meta Data log is not available. No information was returned.

Action: Check SYSLOG for messages ATR132I or ATR172E that will further explain why the log is unavailable. Retry the request when the RM Meta Data log is available.

8 1 Equate symbol: ATRQUERY_ASID_INVALID

Meaning: You specified an address space identifier (ASID) that does not exist.

Action: Specify a valid ASID and retry the request.
8 2 Equate symbol: ATRQUERY_RRS_NOT_ACTIVE

Meaning: The ATRQUERY service is not available; RRS is not active on this system.

Action: Retry the request when RRS is available.
8 4 Equate symbol: ATRQUERY_NOT_SAF_AUTH

Meaning: The caller does not have RACF authority to issue RRS commands.

Action: Obtain READ access to the MVSADMIN.RRS.COMMANDS resource in the FACILITY class and retry the request.
8 5 Equate symbol: ATRQUERY_URSTMASK_RSVD

Meaning: Reserved fields in the UR State Mask were nonzero.

Action: Correct the mask, clearing the reserved fields, and retry the request.
8 6 Equate symbol: ATRQUERY_XINFOMASK_RSVD

Meaning: Reserved fields in the Extended Information Mask were nonzero.

ATR_XINFO_PID_MASK is set but the PLISTVER specified is less than 7. When requesting for Persistent Interest Data, PLISTVER must be 7 or higher.

Action: Correct the mask, PLISTVER or clearing the reserved fields, and retry the request.
8 7 Equate symbol: ATRQUERY_EXCLUSIONMASK_RSVD

Meaning: Reserved fields in the UR Exclusion Condition Mask were nonzero.

Action: Correct the mask, clearing the reserved fields, and retry the request.
8 8 Equate symbol: ATRQUERY_SORTKEY_INVALID

Meaning: The sort table passed contained an invalid sort key.

Action: Correct the sort table and retry the request.
8 9 Equate symbol: ATRQUERY_SORTOPT_INVALID

Meaning: The sort table passed contained an invalid option.

Action: Correct the sort table and retry the request.
8 A Equate symbol: ATRQUERY_SORTNUM_INVALID

Meaning: The sort element number passed is not valid.

Action: Correct the number of elements in the sort table and retry the request.
8 B Equate symbol: ATRQUERY_TID_RANGE_INVALID

Meaning: The value specified for the TIDLOW parameter is higher than the value specified for the TIDHIGH parameter.

Action: Correct either the TIDLOW value or the TIDHIGH value, and retry the request.
8 C Equate symbol: ATRQUERY_TOD_RANGE_INVALID

Meaning: The time specified for the TODBEG parameter is after the time specified for the TODEND parameter.

Action: Correct either the TODBEG value or TODEND value, and retry the request.
8 D Equate symbol: ATRQUERY_LUWIDSTR_INVALID

Meaning: The value passed via the LUWIDSTR parameter is not valid.

Action: Correct the LUWIDSTR value and retry the request.
8 E Equate symbol: ATRQUERY_CURDUR_INVALID

Meaning: The value passed via the CURDUR parameter is not valid.

Action: Correct the CURDUR value and retry the request.
8 F Equate symbol: ATRQUERY_SORTTABPTR_BAD

Meaning: The sort table entry count was nonzero, but a valid table pointer was not passed.

Action: Correct the table pointer value and retry the request.
8 10 Equate symbol: ATRQUERY_AREAALET_SECONDARY

Meaning: The AREAALET specified is the secondary ALET, which is not accessible by the ATRQUERY service routine.

Action: Correct the AREAALET value and retry the request.
8 11 Equate symbol: ATRQUERY_REQUEST_UNKNOWN

Meaning: A downlevel version of RRS did not understand the request.

Action: Correct the parameter value and retry the request.
8 12 Equate symbol: ATRQUERY_GNAME_INVALID

Meaning: The value specified for the GNAME parameter is not valid.

Action: Correct the GNAME value and retry the request.
8 13 Equate symbol: ATRQUERY_SYSNAME_INVALID

Meaning: The value specified for the SYSNAME parameter is not valid.

Action: Correct the SYSNAME value and retry the request.
8 14 Equate symbol: ATRQUERY_RESOURCE_ERROR

Meaning: No buffer was available to satisfy a remote request.

Action: Retry the request.
8 15 Equate symbol: ATRQUERY_TOO_MANY_ITEMS

Meaning: There are too many data items to fit in the buffer to be sorted.

Action: Add more filters and retry the request.
8 16 Equate symbol: ATRQUERY_INSTANCE_FAILURE

Meaning: An error occurred processing a remote request. Your RCTABLE, if one was provided, will contain the failing service identifier, return code, and reason code.

Service identifiers:
1
IXCMSGO macro interface
2
IXCMSGI macro interface
Any other value is an internal error and should be reported to the IBM Support center.

Action: Fix the errors noted in the RCTABLE and retry the request.
8 18 Equate symbol: ATRQUERY_REMOTE_ERROR

Meaning: Errors occurred while querying data on all systems. No information was returned. If you received an RCTABLE, it will contain detailed error information for each system involved in your request.

Action: Fix the errors noted in the RCTABLE and retry the request.
8 19 Equate symbol: ATRQUERY_RESP_NOT_RECEIVED

Meaning: No response was received from the remote system. No information was returned.

Action: Retry the request.
8 1A Equate symbol: ATRQUERY_REMOTE_NOT_ACTIVE

Meaning: The remote system is not active or RRS is not active on the remote system. No information was returned.

Action: Retry the request once the remote system is available.
8 1B Equate symbol: ATRQUERY_AREALEN_INVALID

Meaning: The value specified for the AREALEN parameter is not valid. No information was returned.

Action: Correct the AREALEN value and retry the request.
8 1C Equate symbol: ATRQUERY_AREAADDR_INVALID

Meaning: The value specified for the AREAADDR parameter is not valid. No information was returned.

Action: Correct the AREAADDR value and retry the request.
8 FFF Equate symbol: ATRQUERY_UNEXPECTED_ERROR

Meaning: An unexpected system error occurred.

Action: Contact your system support.

Examples

The following examples show several uses of the ATRQUERY macro.

Example 1

To obtain information about all resource managers known to RRS, issue the following request: 
         ATRQUERY REQUEST=RMINFO,AREAADDR=AREA@,AREALEN=AREAL,         X
               COUNT=RETCNT
*
* INPUT VALUES
*
AREA@    DC     A(RETAREA)               ADDRESS OF RETURN AREA
AREAL    DC     F'1024'                  LENGTH OF RETURN AREA
*
* OUTPUT AREAS
*
RETCNT   DS     F                        RETURNED RM COUNT
RETAREA  DS     1024C                    RETURN AREA
*
* REQUIRED MAPPINGS
*
         CVT DSECT=YES
         IHAECVT
         ATRFZQRY

Example 2

To obtain information about the resource manager named UTRICK, issue the following request: 
         ATRQUERY REQUEST=RMINFO,AREAADDR=AREA@,AREALEN=AREAL,         X
               COUNT=RETCNT,RMNAME=MYRM
*
* INPUT VALUES
*
AREA@    DC     A(RETAREA)               ADDRESS OF RETURN AREA
AREAL    DC     F'1024'                  LENGTH OF RETURN AREA
MYRM     DC     CL32'UTRICK'             RESOURCE MANAGER NAME
*
* OUTPUT AREAS
*
RETCNT   DS     F                        RETURNED RM COUNT
RETAREA  DS     1024C                    RETURN AREA
*
* REQUIRED MAPPINGS
*
         CVT DSECT=YES
         IHAECVT
         ATRFZQRY

Example 3

To obtain information about all URs, issue the following request: 
         ATRQUERY REQUEST=URINFO,AREAADDR=AREA@,AREALEN=AREAL,         X
               COUNT=RETCNT
*
* INPUT VALUES
*
AREA@    DC     A(RETAREA)               ADDRESS OF RETURN AREA
AREAL    DC     F'1024'                  LENGTH OF RETURN AREA
*
* OUTPUT AREAS
*
RETCNT   DS     F                        RETURNED RM COUNT
RETAREA  DS     1024C                    RETURN AREA
*
* REQUIRED MAPPINGS
*
         CVT DSECT=YES
         IHAECVT
         ATRFZQRY

Example 4

To obtain information about all protected URs, issue the following request. 
         ATRQUERY REQUEST=URINFO,AREAADDR=AREA@,AREALEN=AREAL,         X
               COUNT=RETCNT,URTYPE=ATR_PROTECTED
*
* INPUT VALUES
*
AREA@    DC     A(RETAREA)               ADDRESS OF RETURN AREA
AREAL    DC     F'1024'                  LENGTH OF RETURN AREA
*
* OUTPUT AREAS
*
RETCNT   DS     F                        RETURNED RM COUNT
RETAREA  DS     1024C                    RETURN AREA
*
* REQUIRED MAPPINGS
*
         CVT DSECT=YES
         IHAECVT
         ATRFZQRY
         ATRRASM

Example 5

To obtain information about the URs associated with the application running in address space 52, issue the following request: 
         ATRQUERY REQUEST=URINFO,AREAADDR=AREA@,AREALEN=AREAL,         X
               COUNT=RETCNT,ASID=MYASID
*
* INPUT VALUES
*
AREA@    DC     A(RETAREA)               ADDRESS OF RETURN AREA
AREAL    DC     F'1024'                  LENGTH OF RETURN AREA
MYASID   DC     XL2'52'                  ADDRESS SPACE IDENTIFIER
*
* OUTPUT AREAS
*
RETCNT   DS     F                        RETURNED RM COUNT
RETAREA  DS     1024C                    RETURN AREA
*
* REQUIRED MAPPINGS
*
         CVT DSECT=YES
         IHAECVT
         ATRFZQRY
         ATRRASM

Example 6

To return only those URs that are In-Doubt or In-Commit, issue the following request: 
         L   10,URSTMASK
         ATRQUERY REQUEST=URINFO,AREAADDR=AREA@,AREALEN=AREAL,         X
               COUNT=RETCNT,URSTMASK(10),PLISTVER=MAX                  X
*
* INPUT VALUES
*
AREA@    DC     A(RETAREA)               ADDRESS OF RETURN AREA
AREAL    DC     F'1024'                  LENGTH OF RETURN AREA
URSTMASK DC     A(STATES)                UR STATE MASK
STATES   EQU    ATR_IN_DOUBT_MASK+ATR_IN_COMMIT_MASK
*
* OUTPUT AREAS
*
RETCNT   DS     F                        RETURNED RM COUNT
RETAREA  DS     1024C                    RETURN AREA
*
* REQUIRED MAPPINGS
*
         CVT DSECT=YES
         IHAECVT
         ATRFZQRY
         ATRRASM

Example 7

To return URs sorted by UR create time and UR state, in ascending order, issue the following request: 
         ATRQUERY REQUEST=URINFO,AREAADDR=AREA@,AREALEN=AREAL,         X
               COUNT=RETCNT,PLISTVER=MAX,                              X
               SORTTAB=STAB@,SORTNUM=SORTNUM
*
* INPUT VALUES
*
AREA@    DC     A(RETAREA)               ADDRESS OF RETURN AREA
AREAL    DC     F'1024'                  LENGTH RETURN AREA
URSTMASK DC     A(STATES)                UR STATE MASK
STATES   EQU    ATR_IN_DOUBT_MASK+ATR_IN_COMMIT_MASK
*
STAB@    DC     A(SORTTAB)               SORT TABLE ADDRESS
SORTNUM  DC     F'2'                     ENTRIES IN SORT TABLE
SORTTAB  DS     0F                       SORT TABLE-WORD BOUNDARY
         DC     A(ATR_SORT_CREATE_TIME)  PRIMARY KEY
         DC     A(ATR_SORTOPT_ASCENDING) PRIMARY KEY OPTION
         DC     A(ATR_SORT_UR_STATE)     SECONDARY KEY
         DC     A(ATR_SORTOPT_ASCENDING) SECONDARY KEY OPTION
*
* OUTPUT AREAS
*
RETCNT   DS     F                        RETURNED RM COUNT
RETAREA  DS     1024C                    RETURN AREA
*
* REQUIRED MAPPINGS
*
         CVT DSECT=YES
         IHAECVT
         ATRFZQRY
         ATRRASM

Example 8

To return URs that have been In-Doubt more than 5 seconds, issue the following request: 
         ATRQUERY REQUEST=URINFO,AREAADDR=AREA@,AREALEN=AREAL,         X
               COUNT=RETCNT,PLISTVER=MAX,                              X
               SORTTAB=STAB@,SORTNUM=SORTNUM
*
* INPUT VALUES
*
AREA@    DC     A(RETAREA)               ADDRESS OF RETURN AREA
AREAL    DC     F'1024'                  LENGTH OF RETURN AREA
URSTMASK DC     A(STATES)                UR STATE MASK
STATES   EQU    ATR_IN_DOUBT_MASK+ATR_IN_COMMIT_MASK
*
STAB@    DC     A(SORTTAB)               SORT TABLE ADDRESS
SORTNUM  DC     F'2'                     ENTRIES IN SORT TABLE
SORTTAB  DS     0F                       SORT TABLE-WORD BOUNDARY
         DC     A(ATR_SORT_CREATE_TIME)  PRIMARY KEY
         DC     A(ATR_SORTOPT_ASCENDING) PRIMARY KEY OPTION
         DC     A(ATR_SORT_UR_STATE)     SECONDARY KEY
         DC     A(ATR_SORTOPT_ASCENDING) SECONDARY KEY OPTION
*
* OUTPUT AREAS
*
RETCNT   DS     F                        RETURNED RM COUNT
RETAREA  DS     1024C                    RETURN AREA
*
* REQUIRED MAPPINGS
*
         CVT DSECT=YES
         IHAECVT
         ATRFZQRY
         ATRRASM

Example 9

To return all the work manager names in the system, issue the following request: 
         ATRQUERY REQUEST=WMINFO,AREAADDR=AREA@,AREALEN=AREAL,         X
               COUNT=RETCNT,PLISTVER=MAX                               X
*
* INPUT VALUES
*
AREA@    DC     A(RETAREA)               ADDRESS OF RETURN AREA
AREAL    DC     F'1024'                  LENGTH OF RETURN AREA
*
* OUTPUT AREAS
*
RETCNT   DS     F                        RETURNED RM COUNT
RETAREA  DS     1024C                    RETURN AREA
*
* REQUIRED MAPPINGS
*
         CVT DSECT=YES
         IHAECVT
         ATRFZQRY
         ATRRASM

Example 10

Issue the following request to obtain information about URs that meet these conditions:
  • The URs are either In-Doubt or In-Commit.
  • RMs with names matching the pattern "UTR*" have interests in the URs.
  • The URs are sorted by LUWID from lowest to highest; and, in case of ties, sorted by UR creation time from oldest to newest.
         L   10,URSTMASK
         ATRQUERY REQUEST=URINFO,AREAADDR=AREA@,AREALEN=AREAL,         X
               RMNAME=MYRM,COUNT=RETCNT,PLISTVER=MAX,                  X
               URSTMASK=(10),SORTTAB=STABPTR,SORTNUM=SORTNUM
*
* INPUT VALUES
*
AREA@    DC     A(RETAREA)               ADDRESS OF RETURN AREA
AREAL    DC     F'1024'                  LENGTH OF RETURN AREA
MYRM     DC     CL32'UTR*'               RM NAME PATTERN
URSTMASK DC     A(STATES)
SORTNUM  DC     F'2'                     ENTRIES IN SORT TABLE
*
SORTTAB  DS     0F                        SORT TABLE-WORD BOUNDARY
SRTKEY1  DC     A(ATR_SORT_LUWID)         PRIMARY KEY
SRTOPT1  DC     A(ATR_SORTOPT_ASCENDING)  PRIMARY KEY OPTION
SRTKEY2  DC     A(ATR_SORT_CREATE_TIME)   SECONDARY KEY
SRTOPT2  DC     A(ATR_SORTOPT_DESCENDING) SECONDARY KEY OPTION
*
STABPTR  DC     A(SORTTAB)
STATES   EQU    ATR_IN_DOUBT_MASK+ATR_IN_COMMIT_MASK
*
* OUTPUT AREAS
*
RETCNT   DS     F                        RETURNED RM COUNT
RETAREA  DS     1024C                    RETURN AREA
*
* REQUIRED MAPPINGS
*
        CVT DSECT=YES
        IHAECVT
        ATRFZQRY
        ATRRASM

Example 11

Issue the following request to obtain information about URs that meet these conditions:
  • The URs are In-Doubt.
  • The URs are in logging group PLEX1 on any system in that logging group.
         ATRQUERY REQUEST=URINFO,AREAADDR=AREA@,AREALEN=AREAL,         X
               GNAME=MYGROUP,SYSNAME=ALLSYS,PLISTVER=MAX,              X
               RCTABLE=MYRC,RCNUM=MYRCNUM
*
* INPUT VALUES
*
AREA@    DC     A(RETAREA)               ADDRESS OF RETURN AREA
AREAL    DC     F'1024'                  LENGTH OF RETURN AREA
MYGROUP  DC     CL8'PLEX1'               LOGGING GROUP
ALLSYS   DC     CL8'*'                   ALL SYSTEMS
*
* OUTPUT AREAS
*
RETCNT   DS     F                        RETURNED COUNT
RETAREA  DS     1024C                    RETURN AREA
MYRC     DC     CL2304                   RCTABLE
MYRCNUM  DC     F                        RCTABLE ENTRIES
*
* REQUIRED MAPPINGS
*
        CVT DSECT=YES
        IHAECVT
        ATRFZQRY
        ATRRASM