This section describes the journaling action qualifiers.
/EX[TRACT][=file-specification]
Specifies that JOURNAL should transfer the contents of one or more journal files to a single output file in a format intended for processing by an M program. For a description of /EXTRACT output record formats, refer to the Journal Extract Formats section later in this chapter.
/EXTRACT takes an optional argument, which provides an output file-specification. If the output file specification is not provided, MUPIP JOURNAL derives the output file specification of the extract file using the name of the first journal file that is processed in the forward processing phase and a file type of .mjf. Note that, if multiple journal names are specified in the command line the first journal specified might be different from the first journal processed in the forward phase. When /EXTRACT is specified with /RECOVER (or /ROLLBACK), the /JOURNAL command extracts all the journal records processed during a /RECOVER /FORWARD command or the forward phase of (/RECOVER or /ROLLBACK) /BACKWARD command.
When used independent of /RECOVER (or / ROLLBACK), /EXTRACT option can produce a result even though the database file does not exist, although it does try to access the database if it is available. If accessing the database errors out for some reason, the contents of the journal file can still be extracted by temporarily renaming or moving the database file.
If globals in the database have collation enabled, their collation information is stored in the global variable tree of the database and not in the journal file. A journal extract of such globals without the presence of the corresponding database will not be meaningful as the MUPIP JOURNAL command has no way of knowing just from the journal files if the globals are collated, and hence will extract them as if they were uncollated.
Note that, a broken transaction, if found, is extracted to a broken transaction file (refer to the section on /BROKENTRANS for details), and all future complete transactions are considered as lost transactions, and are extracted to a lost transaction file (refer to the section on /LOSTTRANS for details).
To avoid broken transaction or lost transaction processing and instead extract all journal records into one file, use the control qualifier /FENCES=NONE. It is strongly recommended not to use /FENCES=NONE if / RECOVER or /ROLLBACK is also specified.
/RECOVER
Instructs the JOURNAL command to replay database updates from the specified journal file into the appropriate database. /RECOVER initiates the central JOURNAL operation for non-replicated database. JOURNAL commands may specify /RECOVER alone, or with other action qualifiers except /ROLLBACK.
If a transaction is found with incomplete fence, it is considered broken. During forward phase of recovery, if a complete transaction (fenced or unfenced) is found after a broken transaction. /RECOVER increments the error count. If /ERRORLIMIT is reached, the complete transaction goes to lost transaction file, otherwise, it is applied to the database.
All broken and lost transactions are made available as the result of the /RECOVERY. They are written as journal extract format in two different text files. They are the broken transaction file and the lost transaction file. Refer to the sections on BROKENTRANS and LOSTTRANS control qualifier.
When performing JOURNAL /RECOVER with fences (FENCES="PROCESS" or FENCES="ALWAYS"), it is essential for the command to include all the journal files corresponding to the complete set of database files that make up the logical database. If the specified set of journals is incomplete, the recovery reports all transactions that included any missing region as broken. Typically, this means that the results of the recovery are unsatisfactory or even unusable.
MUPIP JOURNAL /RECOVER requires exclusive access to database files before recovery can occur. It keeps the exclusive access to the database files, which means that the database files become inaccessible during the time of recovery.
For direction qualifier /FORWARD, if the target database's current transaction number is less than first transaction number to be processed in the specified journal file for that region, /RECOVER attempts to include previous generation journal file(s) in its processing, unless the /NOCHAIN qualifier is specified. Following the successive previous links of journal files /RECOVER tries to include previous generations of journal files until the transaction number when the journal file was created is less than, or equal to that of the target database. /RECOVER issues one or more informational messages when it includes previous generation journal files.
If target database's current transaction number is not equal to the first transaction number of the earliest journal file to be processed for a region, /RECOVER exits with an error, unless /NOCHECKTN is used. If multiple journal files for a single region are specified in a MUPIP JOURNAL /RECOVER /FORWARD command it behaves as if /NOCHAIN was specified. If the journal files are not a complete set (for example mumps1.mjl, & mumps3.mjl were specified, with mumps2.mjl missing from the command line), MUPIP JOURNAL errors out since the journal files specified are discontinuous in terms of database transaction numbers. On the other hand, specifying just mumps3.mjl automatically includes mumps2.mjl and mumps1.mjl in the recovery.
Forward recovery ignores the current journaling state of the target database file. It disables journaling of the target database file, (if currently ENABLE and ON), while playing forward the database updates. However, it restores the journaling state of the database at the end of a successful recovery (if necessary), except when journaling is ENABLE'd and ON before the recovery. In the latter case, the journaling state at the end of a successful recovery, is switched to ENABLE and OFF. No journaling is performed for the logical updates to the database for JOURNAL / RECOVER /FORWARD.
For direction qualifier /BACKWARD, the target database file should be the same as when GT.M wrote the last complete transaction to the journal. Because the database may be in an indeterminate state due to a failure, exact checks for this match are not possible. If the target database has journaling DISABLE'd (or ENABLE, OFF), /RECOVER /BACKWARD exits with an error message.
If the target database has journaling ENABLE, ON, but the journal file name in database file header does not match the latest generation journal file name specified for that region, /RECOVER exits with an error.
During forward phase of JOURNAL /RECOVER /BACKWARD MUPIP journals the logical updates to the database. It also creates before images. It is always required to have journaling ENABLE'd and ON for /RECOVER /BACKWARD or /ROLLBACK.
If time qualifiers are not specified, MUPIP JOURNAL /RECOVER (or /ROLLBACK) /BACKWARD does an optimal recovery (processing records for the minimum period that is required to assure a proper recovery). /RECOVER /BACKWARD may need to include some previous generations of journal files based on time qualifier (implicit or explicit). It issues appropriate messages whenever such inclusions occur. At the end of backward recovery, the journaling state of the database stays ENABLE, ON.
When a database file is rolled back by /RECOVER /BACKWARD, the corresponding journal file is also rolled back so that the two are synchronized. /RECOVER /BACKWARD then creates a new journal file. If no forward play of journal records is neccessary, the newly created journal file stays empty and the database points to the new journal file. The values for journal allocation and extension in the new journal file, are copied over from the database. The autoswitchlimit value in the new journal file is the maximum of the autoswitchlimit values of all journal files from the latest generation journal file until the turnaround point journal file generation (turnaround point is the point in the journal file where backward processing stops and forward processing begins). The journal allocation/extension values in the new journal file are picked up from the earliest generation of the set of those journal files sharing the maximum autoswitchlimit value.
A prefix rolled_bak_ is added to the journal file, whose entire contents are eliminated (rolled back) by a /RECOVER /BACKWARD. These files are not used by GT.M after the MUPIP JOURNAL /RECOVER, and can be moved/deleted as needed.
/ROLLBACK
/ROLLBACK initiates the central JOURNAL operation for replicated databases. MUPIP JOURNAL commands may specify /ROLLBACK alone or with other action qualifiers, but not with /RECOVER. If you do not use the /FETCHRESYNC qualifier, the database rolls back to the last consistent state. Only asterisk (*) qualifier is allowed for the journal file selection, that is, /ROLLBACK does journal file selection by itself. MUPIP JOURNAL /ROLLBACK requires exclusive access to database files before recovery can occur. It keeps an exclusive access to the database files, that is, these database files are inaccessible during the /ROLLBACK operation.
/ROLLBACK /BACKWARD exits with an error message for following conditions:
-
Any database region corresponding to a journal file processed has replication state turned OFF. Note that, a configuration where there are replicated regions and at least one non-replicated-but-journaled region is not permitted by the replication source server. The source server errors out at startup on such a configuration without having set up the journal pool. Since all GT.M updates to replicated regions need the source server to have set up a journal pool, no updates are possible until the configuration is changed to have only replicated regions or non-replicated-and-non-journaled regions.
-
Any database region corresponding to a journal file identified by the command argument has journaling state DISABLE'd or ENABLE'd and OFF.
-
Any database region corresponding to a journal file has journal state ENABLE'd and ON, but the journal file name specified in the database file header is different than one identified by the command argument.
If a transaction is found with incomplete fence, it is considered broken. For the duration of the rollback, replication is turned OFF on all regions and turned back ON at the end of the rollback.
During the forward phase of rollback, if a complete transaction (fenced or unfenced) is found after a broken transaction, it is considered as a lost transaction. During forward phase of rollback, MUPIP journals the logical updates to the database. All broken and lost transactions are made available as a result of the rollback. These are written as journal extract format in two different text files.
When a database file is rolled back by /ROLLBACK, the corresponding journal file is also rolled back so that the two are synchronized. /ROLLBACK then creates a new journal file. If no forward play of journal records is necessary, the newly created journal file is empty and the database points to the new journal file. The journal allocation/extension/autoswitchlimit values in the new journal file is set in the way as described for /RECOVER /BACKWARD in the previous section under /RECOVER.
A prefix rolled_bak_ is added to the journal file, whose entire contents are eliminated by a /ROLLBACK. These files are not used by GT.M after the MUPIP JOURNAL /RECOVER, and can be moved/deleted as needed.
For /ROLLBACK the target database file should be the same as when GT.M wrote the last complete transaction to the journal.
If the /FETCHRESYNC or /RESYNC qualifiers are not specified, MUPIP does an optimal rollback.
![[Note]](images/note.png)
|
Note |
|---|---|
|
/FORWARD, /CHAIN, /CHECKTN, /REDIRECT and all other time qualifiers are not allowed with /ROLLBACK. |
/SH[OW]=show-option-list
Specifies what information the JOURNAL command displays about a journal file. If /FORWARD direction qualifier is used with /SHOW and /RECOVER action qualifier is not specified, the entire journal file is processed. When /SHOW is specified with /RECOVER (or /ROLLBACK), the JOURNAL command considers all the journal files/records processed during a /RECOVER /FORWARD command or forward phase of a /RECOVER (or /ROLLBACK) /BACKWARD command. When used independent of /RECOVER (or /ROLLBACK), this option does not require database access.
The show-option-list includes (these are not case-sensitive):
AL[L]
H[EADER]
P[ROCESSES]
AC[TIVE_PROCESSES]
B[ROKEN_TRANSACTIONS]
S[TATISTICS]
The following list describes the /SHOW options.
-
AL[L]
ALL displays every available type of information about the journal file. ALL is the default if the show-option-list is omitted. For additional information, refer to the descriptions of each of the other SHOW keywords.
-
AC[TIVE_PROCESSES]
ACTIVE_PROCESSES displays all processes active at the end of the period specified implicitly or explicitly by the JOURNAL command time qualifiers.
-
B[ROKEN_TRANSACTIONS]
BROKEN_TRANSACTIONS displays all processes that had incomplete fenced transactions at the end of the period covered by the JOURNAL command.
-
H[EADER]
HEADER displays the journal file header information. If the MUPIP JOURNAL command includes only the /SHOW=HEADER action qualifier, only the journal file header (not the contents) is processed, irrespective of whether /BACKWARD or /FORWARD direction qualifier is specified.
HEADER displays almost all the fields in the journal file header. The NODE field is printed upto a maximum of the first 12 characters. This information includes:
Before-image journal ENABLED Journal file header size 2048 [0x00000800] Virtual file size 100 [0x00000064] blocks Crash FALSE Recover interrupted FALSE End of Data 7568 [0x00001D90] Prev Recovery End of Data 0 [0x00000000] Journal Creation Time 18-JUN-2003 11:17:43 Time of last update 18-JUN-2003 11:17:48 Begin Transaction 1 [0x00000001] End Transaction 101 [0x00000065] Align size 65536 [0x00010000] bytes Epoch Interval 300 Replication State CLOSED Updates Disabled on Secondary FALSE Jnlfile SwitchLimit 8388600 [0x007FFFF8] blocks Jnlfile Allocation 100 [0x00000064] blocks Jnlfile Extension 100 [0x00000064] blocks Maximum Physical Record Length 1080 [0x00000438] Maximum Logical Record Length 1064 [0x00000428] Turn Around Point Offset 0 [0x00000000] Turn Around Point Time 0 Start Region Sequence Number 0000000000000001 [0x0000000000000001] End Region Sequence Number 0000000000000000 [0x0000000000000000] -
P[ROCESSES]
PROCESSES displays all processes active during the period specified implicitly or explicitly by the JOURNAL command time qualifiers.
-
S[TATISTICS]
STATISTICS displays a count of all journal record types processed during the period specified implicitly or explicitly by the JOURNAL command time qualifiers.
/[NO]V[ERIFY]
/VERIFY verifies a journal file for integrity. This qualifier cannot have a value. /VERIFY scans the files and checks if it is in legal form, if not, it terminates without affecting the database files.
/VERIFY when specified along with /FORWARD verifies the entire journal file For /NOVERIFY /FORWARD, only the tail of a journal file is verified for cross region integrity. In both cases, if /RECOVER is also specified, the forward play of journal records is done in a separate pass only after the verification pass is complete and error-free.
/VERIFY along with /BACKWARD verifies all journal records from the end of the journal file till the turn around point. When /VERIFY /BACKWARD is specified along with /RECOVER or /ROLLBACK, backward processing involves two passes, the first pass to do the verification until the turn around point, and the second pass to apply before image (PBLK) records.
When /NOVERIFY /BACKWARD is specified along with /RECOVER or /ROLLBACK, PBLKs are applied to the database in the same pass as the verification. This speeds up processing. But the disadvantage of this approach is that in the event of verification terminating in the middle of backward processing, there is no protection of cross-region integrity. Fidelity recommends the use of /VERIFY with /RECOVER or /ROLLBACK.
When used independent of /RECOVER (or /ROLLBACK), /[NO]VERIFY option does not need database access. The default is /VERIFY.