Log query request (TYPE=LOG)
You can use the Log query (DSPAPI FUNC=QUERY TYPE=LOG) request to retrieve log information from RECON for a specific instance of a subsystem.
Information from the following RECON data sets is returned:
- PRILOG
- LOGALL
- SECLOG (if applicable)
- PRISLDS (if applicable)
- SECSLDS (if applicable)
The log query request can also return log information for subsystems that started in a specified time range. This request can also be used for a specific subsystem.
Subsections:
- Syntax for the TYPE=LOG query request
- Parameters for the TYPE=LOG query request
- Return and reason codes for the TYPE=LOG query request
- Output for the TYPE=LOG query request
- Log information output
- DSECT of DSPAPQLI
- TYPE=LOG output for PRILOG, SECLOG, PRISLDS, and SECSLDS
- DSECT of DSPAPQLG
- TYPE=LOG output for LOGALL
- DSECT of DSPAPQLA
Syntax for the TYPE=LOG query request
Parameters for the TYPE=LOG query request
- name
- Optional symbol you can specify. If used, begins in column 1.
- TYPE=LOG
- Specifies that log information is requested.
- TOKEN=address | (2 - 12)
- Specifies the address of a 4-byte field that was returned on the FUNC=STARTDBRC request.
- STARTIME=time | (2-12)
- Specifies the time stamp field that contains the start time of the requested log. The time is a packed decimal time stamp in UTC format.
- FROMTIME=time | (2-12)
- Specifies the time stamp field that limits the logs requested
to those whose subsystem started at, or after, the specified time.
The time is a packed decimal time stamp in UTC format.
If you specify this parameter, you must also specify a minimum version number of DBRC API VERSION=2.0.
- TOTIME=time | (2-12)
- Specifies the time stamp field that limits the logs requested
to those whose subsystem started at, or before, the specified time.
The time is a packed decimal time stamp in UTC format. This parameter
may be used along with the FROMTIME parameter.
If you specify this parameter requires that you also specify a minimum version number of API VERSION=2.0.
- SSID=subsystem_ID | (2-12)
- Specifies the subsystem name for the log being queried.
You can specify the SSID parameter only when requesting the previous or next log of a specific subsystem, for example, when LOC previous or next is specified, or a range of logs for a specific subsystem using the FROMTIME or TOTIME parameters.
- LOC=PREV | NEXT | SPEC
- Specifies that the request is for the log with a specified start
time (LOC=SPEC), a start time preceding the specified start time (LOC=PREV),
or a start time following the specified start time (LOC=NEXT). The
STARTIME parameter is used as the base of the search and does not
need to be the start time of a login RECON.
LOC=SPEC is the default.
- 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 log 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 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=LOG request are 1.0 and 2.0.
Return and reason codes for the TYPE=LOG query request
| Code type | Return codes | Reason codes | Meaning |
|---|---|---|---|
| X'00000000' | X'00000000' | Request completed successfully. | |
| Warning | X'00000008' | X'D8400001' | No log record of the requested log type (PRILOG) exists. The request was the previous or next log or logs within a time range specified by FROMTIME or TOTIME. |
| X'00000008' | X'D8400002' | The specified log record of the requested log type - PRILOG - does not 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'D8400100' | 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'D8400001' | Error obtaining storage for LOGINFO block. |
| X'00000028' | X'D8400002' | Error obtaining storage for PRILOG, SECLOG, PRISLDS, or SECSLDS block. | |
| X'00000028' | X'D8400003' | Error obtaining storage for LOGALL 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'D8400001' | Failure locating the previous or next log record of the requested log type - PRILOG. | |
| X'0000002C' | X'D8400002' | Failure locating the specified log record of the requested log type - PRILOG. | |
| X'0000002C' | X'D8400004' | Failure locating the LOGALL record that corresponds to the PRILOG record. | |
| X'0000002C' | X'D8400005' | The LOGALL record that corresponds to the PRILOG record does not exist. | |
| X'0000002C' | X'D8400006' | Failure locating the corresponding SECLOG record. | |
| X'0000002C' | X'D8400007' | Failure locating the corresponding PRISLDS record. | |
| X'0000002C' | X'D8400008' | No PRISLDS record exists for the online log. | |
| X'0000002C' | X'D8400009' | Failure locating the corresponding SECSLDS record. | |
| X'0000002C' | X'D840000A' | Failure occurred in DBRC Time Services processing FROMTIME. | |
| 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'C9000011' | Invalid STARTIME field address. The address of the field containing the STARTIME failed validity checking. The address specifies storage not owned by the calling program. | |
| X'00000030' | X'C9000012' | Invalid FROMTIME field address. The address of the field that contains the FROMTIME parameter failed validity checking. The address specifies storage not owned by the calling program. | |
| X'00000030' | X'C9000013' | Invalid TOTIME field address. The address of the field that contains the TOTIME parameter 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'D8400001' | The STARTIME, FROMTIME, or TOTIME parameter is required. | |
| X'00000030' | X'D8400002' | SSID is required with TRACKER=YES. | |
| X'00000030' | X'D8400003' | The SSID parameter is not allowed when querying a specific active log (LOC=SPEC and TRACKER=NO). | |
| X'00000030' | X'D8400006' | The FROMTIME parameter value must be less than the TOTIME parameter value. | |
| X'00000030' | X'D8400007' | STARTIME cannot be specified with FROMTIME | TOTIME. | |
| X'00000030' | X'D8400008' | LOC cannot be specified with FROMTIME or TOTIME. | |
| X'00000030' | X'D8400010' | The value passed in the FROMTIME parameter is not a valid time |
Output for the TYPE=LOG query request
The following figures illustrate the format of output from a QUERY TYPE=LOG requests. The sample DSECTs that follow the figures describe in detail the fields of the storage blocks and their relationship to each other.
Log information output
DSECT of DSPAPQLI
OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== ===============================
0 (0) STRUCTURE 48 DSPAPQLI
0 (0) CHARACTER 8 APQLI_SSID Log SSID
8 (8) CHARACTER 12 APQLI_STARTTIME Log start time
20 (14) ADDRESS 4 APQLI_PRILOGPTR ptr to PRILOG block
24 (18) ADDRESS 4 APQLI_LOGALLPTR ptr to LOGALL block
28 (1C) ADDRESS 4 APQLI_SECLOGPTR ptr to SECLOG block
32 (20) ADDRESS 4 APQLI_PRISLDSPTR ptr to PRISLDS block
36 (24) ADDRESS 4 APQLI_SECSLDSPTR ptr to SECSLDS block
40 (28) ADDRESS 4 APQLI_PRITSLDSPTR ptr to PRITSLDS block
44 (2C) ADDRESS 4 APQLI_SECTSLDSPTR ptr to SECTSLDS block
CONSTANTS
LEN TYPE VALUE NAME DESCRIPTION
===== ========= ================= =============== ===============================
8 CHARACTER DSPAPQLI APQLI_EYECATCHERTYPE=LOG output for PRILOG, SECLOG, PRISLDS, and SECSLDS
DSECT of DSPAPQLG
OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== ===============================
0 (0) STRUCTURE 96 DSPAPQLG
0 (0) UNSIGNED 4 APQLG_FIRSTLOGDS Offset to first log DS entry
4 (4) UNSIGNED 4 APQLG_LASTLOGDS Offset to last log DS entry
8 (8) SIGNED 4 *(2) Reserved
16 (10) CHARACTER 8 APQLG_SSID Subsystem ID
24 (18) CHARACTER 12 APQLG_STARTTIME Log start time
36 (24) CHARACTER 12 APQLG_ENDTIME Log end time
48 (30) SIGNED 4 APQLG_DSNCOUNT Number of data sets
52 (34) UNSIGNED 1 APQLG_RELVL Log Release Level
1... .... APQLG_ONLINE Online log - PRILOG and SECLOG only
.1.. .... APQLG_LSTAR Last OLDS has been archived - PRILOG and PRITSLDS only
..1. .... APQLG_LSTNA Last OLDS has not been archived - PRILOG and PRITSLDS only
...1 .... APQLG_GAP There is a gap in this log
.... 1... APQLG_PRGAP There is a gap in a prev log
53 (34) UNSIGNED 1 APQLG_FLAGS1 Flags
1... .... APQLG_ONLINE Online log - PRILOG and SECLOG only
.1.. .... APQLG_LSTAR Last OLDS has been archived – PRILOG
and PRITSLDS only
..1. .... APQLG_LSTNA Last OLDS has not been archived –
PRILOG and PRITSLDS only
...1 .... APQLG_GAP There is a gap in this log
.... 1... APQLG_PRGAP There is a gap in a prev log
.... .1.. APQLG_BPE BPE-based subsystem (VERSION=4.0)
54 (36) BIT(8) 1 APQLG_FLAGS2 Flags
1... .... APQLG_TRKNG Tracking log data set
.1.. .... APQLG_NTERM IMS subsystem has terminated normally
..1. .... APQLG_BKLOG Batch backout log
55 (37) CHARACTER 1 * Reserved
56 (38) CHARACTER 8 APQLG_FIRSTLRID Id of first log record
64 (40) UNSIGNED 4 APQLG_PTOKEN PRILOG token
68 (44) CHARACTER 8 APQLG_GSGNAME GSG name
76 (4C) CHARACTER 12 APQLG_CHKPT0 Checkpoint 0 time
88 (58) CHARACTER 8 * Reserved OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== ==============================
0 (0) STRUCTURE 120 APQLG_DS_ENTRY Data set entry
0 (0) UNSIGNED 4 APQLG_DS_NEXT Offset to next log DS entry
4 (4) UNSIGNED 4 APQLG_DS_PREV Offset to prev log DS entry
8 (8) UNSIGNED 4 APQLG_DS_VOLINFO Offset to DS volume info
12 (C) CHARACTER 44 APQLG_DS_DSNAME Data set name
56 (38) CHARACTER 12 APQLG_DS_STARTTIME DS start time
68 (44) CHARACTER 12 APQLG_DS_ENDTIME DS end time
80 (50) BIT(8) 1 APQLG_DS_FLAGS1 Flags
1... .... APQLG_DS_ERR I/O Error
.1.. .... APQLG_DS_DUMMY Log compressed, 1st DS dummy
..1. .... APQLG_DS_RSTBG Restart begin
...1 .... APQLG_DS_RSTEN Restart end
.... 1... APQLG_DS_COLD Cold start
.... .1.. APQLG_DS_NOBMP ERE NOBMP
.... ..1. APQLG_DS_SAVER Backout UORs saved
.... ...1 APQLG_DS_NOID Backouts not identified
81 (51) BIT(8) 1 APQLG_DS_FLAGS2 Flags
1... .... APQLG_DS_TRKARCH Tracking log DS archived
.1.. .... APQLG_DS_TRKFEOV Tracking log closed FEOV
82 (52) CHARACTER 2 APQLG_DS_DFLG3 Reserved
84 (54) CHARACTER 8 APQLG_DS_FLRID First log record ID
92 (5C) CHARACTER 8 APQLG_DS_LLRID Last log record ID
100 (64) UNSIGNED 4 APQLG_DS_LASTBLKSEQNO Last block seq number
104 (68) CHARACTER 8 APQLG_DS_UNITTYPE Unit type name
112 (70) UNSIGNED 2 APQLG_DS_FILESEQ File sequence no
114 (72) UNSIGNED 2 APQLG_DS_VOLCOUNT Number of volumes
116 (74) UNSIGNED 1 APQLG_DS_CKPTCOUNT Number of chkpts on DSN
117 (75) BIT(8) 1 APQLG_DS_CHKPTTYPES CHKPT types.
1... .... APQLG_DS_SIMPL SIMPLE checkpoint
.1.. .... APQLG_DS_SNAPQ SNAPQ checkpoint
..1. .... APQLG_DS_DUMPQ DUMPQ checkpoint
...1 .... APQLG_DS_PURGE PURGE checkpoint
.... 1... APQLG_DS_FREEZ FREEZE checkpoint
118 (76) UNSIGNED 2 * Reserved
OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== ===============================
0 (0) STRUCTURE 48 APQLG_DSVOLUME Volume information
0 (0) UNSIGNED 4 APQLG_DSVOL_NEXT Offset to next volume
4 (4) CHARACTER 6 APQLG_DSVOL_SER VOLSER
10 (A) UNSIGNED 1 APQLG_DSVOL_CKPTCT Volume chkpt count
11 (B) CHARACTER 1 * Reserved
12 (C) CHARACTER 12 APQLG_DSVOL_ENDTIME Volume end time
24 (18) CHARACTER 12 APQLG_DSVOL_CPTID Checkpoint ID
36 (24) CHARACTER 6 APQLG_DSVOL_LOCKSN Lock Sequence Number
42 (2A) CHARACTER 6 * Reserved
CONSTANTS
LEN TYPE VALUE NAME DESCRIPTION
===== ========= ================= =============== ===============================
8 CHARACTER DSPAPQLG APQLG_EYECATCHERTYPE=LOG output for LOGALL
DSECT of DSPAPQLA
OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM DESCRIPTION
======== ======== ========= ======== ============== ===============================
0 (0) STRUCTURE 48 DSPAPQLA
0 (0) UNSIGNED 4 APQLA_DBDSAREAINFO Offset to allocated
DBDS/Area list
4 (4) SIGNED 4 *(3) Reserved
16 (10) CHARACTER 12 APQLA_PRILOGTIME PRILOG time
28 (1C) BIT(8) 1 APQLA_FLAGS Flags
1... .... APQLA_NONREGD Non-registered DB updated
29 (1D) UNSIGNED 3 APQLA_DBDSAREACOUNT Number of DBDS/Areas
allocated on this log
32 (20) UNSIGNED 4 APQLA_DBDSAREALEN Length of DBDS/Area entry
36 (24) CHARACTER 12 APQLA_EARLIESTALLOC Earliest ALLOC time for
this log
OFFSET OFFSET
DECIMAL HEX TYPE LENGTH NAME (DIM) DESCRIPTION
======== ======== ========= ======== ============== ===============================
0 (0) STRUCTURE 32 APQLA_DBDSAREA List of allocated DBDSs and
areas
0 (0) CHARACTER 8 APQLA_DBNAME Database name
8 (8) CHARACTER 8 *
8 (8) CHARACTER 8 APQLA_DDNAME DD name or
8 (8) CHARACTER 8 APQLA_AREANAME AREA name
16 (10) CHARACTER 12 APQLA_FIRSTALLOC Earliest ALLOC time for this
DBDS/Area on this log
28 (1C) SIGNED 2 APQLA_ALLNO Number of ALLOCs for this
DBDS/Area on this log
30 (1E) CHARACTER 2 * Reserved
CONSTANTS
LEN TYPE VALUE NAME DESCRIPTION
===== ========= ================= =============== ===============================
8 CHARACTER DSPAPQLA APQLA_EYECATCHER