HALDB partition query request (TYPE=PART)

You can use the DSPAPI FUNC=QUERY TYPE=PART request to retrieve information for a particular HALDB partition from the RECON data set. You can request data set information for a specific DBDS or all DBDSs in the partition, and can optionally request recovery-related information for the data set, including allocation, image copy, recovery, and reorganization information.

Syntax for the TYPE=PART query request

Read syntax diagramSkip visual syntax diagramnameDSPAPIFUNC=QUERYTYPE=PARTTOKEN= addressDBNAME= nameLOC=ALLLOC=FIRSTLOC=LASTPARTNAME= nameLOC=SPECLOC=PREVLOC=NEXTDDN=NULLDDN= ddnameDDN= *LIST=NONELIST=(ALLOCICRECOVREORG)LIST=ALLRETCODE= returncodeRSNCODE= reasoncodeOUTPUT= outputMF=SMF=(S, list)MF=(L, list)MF=(M, list,COMPLETE,NOCHECK)MF=(E, list,COMPLETE,NOCHECK)SUBPOOL=0SUBPOOL= numberVERSION=2.0VERSION= number

Parameters for the TYPE=PART query request

name
Optional symbol you can specify. If used, begins in column 1.
TYPE=PART
Required parameter that specifies that RECON data set information for a HALDB partition is requested.

When you specify the TYPE=PART, you must also specify a minimum DBRC API version number of VERSION=2.0.

DBNAME=name | (2 - 12)
Specifies the HALDB name of the partition being queried. You can optionally specify the LOC parameter, which indicates that you are interested in either the first partition, last partition, or all partitions of the specified HALDB. If the HALDB uses high keys, the request is for the partition with the lowest or highest high key. Otherwise, the first or last alphanumerical partition is returned. LOC=SPEC|PREV|NEXT may not be specified.
PARTNAME=name | (2 - 12)
Required parameter that specifies the name of a HALDB partition being queried.

The LOC parameter indicates the partition of interest:

  • The default LOC=SPEC indicates a request for the specified partition. This partition might be available or disabled.
  • LOC=PREV indicates a request for the active partition in the HALDB that is before the specified partition. If the HALDB uses high keys, the request is for the partition with the lower high key. Otherwise, the previous alphanumerical partition within the HALDB is returned. The partition name specified must be the name of an active partition registered in the RECON. This is required in order to ensure that the previous partition is within the same HALDB
  • LOC=NEXT indicates a request for the active partition in the HALDB that is after the specified partition. If the HALDB uses high keys, the request is for the partition with the higher high key. Otherwise, the next alphanumerical partition within the HALDB is returned. The partition name specified must be the name of an active partition registered in the RECON. This is required to ensure that the next partition is within the same HALDB.
  • LOC=FIRST|LAST can not be specified with PARTNAME.
To use this parameter, you must also specify a minimum version number of API VERSION=2.0.
DDN=NULL | (2 - 12) | * | ddname
Specifies the DD name of a DBDS set within the partition. An asterisk (* without quotes) can also be specified indicating that information about all DBDSs is requested. If a specific DDN is requested and the request is not for a specific partition information is returned for all DBDSs of the partition.

DDN=NULL indicates that no DBDS information is requested. This is the default.

LIST=( {ALLOC},{IC},{RECOV},{REORG}) | LIST=ALL | LIST=NONE
Specifies the types of supporting information to be included in the query output for the specified DBDS. If DDN is not specified, this information is returned for all DBDSs in the partition. 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 requests all supporting information. LIST=NONE requests no supporting information.
LOC=ALL | FIRST | LAST | PREV | NEXT | SPEC

The optional parameter specifies that the request is for the specified partition (SPEC), or for the first, last, previous, next or all active partitions defined in RECON for the HALDB. LOC=SPEC may return an active or disabled partition. DBNAME is required with LOC=FIRST|LAST|ALL, but is not allowed with LOC=PREV|NEXT|SPEC. Conversely, PARTNAME is required with LOC=PREV|NEXT|SPEC, but is not allowed with LOC=FIRST|LAST|ALL. LOC=ALL is the default with DBNAME. LOC=SPEC is the default with PARTNAME.

