Types of Journal Records

CA IDMS/DB Journal Reports—JREPORTS › Types of Journal Records

Types of Journal Records

Journal reports use the following journal record types:

Record type	Description
TIME	Time record TIME records the date and time the contents of the journal buffer are written to the journal file. A TIME record is created each time a journal buffer is initialized; however, the date and time fields contain binary zeros until the contents of the journal buffer are written to the journal file.
BGIN	Checkpoint BGIN checkpoints mark the beginning of local work done by a transaction branch. They are written to the journal file when a database transaction is initiated if JOURNAL RETRIEVAL is specified in the system definition or when the first update occurs otherwise. Starting with r16 SP4, for compliance and audit reporting, the BGIN checkpoint record contains the user ID of the user signed on who executed the application causing the BGIN to be written. Starting with IDMS Server r16.1 (or IDMS r16 SP6),the BGIN checkpoint record contains the external identity from a multitiered application such as a web application.
AREA	Checkpoint AREA checkpoints record transaction access to a database area. One AREA checkpoint is written to the journal file for each area readied by an explicit DML READY statement or readied automatically by the DBMS. AREA checkpoints are written to the journal file as follows: Under the central version, AREA checkpoints are written to the journal file at the time of the first functional call issued by the application program. In local mode, AREA checkpoints for areas readied in update mode are written to the journal file as each READY statement is processed. AREA checkpoints for areas readied in retrieval mode are written to the journal file at the time of the first functional call.
COMT	Checkpoint COMT checkpoints are written during a commit operation to mark the successful completion of a transaction branch. A COMT checkpoint is similar to an ENDJ checkpoint except that it enables work done after the commit to be recorded on the journal file under the same local identifier (LID). It is only written in response to a COMMIT or COMMIT WORK CONTINUE statement and then only if ON COMMIT WRITE COMT is specified in the system definition.
ENDJ	Checkpoint ENDJ checkpoints are written during a commit operation to mark the successful completion of a transaction branch.
RTSV	Checkpoint RTSV checkpoints mark an SQL statement whose updates must be rolled out. An RTSV checkpoint is written to the journal file whenever an error is encountered while processing an SQL statement and that statement has updated the database.
ABRT	Checkpoint ABRT checkpoints are written during a backout operation to mark the abnormal completion of a transaction branch. If running under the central version, ABRT checkpoints are written only after CA IDMS/DB automatically recovers a failing transaction.
BFOR	Journal record entry BFOR entries record the before image of a database record. A BFOR entry is created when a CA IDMS/DB application program issues a request to update information in the database. When a new record is stored, the BFOR entry contains a null before image, indicating the previous absence of the record in the database. When a BFOR entry contains a null before image, the record-image-length field in the entry is set to zero.
AFTR	Journal record entry AFTR entries record the after image of a database record. An AFTR entry is created when a CA IDMS/DB application program issues a request to update information in the database. When an existing record is removed, the AFTR entry contains a null after image, indicating the deletion of the record from the database. When an AFTR entry contains a null after image, the record-image-length field in the entry is set to zero.
DIND	Distributed checkpoint (In doubt) DIND entries are written by a two-phase commit participant after it has successfully prepared its resources for commit and prior to returning an OK response to its coordinator. The DIND entry contains the Local Transaction Identifiers (LIDs) identifying the work done by the local transaction branches that participated in the distributed transaction. It also contains information about a participant's coordinator and about a coordinator's participants. The specific information that is recorded varies depending on the type of the coordinator or participant.
DCOM	Distributed checkpoint (Commit) DCOM entries are written by a two-phase commit coordinator to signify that a distributed transaction's changes will be committed. Its existence demarcates the first and second phases of the commit process. A participant also writes a DCOM entry immediately upon receiving a Commit request from its coordinator. The DCOM entry contains the Local Transaction Identifiers (LIDs) identifying the work done by the local transaction branches that participated in the distributed transaction. It also contains information about a participant's coordinator and about a coordinator's participants. The specific information that is recorded varies depending on the type of the coordinator or participant.
DBAK	Distributed checkpoint (Backout) DBAK entries are written be a two-phase commit coordinator to signify that a transaction's changes will be backed out. Its existence demarcates the first and second phases of the commit process. A participant also writes a DBAK entry immediately upon receiving a Backout request from its coordinator but only if a DIND had previously been written. The DBAK entry contains the Local Transaction Identifiers (LIDs) identifying the work done by the local transaction branches that participated in the distributed transaction. It also contains information about a participant's coordinator and about a coordinator's participants. The specific information that is recorded varies depending on the type of the coordinator or participant.
DPND	Distributed checkpoint (Pending) DPND entries are written by a two-phase commit coordinator during the second phase of a commit operation if a participant is unable to complete its commit processing due to a failure. By writing this entry, the coordinator is able to forget some participants while remembering others. It is written by a participant if it is forced to heuristically complete its portion of a distributed transaction. The DPND entry contains information about a participant's coordinator and about a coordinator's participants. The specific information that is recorded varies depending on the type of the coordinator or participant.
DFGT	Distributed checkpoint (Forget) DFGT entries are written by two-phase commit coordinators and participants when they have completed their two-phase commit processing for a distributed transaction. A DFGT entry is written only if some other distributed checkpoint entry was previously written for the transaction.

