This document describes the command log format (CLOGLAYOUT=8) that Adabas supports as well as some command log utilities. This format includes the corresponding Adabas buffer descriptions (ABDs) as well. Each segmented buffer (format, record, or multifetch) is written separately and uniquely identified.
Command log layout 8 comprises the following log record types:
the basic log record type (x'0001') is produced for all commands processed on noncluster nuclei and for those that arrive from a remote nucleus and run under internal command queue elements (ICQEs).
the asynchronous request log record type (x'0002') is created on a nucleus that sends a command to another nucleus. This record type is used in Adabas nucleus cluster environments only.
the Adabas event log record type (x'000D') is produced for commands that received response code 145 (ADARSP145).
The DSECT that maps the layout of the CLOGLAYOUT=8 records is called LORECX and can be found in the ADAvrs.SRCE library.
This document covers the following topics:
Notation vrs, vr, or v: When used in this documentation, the notation vrs or vr stands for the relevant version of a product. For further information on product versions, see version in the Glossary.
You can log the extended I/O list to the CLOG data sets for CLOGLAYOUT=8. The ADARUN parameter LOGVOLIO is provided so you can specify this functionality for an Adabas nucleus.
In the enhanced I/O list, an I/O list element contains not only the control byte and the RABN, but also the name of the volume where the RABN resides. In the control byte, the X'40' bit is switched on. Six-byte volume names are attached after the I/O list.
For example, if RABNSIZE = 3 and byte 1 contains:
41 = Associator read 42 = Associator write ... 46 = Work write
In this case, bytes 2-4 contain the three-byte RABN that is read or updated and bytes 5-10 contain the volume name where the RABN resides.
In another example, if RABNSIZE = 4 and byte 1 contains:
C1 = Associator read C2 = Associator write ... C6 = Work write
Bytes 2-5 contain the four-byte RABN that is read or updated and bytes 6-11 contain the volume name where the RABN resides.
The command type field (at hexadecimal offset 12 in the LOREC DSECT and hexadecimal offset 23 in the LORECX DSECT) refers to the following command types:
| Update | A1/A4, E1/E4, N1/N2 |
| Simple | All non-update commands with a single search argument. |
| Complex | All non-update commands with more than one search argument. |
The command type field may contain other information that is unrelated to commands. The flags should therefore be tested with a binary mask:
B'xxxx xusc'
where u is the update flag bit, s is the simple flag bit, and c is the complex flag bit.
The remote nucleus field (at offset 4D in the LOREC DSECT and offset 1C in the LORECX DSECT)represents a remote nucleus ID.
For the basic log record type (x'0001') where the command originates in another nucleus, this field contains the ID of the nucleus that sent the command. It remains zero for locally executed commands and noncluster nuclei.
For the asynchronous request log record type (x'0002'), this field contains the ID of the nucleus to which the command is sent. It is zero for implicit broadcasts (GLOBAL and SYSTEM) and contains the ID of the first destination for explicit broadcasts (list of destinations). The CLOG record contains the Adabas control block, buffers, and (if appropriate) Adabas buffer descriptions (ABDs) related to the first (or only) destination, and the job name and communications ID of the initiator of the request.
The nucleus ID field at offset 58 in the LOREC DSECT and at offset 1A in the LORECX DSECT provides the ID of the nucleus executing the command. In a cluster environment, the nucleus ID is the NUCID; in a noncluster environment, the nucleus ID is zero (0).
Timestamps in an Adabas 8 command log created using CLOGLAYOUT=8 are stored in machine time (GMT). The LORECX record layout that describes the CLOGLAYOUT=8 command log includes a differential time field that stores the difference between machine time and local time at the time the CLOG record is written. This field allows you to calculate the local time of a command log record.
 |
