Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic

Automatic restore point logging

FairCom Server supports a configuration option to automatically perform restore points. This option can be set in the configuration file using the SUBSYSTEM TRNLOG AUTO_RESTORE_POINT block. The supported sub-options are:

  • LOG_INTERVAL N, where is the number of logs between each automatic restore point. Specify 1 to write an automatic restore point to every log. Specify 0 to turn off automatic restore points. LOG_INTERVAL defaults to zero (no automatic restore points).
  • TIMEOUT T, where T is a time in seconds that the automatic restore point waits for active to transactions to commit. TIMEOUT defaults to 2 seconds.
  • FAIL_AFTER_TIMEOUT F, can be YES or NO: YES indicates that if transactions remain active after the restore point timeout period, the restore point call fails; NO indicates that if transactions remain active after the restore point period, those transactions are aborted and the restore point is logged. FAIL_AFTER_TIMEOUT defaults to NO.
  • CHECKPOINT C, where C is YES or NO. YES indicates that a checkpoint is to be logged with the restore point; NO indicates that no checkpoint is to be logged with the restore point. CHECKPOINT defaults to NO.

Example:

SUBSYSTEM TRNLOG AUTO_RESTORE_POINT {

; write an automatic restore point every 2 logs

LOG_INTERVAL 2

; wait for up to 3 seconds for transactions to finish

TIMEOUT 3

; fail if transactions remain active after timeout

FAIL_AFTER_TIMEOUT YES

; write a checkpoint

CHECKPOINT YES

}

Changing automatic restore point settings at runtime

Automatic restore point settings can be changed at runtime by using the ctSETCFG() API function. For example:

rc = ctSETCFG(setcfgCONFIG_OPTION, "subsystem trnlog auto_restore_point {\n\

log_interval 2\n\

timeout 3\n\

fail_after_checkpoint yes\n\

checkpoint yes\n}");

ctadmn use of ctSETCFG()

The ctadmn utility's "Change the specified configuration option" option uses this function, and it now detects when a SUBSYSTEM configuration option is specified. In that situation, it prompts for the SUBSYSTEM sub-options. Here is an example demonstrating how to use ctadmn to turn off automatic restore points at runtime:

10. Change Server Settings

10. Change the specified configuration option

Enter the configuration option and its value >> subsystem trnlog auto_restore_point {

Enter the SUBSYSTEM options you wish to change, one per line.

Finish with a line containing only a closing curly brace: }

To cancel, enter a line containing only an asterisk: *

Enter next line >> log_interval 0

Enter next line >> }

Successfully changed the configuration option.

If an error occurs when changing a SUBSYSTEM option using the ctSETCFG() function, the function returns an error code and may log a descriptive error message to CTSTATUS.FCS. Here is an example, showing a typo in which log_interval0 is specified instead of log_interval 0:

Enter the configuration option and its value >> subsystem trnlog auto_restore_point {

Enter the SUBSYSTEM options you wish to change, one per line.

Finish with a line containing only a closing curly brace: }

To cancel, enter a line containing only an asterisk: *

Enter next line >> log_interval0

Enter next line >> }

Error: Failed to change the configuration option: 749

The following error message will be logged to CTSTATUS.FCS:

Wed Jan 18 14:42:53 2017

- User# 00018 Configuration error: ctSETCFG(), line 2: The option LOG_INTERVAL0 is not supported in the TRNLOG AUTO_RESTORE_POINT subsystem block.

Monitoring automatic restore points

The system snapshot structure, ctGSMS, now includes fields for the automatic restore point settings. The system snapshot version has been updated from 19 to 20:

LONG sarplogint; /* auto restore point log interval */

LONG sarptimout; /* auto restore point tran timeout */

LONG sarplogint; /* auto restore point log interval */

LONG sarptimout; /* auto restore point tran timeout */

/* Auto restore point options bits (ctGSMS sarpoptions field): */

#define ctARP_FAIL_AFTER_TIMEOUT 0x00000001 /* fail if trans active after timeout */

#define ctARP_WRITE_CHECKPOINT 0x00000002 /* write a checkpoint */

A text snapshot now also includes the automatic restore point settings:

automatic restore point interval: 2

active transaction time limit: 3

fail if trans active after timeout: yes

write checkpoint: no

log of last automatic restore point: 81

The ctsnpr utility (included in FairCom DB PRO packages in the source directory) has been updated to support the latest version of the text snapshot output format.

TOCIndex