Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic

File Mode Relationships

The file modes within c-tree break down into three categories: default, permanent, and temporary.

Default File Modes

If no file mode is specified, the default file modes are used. The default file modes are listed below:

  • ctFIXED

If ctSHARED is not specified, the file mode includes ctEXCLUSIVE by default. If ctPERMANENT is not specified, the file mode includes ctVIRTUAL by default. If ctVLENGTH is not specified, the file mode includes ctFIXED by default.

Permanent File Modes

This category of file modes is set at file creation time. The permanent file modes are listed below:

  • ctFIXED or ctVLENGTH
  • ctPREIMG or ctTRNLOG
  • ctLOGIDX

Any of these file modes used when the file is created are attached to the file. Subsequent opens do not need to include these file mode attributes.

The file must be completely recreated to add or remove ctVLENGTH or ctSUPERFILE modes. If you subsequently desire to enable resources, they can be permanently added by EnableCtResource(). UpdateFileMode() can modify the other permanent file modes.

The last three file modes, ctWRITETHRU, ctCHECKLOCK, and ctCHECKREAD, can be added at file open time as temporary modes if they are not already present as permanent modes. This means the feature will be available while the file is opened. Once the file is closed, the feature is not available, unless the file mode is present the next time the file is opened.

Temporary File Modes

The rest of the file modes available in c-tree can be dynamically changed when the file is opened. Ordinarily, it is best to have the data file and its associated indices opened with the same file modes, except for ctVLENGTH, which does not apply to indices.

Read-only and Shared File Modes

c-tree’s interpretation of “opening a file in read-only” mode (ctREADFIL) needs some clarification. When a file is opened with ctREADFIL mode, c-tree enforces the fact that “all-users” (who have this file opened) must be in “read-only” mode, and will not allow the file to be opened if anyone else has it opened for writes or updates. In addition, once you have the file opened with ctREADFIL, no one else can open this file unless they use ctREADFIL. This gives you a way to ensure that no data changes will occur to the file while you have it opened in ctREADFIL mode.

This definition sometimes causes confusion for users who what to open the file “read-only” for themselves, say a query program, yet want to allow other programs to continue updating the file. In order to accommodate this situation, support was added in c-tree V7.12 for (ctREADFIL | ctSHARED). Opening a file with both the ctREADFIL mode OR-ed with the ctSHARED mode will protect the opening application from writes (i.e., enforce read-only), while allowing other programs alternate access privileges.

Therefore c-tree supports both modes:

  • ctREADFIL: restrict all user access to “read-only” ensuring that no one else can modify the file from underneath you.
  • ctREADFIL | ctSHARED: enforce read-only for your specific application while allowing others full access.

An attempt to update data or resources to a file opened in ctREADFIL mode will result in a SWRT_ERR (458).

Note: This only applies to client/server and bound server applications. For standalone models, if both ctREADFIL and ctSHARED are turned on, then the ctSHARED is ignored.

Insert Only - prevent updates and deletes

A new file mode (ctInsertOnly) has been introduced to prevent updates and deletes to data files. This mode also prevents all changes using the low-level WRTREC/WRTVREC. To enable this mode at create time, include the ctInsertOnly bit in XCREBLK.splval passed to CreateIfilXtd8().

PUTHDR() has been extended to support the new mode: ctInsertOnlyhdr.

To enable this mode on existing files, call PUTHDR(datno, YES, ctInsertOnlyhdr). To disable on existing files, call PUTHDR(datno, NO, ctInsertOnlyhdr).

This requires exclusive access to the file.

An ADMIN (or other user) must call PUTHDR to disable ctInsertOnly mode to be able to update the file.

PUTHDR calls for ctInsertOnly can be replicated.