ADAPLP (Protection Log Printout)

This document describes the utility "ADAPLP".

The following topics are covered:

Functional Overview

The ADAPLP utility prints the Protection Log or WORK.

This utility is a multi-function utility. For more information about single- and multi-function utilities, see Adabas Basics -> Using Utilities -> Single- and Multi-function utility.

Note:
LOB values are split into several records in a LOB file; when LOB values are stored in the database, the Protection Log contains the log records for the modifications of the LOB file. This means that ADAPLP does not display the LOB values as one value, but rather it displays the modifications of the corresponding records in the LOB file instead. It is not possible to decompress the LOB file records because the LOB records are too large to fit into one block, and the continued Protection Log records cannot be decompressed.

Procedure Flow

Procedure Flow ADAPLP

Data Set Environment
Variable/
Logical Name 		Storage
Medium 		Additional Information
Associator ASSOx Disk  
Protection log PLPPLG Disk, Tape Utilities Manual
Protection log (last extent) PLPLEX Disk Only required if you process a PLOG with an extension count > 1 and if you use the DECOMPRESS or DELTA option: you must provide the last PLOG extent before the PLOG extent to be processed.
Control statements stdin/
SYS$INPUT 		  Utilities Manual
ADAPLP report stdout/
SYS$OUTPUT 		  Messages and Codes
Work storage WORK1 Disk  

The sequential file PLPPLG can have multiple extents. For information about sequential files with multiple extents, see Adabas Basics, Using Utilities.

Checkpoints

The utility writes no checkpoints.

Control Parameters

The following control parameters are available:

M    DATASET = keyword

     DBID = number

D    [NO]DECOMPRESSED
     
     DELTA

D    [NO]DUMP

     FILES = (number [-number][,number [-number]]...)

D    [NO]HEADER

     INTERNAL_ID = number

     ISN = (number [,number] ... )

     MODIFIED_RABN = number

     NOFILETYPE

     NONULL

     PLOG = (number [,number])

M    RABN = {*|number[-number]}

     RECORD ={*| (number [- number]  [, number  [- number]]...) }

     SEQ = number

D    [NO]SHORT

     THREAD = number

     TSN = number

D    TYPE = (keyword [,keyword]...)

     USER_ID = string

D    [NO]WXA

DATASET

DATASET = keyword

This parameter selects the file containing the Protection Log information to be processed. The keyword can take the values PLOG or WORK. The parameter PLOG must be specified first if DATASET=PLOG is to be specified and the protection log is located on a raw device.

DBID

DBID = number

This parameter selects the database to be used.

This parameter must be used when DATASET=WORK is requested, or if DATASET=PLOG and the protection log is within a raw section. This parameter must be the first parameter to be specified. Otherwise, if this parameter is not specified, the DBID stored in the PLOG is used.

[NO]DECOMPRESSED

[NO]DECOMPRESSED

This option indicates whether for each selected DATA record from a protection log, one line per field is printed with the field name and its decompressed value in hex (DECOMPRESSED) or not (NODECOMPRESSED).

For an inserted record, an after image containing the field values of the record after the insert is displayed.

For an updated record, a before image containing the field values before the update, and an after image containing the field values of the record after the update are displayed.

For a deleted record, a before image containing the field values before the delete operation is displayed.

If you specify DECOMPRESSED and NONULL, no output is produced for the following:

  • Fields with NU or NC option with null-value;

  • MU fields with NU or NC option without a value that is not the null-value;

  • PE groups containing only fields with NU or NC option without a value that is not the null-value;

  • Group names if the group is not PE.

The default is NODECOMPRESSED.

Note:
Decompression (DECOMPRESSED output) is not possible for CONTINUED records. CONTINUED records are created if a PLOG record plus the block header is larger than 32 KB in the PLOG or larger than the block size used for WORK.

Example output for DECOMPRESSED (without NONULL option) 

>>> After Image <<<


Length = 20, ISN = 2

