Subsystem query request (TYPE=SUBSYS)
You can use the Subsystem query (DSPAPI FUNC=QUERY TYPE=SUBSYS) request to retrieve subsystem information from the RECON data set for a specific subsystem or all subsystems.
Syntax for the TYPE=SUBSYS query request
Parameters for the TYPE=SUBSYS query request
- name
- Optional symbol you can specify. If used, begins in column 1.
- TYPE=SUBSYS
- Specifies that subsystem information is requested.
- TOKEN=address | (2 - 12)
- Specifies the address of a 4-byte field that was returned on the FUNC=STARTDBRC request.
- SSID= * | name* | name | (2 - 12)
- Specifies the name of the subsystem being queried. You can use the wildcard keyword * (an asterisk) alone to request information about all subsystems (SSID=*, the default). You can also use it at the end of a name to query subsystems whose names match the pattern. In this case, the asterisk must be preceded by at least one alphabetic character.
- SSYTYPE=ALL | ONLINE | BATCH | DBRCAPI
- Specifies the type of subsystem for which information is being requested. You cannot specify this parameter if you also specify a specific subsystem name for the SSID parameter or if you specify TRACKER=YES. SSTYPE=DBRCAPI requires that you specify a minimum version number of VERSION=2.0. SSTYPE=ALL is the default.
- MF=S | L | M | E
- Optional parameter that specifies the macro form of the request.
- OUTPUT=output | (2 - 12)
- Specifies a field to receive a pointer to the first block of a
possible chain of subsystem information blocks.
The output address is 0 if no output was built which can occur if nothing in the RECON satisfies the request or if an error occurs before any output is built.
The storage for the output blocks is not preallocated by the caller. DBRC acquires storage from the specified subpool for these blocks. The caller must free this storage using the Buffer Release service (DSPAPI FUNC=RELBUF) and specify the returned output address.
- SUBPOOL= 0 | number
- Specifies the subpool number for the storage being obtained. If not specified, the default is the subpool specified by the FUNC=STARTDBRC request. Otherwise, subpool 0 is the default.
- RETCODE=returncode | (2 - 12)
- Specifies a place in storage to receive the return code. If specified as a symbol, the symbol must be the label of a word of storage. If specified as a register, the register must contain the address of a word of storage. If not specified, the return code is placed in register 15.
- RSNCODE=reasoncode | (2 - 12)
- Specifies a place in storage to receive the reason code. If specified as a symbol, the symbol must be the label of a word of storage. If specified as a register, the register must contain the address of a word of storage. If not specified, the reason code is placed in register 0.
- VERSION=2.0 | number
- Specifies the version number of the parameter list to be generated
by this request.
To use the parameters associated with a version, you must specify the number of that version or a later version. If you specify an earlier version level, the parameter is not accepted by macro processing, and an error message is issued at assembly time. If parameters have a version dependency, the parameter descriptions with each request type identify the version number required.
Valid version numbers for the FUNC=QUERY TYPE=SUBSYS request are 1.0 and 2.0.
Return and reason codes for the TYPE=SUBSYS query request
| Code type | Return codes | Reason codes | Meaning |
|---|---|---|---|
| X'00000000' | X'00000000' | Request completed successfully. | |
| Warning | X'00000008' | X'D8600001' | No subsystem record of the requested type, active or tracker, exists. |
| X'00000008' | X'D8600002' | No batch or online subsystem records exist. | |
| Severe error | X'0000000C' | X'C9000001' | Invalid TOKEN. The TOKEN block passed to the API is not recognized as a TOKEN created by a FUNC=STARTDBRC call. |
| X'0000000C' | X'C900000A' | The TCB address is not the same as the TCB address under which the STARTDBRC service was issued. | |
| X'0000000C' | X'D8600100' | Security error. SAF or the DBRC Command Authorization exit routine (DSPDCAX0) determined that the user is not authorized to perform the request. | |
| Storage error | X'00000028' | X'D8600001' | Error obtaining storage for SUBSYS block. |
| X'00000028' | X'D9100001' | An error occurred processing the request. DBRC will release storage that was obtained up to this point. However, another error was encountered during the attempt to release storage. | |
| Internal error | X'0000002C' | X'D8000001' | RECON open failure. |
| X'0000002C' | X'D8600001' | Failure attempting to locate the first or the specified subsystem record of the requested type, active or tracker. | |
| X'0000002C' | X'D8600002' | Failure attempting to locate the next subsystem record of the requested type, active or tracker. | |
| Parameter error | X'00000030' | X'C9000001' | The function (FUNC) specified in the parameter list passed to the API is invalid. |
| X'00000030' | X'C9000002' | Invalid TOKEN field address. The address of the field containing the API TOKEN failed validity checking. The address specifies storage not owned by the calling program. | |
| X'00000030' | X'C9000003' | Invalid RETCODE field address. The address of the field to contain the API RETCODE failed validity checking. The address specifies storage not owned by the calling program. | |
| X'00000030' | X'C9000004' | Invalid RSNCODE field address. The address of the field to contain the API RSNCODE failed validity checking. The address specifies storage not owned by the calling program. | |
| X'00000030' | X'C9000005' | Invalid OUTPUT field address. The address of the field to contain the OUTPUT address failed validity checking. The address specifies storage not owned by the calling program. | |
| X'00000030' | X'C9000010' | Invalid SSID field address. The address of the field containing the SSID failed validity checking. The address specifies storage not owned by the calling program. | |
| X'00000030' | X'D8000001' | Missing or invalid OUTPUT parameter. | |
| X'00000030' | X'D8000002' | Invalid value specified for TYPE parameter. | |
| X'00000030' | X'D8600001' | SSTYPE=ONLINE|BATCH|DBRCAPI cannot be specified on requests for a specific SSID or for a tracking subsystem request (TRACKER=YES). | |
| X'00000030' | X'D8600100' | When using a wildcard, at least one alphabetic character must precede the asterisk. | |
| X'00000030' | X'D8600101' | When using a wildcard, the asterisk must be the last character. |
Output for the TYPE=SUBSYS query request
The following figure illustrates the format of the output from a QUERY TYPE=SUBSYS request. The following DSECT sample describes in detail the fields of the storage blocks and their relationship to each other.
DSECT of DSPAPQSS
OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== ===============================
0 (0) STRUCTURE 64 DSPAPQSS
0 (0) CHARACTER 8 APQSS_SSID Subsystem identifier
8 (8) UNSIGNED 4 APQSS_AUTHLIST Offset to authd DB/Area list
12 (C) SIGNED 4 APQSS_AUTHCOUNT Number of authorized DB/Areas
16 (10) UNSIGNED 2 APQSS_AUTHLEN Length of auth entry
18 (12) CHARACTER 6 * Reserved
24 (18) CHARACTER 12 APQSS_LOGTIME Start time of log
36 (24) UNSIGNED 1 APQSS_RELLVL Subsystem release level
'71'X=V7R1,'81'X=V8R1
'91'X=V9R1, etc.
37 (25) CHARACTER 1 APQSS_COEXLVL Coexistence level
38 (26) UNSIGNED 1 APQSS_IRLMCT IRLM status count
39 (27) CHARACTER 1 * Reserved
40 (28) CHARACTER 8 APQSS_GSGNAME Global Service Group name
48 (30) CHARACTER 5 APQSS_IRLMID IRLM ID of SS
53 (35) CHARACTER 5 APQSS_IRLMBK IRLM ID of backup SS
58 (3A) BIT(8) 1 APQSS_FLAGS Flags
1... .... APQSS_TYPE 1=Online | 0=batch
.1.. .... APQSS_ABTERM Abnormal termination
..1. .... APQSS_RCVPRC Recovery processing started
...1 .... APQSS_BKSIGN Backup SS signed on
.... 1... APQSS_IRLMFL IRLM failure
.... .1.. APQSS_COMMFL COMM failure
.... ..1. APQSS_SYSFL SYS failure
.... ...1 APQSS_ACTVST Status of active SS when backup exists, 1=abterm
59 (3B) BIT(8) 1 APQSS_FLAGS2 FLAGS 2
1... .... APQSS_SHRING Sharing covered DBs
.1.. .... APQSS_TRKER Subsystem is a Tracker
..1. .... APQSS_TRKTRM TRACKER has terminated
...1 .... APQSS_TRCKED SSID is tracked
.... 1... APQSS_FRSTSO 1ST signon after RSR takeover is in progress
.... .1.. APQSS_XRFCAP SS is XRF capable
.... ..1. APQSS_DBRCAPI SS is a DBRC application
(VERSION=2.0)
.... ...1 APQSS_BPE BPE-based subsystem (VERSION=4.0)
.... ..11 * Reserved
60 (3C) SIGNED 2 APQSS_BCKTKN Backup recovery token
62 (3E) CHARACTER 2 * Reserved OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== ===============================
0 (0) STRUCTURE 32 APQSS_AUTHNAME Names of authd DB/Areas
0 (0) CHARACTER 8 APQSS_DBNAME DB name
8 (8) CHARACTER 8 APQSS_AREANM If FP, Area name
16 (10) UNSIGNED 1 APQSS_SHRLVL Share level
17 (11) UNSIGNED 1 APQSS_DBACCS Access intent
18 (12) UNSIGNED 1 APQSS_DBNCOD Encoded state
19 (13) UNSIGNED 1 APQSS_DBSTAT DB status flags
20 (14) UNSIGNED 2 APQSS_DBEQCT DB EQE count
22 (16) SIGNED 2 APQSS_GLBDMB Global DMB number
24 (18) BIT(8) 1 APQSS_AUTHFLAGS Flags
1... .... APQSS_NRDBUP Nonrecov DB/Area updated
.1.. .... APQSS_COVRD DB covered by GSG
..1. .... APQSS_NRECV nonrecoverable DB/Area
...1 .... APQSS_ORDBDS 0=A-J/1=M-V ACTIVE
.... 1... APQSS_OLRON 0 = no OLR active
.... .1.. APQSS_OLROWR 0 = no OLR owner
.... ..1. APQSS_OLROWD 0 OLR not owned by SS
25 (19) CHARACTER 7 * Reserved
CONSTANTS
LEN TYPE VALUE NAME DESCRIPTION
===== ========= ================= =============== ===============================
8 CHARACTER DSPAPQSS APQSS_EYECATCHER