DISABLE

DISABLE is functionally equivalent to the /NOJOURNAL qualifier of MUPIP SET. It specifies that journaling is not an option for the region or file named. If DISABLE is specified, no other options are allowed in the journal-option-list.

ENABLE

ENABLE specifies that the database file or region is available for journaling. By default, specifying ENABLE also turns journaling ON unless OFF is specified in the same option list, you must also specify BEFORE_IMAGES or NOBEFORE_IMAGES.

OFF

OFF specifies that GT.M cease recording subsequent updates to the database in the journal file. OFF may also be used to establish journaling characteristics without creating a journal file or starting journaling. When a database has been SET /JOURNAL=OFF, it has established journal characteristics ready to turn ON, but GT.M does not write journal updates to that file.

	The default for SET /JOURNAL= is ON.

ON

ON instructs MUPIP to create a new journal file and GT.M to record subsequent database updates in that journal file. A SET /JOURNAL=ON must include either BEFORE_IMAGES or NOBEFORE_IMAGES in the accompanying journal-option-list.

Note that ON can be specified only for a file or region with journaling already ENABLE'd, or, if ENABLE is specified at the same time. ON is ignored if journaling is currently DISABLE'd for the database.

Example:

MUPIP SET /JOURNAL=(
ON,BEFORE_IMAGES)

/REGION "*"

This command turns journaling on only for the regions with journaling already ENABLE'd.

	The default for SET /JOURNAL= is ON.

ALI[GNSIZE]=blocks

ALIGNSIZE=blocks specifies in number of 512-byte-blocks, the alignsize of the journal file.

Since a journal file consits of a sequential stream of journal records each of varying size, it is not easy normally to detect the beginning of the last valid journal record in an abnormally terminated journal file (for example, system crash). To facilitate journal recovery in such circumstances, the GT.M run-time system ensures that offsets in the journal file which are multiple of ALIGNSIZE (excepting offset 0 which houses the journal file header) will always be the beginning of a valid journal record. In order to ensure this, GT.M run-time system writes padding data (if necessary) in the form of ALIGN journal records just before the ALIGNSIZE boundary. These ALIGN records also help in skipping past invalid records in the middle of a journal file allowing MUPIP JOURNAL /EXTRACT /FORWARD /FULL to extract as much data of a corrupt journal file as possible.

If the specified ALIGNSIZE is not a perfect power of 2, it is rounded up to the nearest power of 2.

The default ALIGNSIZE value is 128 blocks (=64 kilobytes) and the minimum value is 32 blocks (=16 KiloBytes). The maximum value is 4194304 (=2 GigaBytes).

	The minimum ALIGNSIZE supported will always be greater than or equal to the maximum journal record size which in turn depends on the maximum database block size.

Note that a large value of ALIGNSIZE implies less aligned boundaries for recovery to use and hence slows backward recovery down so drastically that a value of 4194304 causes backward recovery (in case of a crash) to take as much time as forward recovery on that journal file.

ALL[OCATION]=blocks

ALLOCATION=blocks specifies in 512 byte-blocks, the initial size of the journal file allocated on creation. Because, frequent journal file extensions degrade run-time performance, make journal file allocation ample for a production database.

GT.M issues informational messages to the system log whenever the free space available is not much more than the extension size. GT.M provides these extension checks as an operational aid for identifying, before space runs out, that a file system holding the journal file is low on space. When there is no more free space available on the file system holding a journal file, GT.M shuts off journaling for the corresponding database file.

The default ALLOCATION value is 100 blocks. The minimum value allowed is 10. The maximum value is 8,388,607 (4GB-512 bytes, the maximum journal file size).

AU[TOSWITCHLIMIT]=blocks

AUTOSWITCHLIMIT=blocks specifies in 512-byte blocks, a limit on the size of a journal file. When the journal file size reaches the limit, GT.M automatically performs an implicit online switch to a new journal file.

	It is possible to set the AUTOSWITCHLIMIT to a value higher than the maximum file size (in blocks) for the file system. Currently GT.M does not attempt to check for this condition at specification time. When the maximum file-system size is reached, this can cause serious run-time errors. Therefore, ensure that the AUTOSWITCHLIMIT never exceeds the file-system limit.

