OLDS query request (TYPE=OLDS)

You can use the OLDS query (DSPAPI FUNC=QUERY TYPE=OLDS) request to retrieve online log data set information from the RECON for a specific subsystem or all subsystems.

Syntax for the TYPE=OLDS query request

Parameters for the TYPE=OLDS query request

name

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

TYPE=OLDS

Specifies that online log data set information is requested.

TOKEN=symbol | (2 - 12)

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

SSID=* | symbol*| symbol | (2 - 12)

Specifies the subsystem name for the backout being queried. You can use the wildcard keyword * (an asterisk) alone to request all of the OLDS information (SSID=*, the default). You can also use it at the end of a name to query subsystem names that match the pattern. In this case, the asterisk must be preceded by at least one alphabetic character.

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 OLDS information blocks.

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 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

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=OLDS request are 1.0 and 2.0 (default).

Return and reason codes for the TYPE=OLDS query request

Table 1. Return and reason codes for TYPE=OLDS query requests
Code type	Return codes	Reason codes	Meaning
	X'00000000'	X'00000000'	Request completed successfully.
Warning	X'00000008'	X'D8500001'	No PRIOLDS records exist.
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'D8500100'	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'D8500001'	Error obtaining storage for OLDS 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'D8500001'	Failure locating the first or the specified PRIOLDS record.
	X'0000002C'	X'D8500002'	Failure locating the corresponding SECOLDS record.
	X'0000002C'	X'D8500003'	Failure locating the next PRIOLDS 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'C9000010'	Invalid SSID field address. The address of the field containing the SSID 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'D8500100'	When using a wildcard, at least one alphabetic character must precede the asterisk.
	X'00000030'	X'D8500101'	When using a wildcard, the asterisk must be the last character.

Output for the TYPE=OLDS query request

The following figure illustrates the format of the output from a QUERY TYPE=OLDS 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 DSPAPQOL

  OFFSET   OFFSET
 DECIMAL     HEX  TYPE        LENGTH  NAME (DIM)       DESCRIPTION
======== ======== ========= ========  ==============   ===============================
       0      (0) STRUCTURE       48  DSPAPQOL
       0      (0) UNSIGNED         4   APQOL_OLDSINFO  Offset to OLDS list
       4      (4) SIGNED           4   *(3)            Reserved
      16     (10) CHARACTER        8   APQOL_SSID      Subsystem ID
      24     (18) UNSIGNED         2   APQOL_OLDSLEN   Length of OLDS entry
      26     (1A) SIGNED           2   APQOL_OLDSCOUNT Number of OLDS entries
      28     (1C) CHARACTER       12   APQOL_CHKPT0    Checkpoint 0 time
      40     (28) CHARACTER        8   *               Reserved

  OFFSET   OFFSET
 DECIMAL     HEX  TYPE        LENGTH  NAME (DIM)        DESCRIPTION
======== ======== ========= ========  ==============    ===============================
       0      (0) STRUCTURE      128  APQOL_OLDSENTRY   OLDS entry
       0      (0) CHARACTER        8   APQOL_DDNAME     OLDS DD name
       8      (8) CHARACTER       44   APQOL_DSNAM      OLDS data set name
      52     (34) CHARACTER       12   APQOL_OPENTIME   OLDS open time
      64     (40) CHARACTER       12   APQOL_CLOSETIME  Close time
      76     (4C) CHARACTER       12   APQOL_PRILOGTIME Start time of associated
                                                        PRILOG
      88     (58) CHARACTER        8   APQOL_FLSN       LSN of first record in OLDS
      96     (60) CHARACTER        8   APQOL_LLSN       LSN of last record in OLDS
     104     (68) BIT(8)           1   APQOL_FLAG1
                  1... ....             APQOL_RSTBG     Restart begin
                  .1.. ....             APQOL_RSTEN     Restart end
                  ..1. ....             APQOL_COLD      Cold start
                  ...1 ....             APQOL_NOBMP     ERE NOBMP
                  .... 1...             APQOL_SAVER     Backout UORs saved
                  .... .1..             APQOL_NOID      Backouts not identified
                  .... ..1.             APQOL_TRKNG     OLDS created by tracking SS
     105     (69) BIT(8)           1   APQOL_FLAG2      OLDS flags
                  1111 ....             APQOL_STAT      OLDS status
                  1... ....              APQOL_INUSE    OLDS is in use
                  .1.. ....              APQOL_ARNED    Archive needed
                  ..1. ....              APQOL_ARSCH    Archive scheduled (GENJCL)
                  ...1 ....              APQOL_ARSTD    Archive job started
                  .... 1...             APQOL_CLERR     Close error on OLDS
                  .... .1..             APQOL_FEOV      Force EOV at archive
                  .... ..1.             APQOL_DUMMY     OLDS not used due to I/O err
                  .... ...1             APQOL_PRVCE     Close error on previous OLDS
     106     (6A) UNSIGNED         1   APQOL_RELVL      Log release level
     107     (6B) UNSIGNED         1   APQOL_GAVER      GENJCL.ARCHIVE version
     108     (6C) BIT(32)          4   APQOL_BLOCKSEQNO Block sequence number
     112     (70) CHARACTER        8   APQOL_ARJOB      Name of the archive job
                                                        Generated by GENJCL.ARCHIVE
     120     (78) CHARACTER        6   APQOL_LOCKSEQNO  Lock sequence number
     126     (7E) CHARACTER        2   *                Reserved

CONSTANTS

  LEN  TYPE           VALUE          NAME            DESCRIPTION
=====  =========  =================  =============== ===============================
    8  CHARACTER   DSPAPQOL          APQOL_EYECATCHER