DBDS query request (TYPE=DBDS)
You can use the DSPAPI FUNC=QUERY TYPE=DBDS request to retrieve information from the RECON data set for one or more DBDSs in a non-HALDB database, a HALDB partition, a DBDS group, or a CA group. You can also request recovery related information for the data set, including allocation, image copy, recovery, and reorganization information.
Syntax for the TYPE=DBDS query request
Parameters for the TYPE=DBDS query request
- name
- If used, begins in column 1.
- TYPE=DBDS
- Specifies that RECON information for a DBDS or area is requested.
Specifying DBDS with the TYPE parameter requires that you also specify a minimum version number of VERSION=2.0.
- TOKEN=address | (2 - 12)
- Specifies the address of a 4-byte field to receive the API token. This token must be included in all subsequent requests associated with this FUNC=STARTDBRC request.
- DBNAME=name | (2 -12)
- Specifies the database name (non-HALDB) or partition name of the
DBDS being queried. This parameter is used when you are interested
in a specific DBDS of a database or partition. Specifying a HALDB
name is not allowed.
DBDNAME OR PARTNAME must be specified.
- GROUP=name | (2 -12)
- Specifies the name of a DBDS group or CA group containing the
names of the DBDSs being queried. The LOC or DDN parameters are not
allowed with this parameter.
DBNAME or GROUP must be specified. Database and recovery group names are not allowed.
The wildcard GROUP=* can be used for all TYPE=xxxxGROUP queries, but not for TYPE=DBDS. However, it can be used for TYPE=DBDSGROUP.
- DDN=ddname | (2 -12)
- Specifies the DD name of the data sets or areas. This parameter
is used in conjunction with the DBNAME parameter and the LOC parameter
to query a specific data set or the next or previous data set in the
database or partition. DDN=* returns information for all of the data
sets or areas of the database. DDN=* is the default when DBNAME is
specified without LOC=FIRST.
DDN must be specified with LOC=SPEC|NEXT.
When querying the next or previous data set, the value in the DDN parameter is used as the base of the search and does not need to be a DD name of a DBDS registered in RECON for the database or partition.
- LIST=NONE | LIST=({ALLOC},{IC},{RECOV},{REORG}) | LIST=ALL
- Specifies the types of supporting information to be included in
the query output for the returned DBDS. One or more of the specific
values is included in the list - ALLOC (allocation records), IC (image
copy records), RECOV (recovery records), or REORG (reorganization
records). LIST=ALL is specified if all supporting information is
requested. LIST=NONE is specified if no supporting information is
requested.
LIST=NONE is the default.
- LOC=FIRST | NEXT | SPEC
- (Optional) - Specifies that the request is for the specified
partition (SPEC), the first, or the next DBDS defined in RECON for
the database or partition. DBNAME is required with the LOC parameter.
DDN, with no wildcard, is required with LOC=NEXT|SPEC. DDN is not
allowed with LOC=FIRST. LOC=SPEC is the default when a specific
DDN is specified. LOC is not allowed with GROUP.
Specify DDN=* to also request data set or area information. If you specify a specific DDN (DDN=ddn), the specified DDN is ignored and all data set or area information is returned.
Partitions are returned in high key order if the HALDB uses high keys. Otherwise, partitions are returned in alphanumerical order.
- 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.
- OUTPUT=output | (2 - 12)
- Specifies a field to receive a pointer to the first of a possible
chain of blocks that contain the information for the partition.
The output address is zero if no output was built. This result 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
- Optional parameter that 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.
- MF=S | L | M | E
- Specifies the macro form of the request.
- VERSION=2.0 | number
- Optional parameter that specifies the version number of the parameter
list to be generated by this macro.
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.
The default version is 2.0.Note: TYPE=DBDS requires that you specify a minimum version number of API VERSION=2.0.
Return and reason codes for the TYPE=DBDS query request
| Code type | Return code | Reason code | Meaning |
|---|---|---|---|
| X'00000000' | X'00000000' | Request completed successfully. | |
| Warning | X'00000008' | X'D8210001' | No DBDSs or areas for the DB are registered in the RECON data set. No information blocks are returned. |
| X'00000008' | X'D8210002' | The specified DBDS or area is not registered in the RECON data set. No information blocks are returned. | |
| X'00000008' | X'D8210003' | The specified DBNAME is a HALDB. DBNAME must specify a non-HALDB or a HALDB partition name. No information blocks are returned. | |
| X'00000008' | X'D8210004' | The specified group is not registered in the RECON data set. No information blocks are returned. | |
| X'00000008' | X'D8210005' | The specified group is not a DBDS or CA group. No information blocks are returned. | |
| X'00000008' | X'D8210006' | The specified DBNAME is not registered in RECON. No information blocks are returned. | |
| 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'D8210001' | SAF or the DBRC cmd auth exit (DSPDCAX0) has determined that the user is not authorized to perform the request. | |
| Storage error | X'00000028' | X'D8210001' | Error obtaining storage for DBDS block. |
| X'00000028' | X'D8210002' | Error obtaining storage for AREA block. | |
| X'00000028' | X'D8210003' | Error obtaining storage for RCVINFO block. | |
| X'00000028' | X'D8210004' | Error obtaining storage for ALLOC block. | |
| X'00000028' | X'D8210005' | Error obtaining storage for IC block. | |
| X'00000028' | X'D8210006' | Error obtaining storage for REORG block. | |
| X'00000028' | X'D8210007' | Error obtaining storage for RECOV block. | |
| X'00000028' | X'D9100001' | An error occurred processing the request. DBRC releases any storage obtained up to this point. However, another error was encountered during the attempt to release storage. | |
| Internal error | X'0000002C' | X'D8000001' | Failure opening the RECON data set. |
| X'0000002C' | X'D8210001' | Failure locating the first DBDS record. | |
| X'0000002C' | X'D8210002' | Failure locating the specified DBDS record. | |
| X'0000002C' | X'D8210003' | Failure locating the next DBDS record. | |
| X'0000002C' | X'D8210004' | Failure locating the first Area Auth record. | |
| X'0000002C' | X'D8210005' | Failure locating the first ALLOC record. | |
| X'0000002C' | X'D8210006' | Failure locating the next ALLOC record. | |
| X'0000002C' | X'D8210007' | Failure locating the first IC record. | |
| X'0000002C' | X'D8210008' | Failure locating the next IC record. | |
| X'0000002C' | X'D8210009' | Failure locating the first REORG record. | |
| X'0000002C' | X'D821000A' | Failure locating the next REORG record. | |
| X'0000002C' | X'D821000B' | Failure locating the first RECOV record. | |
| X'0000002C' | X'D821000C' | Failure locating the next RECOV record. | |
| X'0000002C' | X'D821000D' | Failure locating the specified group record (DBDS group). | |
| X'0000002C' | X'D821000E' | Failure locating the specified group record (CA group). | |
| X'0000002C' | X'D821000F' | Failure locating a DBDS from the specified group record. | |
| X'0000002C' | X'D8210010' | Failure locating the DB record with the specified DBNAME. | |
| X'0000002C' | X'D8210011' | Failure attempting to locate the first AVAIL IC record. | |
| X'0000002C' | X'D8210012' | Failure attempting to locate the next AVAIL IC record. | |
| Parameter error | X'00000030' | X'C9000001' | The function (FUNC) specified in the parameter list that is 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 that is 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 that is 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 that is 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 that is not owned by the calling program. | |
| X'00000030' | X'C9000008' | Invalid DBNAME or GROUP address. The address of the field containing the DBNAME or GROUP failed validity checking. The address specifies storage that is not owned by the calling program. | |
| X'00000030' | X'C9000009' | Invalid DDN address. The address of the field containing the DDN failed validity checking. The address specifies storage that is 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'D8000003' | Query TYPE=DBDS requires a minimum API version of 2.0. | |
| X'00000030' | X''D8210001' | The DBNAME or GROUP is required. | |
| X'00000030' | X'D8210002' | DDN specified with invalid LOC value. Only LOC=NEXT|SPEC can be entered. | |
| X'00000030' | X'D8210003' | Invalid LOC value. When no DDN is specified only LOC=FIRST can be used. | |
| X'00000030' | X'D8210004' | The DDN parameter is not allowed with GROUP parameter. | |
| X'00000030' | X'D8210005' | The LOC is not allowed with GROUP parameter. |
The following block mappings relate to the TYPE=DB and TYPE=DBDS request:
- DSPAPQAR – Fast Path AREA block
- DSPAPQDS – DBDS block
- DSPAPQEL – EEQE List
- DSPAPQSL – Subsystem List (Fast Path only)
- DSPAPQRI – Recovery Information (RCVINFO) block
- DSPAPQAL – Allocation block
- DSPAPQIC – Image Copy block
- DSPAPQRV – Recovery block
- DSPAPQRR – Reorganization block