The default value for AUTOSWITCHLIMIT is 8388600 & the maximum value is 8388607 blocks (4GB-512 bytes). The minimum value for AUTOSWITCHLIMIT is 2048 (number of blocks needed to have 64 ALIGNSIZE boundaries each 16 KB, which is the minimum ALIGNSIZE). If the AUTOSWITCHLIMIT value is less than the sum of allocation and extension values, an error is issued. If the difference between the AUTOSWITCHLIMIT and the allocation value is not a multiple of the extension value, MUPIP rounds-down the value to make it a multiple of the extension value. An informational message to this effect is issued. In the event of the rounded value of AUTOSWITCHLIMIT being less than the minimum, an error is issued.

[NO]BEFORE_IMAGES

[NO]BE[FORE_IMAGES] controls whether or not the journal should capture BEFORE_IMAGES of GDS blocks that an update is about to modify. Databases using MM access must use NOBEFORE_IMAGES journaling. A SET /JOURNAL=ON must include either BEFORE_IMAGES or NOBEFORE_IMAGES in the accompanying journal-option-list.

	If both NOBEFORE_IMAGES and BEFORE_IMAGES are specified in the same journal-option-list, the last of these specifications overrides any previous one(s).

A BEFORE_IMAGES journal provides the option of performing Rollback Recovery (that is, Backward Recovery) of the associated database. BEFORE_IMAGES increases the load on I/O and CPU resources, and therefore may affect performance.

	Since new journal files are created only with the ON option and since every ON specification must include either BEFORE_IMAGES or NOBEFORE_IMAGES, specifying [NO]BEFORE_IMAGES along with the OFF option establishes a value for the BEFORE_IMAGES option that always gets overridden by a later ON option specification.

Although it is possible to perform an online switch of a database from (or to) NOBEFORE-IMAGE journaling to (or from) BEFORE-IMAGE journaling, it is important to understand that backward recovery can never succeed if it encounters even one in a set of journal files for a database without BEFORE-IMAGES.

BU[FFER_SIZE]=blocks

BUFFER_SIZE=blocks specifies, in 512-byte blocks, the amount of memory used to buffer journal file output.

MUPIP requires standalone access to the database in order to actually modify BUFFER_SIZE. Therefore, this option cannot be used to change the current journal-buffer-size as part of an online switch of the journal files.

The minimum BUFFER_SIZE is one more than the number of 512-byte blocks required to hold one GDS database block. The maximum is 2000 blocks. The default value is 128 blocks.

EP[OCH_INTERVAL]=seconds

EPOCH_INTERVAL=seconds specifies the elapsed time interval between two successive EPOCHs. An EPOCH is a checkpoint, at which all updates to a database file are committed to disk.

A smaller EPOCH_INTERVAL reduces the time to recover after a crash at the cost of increased I/O load on the run-time system (due to more frequent checkpoints). A larger EPOCH_INTERVAL has the opposite effect.

The default EPOCH_INTERVAL value is 300 seconds (5 minutes). The minimum value is 1 second. The maximum value is 32,767 (one less than 32K) seconds, or approximately 9.1 hours.

EX[TENSION]=blocks

EXTENSION=blocks specifies the size of the journal file extension performed when the file expands and becomes full.

Every extension triggers a check of free space available on the device used for the journal file. GT.M issues informational messages to the system log whenever the free space available is not much more than the extension size. GT.M provides these extension checks as an operational aid for identifying, before space runs out, that a file system holding the journal file is low on space. When there is no more free space available on the file system holding a journal file, GT.M shuts off journaling for the corresponding database file.

The Allocation and extension values determine when a check is done on the filesystems to see if it has enough space to hold an extension worth of journal data. When a journal file reaches the size specified by the sum of ALLOCATION and any multiple of EXTENSION, GT.M checks the file system for room, and if the available space is less than three times the EXTENSION, it writes warnings to the operator log. GT.M provides these extension checks as an operational aid for identifying, before space runs out, that a file system holding the journal file is low on space. When there is no more free space available on the file system holding a journal file, GT.M shuts off journaling for the corresponding database file.