Partitions are returned in high key order if the HALDB uses high keys. Otherwise, partitions are returned in alphanumerical order.

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.
RETCODE=returncode | (2 - 12)
Specifies a location 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.
OUTPUT=output | (2 - 12)
Required parameter that 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 0 if no output is built. This can happen if nothing in the RECON data set satisfies the request or if an error occurs before any output is built.

The storage for the output blocks is not pre-allocated 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 that is 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 for 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=PART requires that you specify a minimum version number of API VERSION=2.0.

Return and reason codes for the TYPE=PART query request

The following table contains most of the return and reason codes for TYPE=PART query requests. The other possible return and reason codes relate to DBRC, not the query request.

Table 1. Return and reason codes for TYPE=PART query requests
Code type Return codes Reason codes Meaning
  X'00000000' X'00000000' Request completed successfully.
Warning X'00000008' X'D8210002' The specified DBDS or Area is not registered in RECON. No information blocks are returned.
  X'00000008' X'D8220001' No partitions are registered in RECON for the HALDB. No information blocks are returned.
  X'00000008' X'D8220002' The specified partition is not registered in RECON. No information blocks are returned.
  X'00000008' X'D8220003' A high key partition preceding the specified partition does not exist in RECON. No information blocks are returned.
  X'00000008' X'D8220004' A high key partition following the specified partition does not exist in RECON. No information blocks are returned.
  X'00000008' X'D8220005' The DBNAME specified is not registered in RECON. No information blocks are returned.
  X'00000008' X'D8220006' No active partitions found while searching for the FIRST or LAST partition of the HALDB.
  X'00000008' X'D8220007' No active partitions found while searching for the PREV or NEXT partition.
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'D8220100' Security error. 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'D8220001' Error obtaining storage for PART 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'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'D8220001' Failure locating the first HALDB partition record.
  X'0000002C' X'D8220002' Failure locating the DB record associated with the HALDB partition being processed.
  X'0000002C' X'D8220003' Failure locating the next HALDB partition record.
  X'0000002C' X'D8220004' Failure locating the specified HALDB (DBNAME).
  X'0000002C' X'D8220005' Failure locating the first or last active partition.
  X'0000002C' X'D8220006' Failure locating the first or last high key partition.
  X'0000002C' X'D8220007' Failure locating the previous or next high key partition.
  X'0000002C' X'D8220008' Failure locating the PART record corresponding to an existing Part DB record.
  X'0000002C' X'D8220009' Failure locating the previous or next partition of HALDB that uses a part selection routine.
  X'0000002C' X'D822000A' Failure locating the HALDB record for the specified partition.
  X'0000002C' X'D822000B' Failure locating the Part DB record for the specified PARTNAME.
  X'0000002C' X'D822000C' Neither the PART record nor the Part DB record is passed to ProcessPART.
  X'0000002C' X'D822000D' Failure locating the PART record associated with the HALDB partition being processed.
  X'0000002C' X'D82221xx' Internal Query DBDS call returned RC=X'30' RSN=X'D82100xx', a parameter error.
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 DBNAME or PARTNAME address. The address of the field containing the DBNAME or PARTNAME failed validity checking. The address specifies storage 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 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' TYPE=PART requires at least VERSION=2.0.
  X'00000030' X'D8220002' LOC=FIRST|LAST|ALL cannot be used with PARTNAME.
  X'00000030' X'D8220003' LOC=PREV|NEXT cannot be used with DBNAME.
  X'00000030' X'D8220004' Explicit name must be specified in DBNAME or PARTNAME. An asterisk cannot be used.
  X'00000030' X'D8220005' DBNAME specified is not a HALDB.
  X'00000030' X'D8220006' The partition name specified with LOC=PREV|NEXT must be an active partition.
  X'00000030' X'D8220007' PARTNAME must specify the name of a partition.

Output for TYPE=PART queries

The following mappings are used for the TYPE=PART query:

  • DSPAPQHP - HALDB Partition block
  • DSPAPQSL - Subsystem List