FairCom ISAM for C

QuietCtree

Temporarily suspends operation of the FairCom Server for specific files/actions.

Declaration

NINT QuietCtree( pTEXT filespec, LONG timeoutSEC, LONG action )

Short Name

ctQUIET()

Description

Overview

A connection can call ctQuiet() to start quiescing the database. It can set action code options to block some or all activities, such as new file opens, new logins, new transactions, and all APIs except ctQuiet(). It can call this function multiple times to unblock some or all of the previously blocked activities, such as allow new logins but not new transactions.

The typical flow is to call ctQuiet() to block all new activity. When ctQuiet() returns, the app calls it again to flush all files. When ctQuiet() returns, the app performs some action like taking a snapshot of all the files for a backup. Then lastly, the app calls ctQuiet() again to unblock everything, which returns the database back to normal.

ctQuiet() supports various types of actions related to pausing system activity. This allows, for example, a clean filesystem level copy of data and index files. External hardware snapshots are also possible when available. Placing the files in a "closed" and "clean" (that is, flushed) state allows quick recovery from these backups. Unflushed files can also be copied, and if the transaction logs are included, a server can bring the files to a current consistent state during automatic recovery.

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.

When connecting to a quieted server with the intent to remove the quiet state when the original caller of ctQuiet() has disconnected, you must set the InitISAMXtd() user profile mask (userprof parameter) to USERPRF_ADMSPCL. Here is an example:

INTISAMX(bufs, file, 0,128,0,0,USERPRF_ADMSPCL,admnuser,admnword,srv_name)

Note the command-line utility ctquiet (ctquiet - Quiesce FairCom DB Utility, ctquiet Utility) sets the user profile mask (userprof parameter) to USERPRF_ADMSPCL when the -x switch is used, so this is another method for waking up the server when the quiescing client has been abandoned.

QuietCtree() returns NSUP_ERR (454) on those servers where this feature is not enabled.

filespec is currently ignored (file-specific quiet operations are not currently supported).
timeoutSEC specifies the time in seconds to wait before aborting transactions prior to blocking.
action is either a block or unblock code from the following tables:

Block Action Codes

Symbolic Code	Value	Description
ctQTblockAllFiles	0x000002	block all files, ignore filespec
ctQTblockLogons	0x000010	block new logons
ctQTblockTransactions	0x000020	block new transactions
ctQTblockLogFiles	0x000100	block server log files (requires ctQTnoActiveTran and ctQTblockTransactions, and blocked access to the log files will sleep regardless if ctQTblockError is specified.)
ctQTblockAPI	0x004000	block all API's except QuietCtree( ctQTunblockAPI )

Unblock Action codes

ctQTunblockFiles	0x000800	permit file access
ctQTunblockTransactions	0x000200	permit new transactions
ctQTunblockLogons	0x000400	permit new logons
ctQTunblockAPI	0x008000	unblock all API's

Other options can be passed into ctQUIET() for additional control. These values are OR-ed into the action parameter.

ctQUIET() Options

Symbolic Code	Value	Description
ctQTblockError	0x000040	return error on block instead of sleeping
ctQTnoActiveTran	0x000080	ensure no transactions are pending at the time the actions specified by the above blocking options are taken - any pending transaction are aborted
ctQTflushTranFiles	0x020000	flush before file block
ctQTflushNonTranFiles	0x040000	flush before file block
ctQTfailAfterTimeout	0x01000000	abandon the ctQUIET() call if transactions are still active after timeout period - see Timeout Notes below
ctQTwaitForReplReaders	0x02000000	(Supported in V11.5 and later) Wait for all replication readers that have registered with the server to finish processing all committed transactions. If the ctQTfailAfterTimeout option has been included, the specified timeout will apply to this option, too.
ctQTignoreInactiveReplReaders	0x04000000	(Supported in V11.5 and later) When used with ctQTwaitForReplReaders, this allows the ctQUIET() call to ignore replication readers that are not connected to the server or that have not set a log position.

The following actions and options are combinations of the above actions for convenience.

Symbolic Code	Value
ctQTblockALL	(ctQTblockAllFiles \| ctQTblockLogFiles \| ctQTblockAPI)
ctQTflushAllFiles	(ctQTflushTranFiles \| ctQTflushNonTranFiles)
ctQTunblockALL	(ctQTunblockTransactions \| ctQTunblockLogons \| ctQTunblockFiles \| ctQTunblockLogFiles \| ctQTunblockAPI)

The action codes for ctQUIET() are defined in ctport.h.

Note: Except for ctQTblockLogFiles, all references to files imply c-tree data and/or index files.

When the blocks are set, callers that hit the blocks sleep until the block is released and then continue with their API request, except when the caller’s transaction was aborted by QuietCtree(). If the transaction was aborted, then when the caller's block is released, the current API request returns with a QTAB_ERR (817). If the transaction was aborted but the caller has not made an API call since the transaction was aborted, then the next API call will return immediately with the QTAB_ERR. QTAB_ERR is returned to alert the caller that its current transaction has been aborted. Transactions are aborted by QuietCtree() only if ctQTnoActiveTran is part of the QuietCtree() request.

QuietCtree() is designed to permit multiple calls to achieve the desired results. When the final blocking attribute is removed by a call to QuietCtree(), QuietCtree() is completed which gives ups its interlocks on other QuietCtree()/ctFILBLK() calls and dynamic dumps.

