 |
Description
CNZQUERY enables you to obtain information about the consoles component.
You can specify whether you want information about WTORs and the message
retention facility (AMRF) returned. The information is returned in
an answer area defined by mapping macro CNZMYQUA.
Environment
The requirements for the caller are:
| Environmental factor |
Requirement |
|---|
| Minimum authorization: |
Supervisor state or PKM 0 |
| Dispatchable unit mode: |
Task |
| Cross memory mode: |
Any PASN, any HASN, any SASN |
| AMODE: |
31-bit |
| ASC mode: |
Primary or access register (AR) |
| Interrupt status: |
Enabled for I/O and external interrupts |
| Locks: |
The caller must not be locked. |
| Control parameters: |
Control parameters must be in the primary address
space or, for AR-mode callers, must be in an address/data space that
is addressable through a public entry on the caller's dispatchable
unit access list (DU-AL). The user-provided answer area (via the
ANSAREAALET parameter) must be in a 2G data space on the caller's
dispatchable unit access list or must be a 2G commmon-area data space.
|
Programming requirements
The caller must include the CNZMYQUA macro to get a mapping of
the output area which is in the data space designated by the ANSAREAALET
keyword. This macro also includes symbolic constants for the return
and reason codes provided by this service.
It is recommended that, after using the returned information the
pages in the ANSAREAALET data space be released with the RELEASE parameter
of the DSPSERV macro.
Restrictions
The caller must not have EUT FRRs established.
Input register information
Before issuing the CNZQUERY macro, the caller does not have to
place any information into any general purpose register (GPR) unless
using it in register notation for a particular parameter, or using
it as a base register.
In that case, the caller does not have to place any information
into any access register (AR) unless using it in register notation
for a particular parameter, or using it as a base register.
Output register information
When control returns to the caller, the GPRs contain: - Register
- Contents
- 0
- Reason code if GPR15 is not 0
- 1
- Used as a work register by the system
- 2-13
- Unchanged
- 14
- Used as a work register by the system
- 15
- Return code
When control returns to the caller, the ARs contain: - Register
- Contents
- 0-1
- Used as work registers by the system
- 2-13
- Unchanged
- 14-15
- Used as work registers by the system
Syntax
The CNZQUERY macro is written as follows:
| Syntax |
Description |
|---|
| |
|
| name |
name: symbol. Begin name in
column 1. |
| |
|
| ␢ |
One or more blanks must precede CNZQUERY. |
| |
|
| CNZQUERY |
|
| |
|
| ␢ |
One or more blanks must follow CNZQUERY. |
| |
|
| WTOR=NO |
DEFAULT: WTOR=NO |
| WTOR=YES |
|
| |
|
| ,AMRF=NO |
DEFAULT: AMRF=NO |
| ,AMRF=YES |
|
| |
|
| ,ANSAREAALET=ansareaalet |
ansareaalet: 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 |
Default: PLISTVER=IMPLIED_VERSION |
| ,PLISTVER=MAX |
|
| ,PLISTVER=0 |
|
| |
|
| ,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 CNZQUERY macro invocation. The name must conform to the rules
for an ordinary assembler language symbol.
- WTOR=NO
- WTOR=YES
- An optional parameter that indicates whether or not information
about WTORs is to be returned.
DEFAULT: NO
- WTOR=NO
- Do not return information about WTORs.
- WTOR=YES
- Return information about WTORs. A queue of OREs is returned, each
of which has field ORERWQE which contains the address of the associated
WQE only when bits ORESUSP and OREINUSE are both off. When either
of those bits is on, there is no associated WQE, as the building of
the ORE is not yet complete. The address of the first ORE is in field
CNZMYQUAH_First_ORE_Addr. The ORE is mapped by IHAORE and the address
of the next ORE is in field ORELKP, with a zero value in ORELKP indicating
that this is the last element of the queue. The WQE is mapped by IHAWQE.
Bit Cnzmyquah_Valid_WTOR_INFO is set to 1 when the information is
successfully returned.
- ,AMRF=NO
- ,AMRF=YES
- A optional parameter that indicates whether or not information
about the action message retention facility (AMRF) is to be returned.
DEFAULT:
NO
- ,AMRF=NO
- Do not return information about the AMRF.
- ,AMRF=YES
- Return information about the AMRF. Three queues of WQEs are returned.
The address of the first immediate action WQE is in field CNZMYQUAH_First_IA_WQE_Addr.
The address of the first eventual action WQE is in field CNZMYQUAH_First_EA_Addr.
The address of the first critical eventual action WQE is in field
CNZMYQUAH_First_CEA_WQE_Addr. The WQE is mapped by IHAWQE and the
address of the next WQE is in field WQELKP, with a zero value in WQELKP
indicating that this is the last element of the queue. In addition,
some status information about AMRF is returned (field CNZMYQUAH_AMRF_Status).
Bit Cnzmyquah_Valid_AMRF_INFO is set to 1 when the information is
successfully returned.
- ,ANSAREAALET=ansareaalet
- A required input field that contains the ALET of the data space
which is to contain the output information. The data space must be
on the dispatchable unit access list or be a common area data space.
It must include the address range X'1000' through X'7FFFEFFF' (that
is, it is a 2G data space). It may contain the 0 and X'7FFFF000' pages.
The area is mapped by macro CNZMYQUA. The header area, mapped by dsect
CNZMYQUAHDR, will begin at location X'1000' in the data space.
To
code: Specify the RS-type address, or address in register (2)-(12),
of a fullword field.
- ,RETCODE=retcode
- An optional output parameter into which the return code is to
be copied 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 reason code is to
be copied from GPR 0.
To code: Specify the RS-type address
of a fullword field, or register (2)-(12).
- ,PLISTVER=IMPLIED_VERSION
- ,PLISTVER=MAX
- ,PLISTVER=0
- An optional input parameter in the "0–0" range that specifies
the version of the macro. PLISTVER is the only key allowed on the
list form of MF and determines which parakmeter list is generated.
Note that MAX may be specified instead of a number, and the parameter
list will be of the largest size currently supported. This size may
grow from release to release (thus possibly affecting the amount of
storage needed by your program). If your program can tolerate this, IBM® recommends
that you always specify MAX when creating the list form parameter
list as that will ensure that the list form parameter list is always
long enough to hold whatever parameters might be specified on the
execute form.
DEFAULT: IMPLIED_VERSION. When PLISTVER is
omitted, the default is the lowest version which allows all of the
parameters specified on the invocation to be processed.
To
code: Specify one of the following: - IMPLIED_VERSION
- MAX
- A decimal value of 0
- ,MF=S
- ,MF=(L,list addr)
- ,MF=(L,list addr,attr)
- ,MF=(L,list addr,0D)
- ,MF=(E,list addr)
- ,MF=(E,list addr,COMPLETE)
- An optional input parameter that specifies the macro form.
Use
MF=S to specify the standard form of the macro, which builds an inline
parameter list and generates the macro invocation to transfer control
to the service. MF=S is the default.
Use MF=L to specify the
list form of the macro. Use the list form together with the execute
form of the macro for applications that require reentrant code. The
list form defines an area of storage that the execute form uses to
store the parameters. Only the PLISTVER parameter may be coded with
the list form of the macro.
Use MF=E to specify the execute
form of the macro. Use the execute form together with the list form
of the macro for applications that require reentrant code. The execute
form of the macro stores the parameters into the storage area defined
by the list form, and generates the macro invocation to transfer control
to the service.
- ,list addr
- The name of a storage area to contain the parameters. For MF=S
and MF=E, this can be an RS-type address or an address in register
(1)-(12).
- ,attr
- An optional 1- to 60-character input string that you use to force
boundary alignment of the parameter list. Use a value of 0F to force
the parameter list to a word boundary, or 0D to force the parameter
list to a doubleword boundary. If you do not code attr,
the system provides a value of 0D.
- ,COMPLETE
- Specifies that the system is to check for required parameters
and supply defaults for omitted optional parameters.
ABEND codes
CNZQUERY might terminate abnormally with an abend code of X'0C2'.
See z/OS MVS System Codes for
an explanation and response for this code.
Return and reason codes
Return and reason code constants are defined in macro CNZMYQUA.
When the CNZQUERY macro returns control to your program, GPR 15
(and retcode, if you coded RETCODE) contains one
of the following hexadecimal return codes. GPR 0 (and rsncode,
if you coded RSNCODE) contains one of the following reason codes.
Table 1. Return and Reason
Codes for the CNZQUERY Macro| Hexadecimal Return Code |
Reason Code |
Equate symbol
Meaning and Action
|
|---|
| 00 |
00 |
Equate symbol: CNZQUERYRc_OK Meaning:
CNZQUERY request successful.
Action: None.
|
| 08 |
|
Equate symbol: CNZQUERYRc_InvParm Meaning:
CNZQUERY request specifies invalid parameter.
Action:
Refer to action under the individual reason code.
|
| 08 |
xxxx0801 |
Equate symbol: CnzqueryRsn_BadParmList Meaning:
Unable to access parameter list.
Action: Check for possible
storage overlay.
|
| 08 |
xxxx0802 |
Equate symbol: CnzqueryRsn_SrbMode Meaning:
SRB mode.
Action: Avoid requesting this function in
SRB mode.
|
| 08 |
xxxx0803 |
Equate symbol: CnzqueryRsn_NotEnabled Meaning:
Not enabled.
Action: Avoid requesting this function
while not enabled.
|
| 08 |
xxxx0804 |
Equate symbol: CnzqueryRsn_BadAnsAreaALET Meaning:
Bad answer area ALET.
Action: Make sure that the ALET
associated with the answer area is valid. The access
register might not have been set up correctly.
|
| 08 |
xxxx0805 |
Equate symbol: CnzqueryRsn_BadAnsArea Meaning:
Error accessing answer area. The data space might not have been defined
to span 2G.
Action: Make sure that the provided answer
area is a valid 2G data space.
|
| 08 |
xxxx0806 |
Equate symbol: CnzqueryRsn_ReservedNot0 Meaning:
Reserved field not 0.
Action: Check for possible storage
overlay of the parameter list.
|
| 08 |
xxxx0807 |
Equate symbol: CnzqueryRsn_BadParmlistALET Meaning: Bad parmlist ALET.
Action:
Make sure that the ALET of the parameter list is valid. The
access register might not have been set up correctly.
|
| 08 |
xxxx0808 |
Equate symbol: CnzqueryRsn_BadVersion Meaning:
Bad version number.
Action: Check for possible storage
overlay of the parameter list.
|
| 08 |
xxxx0809 |
Equate symbol: CnzqueryRsn_Locked Meaning:
Locked.
Action: Avoid requesting this function in this
environment.
|
| 08 |
080A |
Equate symbol: CnzqueryRsn_FRR Meaning:
An FRR is set.
Action: Avoid requesting this function
in this environment.
|
| 10 |
|
Equate symbol: CnzqueryRC_CompError Meaning:
Unexpected failure.
Action: Refer to the action provided
with the specific reason code.
|
| 10 |
xxxx1001 |
Equate symbol: CnzqueryRsn_CompError Meaning:
Unexpected failure. The state of the request is unpredictable.
Action:
Contact your system programmer.
|
Example
* * 25800000
* Example 1 * 25850000
* * 25900000
* Operation: * 25950000
* * 26000000
* After having established addressability and a dynamic area, * 26050000
* * 26100000
* * 26150000
* 1. Create a 2G data space * 26200000
* * 26250000
* 2. Add the data space to the dispatchable unit access list * 26300000
* * 26350000
* 3. Invoke CNZQUERY to retrieve WTOR and AMRF information * 26400000
* * 26450000
* 4. Examine the WTOR queue * 26500000
* * 26550000
* 5. Examine the AMRF Immediate Action queue * 26600000
* * 26650000
* 6. Delete the access list entry * 26700000
* * 26750000
* 7. Delete the data space * 26800000
* * 26850000
* * 26900000
* * 26950000
* The code is as follows. * 27000000
* * 27050000
* SAC 512 Enter AR ASC mode * 27100000
* SYSSTATE ASCENV=AR,ARCHLVL=2 * 27150000
* ************************************************************* * 27200000
* * Create a 2G data space * * 27250000
* ************************************************************* * 27300000
* DSPSERV CREATE,NAME=dsName,BLOCKS=MaxBlocks, * * 27350000
* STOKEN=dsSTOKEN, * * 27400000
* MF=(E,DSPSERVL) * 27450000
* * * 27500000
* * Place code here to check return code from GPR 15 and * 27550000
* * reason code from GPR 0. * 27600000
* * * 27650000
* ************************************************************* * 27700000
* * Add the data space to the dispatchable unit access list * * 27750000
* ************************************************************* * 27800000
* ALESERV ADD,STOKEN=dsSTOKEN,ALET=dsALET, * * 27850000
* MF=(E,ALESERVL) * 27900000
* * * 27950000
* * Place code here to check return code from GPR 15. * 28000000
* * * 28050000
* ************************************************************* * 28100000
* * Retrieve WTOR and AMRF information * * 28150000
* ************************************************************* * 28200000
* CNZQUERY WTOR=YES,AMRF=YES,ANSAREAALET=dsALET, * * 28250000
* RETCODE=LRetcode,RSNCODE=LRsncode, * * 28300000
* MF=(E,CNZQUERYL) * 28350000
* * * 28400000
* * Place code here to check return/reason codes. * 28450000
* * * 28500000
* LHI 2,HeaderAddr Access header info * 28550000
* LAM 2,2,dsALET With ALET * 28600000
* USING CnzmyquaHdr,2 * 28650000
* ************************************************************* * 28700000
* * Examine the WTOR queue * * 28750000
* ************************************************************* * 28800000
* CPYA 3,2 ORE ALET = hdr ALET * 28850000
* ICM 3,B'1111',Cnzmyquah_First_ORE_Addr * 28900000
* JZ NO_OREs * 28950000
* USING OREF,3 * 29000000
* CPYA 4,2 WQE ALET = ORE ALET * 29050000
* NEXT_ORE DS 0H * 29100000
* L 4,ORERWQE * 29150000
* USING WQE,4 * 29200000
* * * 29250000
* * Place code here to examine the specific ORE and * 29300000
* * its associated WQE * 29350000
* * * 29400000
* DROP 4 * 29450000
* ICM 3,B'1111',ORELKP * 29500000
* JNZ NEXT_ORE * 29550000
* DROP 3 * 29600000
* NO_OREs DS 0H * 29650000
* ************************************************************* * 29700000
* * Examine the AMRF Immediate Action queue * * 29750000
* ************************************************************* * 29800000
* CPYA 3,2 WQE ALET = hdr ALET * 29850000
* ICM 3,B'1111',Cnzmyquah_First_IA_WQE_Addr * 29900000
* JZ NO_WQEs * 29950000
* USING WQE,3 * 30000000
* NEXT_WQE DS 0H * 30050000
* * * 30100000
* * Place code here to examine the specific WQE. * 30150000
* * * 30200000
* ICM 3,B'1111',WQELKP * 30250000
* JNZ NEXT_WQE * 30300000
* DROP 3 * 30350000
* NO_WQEs DS 0H * 30400000
* ************************************************************* * 30450000
* ************************************************************* * 30500000
* * Delete the access list entry * * 30550000
* ************************************************************* * 30600000
* ALESERV DELETE,ALET=dsALET, * * 30650000
* MF=(E,ALESERVL) * 30700000
* * * 30750000
* * Place code here to check return code from GPR 15. * 30800000
* * * 30850000
* ************************************************************* * 30900000
* * Delete the data space * * 30950000
* ************************************************************* * 31000000
* DSPSERV DELETE,STOKEN=dsSTOKEN, * * 31050000
* MF=(E,DSPSERVL) * 31100000
* * * 31150000
* * Place code here to check return code from GPR 15 and * 31200000
* * reason code from GPR 0. * 31250000
* * * 31300000
* ************************************************************* * 31350000
* * Exit the module * * 31400000
* ************************************************************* * 31450000
* * * 31500000
* * Place code here to free the dynamic area and * 31550000
* * exit the module. * 31600000
* * here * 31650000
* * * 31700000
* HeaderAddr EQU x'1000' Where Cnzmyqua_Hdr is placed * 31750000
* STATAREA DS 0D * 31800000
* dsName DC CL8'MYDATASP' * 31850000
* MaxBlocks DC A(524288) Number of blocks in full 2G data space* 31900000
* DYNAREA DSECT * 31950000
* dsSTOKEN DS D * 32000000
* dsALET DS D * 32050000
* LRetcode DS F * 32100000
* LRsncode DS F * 32150000
* ListForms DS 0D * 32200000
* DSPSERV MF=(L,DSPSERVL) * 32250000
* ORG ListForms * 32300000
* ALESERVL ALESERV MF=L * 32350000
* ORG ListForms * 32400000
* CNZQUERY MF=(L,CNZQUERYL) * 32450000
* ORG , * 32500000
* CNZMYQUA Output information * 32550000
* IHAWQE WQE * 32600000
* IHAORE ORE * 32650000
* * 32700000
|
z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN
Copyright IBM Corporation 1990, 2014