Field    : AA: ^30372E31322E3034
Group    : AB
Field    : AC: ^2020202020202020202020202020202020202020
Field    : AE: ^2020202020202020202020202020202020202020
Field    : AD: ^2020202020202020202020202020202020202020
Field    : AF: ^20
Field    : AG: ^20
Field    : AH: ^0000000C
Group    : A1
MU-field : AI, count = ^01
           AI(  1): ^2020202020202020202020202020202020202020
Field    : AJ: ^2020202020202020202020202020202020202020
Field    : AK: ^20202020202020202020
Field    : AL: ^202020
Group    : A2
Field    : AN: ^202020202020
Field    : AM: ^202020202020202020202020202020
Field    : AO: ^202020202020
Field    : AP: ^20202020202020202020202020202020202020202020202020
PE-group : AQ, count = ^01
  PE index (1)
Field    : AR: ^202020
Field    : AS: ^000000000C
MU-field : AT, count = ^01
           AT(  1): ^000000000C
End of PE-group : AQ
Group    : A3
Field    : AU: ^3030
Field    : AV: ^3030
PE-group : AW, count = ^01
  PE index (1)
Field    : AX: ^3030303030303030
Field    : AY: ^3030303030303030
End of PE-group : AW
MU-field : AZ, count = ^01
           AZ(  1): ^202020

Example output for DECOMPRESSED (with NONULL option) 

>>> After Image <<<


Length = 15, ISN = 2

Field    : AA: ^30372E31322E3034
Field    : AF: ^20
Field    : AG: ^20

DELTA

DELTA

This parameter indicates that only changed fields after an update are displayed.

For an inserted record, the same output is produced as with the options DECOMPRESSED, NONULL.

For an updated record, a Delta containing the modified field values is displayed. Note that for MU/PE fields, the value count displayed can be smaller than the displayed MU/PE indices if the MU/PE count has been decreased - this is because all field values have been set to the null value.

If a record is deleted, no output is produced, however, you can see the deletion if you display protection log entries of the type CE.

Note:
Decompression (DELTA output) is not possible for CONTINUED records. CONTINUED records are created if a PLOG record plus the block header is larger than 32 KB in the PLOG or larger than the block size used for WORK.

[NO]DUMP

[NO]DUMP

This option indicates whether the variable part of a Protection Log record is included in the printout (DUMP) or not (NODUMP).

If DUMP is specified, the variable part of each Protection Log record is displayed in both hexadecimal and uninterpreted ASCII format.

DUMP implicitly resets SHORT.

The default is NODUMP.

FILES

FILES = (number [-number][,number [-number]]...)

The Protection Log records are only displayed if they belong to the file(s) specified by this parameter.

Only records of the types DA, DV, EXT, INDEX and FCB are displayed.

Please refer to the tables at the end of this section for a description of the various types of Protection Log records.

[NO]HEADER

[NO]HEADER

This option indicates whether for each block of the Protection Log a header is displayed (HEADER) or not (NOHEADER).

The default is HEADER.

INTERNAL_ID

INTERNAL_ID = number

This option displays only the records with the specified internal ID.

ISN

ISN = (number [,number] ... )

The Protection Log records are only displayed if they belong to the ISNs specified by this parameter. Only records of the types DA and DV are displayed. Please refer to the tables at the end of this section for a description of the various types of Protection Log records. This parameter can only be used in conjunction with the FILE parameter.

MODIFIED_RABN

MODIFIED_RABN = number

This option displays only the records in which modifications for the specified RABN are logged.

Please refer to the tables at the end of this section for a description of the various types of Protection Log records.

NOFILETYPE

NOFILETYPE

This keyword specifies that record types that are independent of file numbers (for example ET and BT records) will be displayed in addition to the record types that are bound to file numbers.

Example

adaplp dbid=6 file=25 type=(da,dv,et,bt) nofiletype

The DA and DVT records of file 25 together with all ET and BT records will be displayed.

NONULL

