DBRC start request (STARTDBRC)

You can use the DBRC start request (STARTDBRC) to initialize the DBRC API and to start DBRC.

Syntax for the STARTDBRC request

Read syntax diagramSkip visual syntax diagramnameDSPAPIFUNC=STARTDBRCTOKEN= addressSYSPRINT= ddnameREADONLY=NOSSID=NULLSSID= nameREADONLY=YESSSID=NULLRECON1= ddnameRECON2= ddnameRECON3= ddnameIMS= ddnameSUBPOOL=0SUBPOOL= numberMF=SMF=(S, list)MF=(L, list)MF=(M, list,COMPLETE,NOCHECK)MF=(E, list,COMPLETE,NOCHECK)RETCODE= returncodeRSNCODE= reasoncodeVERSION=2.0VERSION= number

Parameters for STARTDBRC

name
Optional symbol you can specify. If used, begins in column 1.
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 STARTDBRC request.
SYSPRINT= ddname | (2 - 12)
Specifies the address of an 8-byte field that contains the DD name of an output data set to be used for messages. If omitted, the default name SYSPRINT is used.
READONLY=NO | YES
Specifies whether (YES) or not (NO) the application needs read only access to the DBRC information. READONLY=NO requires that the application has a minimum of UPDATE level authority to the RECON data sets.

To use this parameter, you must specify API VERSION=2.0 or later.

SSID=NULL | name
Specifies the address of an 8-byte field that contains the subsystem name that is used to register with DBRC. If you specify SSID=NULL, registration with DBRC is not done. Do not specify both READONLY=YES and SSID=symbol.

The default is SSID=NULL. To use this parameter, you must specify API VERSION=2.0 or later.

RECON1=ddname | (2 - 12)
Specifies the address of an 8-byte field that contains the DD name that is used in place of the default DD name RECON1.

If omitted, the default name RECON1 is used. To use this parameter, you must specify API VERSION=2.0 or later.

RECON2=ddname | (2 - 12)
Specifies the address of an 8-byte field that contains the DD name that is used in place of the default DD name RECON2.

If omitted, the default name RECON2 is used. To use this parameter, you must specify API VERSION=2.0 or later.

RECON3=ddname | (2 - 12)
Specifies the address of an 8-byte field that contains the DD name that is used in place of the default DD name RECON3.

If omitted, the default name RECON3 is used. To use this parameter, you must specify API VERSION=2.0 or later.

IMS=IMS | ddname
Specifies the address of an 8-byte field that contains the DD name that is used in place of the default DD name IMS.

The default is IMS=IMS. To use this parameter, you must also specify API VERSION=2.0 or later.

SUBPOOL=0 | number
Specifies the default subpool number that is to be used for all requests (for example QUERY and AUTH) that return storage. For information on valid subpools for your program, see the z/OS® MVS™ Assembler Services Guide.

SUBPOOL=0 is the default for the request if SUBPOOL is not specified here or on the request.

MF=S | L | M | E
Specifies the macro form of the request.
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 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 required version number.

Return and reason codes for STARTDBRC

Table 1. Return and reason codes for the STARTDBRC request
Code type Return codes Reason codes Meaning
  X'00000000' X'00000000' Request completed successfully.
Warning X'00000004' X'E2000001' The RECON data sets are not initialized. The only function allowed is an INIT.RECON command.
  X'00000004' X'E2000002' The RECON data sets are not upgraded. The only function allowed is a CHANGE.RECON UPGRADE command.
Severe error X'0000000C' X'C9000002' DBRC could not successfully initialize during phase 0 of DBRC initialization.
  X'0000000C' X'C9000003' DBRC could not successfully initialize during phase 1 of DBRC initialization.
  X'0000000C' X'C9000004' A z/OS LOAD failed for the DBRC module DSPCRTR0.
  X'0000000C' X'C9000005' STORAGE request failure. The API cannot obtain storage necessary to complete the request.
  X'0000000C' X'C9000012' STARTDBRC has been previously issued without an intervening STOPDBRC.
  X'0000000C' X'C9D40001' DSPAPI macro load failed for DBRC module DSPAPI00.
  X'0000000C' X'E2000001' The RECON data sets are not initialized. STARTDBRC fails because an SSID was supplied and SIGNON cannot be performed.
  X'0000000C' X'E2000002' The RECON data sets are not upgraded. STARTDBRC fails because an SSID was supplied and SIGNON cannot be performed.
  X'0000000C' X'E2000003' STARTDBRC specified READONLY. However, an SSID was supplied and SIGNON cannot be performed.
  X'0000000C' X'E200000A' RECON is either not initialized or not upgraded and V1 is the caller.
  X'0000000C' X'E2000100' Security error. SAF or the DBRC Command Authorization exit routine (DSPDCAX0) determined that the user is not authorized to perform the request.
  X'0000000C' X'E210nnnn' Error attempting to sign on the application. 'nnnn' is the return code from DBRC Signon module, DSPSSIGN.
Internal error X'00000028' X'C9000001' DBRC internal error. Failure writing the subsystem record.
Parameter error X'00000030' X'C9000001' Parameter error. 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 to contain 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'C9000006' Invalid SYSPRINT field address. The address of the field containing the SYSPRINT DD name failed validity checking. The address specifies storage not owned by the calling program.
  X'00000030' X'C900000A' Invalid IMS field address. The address of the field that contains the IMS DD name failed validity checking.
  X'00000030' X'C900000C' Invalid RECON1 field address. The address of the field that contains the RECON1 DD name failed validity checking. The address specifies storage that is not owned by the calling program.
  X'00000030' X'C900000D' Invalid RECON2 field address. The address of the field that contains the RECON2 DD name failed validity checking. The address specifies storage that is not owned by the calling program.
  X'00000030' X'C900000E' Invalid RECON3 field address. The address of the field that contains the RECON3 DD name failed validity checking. The address specifies storage that is not owned by the calling program.
  X'00000030' X'E2100001' An SSID of zeroes or blanks was specified.