Backout query request (TYPE=BACKOUT)
You can use the Backout query (DSPAPI FUNC=QUERY TYPE=BACKOUT) request to retrieve backout information from the RECON data set for a specific subsystem or all subsystems.
Syntax for the TYPE=BACKOUT query request
Parameters for the TYPE=BACKOUT query request
- name
- If used, begins in column 1.
- TYPE=BACKOUT
- Specifies that backout 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 information about all groups (SSID=*, which is the default). You can also add it at the end of a name to query all subsystems whose names 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)
- Required parameter that specifies a field to receive a pointer
to the first block of backout information blocks.
The output address is 0 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 that is 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.
Valid version numbers for the FUNC=QUERY TYPE=BACKOUT request are 1.0 and 2.0.
Return and reason codes for the TYPE=BACKOUT query request
| Code type | Return codes | Reason codes | Meaning |
|---|---|---|---|
| X'00000000' | X'00000000' | Request completed successfully. | |
| Warning | X'00000008' | X'D87000001' | No backout 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'D8700100' | 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'D87000001' | Error obtaining storage for BACKOUT block. |
| X'00000028' | X'D91000001' | 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'D8700001' | Failure locating the first or the specified backout record. | |
| X'0000002C' | X'D8700002' | Failure locating the next backout 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'D80000001' | Missing or invalid OUTPUT parameter. | |
| X'00000030' | X'D80000002' | Invalid value specified for TYPE parameter. | |
| X'00000030' | X'D8700100' | When using a wildcard, at least one alphabetic character must precede the asterisk. | |
| X'00000030' | X'D8700101' | When using a wildcard, the asterisk must be the last character. |
Output for TYPE=BACKOUT QUERY request
DSECT of DSPAPQBO
The following example is a sample DSECT describes in detail the fields of the storage blocks and their interrelationship.
OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== ===========================
0 (0) STRUCTURE 48 DSPAPQBO
0 (0) CHARACTER 8 APQBO_SSID Subsystem identifier
8 (8) UNSIGNED 4 APQBO_FIRSTUOR Offset of first UOR entry
12 (C) UNSIGNED 4 APQBO_LASTUOR Offset of last UOR entry
16 (10) CHARACTER 12 APQBO_TIMEFIRST Earliest UOR time
28 (1C) CHARACTER 12 APQBO_TIMELAST Latest UOR time
40 (28) BIT(8) 1 APQBO_FLAGS Backout flags
1... .... APQBO_SAVER SAVUOR call during restart
41 (29) CHARACTER 3 * Reserved
44 (2C) SIGNED 4 APQBO_UORCOUNT Number of UORs
============================================================================
The following structure maps the unit of recovery entries.
There is one such entry for each unit of recovery (that is, there
are apqbo_UORcount entries). Each unit of recovery entry
contains the offset within the backout block to the previous
and following entries. Field apqbo_PrevUOR is the offset of
the previous entry and apqbo_NextUOR is the offset of the
following entry. For the first unit of recovery (UOR) entry,
apqbo_PrevUOR will be zero. Similarly, apqbo_NextUOR will be
zero for the last entry. Addressability to the first UOR entry
is given by:
rfy apqbo_UORentry based(addr(DSPAPQBO) + apqbo_FirstUOR)
Addressability to the last UOR entry is given by:
rfy apqbo_UORentry based(addr(DSPAPQBO) + apqbo_LastUOR)
Addressability to the next UOR entry, if one exists (that is:
apqbo_NextUOR not equal to 0), is given by:
rfy apqbo_UORentry based(addr(DSPAPQBO) + apqbo_NextUOR)
Similarly, to address the previous entry (when apqbo_PrevUOR
not equal to 0):
rfy apqbo_UORentry based(addr(DSPAPQBO) + apqbo_PrevUOR)
Once addressability has been established to a UOR entry,
addressability to the ith database for this UOR is given by:
rfy apqbo_DBent
based(addr(apqbo_UORentry) + apqbo_DBoffset
+ (i-1) apqbo_DBLength)
============================================================================ OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== =============================
0 (0) STRUCTURE 64 APQBO_UORENTRY Unit of Recovery entry
0 (0) CHARACTER 64 APQBO_PREFIX Prefix section
0 (0) UNSIGNED 4 APQBO_NEXTUOR Offset of next UOR entry
4 (4) UNSIGNED 4 APQBO_PREVUOR Offset of previous UOR entry
8 (8) UNSIGNED 4 APQBO_DBOFFSET Offset to DB entries
12 (C) CHARACTER 12 APQBO_UORTIME Time stamp for this UOR
24 (18) CHARACTER 8 APQBO_UORPSB PSB name
32 (20) BIT(16) 2 APQBO_UORFLAGS
1... .... APQBO_DEFBO Deferred backout - dynamic
backout failure
.1.. .... APQBO_INFLT Inflight UOR
..1. .... APQBO_INDOU Indoubt UOR
...1 .... APQBO_BMP BMP UOR
.... 1... APQBO_BOCAN BBO identified candidate
.... .1.. APQBO_COLDN Cold start ended for UOR
.... ..1. APQBO_BBOK Backed out OK by BBO
.... ...1 APQBO_CMD UOR modified by command
33 (21) 1... .... APQBO_BATCH Batch IMS UOR
34 (22) CHARACTER 6 * Reserved
40 (28) CHARACTER 16 APQBO_RTOKN Recovery token
40 (28) CHARACTER 8 APQBO_RTSSID SSID for this token
48 (30) CHARACTER 8 APQBO_UORID Unique UOR ID
56 (38) SIGNED 4 APQBO_DBCOUNT Number of DBs for this UOR
60 (3C) UNSIGNED 2 APQBO_DBLENGTH Length of each DB entry
62 (3E) CHARACTER 2 * Reserved
OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== ===============================
0 (0) STRUCTURE 16 APQBO_DBENT Database entry
0 (0) CHARACTER 8 APQBO_DBNAME Database name
8 (8) BIT(8) 1 APQBO_DBFLAGS Flags
1... .... APQBO_DBOUT UOR backed out for this DB
.1.. .... APQBO_DBDEF Dyn backout failure this DB
9 (9) CHARACTER 7 * Reserved
CONSTANTS
LEN TYPE VALUE NAME DESCRIPTION
===== ========= ================= =============== ===============================
8 CHARACTER DSPAPQBO APQBO_EYECATCHER