FairCom ISAM for C

ctquiet - Quiesce FairCom DB Utility

The ctquiet utility allows an administrator to quiet the server from a script. An interactive option is available in the ctadmn utility.

Operational Model:

• Client

Usage:

ctquiet [-c] [-f] [-i] [-m] {-p password|-a authfile} [-r] [-s server] [-t timeout] [-u] [-x] [-w]

Parameters:

• -a: Authentication file name
• -c: Wait for replication readers to finish processing
• -f: Full consistency (default: crash consistency)
• -i: Ignore inactive replication readers (used with -c option)
• -m: Quiesces the server, changes the specified configuration options, and resumes normal server activity. Allows changing server configuration options that require the server to be quiesced, avoiding additional calls to the Server. Can be specified one or more times in a call to ctquiet.
• -p: Admin Password
• -r: Create an incremental backup restore point. Automatically unquiets server
• -s: Server (default: FAIRCOMS@localhost)
• -t: Set transaction timeout in seconds. (maximum/default: 60 seconds).
• -u: Unquiet server
• -x: Abandon Quiet request if timeout exceeded. (Default: Abort long transactions.) Applies ctQTfailAfterTimeout mode. This mode has been extended to apply to restore point checkpoint creation for incremental forward rolls.
• -w - (Linux only) Execute command on successful quiet. Waits for SIGINT to unquiet server.

Note: The -c option requires ALL client utilities, replication readers, and servers to be installed from FairCom DB V11.3 or later. It is not compatible as a drop-in to current running environments.

Support for Incremental Backup Restore Points

Several changes have been made to ctquiet to support restore points necessary to carry out an incremental backup strategy:

• The -r feature can be used to generate the restore point files necessary to carry out an incremental backup strategy.
• The ctQTfailAfterTimeout mode has been extended to apply to restore point checkpoint creation for incremental forward rolls.
• The -x option applies the ctQTfailAfterTimeout mode to the already existing options.
• The -t timeout output has an effect only if -f or -r is specified.
• The default timeout has been changed to match the server's maximum.

Authentication File

This utility supports the use of an encrypted password file. Encrypted password files keep user IDs and passwords from plain view when the utility is used within a script file. They are created with the ctcmdset utility. The plain text form of the file should be:

; User Id
USERID ADMIN
; User Password
PASSWD <pass>

Use the -1 option to specify the name of the encrypted file. Use the -a option to specify the name of the encrypted file.

Full Consistency

Note: This utility provides a -f option, which enables full consistency (also known as a "clean quiesce") in which files are flushed to disk from cache. When this option is used, the system does not require any files to be rebuilt or recovery from transaction logs to occur.

The default is the -f option is off, which results in "crash consistency" (also known as a "dirty quiesce"). The default means that transaction logs are required and, if present, the transaction logs are used to get back into a clean state once recovery completes.

If files are NOT under transaction control, the -f option is strongly recommended, otherwise you will have to do a rebuild to get the files back to a clean state.

Physical Copy of Files

A quiesced state allows a physical copy of files to be taken that can then be restored at a later time. For systems that provide hardware-based snapshot features, this allows extremely fast system backups to take place while maintaining full data integrity.

The -r option creates an incremental backup restore point. After the ctquiet call succeeds, this new restore point and all server transaction logs can be copied to a backup area and used for an incremental recovery.

Timeout

The -f and -r options require that no transactions are active for the quiet to complete. The quiet operation defaults to waiting 60 seconds for the outstanding transaction to complete before aborting these transactions. Operations by other users and connections wait during this time.

The -t and -x options modify the timeout behavior:

• -t - Allows setting a shorter timeout. Times longer than 60 seconds are reduced to 60 seconds.
• -x - Instead of aborting the transactions, the quiet operation will fail if the timeout expires without all transactions completing.

Example 1:

You want to create a server backup for your application that is not using transaction logging on all the files you want to backup. Only allow 10 seconds before aborting outstanding transactions.

ctquiet -f -t 10 -s FAIRCOMS -p <admin password>

Make your backup and then end the quiet:

ctquiet -u -s FAIRCOMS -p <admin password>

Example 2:

You want to create a fast server backup, and all your files are using transaction logging. Your backup will need to go through recovery before being used.

ctquiet -s FAIRCOMS -p <admin password>

Make your backup and then end the quiet:

ctquiet -u -s FAIRCOMS -p <admin password>

Example 3:

You want to create a restore point for an incremental backup and only allow a brief (1 second) delay. You don't want ctquiet to abort any long running transactions.

ctquiet -r -t 1 -x -s FAIRCOMS -p <admin password>

Notes

• When you quiesce the server, as long as the connection that quiesced the server remains connected, all other connections are blocked. Only if that connection goes away do we allow the ADMIN user to logon again and undo the quiesce.
• After the server is quiet and the ctquiet utility disconnects, one ADMIN connection is allowed to reconnect. There is no prevention of a separate process connecting as ADMIN while the server is in a quiet state and precluding the unquiet call.
• There is a subtle distinction between a "quiet" state and a file blocked with the ctFILBLK() call. While in the quiet state, files are not physically closed and cannot be moved or replaced while in this mode. Compare this to a "blocked" state, where the file can be replaced, as the OS file handle has been released.
• When the optional -w COMMAND switch is used (unavailable on Windows), the behavior of ctquiet is modified to perform as follows:
  1. After successfully quieting the server, it makes a system call to execute COMMAND.
  2. It remains connected and waits for SIGINT to unquiet the server. If ctquiet is killed before receiving SIGINT, the server will remain in a quiet state until a new connection unquiets the server.