Initialize file structures and index buffer area (extended version).
Extended ISAM function
COUNT InitISAMXtd(COUNT bufs, FILNO fils, COUNT sect,
COUNT dbufs, COUNT userprof, pTEXT userid,
pTEXT userword, pTEXT servname)
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
InitISAMXtd() is a variation of InitISAM() that permits the use of the FairCom Server’s security system. This section expands on the description of InitISAM().
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 configuration file.
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.
USERPRF_X509 - If this bit is set then the caller is expected to provide a null terminated string containing a trusted certificate in PEM format in the userword argument and the userid is ignored. It is up to the caller to ensure the certificate is trusted which can be done by the TLS handshake. Presenting an untrusted or compromised certificate could allow unknown users to login with admin privileges. The server must be configured to allow x509 Authentication. See x509_AUTHENTICATION with the x509_PATH server keyword.
In database models besides server dll the USERPRF_X509 profile bit has no effect.
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.
The following error codes may be seen in addition to those for InitISAM():
Invalid user ID.
Invalid user password.
Invalid Server name.
See c-tree Error Codes for a complete listing of valid c-tree error values.
InitISAM(), OpenISAM(), CloseISAM(), TransformKey(), GetCtTempFileName(), Begin()