Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic

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

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).

  • 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);

}

See also

ctFILBLK()

TOCIndex