QuietCtree

Temporarily suspends operation of the c-tree Server for specific files/actions.

Declaration

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

Short Name

ctQUIET()

Description

QuietCtree() supports various types 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. By having 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.

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

filespec refers to the filename of the data or index file to be blocked.
timeoutMS specifies the time in milliseconds 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	at the time the actions specified by the above blocking options are taken ensure no transactions are pending. Any pending transaction are aborted.
ctQTflushTranFiles	0x020000	flush before file block
ctQTflushNonTranFiles	0x040000	flush before file block

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 c-treeACE 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 c-tree 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.

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.
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 4 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 Improper segment mode. Review “Key Segment Modes” in the c-tree Plus Programmer’s Guide.
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 Plus Error Codes for a complete listing of valid c-tree Plus 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);