NONULL

The NONULL parameter is only relevant if the DECOMPRESSED parameter is also specified. Please refer to the DECOMPRESSED parameter for further information.

PLOG

PLOG = (number[,number])

This parameter is required if DATASET=PLOG is specified and the protection log is within a raw section. It is optional if the protection log is within a file system. The PLOG number and the extension count can be specified. If an extension count is specified, then only the specified extent will be processed. If no extension count is specified, Adabas will open subsequent extents when necessary. The parameter PLOG must be specified before DATASET=PLOG is specified.

Example:

Section layout

         .
         .
         .
250000 260000  10001  30  PLG.36 created

377000 378000   1001  30  PLG.36(3) created

adaplp: plog=36
adaplp: dataset=plog

PLG.36 will be opened

adaplp: plog=(36,3)
adaplp: dataset=plog

PLG.36(3) will be opened.

RABN

RABN ={*| number [- number] }

This parameter selects one block or a range of consecutive blocks on the WORK or Protection Log file. The information contained in the specified blocks is displayed.

If you specify "*", all blocks are displayed.

Notes:

  1. If you start ADAPLP without specifying RABN, the utility will run, but will not produce any output.
  2. After specifying the RABN parameter, the requested output is generated immediately. Therefore, you must specify all other parameters required for the output generation, for example the DATASET parameter, before the RABN parameter.

Example

adaplp: rabn = 123

adaplp: rabn = 123 - 1246

RECORD

RECORD ={*| (number [- number]  [, number  [- number]]...) }