Warning: PRILOG is a sample user program and is not supported under any maintenance contract agreement. |
Adabas provides the PRILOG print program to read and report the contents of Adabas command logs.
PRILOG reads a sequential Adabas command log that has been produced directly by the Adabas nucleus (DDLOG file) or by the ADARES CLCOPY utility when the Adabas nucleus uses dual or multiple command logging.
PRILOG is supplied in both source and object form.
In source form, three modules (PRILOG, CCSTCK, and PRILOGD) are supplied for z/OS. These modules replace all PRILOG versions supplied with earlier versions of Adabas.
Two of the PRILOG modules are system-independent components and one is specific to a particular operating system:
| PRILOG | interprets control statements; generates report lines from CLOG records. | ||
| CCSTCK | converts internal timestamp information on CLOG records into a more useful form before printing, making it compliant with Year 2000 standards. CCSTCK is provided independently so it can also be used by other programs. | ||
| PRILOGD | retrieves an input control card image and a CLOG record
and prints a line. PRILOGD is system-dependent. It contains a number of
parameters that are described in the source.
|
This section covers the following topics:
As input, the PRILOG program requires CLOG records and control statements.
Control statements must begin with the program name "PRILOG" in columns 1 through 7; at least one space must follow the program name before parameters are entered.
Parameters can be entered up to column 71. No continuation or parameter splitting is permitted. Additional parameters can be entered on a separate PRILOG statement.
A comment line begins with an asterisk (*). Comments may also be added to the right side of the parameter string as long as the comment is separated from the parameter value by at least one space.
Three parameters can be entered on the PRILOG control statements:
The CLOGLAYOUT parameter identifies the format of the CLOG records being used as input to the PRILOG program. The only valid value is 8, which is also the default. The syntax is:
CLOGLAYOUT={8}
Note:
If this parameter is omitted, the utility will work out which
CLOG layout is required in the command log input file.
The EVENT parameter indicates that the event log should be included in the CLOG records, if CLOGLAYOUT=8. The event log contains data about when the event happened, the user that received it, and other data about the ISN accessed.
The FIELDS parameter identifies the item (or items) from the CLOG records that are to be printed. Its syntax is:
FIELDS= { ( item, ... ) | ( LIST) }
Replace item with one of the following:
| Item | Description |
|---|---|
| ACBX | Adabas extended control block, displayed in hexadecimal format |
| FB | format buffer |
| IB | ISN buffer |
| IOL | I/O list |
| LIST | Adabas control block field list |
| MB | multifetch buffer |
| PB | performance buffer |
| RB | record buffer |
| SB | search buffer |
| UXB | user exit B buffer |
| VB | value buffer |
| VERB | verbosity (see below) |
The default value is "LIST". Multiple items can be listed in any order.
If a data item listed in the FIELDS parameter is not being captured during the ADALOG session and is therefore not present in the CLOG record, the request to print that data item is ignored.
If "VERB" is specified, then a more verbose output is generated. The additional fields displayed are the Additions 1, Additions 2 and Additions 5 fields along with the full communications ID. These values are all displayed in hexadecimal format. Also, if the DIMENSIONS parameter specifies a narrower output format, the fields not printed in the columns will be displayed in the verbose output format.
Note:
The "VERB" option is only
effective when specified in addition to another one of the FIELDS options (for
example, LIST).
The optional DIMENSIONS parameter is used to specify the format that the printed output should take. The number of columns must be 80, 133, or 163, but any number of rows can be specified. If no value for rows is specified, there will be no page breaks and the column headers will print only once. The syntax of the DIMENSIONS parameter:
DIMENSIONS=({80[, x] | 133[, x] | 163[, x] | OLD})
If the DIMENSIONS parameter is not specified when CLOGLAYOUT=8 is specified, the output will default to 163 columns with no page breaks. If you prefer to generate the traditional 118-column/58-row output format for CLOGLAYOUT=8 logs, specify DIMENSIONS=OLD.
You can also filter the PRILOG output using the command selection parameters described in this section:
Use the CLASS parameter to select log records whose command codes belong to the specified command classes. The CLASS parameter has the following syntax:
CLASS=(keyword[,keyword]...)
The following table describes the keywords that can be specified:
| Keyword | Commands Included |
|---|---|
| CONTROL | BT, CL, C1, C3, C5, ET, HI, OP, MC, RC, RE, or RI |
| FIND | S1, S2, S4, S8, or S9 |
| READ | LF, L1, L2, L3, L4, L5, L6, or L9 |
| UPDATE | A1, E1, I1, N1, or N2 |
In the following example, the commands included in the FIND and UPDATE keywords are selected:
PRILOG CLASS=(FIND,UPDATE)
Use the COMMAND parameter to select log records whose commands match specified Adabas command names. The COMMAND parameter has the following syntax:
COMMAND=(cmd[,cmd]...)
Any valid Adabas command can be specified for cmd. In the following example, log records for the OP, S1, L1, E1, and CL commands are selected:
PRILOG COMMAND=(OP,S1,L1,E1,CL)
Use the DATE parameter to select log records whose timestamps fall between the inclusive start and end times specified. The DATE parameter has the following syntax:
DATE=(start-dd-mmm-yyyy[:start-hh:mm:ss][,end-dd-mmm-yyyy[:end-hh:mm:ss]])
All times must be specified in military (24-hour) time format.
The first date and time specified in the DATE parameter is the start date and time; the second date and time pair in the syntax is the end date and time. A comma separates these start and end timestamps. Log records with dates that fall on or between these timestamps will be selected. In the following example, all log data occurring between (and including) 19:16:00.000 and 20:20:20.999 on October 10, 2006 will be selected.
PRILOG DATE=(10-OCT-2006:19:16:00,10-OCT-2006:20:20:20)
If a time is specified, a date is mandatory. If a time is not specified or if only part of the time is specified, the missing values will be assumed to be zero. For example, a specification of 10-OCT-2006:19:16 is interpreted as 10-OCT-2006:19:16:00 and a specification of 10-OCT-2006:19 is interpreted as 10-OCT-2006:19:00:00.
If no start timestamp is specified, then all records that fall up until the end of the specified range are selected. In the following example, all log records are selected that occurred earlier than and at 20:20:20:999 of October 10, 2006:
PRILOG DATE=(,10-OCT-2006:20:20:20)
If no end timestamp is specified, then all records that fall after the start of the specified range are selected. In the following example, all log records are selected that occur after or at 20:00:00:000 on October 10, 2006.
PRILOG DATE=(10-OCT-2006:20:00:00)
If only one date (with no comma) is specified, then the records that are selected must have a timestamp that match the specified timestamp. In the following example, all log records are selected that occur within (and including) the range 10-OCT-2006:19:16:00.000 through 10-OCT-2006:19:16:00.999:
PRILOG DATE=(10-OCT-2006:19:16)
Use the file parameter to select log records which reference a specified list of file numbers or range of file numbers. The FILE parameter has the following syntax:
FILE=(num[-num][,num[-num]]...)
Any valid Adabas file numbers can be substituted for num. A maximum of ten ranges or file number values may be specified
In the following example, any log record referencing file numbers 10, 20 or 30 through 40 are selected.
PRILOG FILE=(10,20,30-40)
Use the LOGIN_ID parameter to select log records with references to a specific login ID. The LOGIN_ID parameter has the following syntax:
LOGIN_ID=string
Only one login ID can be specified for string. In the following example, any log record containing XSCPCOC in the LOGIN_ID column is selected.
PRILOG LOGIN_ID=XSCPCOC
Use the RECORDS parameter to select log records with references to the specified command sequence number or range of command sequence numbers. The RECORDS parameter has the following syntax:
RECORDS=num[-num]
Any valid command sequence number can be substituted for num. In the following example, any log record containing a command sequence number between and including 101 and 677 will be selected.
PRILOG RECORDS=101-677
Use the RESPONSE parameter to select log records that reference the specified list of response codes or range of response codes. The RESPONSE parameter has the following syntax:
RESPONSE=(num[-num][,num[-num]]...)
Any valid Adabas response codes can be substituted for num. A maximum of ten ranges or response code values may be specified
In the following example, any log record referencing response codes 0, 17, or 15 through 61 are selected.
PRILOG RESPONSE=(0,17,15-61)
Use the USER_ID parameter to select log records with references to a specific user ID. The USER_ID parameter has the following syntax:
USER_ID=string
Only one user ID can be specified for string. In the following example, any log record containing XSCPCOC in the USER_ID column is selected.
PRILOG USER_ID=XSCPCOC
PRILOG messages are documented in the Adabas Messages and Codes manual as "PL6nnna" (independent) and "PL6ann" (system-dependent) messages.
The following components comprise the PRILOG print program for z/OS:
| Member | Library | Description | ||
|---|---|---|---|---|
| PRILOG | ADAvrs.SRCE | Independent PRILOG assembly language source module | ||
| PRILOGD | ADAvrs.SRCE | z/OS-dependent PRILOG assembly language source
module.
|
||
| CCSTCK | ADAvrs.SRCE | Independent Adabas STCK conversion assembly language source module | ||
| ASMPRILO | ADAvrs.JOBS | Sample JCL to assemble and link the PRILOG, CCSTCK, and PRILOGD components into the PRILOG load module. | ||
| JPRILOG | ADAvrs.JOBS | Sample JCL to execute the PRILOG utility |
The PRILOG program uses three files:
| Files | Description |
|---|---|
| DDDDCARD | used for input parameter data; may be any sequential 80-byte record file supported by QSAM. |
| DDPRINT | used for the output command log report; may be assigned to SYSOUT or to any 121-byte record data set with record format of FBA. |
| DDCLOGIN | used for the input sequential command log file; must be a sequential file produced by the ADARES CLCOPY utility, or the direct DDLOG sequential file produced by an Adabas nucleus when single command logging is used. |
|
Warning: PRILOGC is a sample user program and is not supported under any maintenance contract agreement. |
Adabas provides the PRILOGC print program to read and report the contents of Adabas command logs.
PRILOGC reads a sequential Adabas command log that has been produced directly by the Adabas nucleus (DDLOG file) or by the ADARES CLCOPY utility when the Adabas nucleus uses dual or multiple command logging.
PRILOGC is supplied only in source form. To use PRILOGC you must at least compile the source provided by Software AG, although no modifications are necessary.
PRILOGC sources are supplied for z/OS. These modules replace all PRILOGC versions supplied with earlier versions of Adabas.
Two of the PRILOGC modules are system-independent components, and one is specific to a particular operating system.
This section covers the following topics:
For z/OS environments, the following sources are provided:
| PRILOGC | Main program logic - written in C. |
| CCSTCK | Code to convert a STCK value into YYMMDD - written in assembler. |
| ADABASX/ADACLGX/ADAENV/IODESAM | C header files used by PRILOGC. |
The following JCL members are provided in z/OS environments:
| ASMPRILC | Sample JCL to assemble the CCSTCK ADABAS STCK convert routine and link-edit the CCSTCK module. Also use this member to compile and link PRILOGC using the IBM/C compiler. |
| JPRILOGC | Sample JCL to run PRILOGC |
As input, the PRILOGC program requires CLOG records and control statements.
Control statements are read from stdin and take one or more of the following parameters:
a: print Additions fields l: large line size b: dump with verbosity t: dump with traditional format - dump records in format used by earlier prilogc with Version 5 CLOGS c: dump Control Block f: dump Format Buffer r: dump Record Buffer s: dump Search Buffer u: dump User Buffer v: dump Value Buffer n: dump ISN Buffer 6: dump in Open System V6 Format 8: dump in Mainframe V8 Format x: dump extended Buffer (User Data) i: dump IO List h: dump help information d: output dimensions (columns,rows), where columns can be 80 or 133 or 163
Example: -clfrsvbtnix -d=133,200 -event
If a data item specified from the list above is not being captured during the ADALOG session and is therefore not present in the CLOG record, the request to print that data item is ignored.
If -b verbosity is specified, then a more verbose output is generated. The additional fields displayed are the Additions 1, Additions 2, and Additions 5 fields along with the full communications ID. These values are all displayed in hexadecimal format. Also, if the -d DIMENSIONS parameter specifies a narrower output format, the fields not printed in the columns will be displayed in the verbose output format.
The optional DIMENSIONS parameter (-d=cols,rows) is used to specify the format that the printed output should take. The number of columns must be 80, 133, or 163, but any number of rows can be specified. If no value for rows is specified, there will be no page breaks and the column headers will print only once.
If -event is specified, the CLOG data output includes the event log data (when CLOGLAYOUT=8). The event log contains data about when the event happened, the user that received it, and other data about the ISN accessed.
You can also filter the PRILOGC output using the command selection parameters described in this section:
Use the CLASS parameter to select log records whose command codes belong to the specified command classes. The CLASS parameter has the following syntax:
CLASS=(keyword[,keyword]...)
The following table describes the keywords that can be specified:
| Keyword | Commands Included |
|---|---|
| CONTROL | BT, CL, C1, C3, C5, ET, HI, OP, MC, RC, RE, or RI |
| FIND | S1, S2, S4, S8, or S9 |
| READ | LF, L1, L2, L3, L4, L5, L6, or L9 |
| UPDATE | A1, E1, I1, N1, or N2 |
In the following example, the commands included in the FIND and UPDATE keywords are selected:
CLASS=(FIND,UPDATE)
Use the COMMAND parameter to select log records whose commands match specified Adabas command names. The COMMAND parameter has the following syntax:
COMMAND=(cmd[,cmd]...)
Any valid Adabas command can be specified for cmd. In the following example, log records for the OP, S1, L1, E1, and CL commands are selected:
PRILOGC COMMAND=(OP,S1,L1,E1,CL)
Use the DATE parameter to select log records whose timestamps fall between the inclusive start and end times specified. The DATE parameter has the following syntax:
DATE=(start-dd-mmm-yyyy[:start-hh:mm:ss][,end-dd-mmm-yyyy[:end-hh:mm:ss]])
All times must be specified in military (24-hour) time format. Note that the date fields above can optionally be followed by hours, minutes, and seconds.
The first date and time specified in the date parameter is the start date and time; the second date and time pair in the syntax is the end date and time. A comma separates these start and end timestamps. Log records with dates that fall on or between these timestamps will be selected. In the following example, all log data occurring between (and including) 19:16:00.000 and 20:20:20.999 on October 10, 2006 will be selected.
DATE=(10-OCT-2006:19:16:00,10-OCT-2006:20:20:20)
If a time is specified, a date is mandatory. If a time is not specified or if only part of the time is specified, the missing values will be assumed to be zero. For example, a specification of 10-OCT-2006:19:16 is interpreted as 10-OCT-2006:19:16:00 and a specification of 10-OCT-2006:19 is interpreted as 10-OCT-2006:19:00:00.
If no start timestamp is specified, then all records that fall up until the end of the specified range are selected. In the following example, all log records are selected that occurred earlier than and at 20:20:20:999 of October 10, 2006:
DATE=(,10-OCT-2006:20:20:20)
If no end timestamp is specified, then all records that fall after the start of the specified range are selected. In the following example, all log records are selected that occur after or at 20:00:00:000 on October 10, 2006.
DATE=(10-OCT-2006:20:00:00)
If only one date (with no comma) is specified, then the records that are selected must have a timestamp that match the specified timestamp. In the following example, all log records are selected that occur within (and including) the range 10-OCT-2006:19:16:00.000 through 10-OCT-2006:19:16:00.999:
DATE=(10-OCT-2006:19:16)
Use the file parameter to select log records which reference a specified list of file numbers or range of file numbers. The FILE parameter has the following syntax:
FILE=(num[-num][,num[-num]]...)
Any valid Adabas file numbers can be substituted for num. A maximum of ten ranges or file number values may be specified
In the following example, any log record referencing file numbers 10, 20 or 30 through 40 are selected.
FILE=(10,20,30-40)
Use the LOGIN_ID parameter to select log records with references to a specific login ID. The LOGIN_ID parameter has the following syntax:
LOGIN_ID=string
Only one login ID can be specified for string. In the following example, any log record containing XSCPCOC in the LOGIN_ID column is selected.
LOGIN_ID=XSCPCOC
Use the RECORDS parameter to select log records with references to the specified command sequence number or range of command sequence numbers. The RECORDS parameter has the following syntax:
RECORDS=num[-num]
Any valid command sequence number can be substituted for num. In the following example, any log record containing a command sequence number between and including 101 and 677 will be selected.
RECORDS=101-677
Use the RESPONSE parameter to select log records that reference the specified list of response codes or range of response codes. The RESPONSE parameter has the following syntax:
RESPONSE=(num[-num][,num[-num]]...)
Any valid Adabas response codes can be substituted for num. A maximum of ten ranges or response code values may be specified
In the following example, any log record referencing response codes 0, 17, or 15 through 61 are selected.
RESPONSE=(0,17,15-61)
Use the USER_ID parameter to select log records with references to a specific user ID. The USER_ID parameter has the following syntax:
USER_ID=string
Only one user ID can be specified for string. In the following example, any log record containing XSCPCOC in the USER_ID column is selected.
USER_ID=XSCPCOC
The following components comprise the PRILOGC print program for z/OS:
| Member | Library | Description |
|---|---|---|
| PRILOGC | ADAvrs.SRCE | Independent PRILOGC source module written in C. |
| CCSTCK | ADAvrs.SRCE | Independent Adabas STCK conversion assembly language source module. |
| ASMPRILC | ADAvrs.JOBS | Sample JCL to assemble and link CCSTCK, and compile and link PRILOGC load module. |
| JPRILOGC | ADAvrs.JOBS | Sample JCL to execute the PRILOGC utility. |
Before PRILOGC can run on z/OS, the PRILOGC load module must be built by running the compile and link step of the sample job ASMPRILC.
The PRILOGC program uses three files:
| Files | Description |
|---|---|
| PARM data | PRILOGC control card parameter data, passed via the PARM= keyword on the JCL EXEC statement. |
| SYSPRINT | used for the output command log report; may be assigned to SYSOUT or to any 121-byte record data set with record format of FBA. |
| PRLIN | used for the input sequential command log file; must be a sequential file produced by the ADARES CLCOPY utility, or the direct DDLOG sequential file produced by an Adabas nucleus when single command logging is used. |