A call to ctQUIET() with mode ctQTblockALL | ctQTflushAllFiles can be used to suspend all activity within FairCom DB and flush all files so that they have all updates written to disk and the update flag in the header of the files is reset, so that they can then be copied by an external process. However, this option forces a "no active transaction" state. This means that any transactions that are active when ctQUIET() is called are aborted.

A call to ctQUIET() with mode ctQTblockAPI can be used to suspend all activity on the FairCom Server while files remain open, potentially having updated data and index cache pages that have not been written to disk. In this mode, active transactions are simply suspended and they are resumed when ctQUIET() is called with mode ctQTunblockAPI. If you use this ctQUIET() mode and then copy the data and index files and the active transaction log files, you can then run automatic recovery on the files and you will have a point in time consistent copy of the file (where the point of time is the time the ctQUIET() successfully blocked all API calls: transactions that are pending as of that time are not included in the files).

Note: QuietCtree() cannot be called with a mix of ctQTblock and ctQTunblock action codes.

Quiet vs. Blocking

There is a subtle distinction between QuietCtree() and ctFILBLK(). QuietCtree() does not "physically" close files. This has particular implications on the Windows filesystem, as files are not allowed to be removed in this case as there is an open OS file handle still maintained. Compare to ctFILBLK() where files can be deleted or otherwise replaced while in the blocked state as the OS file handle may be released. Unix systems do not impose this restriction on files, thus, care should be taken in these environments to not replace or otherwise delete a file while in a Quiet state. Always use the file block API to physically replace a file.

Timeout Notes

The quiesce mode can be set to abandon the ctQUIET() call if transactions are still active after timeout period.

The ctQUIET() option ctQTnoActiveTran causes ctQUIET() to wait for the specified timeout interval for all active transactions to complete. As soon as all active transactions have completed, ctQUIET() continues putting the server into a quiesced state. But if any transactions remain active after the specified timeout interval, c-tree Server terminates those transactions.

The ctQTfailAfterTimeout mode changes this behavior so that when the specified timeout interval has passed the ctQUIET() call fails if any transactions remain active. To use this option, OR in the ctQTfailAfterTimeout mode to the action parameter that you pass to ctQUIET(). When ctQUIET() fails because this option is used and transactions remain active after the timeout period, it returns error code QTFA_ERR (1031).

It is possible for ctQUIET() to get into an abandoned state if the calling application (or c-tree utility ctquiet or ctadmn option 8) are terminated before c-tree is taken out of the quiesce state. When in an abandoned state any new client connections that are attempted will receive the QABN_ERR (error 898). Any existing connections that were waiting before the abandoned state occurs will continue to wait.

Example:

NINT rc;

if (!(rc = ctQUIET(NULL, 2, ctQTblockALL | ctQTflushAllFiles | ctQTfailAfterTimeout))) {

printf(""Successfully quiesced server.\n"");

} else {

printf(""Error: Failed to quiesce server: %d\n"", rc);

}

Return Values

Value	Symbolic Constant	Explanation
0	NO_ERROR	Successful operation.
816	QTUQ_ERR	Only one QuietCtree() process at a time.
817	QTAB_ERR	Transaction aborted by QuietCtree().
818	QTFB_ERR	QuietCtree() / ctFILBLK() conflict.
820	QTBK_PND	trying to get QUIET. leave core. ctQUIET() found a connection already in the c-tree core and it's forcing it to exit the core.
825	QTOP_ERR	QuietCtree() called with files opened.
826	QBAD_ERR	Improper QuietCtree() action: see sysiocod for details
440	DDDM_ERR	Dynamic Dump already in progress.
70	TEXS_ERR	Transaction already pending.
101	INOT_ERR	Could not satisfy and ISAM search request for index isam_fil. This error frequently indicates "End of File" reached, or "Record not Found." The following items are the probable causes of the INOT_ERR (101). Passing GetRecord() a duplicate allowed index number (keyno). GetRecord() does not support duplicate allowed indices. Improper target padding. Review “Key Segment Modes” in the c-tree Plus Programmer’s Guide. Not calling TransformKey() on target. Refer to “TransformKey” in the Function Reference Guide Passing ctDeleteSequence() a sequence name that does not exist Improper segment mode. Review “Key Segment Modes” in the c-tree Plus Programmer’s Guide. ctFILBLK() is called and the file is already blocked.
454	NSUP_ERR	Operation or service not supported. Using an option unavailable to this library.

Possible sysiocod Returns

Value	Symbolic Constant	Explanation

1	QBKU_COD	block and unblock actions mixed
2	QBUN_COD	cannot block after unblock has begun
3	QMBK_COD	mixed file block types
4	QSPC_COD	missing filespec
5	QMAP_COD	mixed API block types
6	QBAP_COD	blockAllFiles requires blockAPI
7	QBFA_COD	cannotBlockAllFiles after blockFiles
8	QFAP_COD	file flush requires blockAPI
9	QLAP_COD	blockLogFiles requires blockAPI

See c-tree Error Codes for a complete listing of valid c-tree error values.

Example

NINT quiesce()

{

if (!QuietCtree( NULL, 1000, ctQTblockALL | ctQTflushAllFiles )) {

printf("Successful Quiesce.\n\n");

printf("It is now safe to perform sytem administrator duties.\n");

printf("Press RETURN once the backup is completed to resume the c-tree Server\n");

getchar();

if (rc = ctQUIET( NULL, 1000, ctQTunblockALL )) {

printf("Could not resume. Error: %d\n", rc);

}

} else {

printf("Could not quiesce\n");

}

return(0);

}