ctFILBLK

ctFILBLK() allows a user to block access to a file.

Declaration

The file block routine is declared as follows:

NINT  ctFILBLK(pTEXT filename,LONG action);

Description

ctFILBLK() permits a file to be blocked and unblocked by name.

filename is the name of the file to be blocked.
action is the ctFILBLK() mode desired for this file.

A user must have ADMIN permission to call this function. This routine permits an ADMIN group user to interrupt the file connection between users and the file. This allows, for example, an administrator to block access to a data file, open and update the file in exclusive mode, close the file, remove the file while the c-tree Server continues operating, replace the file with an alternate data file, and finally unblock the file and re-establish the user file connections.

Configuration keyword COMPATIBILITY NONADMIN_FILBLK removes the ADMIN requirement.

Blocking Files

To block a file, the action parameter is comprised of a number of bit fields OR-ed together. Exactly one from each group below must be selected:

Select this option.

Action Parameter	Action Taken
ctFBblock	Block the file.

Select ONE of the following two options.

Action Parameter	Action Taken
ctFBisam	block data and associated index files.
ctFBlowl	block only the particular file named.

Select ONE of the following two options.

Action Parameter

Action Taken

ctFBautopen

Returns FBLK_ERR (798) while the block is active, and automatically reopens the file when the block is removed. The first access after the block is removed succeeds.*

ctFBappopen

Returns FBLK_ERR (798) while the block is active, and returns FBLK_RDO (799) when the file is available.

The application must issue a close and then reopen the file to continue using the file.

*ctFBautopen -- The return when the file is unblocked is as if the file had not been shutdown by the server. No information about the client’s file state is maintained upon reopen: no current ISAM position or sequence sets or batches or data filters or file ranges or locks are maintained. Also, if a client has a file open and has updated that file in a transaction and has not yet committed the transaction, then if an administrator blocks that file, that client's transaction is aborted.

Unblocking Files

If the original blocker quits without unblocking the file(s), then the file(s) will unblocked by default.

Optionally, additional action parameters can be specified to modify this behavior:

The original blocking user to disconnect (quit) without resulting in the block to be cleared.
A different user to unblock file.

Action Parameter

Action Taken

ctFBpersist

Block persists after blocker quits.

ctFBdifuser

Allow a different user to unblock the file if the original blocker quits.

If the original blocker quits without unblocking the file(s), then the file(s) will not be accessible to any other user until the blocked is cleared.

To unblock the file, call ctFILBLK() using the same file name and action set to ctFBunblock.

Action Parameter	Action Taken
ctFBunblock	Unblock a file.

In the event a file block occurs when a thread connected to the file is in the middle of a transaction that has updated the file, then the transaction is aborted before the block is placed.

Some general comments on the ctFILBLK() routine:

An attempt to block FAIRCOM.FCS or the SYSLOG files results in a SWRT_ERR (458).
An FBLK_SUP (802) error is returned on an attempt to block a SUPERFILE member. The entire SUPERFILE must be blocked, not just an individual member.
ADMIN may always unblock files, except if that specific ADMIN instance had the file open when it was blocked.
Only the original blocker may open the file while it is blocked.

Returns

ctFILBLK() returns the following return codes:

Value	Symbolic Constant	Explanation
458	SWRT_ERR	Write permission not granted.
798	FBLK_ERR	File is blocked, retry later.
799	FBLK_RDO	File block cleared: close/reopen file to gain access.
800	FBLK_PND	Attempting to set file block.
802	FBLK_SUP	file block not supported for file type

Please see Appendix A of the Programmer’s Reference Guide for a complete list of c-tree errors.

The following pseudocode provides an example of using ctFILBLK().

Example


#include <ctreep.h>


NINT rc = 0;

char[255] filename;

strncpy(filename, “mydata.dat”, 10);


/* Initialize c-tree Plus */

rc = (InitISAMXtd(16, 16, 16, 16, 0, "ADMIN", "ADMIN", "FAIRCOMS"))

if (rc)

    printf(“ctree Plus failed to initialize with error %d”, rc);


/* block the data file mydata.dat and associated indices */

rc = ctFILBLK(filename, ctFBblock | ctFBisam | ctFBautopen);

if (rc)

    printf(“ctFILBLK failed to block file %s with error %d”, filename, rc);


/* Any attempts by other clients to access mydata.dat will fail with FBLK_ERR from here */


/* Swap out the file with a new version */

system(“mv mydata.dat mydata.backup”);

system(“mv newdat.dat mydata.dat”);


/* unblock mydata.dat and associated indices */

rc = ctFILBLK(filename, ctFBunblock);

if (rc)

    printf(“ctFILBLK failed to unblock file %s with error %d”, filename, rc);


/* mydata.dat and associated indices are again available */

CloseISAM();


exit(0);