Group query request (TYPE=*GROUP)
You can use the Group query (DSPAPI FUNC=QUERY TYPE=*GROUP) request to retrieve group and member information for various types of groups that are registered in the RECON data set.
The following list outlines the groups that you can retrieve information for through the Group query (DSPAPI FUNC=QUERY TYPE=*GROUP) request:
- DBDS group (TYPE=DBDSGROUP)
- DB group (TYPE=DBGROUP)
- Recovery group (TYPE=RECOVGROUP)
- CA group (TYPE=CAGROUP)
Subsections:
- Syntax for the TYPE=*GROUP query request
- Parameters for the TYPE=*GROUP query request
- Return and reason codes for the TYPE=*GROUP query request
- Output for the TYPE=*GROUP query request
- Output for QUERY TYPE=DBDSGROUP, DBGROUP, and RECOVGROUP
- DSECT of DSPAPQDG
- Output for QUERY TYPE=CAGROUP
- DSECT of DSPAPQCG
- DSECT of DSPAPQCA
Syntax for the TYPE=*GROUP query request
Parameters for the TYPE=*GROUP query request
- name
- Optional symbol you can specify. If used, begins in column 1.
- TYPE=DBDSGROUP | DBGROUP | RECOVGROUP | CAGROUP
- Specifies the type of group for which information is requested.
- CAINFO= YES | NO
- Specifies whether CA execution information is to be included with
the CAGROUP information. CAINFO is valid only with TYPE=CAGROUP. CAINFO
defaults to NO when TYPE=CAGROUP is specified, indicating that only
the CA group member information is requested.
If CAINFO=NO is specified or if CAINFO=YES is specified and no CA execution information exists, the block-dependent pointer (apqhd_depptr) in the header of the CAGROUP block is 0.
- TOKEN=symbol | (2 - 12)
- Specifies the address of a 4-byte field that was returned on the FUNC=STARTDBRC request.
- GROUP= * | symbol | symbol* | (2 - 12)
- Specifies the name of the group being queried. You can use the
wildcard keyword * (an asterisk) alone to request information about
all groups. You can also use the wildcard at the end of a name, in
which case the asterisk must be preceded by at least one alphabetic
character. The default is GROUP=*.
Either the GROUP keyword or the NAME keyword can be used. GROUP is preferred. NAME is accepted for compatibility.
- NAME= * | symbol | symbol* | (2 - 12)
- See the GROUP parameter.
- MF=S | L | M | E
- 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 group information blocks. See Output for the TYPE=*GROUP query request for a detailed description
of the information blocks returned.
The output address is zero if no output was built which can occur if nothing in the RECON satisfies the request or if an error occurs before any output could be 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)
- If specified as a symbol, specifies the label of a word of storage to receive the return code. If specified as a register, the register must contain the address of a word of storage to receive the return code. Regardless of whether RETCODE is specified, register 15 contains the return code.
- RSNCODE=reasoncode | (2-12)
- If specified as a symbol, the symbol must be the label of a word of storage to receive the reason code. If specified as a register, the register must contain the address of a word of storage to receive the reason code. Regardless of whether RSNCODE is specified, register 0 contains the reason code.
- 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=xxxxGROUP request are 1.0 and 2.0.
Return and reason codes for the TYPE=*GROUP query request
The following table contains most of the return and reason codes for TYPE=*GROUP query requests.
| Code type | Return codes | Reason codes | Meaning |
|---|---|---|---|
| X'00000000' | X'00000000' | Request completed successfully. | |
| Warning | X'00000008' | X'D8300001' | No group records of the requested type exist in the RECON data set. |
| 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'D8300100' | 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'D8300001' | Error obtaining storage for CAGROUP block. |
| X'00000028' | X'D8300003' | Error obtaining storage for DBDSGRP, DBGRP, or RECOVGRP block. | |
| X'00000028' | X'D8310001' | Error obtaining storage for CA block. | |
| X'00000028' | X'D9100001' | An error occurred processing the request. DBRC releases 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'D8300001' | Failure locating a specific group record or the first group record of the requested group type. | |
| X'0000002C' | X'D8300002' | Failure locating the next group record of the requested group type. | |
| X'0000002C' | X'D8300003' | Failure locating a CA record. | |
| 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'C9000008' | Invalid GROUP or NAME field address. The address of the field containing the group name 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'D8300001' | CAINFO=YES is only allowed with TYPE=CAGROUP. | |
| X'00000030' | X'D8300100' | When using a wildcard, at least one alphabetic character must precede the asterisk. | |
| X'00000030' | X'D8300101' | When using a wildcard, the asterisk must be the last character. |
Output for the TYPE=*GROUP query request
The next few figures illustrate the format of the output from a QUERY TYPE=*GROUP requests. Following the figures that graphically describe the layout of the output are sample DSECTs that describe in detail the fields of the storage blocks and their relationship to each other.
Output for QUERY TYPE=DBDSGROUP, DBGROUP, and RECOVGROUP
DSECT of DSPAPQDG
OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== ============================
0 (0) STRUCTURE 32 DSPAPQDG
0 (0) CHARACTER 8 APQDG_GROUPNAME Group name
8 (8) UNSIGNED 4 APQDG_MEMBERINFO Offset to group member list
12 (C) UNSIGNED 2 APQDG_MEMBERLEN Length of group member entry
14 (E) SIGNED 2 APQDG_MEMBERCOUNT Number of group members
16 (10) SIGNED 4 *(3) Reserved
28 (1C) CHARACTER 4 * Reserved
OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== ============================
0 (0) STRUCTURE 16 APQDG_MEMBER List of group members
0 (0) CHARACTER 16 *
0 (0) CHARACTER 16 APQDG_DBDSG DBDS group
0 (0) CHARACTER 8 APQDG_DBDSG_DBNAME Database name
8 (8) CHARACTER 8 *
8 (8) CHARACTER 8 APQDG_DBDSG_DDNAME DD name or
8 (8) CHARACTER 8 APQDG_DBDSG_AREANAME AREA name
0 (0) CHARACTER 16 APQDG_DBG DB group
0 (0) CHARACTER 8 *
0 (0) CHARACTER 8 APQDG_DBG_DBNAME Database name or
0 (0) CHARACTER 8 APQDG_DBG_AREANAME AREA name
8 (8) CHARACTER 8 * Not used
0 (0) CHARACTER 16 APQDG_RECOVG Recovery group
0 (0) CHARACTER 8 APQDG_RECOVG_DBNAME Database name
8 (8) CHARACTER 8 APQDG_RECOVG_AREANAME AREA name, null if
not Fast Path
CONSTANTS
LEN TYPE VALUE NAME DESCRIPTION
===== ========= ================= =============== ===============================
8 CHARACTER DSPAPQDG APQDG_EYECATCHEROutput for QUERY TYPE=CAGROUP
The CA block is only returned when CAINFO=YES is specified and records of a change accumulation exist in the RECON.
DSECT of DSPAPQCG
OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== ===============================
0 (0) STRUCTURE 48 DSPAPQCG
0 (0) CHARACTER 8 APQCG_GROUPNAME Group name
8 (8) UNSIGNED 4 APQCG_MEMBERINFO Offset to group member list
12 (C) UNSIGNED 2 APQCG_MEMBERLEN Length of group member entry
14 (E) SIGNED 2 APQCG_MEMBERCOUNT Number of group members
16 (10) SIGNED 4 *(2) Reserved
24 (18) SIGNED 2 APQCG_GRPMAX Maximum number of CAs that may
be predefined for this CA group
26 (1A) SIGNED 2 APQCG_AVAILCA# Number of available CA data
sets for this group
28 (1C) SIGNED 2 APQCG_USEDCA# Number of used CA data sets
30 (1E) BIT(8) 1 APQCG_FLAGS Flags
1... .... APQCG_REUSE Reuse CA data sets
31 (1F) CHARACTER 1 * Reserved
32 (20) CHARACTER 8 APQCG_CAJCL GENJCL CAJCL member name
40 (28) CHARACTER 8 APQCG_DFJCL DEFLTJCL member name
48 (30) SIGNED 2 APQCG_RECOVPD Retention Period (Version=4.0)
OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== ===============================
0 (0) STRUCTURE 16 APQCG_MEMBER List of group members
0 (0) CHARACTER 8 APQCG_DBNAME Database name
8 (8) CHARACTER 8 *
8 (8) CHARACTER 8 APQCG_DDNAME DD name or
8 (8) CHARACTER 8 APQCG_AREANAME AREA name
CONSTANTS
LEN TYPE VALUE NAME DESCRIPTION
===== ========= ================= =============== ===============================
8 CHARACTER DSPAPQCG APQCG_EYECATCHERDSECT of DSPAPQCA
OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== ===============================
0 (0) STRUCTURE 96 DSPAPQCA
0 (0) CHARACTER 8 APQCA_GROUPNAME Group name
8 (8) UNSIGNED 4 APQCA_MEMBERINFO Offset to group member list
12 (C) UNSIGNED 2 APQCA_MEMBERLEN Length of each member entry
14 (E) SIGNED 2 APQCA_MEMBERCOUNT Number of group members
16 (10) UNSIGNED 4 APQCA_VOLINFO Offset to volume information
20 (14) SIGNED 4 * Reserved
24 (18) CHARACTER 44 APQCA_DSN Data set name
68 (44) CHARACTER 12 APQCA_STOPTIME Packed decimal date/time - for
predefined datasets, represents
record creation time.
Otherwise, it is the stoptime
of the last logtape volume used
as input to the Change
Accumulation utility that
produced this CA as output. If
the CA run included an
'incomplete log subset' it is
the start time of the first
truncated log volume.
80 (50) CHARACTER 12 APQCA_RUNTIME CA run time
92 (5C) BIT(8) 1 APQCA_FLAGS Flags
1... .... APQCA_ERROR Error on data set
.1.. .... APQCA_SUBSET Subset of logs used for CA
..1. .... APQCA_COMMAND SUBSET/COMP has been set or
reset with an external cmd
...1 .... APQCA_AVAIL Available CA indicator
93 (5D) CHARACTER 3 * Reserved
96 (60) UNSIGNED 4 APQCA_OFFUD Offset to user data (VERSION=4.0)
100 (64) UNSIGNED 2 APQCA_LENUD Length of user data (VERSION=4.0)
OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== ===============================
0 (0) STRUCTURE 80 APQIC_USER Data for user IC
0 (0) CHARACTER 80 APQRV_UDATA User supplied data (VERSION=4.0)
OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== ===============================
0 (0) STRUCTURE 56 APQCA_MEMBER List of group members
0 (0) CHARACTER 8 APQCA_MEM_DBNAME Database name
8 (8) CHARACTER 8 *
8 (8) CHARACTER 8 APQCA_MEM_DDNAME DD name or
8 (8) CHARACTER 8 APQCA_MEM_AREANAME AREA name
16 (10) UNSIGNED 4 APQCA_MEM_DSSN Data Set sequence number
20 (14) UNSIGNED 4 APQCA_MEM_USID USID of last change
accumulated
24 (18) CHARACTER 8 APQCA_MEM_LRID LRID of last change accumulated
32 (20) CHARACTER 12 APQCA_MEM_PURGETIME Purge time
44 (2C) CHARACTER 6 APQCA_MEM_LSN Lock sequence number
50 (32) BIT(8) 1 APQCA_MEM_FLAGS Member flags
1... .... APQCA_MEM_NOCHG No changes accumulated
.1.. .... APQCA_MEM_INDOUBT Indoubt EEQEs accumulated
..1. .... APQCA_MEM_INCOMP Incomplete CA
51 (33) CHARACTER 5 * Reserved