FairCom ISAM for C

ctFILBLKX

Immediately block access to a file upon specified conditions.

Declaration

NINT ctFILBLKX (ctFILE_BLOCK_XTD_OPTIONS *pctFileBlockXtdOptions);

typedef struct ctFileBlockXtdOptions_t {

UCOUNT structVersion; /* [IN] version of this structure */

UCOUNT tranTimeoutSec; /* [IN] optional transaction timeout in seconds */

ULONG action; /* [IN] file block action bits */

cpTEXT fileName; /* [IN] name of file to block or unblock */

} ctFILE_BLOCK_XTD_OPTIONS;

Description

The file block function (ctFILBLK()) immediately blocks a file. New in V13 is file block support that gives pending transactions time to complete before the file is blocked. In order to support this feature, we introduced an extended version of the file block function that supports specifying a transaction timeout in seconds. When a non-zero transaction timeout is specified, the server optionally blocks new transactions and then waits for all active transactions to complete for those connections that have the file to be blocked open, then unblocks new transactions once the startup phase of the file block has been set up.

To set a transaction timeout, set the tranTimeoutSec field of the ctFILE_BLOCK_XTD_OPTIONS structure to a non-zero timeout value in seconds. A tranTimeoutSec value of zero indicates no transaction timeout.

To block new transactions at the start of the file block, OR in the ctFBblockNewTransactions mode bit to the action field of the ctFILE_BLOCK_XTD_OPTIONS structure.

We updated the ctfilblkif utility with option -t (trantimeoutSec) and option -n to block new transactions at the start of the file block. For example, the following command will block new transactions and allow active transactions 3 seconds to complete before blocking the mark.dat file:

ctfilblkif -f mark.dat -n -t 3

Return Values

Value	Symbolic Constant	Explanation
0	CTDBRET_OK	Successful operation.

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

Example

This example shows blocking a file with a 10 second transaction timeout and blocking new transaction until the file block startup has completed:

ctFILE_BLOCK_XTD_OPTIONS fileBlockXtdOptions = { 0 };

NINT ret;

fileBlockXtdOptions.structVersion = ctFILE_BLOCK_XTD_OPTIONS_VERS_V01;

fileBlockXtdOptions.fileName = "myfile.dat";

fileBlockXtdOptions.action = ctFBblock | ctFBisam | ctFBblockNewTransactions;

fileBlockXtdOptions.tranTimeoutSec = 10;

ret = ctFILBLKX(&fileBlockXtdOptions);