Relating Local and Distributed Journal Entries

BGIN, COMT, ENDJ, and ABRT checkpoints and BFOR and AFTR journal entries log work done by a transaction branch within the local system. They contain a 4-byte local identifier (LID) that uniquely identifies this work. In order to associate work done locally with a distributed transaction, DIND, DCOM, and DBAK checkpoints contain a list of LID values representing the local work units that are part of the distributed work unit.

The following illustrates the sequence in which local and distributed journal records can be written to a journal file for a distributed transaction:

BGIN - indicates the start of work done locally
BFOR/AFTR - one or more pairs
DIND - on a participant only
DCOM or DBAK - on a participant and a coordinator
COMT or ENDJ - if a DCOM was written
ABRT - if a DBAK was written
DPND - on a coordinator if the commit operation was interrupted; on a participant if the transaction was heuristically completed
DFGT - on a participant and a coordinator if any other distributed checkpoint was written

Special Considerations for BFOR and AFTR Entries

BFOR and AFTR entries are also written when CA IDMS/DB brings relocated records back to the home page or physically deletes logically deleted records. These actions can occur during any operation; therefore, BFOR and AFTR entries can appear for retrieval-only transactions that have readied the applicable area in update mode.
Corresponding BFOR and AFTR entries are not necessarily contiguous in the journal file. For example, the BFOR record for one transaction may be immediately followed by an AFTR record for a different transaction. The BFOR and AFTR entries for a database record contain either the whole record or a portion of the record, as follows:
- If the data portion of the record has been changed, the journal record entries contain the entire database record (that is, the dbkey, prefix, and data portions).
- If only pointers in the record prefix have been changed, only the dbkey and prefix portions of the record are written to the journal file.
BFOR and AFTR entries can also span journal blocks. A record that spans a journal block appears as two records with the second portion offset by the length of the first portion. For example, if 200 bytes remain in a journal block, a 500-byte BFOR record is journaled as one 200-byte and one 300-byte BFOR journal entry; the 300-byte entry has an offset of 200.

Special Considerations for Distributed Checkpoint Entries

Distributed Checkpoint entries (types DIND, DCOM, DBAK, DPND, and DFGT) can be larger than a single disk journal block. If this is the case, they are split into as many journal blocks as necessary to hold the entire record.
Distributed Checkpoint entries can also be split across disk journal files and, hence, across archive files.

The following figures show the record layouts for the journal record types.

Field Definitions for JREPORT 000

