RECON status query request (TYPE=RECON)

You can use the RECON status query (DSPAPI FUNC=QUERY TYPE=RECON) request to retrieve information pertaining to the RECON data sets, including RECON header information as well as the status of each RECON data set.

Syntax for the TYPE=RECON query request

Parameters for the TYPE=RECON query request

name

Optional symbol you can specify. If used, begins in column 1.

TYPE=RECON

Specifies that RECON status information is requested.

TOKEN=symbol | (2 - 12)

Required parameter that specifies the address of a 4-byte field that was returned on the FUNC=STARTDBRC request.

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 RECON status information block.

The output address is zero if no output was built. This 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.

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 are 1.0 and 2.0.

Return and reason codes for the TYPE=RECON query request

Table 1. Return and reason codes for TYPE=RECON queries
Code type	Return codes	Reason codes	Meaning
	X'00000000'	X'00000000'	Request completed successfully.
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'D8100100'	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'D8100001'	Error obtaining storage for the RECON block.
Internal error	X'0000002C'	X'D8000001'	RECON open failure.
	X'0000002C'	X'D8100001'	Failure attempting to locate the RECON header 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'D8000001'	Missing or invalid OUTPUT parameter.
	X'00000030'	X'D8000002'	Invalid value specified for TYPE parameter.

Output for the TYPE=RECON query request

The following figure illustrates the format of the output from a QUERY TYPE=RECON request. The following DSECT sample describes in detail the fields of the storage blocks and their relationship to each other.

begin figure description. This figure is described in the surrounding text and in the DSECT descriptions that follow it. end figure description.

DSECT of DSPAPQRC

  OFFSET   OFFSET
 DECIMAL     HEX  TYPE        LENGTH  NAME (DIM)        DESCRIPTION
