|
|
|
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.
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 |
CTDBRET_OK |
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).
|
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);
}
See also
ctFILBLK()