The journal record field definitions as they appear in the JREPORT 000 parameter module appear as follows. The parameters show the actual names (and synonyms) of the journal record fields.

 REC$0**** 'J' REPORTS IDMS JOURNAL FILE   volser    REC PARAMETERS
 REC REC-LEN                           1  2 1
 REC TYPE                              5  4
 REC GMT                               9  8
 REC SEQ                              17  8 1
 REC SEQ-A                            17  8    $IDMS/2882 HEX COMPARE
 REC QUAL                             25  8 1  $qualifier:
 REC QUAL-CV                          25  8       $CV: node
 REC QUAL-LOCAL                       25  8 1     $Local: GMT
 REC CVNO                             33  1
 REC VERS                             34  1
 REC RSV1                             35  2    $Reserved
 REC $ BGIN,COMT,ENDJ,ABRT,RTSV, Plus AREA,BFOR,AFTR RECORDS ********
 REC TRANSACT-ID                      37  4 1
 REC TRANSACT-IDC                     37  4
 REC $ BGIN,COMT,ENDJ,ABRT,RTSV, Plus AREA RECORDS ******************
 REC VIB                              41  4 1
 REC $ BGIN,COMT,ENDJ,ABRT,RTSV RECORDS******************************
 REC PROGRAM-NAME                     45  8
 REC DTESTAMP                         53  8
 REC DTESTAMPX                        53  8 1
 REC OLDTIM                           61  8 2  $not used
 REC UPDATE-QUIESE                    69  2 1
 REC QUIESCE                          71  2 1
 REC SAVEPOINT-SEQ                    73  8 1  $RTSV only.
 REC TASK-ID                          73  8    $Local Task id.
 REC LT-P1                            73  4
 REC LT-P2                            77  4 1
 REC $ COMT,ENDJ,ABRT RECORDS ONLY **********************************
 REC UPDATED                          81  4 1
 REC DB-STATS                         85 60
 REC READ                             85  4 1
 REC WRITTEN                          89  4 1
 REC PAGE-REQUESTS                    93  4 1
 REC CALC-ON                          97  4 1
 REC CALC-NOT-ON                     101  4 1
 REC VIA-ON                          105  4 1
 REC VIA-NOT-ON                      109  4 1
 REC REC-REQUESTED                   113  4 1
 REC CURR-OF-TR                      117  4 1
 REC CALLS                           121  4 1
 REC FGMT-STORED                     125  4 1
 REC FGMT-RETURNED                   129  4 1
 REC LOCKS-REQUESTED                 133  4 1
 REC SHARED-LOCKS-HELD               137  4 1
 REC EXCLUSIVE-LOCKS-HELD            141  4 1
 REC TR-ID-CV                        145  4 1    $TRANSACTION ID.
 REC TASK-ID-CV                      149  4 1    $TCE address.
 REC LOCAL-TASK-ID-CV                153  8
 REC LT-PART1                        153  4
 REC LT-PART2                        157  4 1
 REC LT-PART2A                       157  3 1    $ IDMS/2549
 REC LT-PART2B                       160  1 1    $ IDMS/2549
 REC IX-STATS                        161 40
 REC IX-SR8-SPLITS                   161  4 1
 REC IX-SR8-SPAWNS                   165  4 1
 REC IX-SR8-STORED                   169  4 1
 REC IX-SR8-ERASED                   173  4 1
 REC IX-SR7-STORED                   177  4 1
 REC IX-SR7-ERASED                   181  4 1
 REC IX-BTREE-SEARCHES               185  4 1
 REC IX-BTREE-LEVELS-SEARCHED        189  4 1
 REC IX-ORPHANS-ADOPTED              193  4 1
 REC IX-LEVELS-SEARCHED-BEST         197  2 1
 REC IX-LEVELS-SEARCHED-WORST        199  2 1
 REC $ TIME RECORD ONLY *********************************************
 REC T-DATESTMP                       37  8 1
 REC $ BGIN RECORD ONLY *********************************************
 REC USER-ID                          81 32
 REC EXTERNAL-ID                     113 32
 REC $ AREA RECORD ONLY *********************************************
 REC AREA                             45 18
 REC RESERVED2                        63  2
 REC LOW-PAGE                         65  4 1
 REC HIGH-PAGE                        69  4 1
 REC MODE                             73  2 1
 REC ACCESS                           75  2 1
 REC $ BFOR & AFTR RECORDS ONLY *************************************
 REC IDMS-VSAM-FLAG                   41  1 1
 REC AREA-TYPE                        41  1 1
 REC VERB-NUM                         42  1 1
 REC VERB                             42  1 1
 REC PAGE-GROUP                       43  2 1
 REC DBK-FORMAT                       45  4 1
 REC DBK-LINES                        48  1 1
 REC DB-KEY                           49  4 1
 REC DB-KEY1                          49  3 1    $IDMS/1209
 REC DB-KEY2                          52  1 1    $IDMS/1209
 REC DB-KEY-A                         49  4      $Hex compares IDMS/2721
 REC USER-REC-ID                      53  2 1
 REC USER-REC-ID-A                    53  2      $Hex compares IDMS/1893
 REC PG-DISPL                         55  2 1
 REC IMAGE-LEN                        57  2 1
 REC PREFIX-LEN                       59  2 1
 REC DISPLACEMENT                     61  2 1
 REC SPAN-OFFSET                      63  2 1
 REC USER-RECORD                      65  2 1
 REC $ Rnn.n DXXX RECORDS: DIND,DCOM,DBAK,DPND,DFGT *****************
 REC DTRIDQ                           37 24
 REC DTRID                            37 16
 REC DNODE                            37  8
 REC DID                              45  8
 REC DBRANCH-ID                       53  8
 REC DFLAG1                           61  1
 REC DFLAG2                           62  1
 REC STATE                            63  1
 REC OUTCOME                          64  1
 REC PREPARE-OUTCOME                  65  1
 REC BACKOUT-REASON                   66  1
 REC DRESERVED                        67  2
 REC LIDOFF                           69  2 1
 REC LIDNUM                           71  2 1
 REC XIDOFF                           73  2 1
 REC XIDNUM                           75  2 1
 REC RIOFF                            77  2 1
 REC RICNT                            79  2 1
 REC DVLEN                            81  2 1
 REC DVOFF                            83  2 1
 REC DXXX-RECORD                      85  2 1