|
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:
Minimum authorization: |
Problem state, any PSW key, or RACF® authority as defined in the
following paragraphs |
Dispatchable unit mode: |
Task |
Cross memory mode: |
Any PASN, any HASN, any SASN |
AMODE: |
31-bit |
ASC mode: |
Primary |
Interrupt status: |
Enabled for I/O and external interrupts |
Locks: |
No locks may be held |
Control parameters: |
Control parameters must be in the
primary address space. |
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.
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.
|
|
|
name |
name: symbol.
Begin name in column 1. |
|
␢ |
One or more blanks must precede ATRQUERY. |
|
ATRQUERY |
|
␢ |
One or more blanks must follow ATRQUERY. |
|
|
|
REQUEST=RMINFO |
|REQUEST=WMINFO |
|REQUEST=SYSINFO |
|REQUEST=URINFO |
|
,RMNAME=rmname |
rmname: RS-type
address or address in register (2) - (12). |
|
,WMNAME=wmname |
wmname: RS-type
address or address in register (2) - (12). |
|
,ASID=asid |
asid: RS-type
address or address in register (2) - (12). |
|
,URID=urid |
urid: RS-type
address or address in register (2) - (12). |
|
|,URIDSTR=uridstr |
uridstr: RS-type
address or address in register (2) - (12). |
|
,SURID=surid |
surid: RS-type
address or address in register (2) - (12). |
|
|,SURIDSTR=suridstr |
suridstr: RS-type
address or address in register (2) - (12). |
|
,URTYPE=urtype |
urtype: symbol
or value in register (2) - (12). |
|
,URSTATE=urstate |
urstate: symbol
or value in register (2) - (12). |
|
|,URSTMASK=urstmask |
urstmask: RS-type
address or address in register (2) - (12). |
|
,LUWID=luwid |
luwid: RS-type
address or address in register (2) - (12). |
|
|,LUWIDSTR=luwidstr |
luwidstr: RS-type
address or address in register (2) - (12). |
|
,TID=tid |
tid: RS-type address
or address in register (2) - (12). |
|
|,TIDLOW=tidlow |
tidlow: RS-type
address or address in register (2) - (12). |
|
|,TIDHIGH=tidhigh |
tidhigh: RS-type
address or address in register (2) - (12). |
|
,GTID=gtid |
gtid: RS-type
address or address in register (2) - (12). |
|
|,GTIDSTR=gtidstr |
gtidstr: RS-type
address or address in register (2) - (12). |
|
|,XID=xid |
xid: RS-type address
or address in register (2) - (12). |
|,XIDFORMATIDSTR=
xidformatidstr
|
xidformatidstr: RS-type
address or address in register (2) - (12). |
|,XIDGTRIDSTR=
xidgtridstr
|
xidgtrridstr: RS-type
address or address in register (2) - (12). |
|,XIDBQUALSTR=
xidbqualstr
|
xidbqualstr: RS-type
address or address in register (2) - (12). |
|
,RMNAME=rmname |
rmname: RS-type
address or address in register (2) - (12). |
|
,WMNAME=wmname |
wmname: RS-type
address or address in register (2) - (12). |
,GNAME=gname |
gname: RS-type
address or address in register (2) - (12). |
,SYSNAME=sysname |
sysname: RS-type
address or address in register (2) - (12). |
,METADATA |
|
|
,TODBEG=todbeg |
todbeg: RS-type
address or address in register (2) - (12). |
|
,TODEND=todend |
todend: RS-type
address or address in register (2) - (12). |
|
,CURDUR=curdur |
curdur: RS-type
address or address in register (2) - (12). |
|
,DEFURONLY=defuronly |
defuronly: RS-type
address or address in register (2) - (12). |
|
|,EXCLMASK=exclmask |
exclmask: RS-type
address or address in register (2) - (12). |
|
,SORTTAB=sorttab |
sorttab: RS-type
address or address in register (2) - (12). |
,SORTNUM=sortnum |
sortnum: RS-type
address or address in register (2) - (12). Note: SORTTAB and SORTNUM
must be specified together, on the same line, separated by a comma.
|
|
,EXINFOMASK=exinfomask |
exinfomask: RS-type
address or address in register (2) - (12). |
|
,AREAADDR=areaaddr |
areaaddr: RS-type
address or address in register (2) - (12). |
|
,AREALEN=arealen |
arealen: RS-type
address or address in register (2) - (12). |
,AREAALET=areaalet |
areaalet: RS-type
address or address in register (2) - (12). |
|,AREAOPT=BYADDR |
Return complete addresses in the
control structures |
|,AREAOPT=BYOFFSET |
Return offsets from the beginning
of the storage area in the control structures |
|
,COUNT=count |
count: RS-type
address or address in register (2) - (12). |
|
,RCTABLE=rctable |
rctable: RS-type
address or address in register (2) - (12). |
,RCNUM=rcnum |
rcnum: RS-type
address or address in register (2) - (12). |
|
,RETCODE=retcode |
retcode: RS-type
address or register (2) - (12). |
|
,RSNCODE=rsncode |
rsncode: RS-type
address or register (2) - (12). |
|
,PLISTVER=IMPLIED_VERSION |
|
,PLISTVER=MAX |
Default: PLISTVER=IMPLIED_VERSION |
,PLISTVER=1 |
,PLISTVER=2 |
,PLISTVER=3 |
,PLISTVER=4 |
,PLISTVER=5 |
,PLISTVER=6 |
,PLISTVER=7 |
|
,MF=S |
Default: MF=S |
,MF=(L,list addr) |
list addr: RS-type
address or register (1) - (12). |
,MF=(L,list
addr,attr) |
,MF=(L,list
addr,0D) |
,MF=(E,list
addr) |
,MF=(E,list addr,COMPLETE) |
|
|
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: - 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.
- 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: - 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.
- 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: - 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.
- 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 ParameterSort 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:
- 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:
- 7, if you use the parameters from PLISTVER=6 plus the following
parameters:
- 8, if you use the parameters from PLISTVER=7 plus the following
parameters:
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.
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
|