The default EXTENSION value is 100 blocks. The minimum EXTENSION is zero (0) blocks and the maximum is 65,535 (one less than 64K) blocks.

	Use EXTENSION size of zero (0) with caution, since it shuts journaling off whenever the first extension becomes necessary.

F[ILENAME]=journal filename

F[ILENAME]=journal filename, specifies the name of the journal file. FILENAME is incompatible with SET /REGION, if more than one region is specified.

The default value for the journal-option is based on the following convention:

If the database has a dat extension, the basename of the database filename is taken as the basename for the journal file with an extension of mjl. For example, database name mumps.dat results in a default name mumps.mjl. If the database filename does not have a dat extension, the full database filename is taken replacing ALL occurrences of periods (.) with underscores (_) with an extension of mjl. For example, database name mumps.acn results in a default name mumps_acn.mjl.

Therefore, a journal file always has an extension of mjl. If the new journal filename (the one specified in the FILENAME option or the default) already exists, the existing file is renamed with the string "_YYYYJJJHHMMSS" appended to the existing file extension where the string denotes the time of creation of the existing journal file in the following format:

YYYY           4-digit-year                                    such as 2001
JJ             3-digit-Julian-day (between 1 and 366)          such as 199
HH             2-digit-hour in 24 hr format                    such as 14
MM             2-digit minute                                  such as 40
SS             2-digit seconds                                 such as 30

Assuming the above example for the string value, a journal file mumps.mjl might be renamed to mumps.mjl_2001199144030.

If GT.M detects that the rename-logic yields a filename that already exists, the string "_N[N[N[N...]]]" is appended to the renamed filename where "N[N[N...]]" denotes the sequence of numbers

0,1,2,3,4,5,6,7,8,9,90,91,92,93,94,95,96,97,98,99,990,991,...

Numbers from the above sequence are tried in that order until a non-existing rename-filename string is found.

Taking the same example as above, in case mumps.mjl_2001199144030 and mumps.mjl_2001119144030_0 already exists, the rename string would be mumps.mjl_2001199144030_1.

If the existing file renaming scheme or the default journal file naming scheme discussed above results in a filename longer than 255 characters (due to the suffix creation rules), GT.M issues an error and turns off journaling (and replication, if it is active).

For journal recovery purposes, a field is maintained in every journal file’s header that stores the name of the previous generation journal file for the same database file. When a MUPIP SET changes the journal state from DISABLED or OFF to ON, GT.M creates new journal files with no previous generation journal file name. This indicates that this is a fresh start of journaling for the particular database. When journaling is already ON, and GT.M is implicitly (due to AUTOSWITCHLIMIT being reached) or explicitly (due to MUPIP SET JOURNAL) required to create new journal files, GT.M maintains the previous generation journal filename (after any appropriate rename), in the new journal file’s header.

In all cases where journaling is ON both before and after a journal file switch, the previous generation journal file name is maintained in the new journal file's header excepting the following cases, where it is cleared:

The previous generation journal filename is a back link from the current generation journal.

If a FILENAME is explicitly specified in a MUPIP SET /JOURNAL command and the specified FILENAME coincides with an already existing file that is not the currently active journal file for the database specified and the database has journaling currently ENABLED and turned ON, then GT.M returns an error status and makes no change to the journaling state of the database. This is done in order to avoid possible cycles in the back-links (such as, a3.mjl has a back-link to a2.mjl which in turn has a back-link to a1.mjl which in turn has a back-link to a3.mjl thereby creating a cycle). Cycles could prevent journal recovery. Also note that cycles in back-links are possible only due to explicit FILENAME specifications and never due to picking up existing FILENAME characteristics from the database or by using the default FILENAME.

Specification of SYNC_IO causes every WRITE to a journal file to be committed directly to disk. On high-end disk subsystems (for example, those that include non-volatile cache and that consider the data to be committed when it reaches this cache), this might result in better performance than the NOSYNC_IO option.