This parameter selects the records or ranges of records to be printed. All of the records are printed if `*' or nothing is specified.

Example:

adaplp: record = (2-5,9,11)

The records 2, 3, 4, 5, 9 and 11 are written while printing one or more PLOG blocks.

SEQUENCE

SEQUENCE = number

This option displays only the records written by the specified sequence number.

[NO]SHORT

[NO]SHORT

This option indicates whether only Protection Log block headers are printed out (SHORT), or whether all the records in each block are included in the display (NOSHORT).

SHORT implicitly resets DUMP.

By default, the Protection Log block header is displayed followed by all of the records contained in the block.

The default is NOSHORT.

THREAD

THREAD = number

This option displays only the records with the specified thread.

TSN

TSN = number

This option displays only the records with the specified transaction sequence number (TSN).

Only records of the type BT, C5, CL, DA, DV, ET and XA are displayed.

Please refer to the tables at the end of this section for a description of the various types of Protection Log records.

TYPE

TYPE = (keyword [,keyword]...)

This option displays only the protection log records specified by the given keyword(s). Each keyword corresponds to one or more protection log record types, as shown in the following table.

Keyword Protection Log record type
AB AB
ASSO the record type AC and all record types that are selected by the keywords EXT, FCB and INDEX
AT AT
BF BS, BE, BF
BT BT
C1 C1
C5 C5
CE CE
CF CF
CT CT
DA DA
DATA all record types that are selected by the keywords BT, CE, DA, DV, ET and OP.
DC DC
DT DT
ET ET, CL
EXT ACEXT, UIEXT, NIEXT, DSEXT
FCB FCBDS, FCBIX, SPISN
INDEX FE, INDEX, IB, INSRU, REMRU
OP OP
XA all record types that are selected by the keywords YB, YD, YF and YP
YB YB
YD YD
YF YF
YP YP

Please refer to the tables at the end of this section for a description of the various types of Protection Log records.

The default is to display all protection log record types.

USER_ID

USER_ID = string

This option displays only the records which start with the specified user ID.

Only records of the type BT, C1, C5, CL, DA, DV, ET, FCBDS, FCBIX, INDEX and XA are displayed.

Please refer to the tables at the end of this section for a description of the various types of Protection Log records.

[NO]WXA

[NO]WXA

This option alternates between the WORK part 1 ring buffer (NOWXA) and WORK part 1 XA area (WXA).

The default is NOWXA.

ADAPLP Output

Each block of the Protection Log or WORK is preceded by a header, which consists of the following:

  • the block sequence number;

  • the size of the block;

  • the number of the session that the block belongs to (identical to the PLOG number);

  • the time stamp showing when the block was created (internal time stamp for WORK).

The output for a record consists of the following entries:

  • a record sequence number (starting at 1 for each block);

  • the internal length of the record;

  • the command sequence number (uniquely identifies a command);

  • the type of PLOG record (see the following table for more information);

  • the number of the thread that executed the command.

In addition, most records also have the following entries:

  • the internal user identification (in hexadecimal notation) that is uniquely assigned for each command that opens a transaction.

The table below shows the types of PLOG records:

Type Description
AB logs WORK wrap around (WORK only).
AC logs the relocation of a record during backout transaction (WORK only).
ACEXT logs the extension of the address converter (WORK only).
AT logs the adding of a field (ADADBM).
BE logs the end of a buffer flush (WORK only).
BF logs the start and end of a buffer flush (WORK only).
BS logs the start of a buffer flush (WORK only).
BT logs the start of BT processing.
C1 log record from a C1 command. Contains the checkpoint name (PLOG only).
C5 log record from a C5 command (PLOG only).
CE indicates the last entry of a command (last entry with this sequence number). If the command was a delete operation, the file number and the ISN of the deleted record is displayed.
Example
>>> DELETE FILE 10 ISN 2 <<<
CF logs the creation of an FDT (ADAFDU).
CL logs the CLOSE of a user.
CT logs the creation of a file (ADAFDU).
DA logs a data record change. The file, RABN, and ISN of the data record are displayed. The record is either an after image (AI), a before image (BI), or a delta image (DI) and is displayed when DUMP is enabled. `TSN' is an internal transaction sequence number. All entries that originate from one transaction have the same TSN (see also the description of the ET command in the Command Reference Manual). The output of `WB' is only displayed if DATASET=WORK has been specified. It shows the WORK block where the previous PLOG record of the same TSN can be found. A `clu' value that is not zero indicates an exclusive or privileged user.
DC logs the dropping of a field (ADADBM).
DSEXT logs the extension of data storage (WORK only).
DT logs the deletion of a file (ADADBM).
DV logs a descriptor update (should always be preceded by a DA record). The entries for the file, ISN, TSN, clu, and WB are the same as for the DA record type.
ET log entry from an ET command. The ET TSN gives the TSN of the last user data written by an ET command.
FCBDS logs an FCB change for data storage (WORK only).
FCBIX logs an FCB change for the normal index (WORK only).
FE logs a change of an index block's first entry (WORK only).
IB logs an index block that is modified (WORK only).
INDEX logs an index block that is split (WORK only).
INSRU logs the insertion of an index block into a reusage chain (WORK only).
NIEXT logs the extension of the normal index (WORK only).
OP logs the OPEN of a user.
REMRU logs the deletion of an index block from a reusage chain (WORK only).
SPISN logs changes in ISN reusage or space reusage.
UIEXT logs the extension of the upper index (WORK only).
YB logs the backout of a transaction within the XA protocol.
YD logs the discarding of a heuristically terminated transaction within the XA protocol .
YF logs the final commit of a transaction within the XA protocol.
YP logs the preliminary commit of a transaction within the XA protocol.

There are also several flags that may be displayed with DA or DV records:

Flag Description
AI the data of this PLOG record contain an after image of the data record (record type DA).
BACKOUT indicates that the record was written during a backout within a single command.
BI the data of this PLOG record contain a before image of the data record (record type DA).
BT indicates that the record was written during the backout of a transaction.
DI the data of this PLOG record contain a delta image of the data record (record type DA).
FDATA indicates that this is the first DA record of this command.
FIRST_ENTRY indicates that this is the first record with a given sequence number.
HIMERGE merge of the highest index level.
HISPLIT split of the highest index level.
USERD transaction carries user data.