======== ======== ========= ========  ==============    ===============================
       0      (0) STRUCTURE      560  DSPAPQRC
       0      (0) CHARACTER       44   APQRC_DATA       Initialized with "RECOVERY
                                                        CONTROL DATASET"
      44     (2C) UNSIGNED         4   APQRC_RECONINFO  Offset to RECON data set
                                                        info
      48     (30) SIGNED           4   *(2)             Reserved
      56     (38) UNSIGNED         2   APQRC_RECONINFOLEN  Length of each RECON dataset info element
      58     (3A) UNSIGNED         1   APQRC_RECONCOUNT    # of RECON dataset elements
      59     (3B) CHARACTER        1   *                Reserved
      60     (3C) BIT(8)           1   APQRC_FLAGS      Process flags...
                  1... ....             APQRC_NOCHK     1= NOCHECK log tape dsn check
                  .1.. ....             APQRC_CHK17     1= CHECK17 log tape dsn check
                  ..1. ....             APQRC_CHK44     1= CHECK44 log tape dsn check
                  ...1 ....             APQRC_LSTLG     1= list log DSN
                  .... 1...             APQRC_INUPG     Upgrade in progress. 
                  .... .1..             APQRC_REORGV    Reorg verification
      61     (3D) BIT(8)           1   APQRC_FLAG2      More flags...
                  1... ....             APQRC_FORCE     1 = FORCER, 0 = NOFORCER
                  .1.. ....             APQRC_CATDS     1=CA|IC|LOGS cataloged
                  ..1. ....             APQRC_TRACE     1 = ext. GTF trace on
                  ...1 ....             APQRC_CMDSAF    SAF enabled
                  .... 1...             APQRC_CMDEXIT   Cmd auth exit enabled
                  .... .1..             APQRC_PRA	      Parallel RECON Access in use (VERSION=2.0)
                  .... ..1.             APQRC_LISTFUZZY PRA Concurrent LIST active (VERSION=2.0)
      62     (3E) CHARACTER        2   *                Reserved
      64     (40) CHARACTER      136   APQRC_CLEAN      Fields needed for cleanup
      64     (40) SIGNED           4    APQRC_CSET      0 = updates not in progress,
                                                        >0 = update in progress
      68     (44) SIGNED           4    APQRC_TYPE      Type of update
      72     (48) CHARACTER       32    APQRC_OKEY      Key of original record
     104     (68) CHARACTER       32    APQRC_BKEY      Key of base record that is in
                                                        the process of being changed
     136     (88) CHARACTER       32    APQRC_NKEY      Key of new record
     168     (A8) CHARACTER       16    APQRC_DBID      DBID of DBDS
     168     (A8) CHARACTER        8     APQRC_DBD      DBD name
     176     (B0) CHARACTER        8     APQRC_DDN      DD name
     184     (B8) CHARACTER        8    APQRC_CAGRP     CA group name
     192     (C0) CHARACTER        8    APQRC_DDNEW     New DBDS DD name
     200     (C8) UNSIGNED         2   APQRC_DMBNO      DMB sequence number
     202     (CA) UNSIGNED         2   APQRC_LASTREUSEDDMB#   Last reused DMB number, valid
                                                        only when apqrc_DMBNO is 32767
     204     (CC) CHARACTER        7   APQRC_INITTOKEN  Recon init. token
     211     (D3) CHARACTER        8   APQRC_CMDHLQ     Cmd auth high lvl qual
     219     (DB) UNSIGNED         1   APQRC_MVERS      Minimum IMS version
     220     (DC) BIT(8)           1   APQRC_NWFLG      Fields needed for RECON I/O
                                                        error(s)

                  1... ....             APQRC_NEW    1=STARTNEW, 0=NONEW
     221     (DD) CHARACTER        3   *                Reserved
     224     (E0) CHARACTER        8   APQRC_SSIDN      SSID for DASD
     232     (E8) CHARACTER        8   APQRC_DASDU      Unit type for DASD
     240     (F0) CHARACTER        8   APQRC_TAPEU      Unit type for tape
     248     (F8) CHARACTER       24   APQRC_TIME
     248     (F8) CHARACTER        2    APQRC_TZDEF     Input offset default
     250     (FA) CHARACTER        5    APQRC_TMFMT     Time format options
     255     (FF) CHARACTER        1    *               Reserved
     256    (100) SIGNED           2    APQRC_TPREC     Time-stamp precision
     258    (102) CHARACTER       12    APQRC_LOGRT     Minimum log retention period
     270    (10E) SIGNED           2    APQRC_TZNUM     Number of entries in time zone label table
     272    (110) CHARACTER        8   APQRC_TZTBL(32)  Time zone label table
     528    (210) BIT(16)          2   APQRC_TROPT      DBRC trace options
     530    (212) CHARACTER        5   APQRC_IMSPLEX    IMSplex name
     535    (217) CHARACTER        5   *                Reserved
     540    (21C) UNSIGNED         4   APQRC_SIZW_DSNUM   SIZEALERT dsnum
     544    (220) UNSIGNED         4   APQRC_SIZW_VOLNUM  SIZEALERT volnum
     548    (224) UNSIGNED         4   APQRC_SIZW_PERCENT SIZEALERT percent
     552    (228) UNSIGNED         4   APQRC_LOGW_DSNUM   LOGALERT dsnum
     556    (22C) UNSIGNED         4   APQRC_LOGW_VOLNUM  LOGALERT volnum
     560    (230) UNSIGNED        44   APQRC_CMDRNQ       CMDAUTH RECON qual
     604    (25C) UNSIGNED         8   APQRC_DBCOUNT      REGISTERED DBCOUNT
   612    (264) CHARACTER        8   APQRC_CATLG        CATALOG NAME (VERSION=6.0)
  OFFSET   OFFSET
 DECIMAL     HEX  TYPE        LENGTH  NAME (DIM)                DESCRIPTION
======== ======== ========= ========  ==============            ===============================
       0      (0) STRUCTURE       53  APQRC_RECONDS_INFO
       0      (0) CHARACTER        8   APQRC_RECONDS_DDNAME     RECON DD name
       8      (8) CHARACTER       44   APQRC_RECONDS_DSNAME     RECON DS name
      52     (34) BIT(8)           1   APQRC_RECONDS_STATUS     RECON DS status
                  1... ....             APQRC_RECONDS_COPY1     COPY 1
                  .1.. ....             APQRC_RECONDS_COPY2     COPY 2
                  ..1. ....             APQRC_RECONDS_SPARE     Spare
                  ...1 ....             APQRC_RECONDS_DISCARDED Discarded
                  .... 1...             APQRC_RECONDS_UNAVAIL   Unavailable
CONSTANTS

  LEN  TYPE           VALUE          NAME                       DESCRIPTION
=====  =========  =================  ===============            ===============================
    8  CHARACTER   DSPAPQRC          APQRC_EYECATCHER