CNZQUERY — Consoles query
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
- 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
- Register
- Contents
- 0-1
- Used as work registers by the system
- 2-13
- Unchanged
- 14-15
- Used as work registers by the system
Performance implications
None.
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.
| 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