FairCom ISAM for C

InitCTreeXtd

Initialize file structures and index buffer area (extended version).

Short Name

INTREEX()

Type

Extended Low-Level file function

Declaration

COUNT InitCTreeXtd(COUNT bufs, FILNO fils, COUNT sect,

COUNT dbufs, COUNT userprof, pTEXT userid,

pTEXT userword, pTEXT servname)

Description

In V12 the file number typedef was formally changed from COUNT, a two-byte value to FILNO, a four-byte value. Refer to this link for compatibility details. Four Byte File Numbering

InitCTreeXtd() is a variation of InitCTree() that permits the use of the FairCom Server’s security system. This section expands on the description of InitCTree().

bufs and dbufs specify the number of buffers for index and data file I/O respectively. Usually bufs and dbufs have the same value. In a program using index file manipulations with very little data file work, make dbufs smaller to save buffer space. In a Server environment bufs, dbufs, and sect are ignored. They are set by the Server configuration. fils is limited by the FILES setting in the Server’s ctsrvr.cfg.

userprof is the user profile mask. It accepts the following values:

USERPRF_CLRCHK - instructs single-user TRANPROC applications to remove S*.FCS and L*.FCS files upon a successful application shutdown. The c-tree checkpoint code determines at the time of a final checkpoint if there are no pending transactions or file opens, and if this user profile bit has been turned on. If so, the S*.FCS and L*.FCS files are deleted. However, if the application is causing log files to be saved (very unusual for a single-user application), then the files are not cleared. The USERPRF_CLRCHK option is off by default. See Single-User Transaction Processing in the c-tree Programmer’s Reference Guide for additional information.

USERPRF_LOCLIB - specifies this instance of c-tree is to be directed to a local database. Applicable only to client/server when using “Local Library Support”.

USERPRF_NDATA - enable the manual mode of UNIFRMAT support. Enabling the manual record transformation mode would only be desirable if you are performing your own record level byte flipping or your record structures contain no numeric data (i.e., LONG, FLOAT, . . .). A side benefit of enabling this manual mode is the virtual elimination of Server DODA requests, thereby reducing network traffic by one function call per file open.

USERPRF_NTKEY - disables the automatic TransformKey() feature. See the TransformKey() function description for more information.

USERPRF_PTHTMP - changes GetCtTempFileName() from its default operation of returning a temporary file name to specifying a directory name where temporary files are to reside.

USERPRF_SAVENV - enable the automatic ctSAVENV feature. See the Begin() function description for more information.

To use more than one value, OR the values together. Leave userprof set to zero to accept the defaults.

userid is a pointer to a buffer containing the user ID. If userid is null, the user is assigned the ID of GUEST

userword is a pointer to a buffer containing the user password.

servname is a pointer to a Server name if you are going to use a Server name other than the default.

For more information on user ID’s, user passwords, and server names, review ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) and Client-Side Operation in the c-tree Programmer’s Reference Guide.

Return

The following error codes may be seen in addition to those for InitCTree():

Value	Symbolic Constant	Explanation
450	LUID_ERR	Invalid user ID.
451	LPWD_ERR	Invalid user password.
453	NSRV_ERR	Invalid Server name.

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