FairCom ISAM for C

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.

Note: ctFILBLK does not block access to a file if KEEPOPEN_LIST is in use. Calling CloseCtFileByName will close the file and it will remain closed until unblocked by a subsequent ctFILBLK call.

ADMIN Access

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. The file must also be opened by the blocking caller, and the blocking caller must have write permissions on 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 FairCom DB continues operating, replace the file with an alternate data file, and finally unblock the file and re-establish the user file connections.

Note: The FairCom Server configuration keyword COMPATIBILITY NONADMIN_FILBLK removes the ADMIN requirement. A non-ADMIN user can set a file block if:

  1) This keyword is set.
  and
  2) They have the file opened with update permissions.

If either of these conditions is not met, a LADM_ERR (589) error will be returned.

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. Can be used if you handle your files ONLY with the ISAM API. This mode requires the file to contain the IFIL structure because it is used to determine which index files needs to be blocked.
ctFBlowl	Block only the particular file named. Can be used if all clients on the FairCom Server handle the files ONLY with the Low-Level API. Do not use this parameter if any client on the FairCom Server handles the files with the ISAM API. ISAM access may return FMOD_ERR (48) or LISM_ERR (963). If you have a Low-Level application blocking the file with ctFBlowl but the file is already open by an ISAM application you will get error 48, so you need to make sure that you are using ONLY the Low-Level API.

Action Parameter

Action Taken

ctFBisam

Block data and associated index files. Can be used if you handle your files ONLY with the ISAM API.

This mode requires the file to contain the IFIL structure because it is used to determine which index files needs to be blocked.

ctFBlowl

Block only the particular file named. Can be used if all clients on the FairCom Server handle the files ONLY with the Low-Level API.

Do not use this parameter if any client on the FairCom Server handles the files with the ISAM API. ISAM access may return FMOD_ERR (48) or LISM_ERR (963).

If you have a Low-Level application blocking the file with ctFBlowl but the file is already open by an ISAM application you will get error 48, so you need to make sure that you are using ONLY the Low-Level API.

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.

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 shut down 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.

Note: FairCom does not guarantee preserving the state of a transaction, locks, ISAM context when a file is blocked and then unblocked, even if using the auto open option. Because ISAM context information is lost when the file is blocked, an error 590 may be returned after the file has been blocked and unblocked using ctFBautopen or when using ctfilblkif utility, which uses this mode.

Note: If you must delete a data file while it is in a blocked state, the file will need to be opened in exclusive mode before a c-tree delete operation (such as DELRFIL()) will succeed. Even though a data file might be in a blocked state, the process holding the block on the file is allowed to perform an exclusive file open.

Unblocking Files

If the original blocker quits without unblocking the file(s), then the file(s) will be 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.

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
2	KDUP_ERR	Duplicate Key Error. The key value already exists in the index.
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.
48	FMOD_ERR	Operation incompatible with type of file. The specifics vary by function: The specified keyno is not an index file number. The file is not a data file or it does not contain an IFIL resource (ctFILBLK in ctFBisam mode). One or more associated file (data and index files) is not TRANDEP (using RENIFIL / RENIFILX).
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
963	LISM_ERR	An attempt to close an ISAM data file with the low-level file close routine CLSFIL. COMPATIBILITY CLSFIL_ISAM restores the old behavior when CLSFIL is called for an ISAM data file. For standalone applications the CLSFIL behavior can be restored by compiling the code with NO_ctBEHAV_CLSFIL_ISAM.

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

Example

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

#include <ctreep.h>

NINT rc = 0;

char[255] filename;

strncpy(filename, "mydata.dat", 10);

/* Initialize FairCom DB */

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

if (rc)

printf("ctree failed to initialize with error %d", rc);

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

/* NOTE: this example uses the ADMIN user, so the caller does not need to

** open the file before calling ctFILBLK. */

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 indexes */

rc = ctFILBLK(filename, ctFBunblock);

if (rc)

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

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

CloseISAM();

exit(0);