InitCTree

Initialize file structures and index buffer area.

Short Name

INTREE()

Type

Low-Level file function

Declaration

COUNT InitCTree(COUNT bufs, FILNO fils, COUNT sect) 

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

InitCTree() acquires the memory space necessary for the data and index file structures as well as the space for the index file buffers. Finally, it initializes this memory area. Call CloseISAM() or StopUser() to free these resources.

The InitCTree() parameters are defined as follows:

In a single user system, increasing bufs reduces the number of disk accesses necessary to retrieve a key value. The buffers are shared across all index files via a “least recently used” scheme.

In Standalone Multi-user systems, the need to force updates back to the disk implies that local buffering is of little value. Rather, the shared hard disk should be cached in order to achieve global buffering of the index file. In a Standalone Multi-user system, bufs should be set around three, regardless of the number of index files in use.

sect * 128 determines how many bytes are available in each B-Tree node. When an index file is created, the node size is permanent. When an index file is opened, a check is made to be sure that the current node size is at least as large as when the index was created. That is, an index file can be opened if sect has been increased since file was created, but not if it has been reduced. Superfiles must be opened with the exact node size as when they were created.

Originally, the most common value used for sect is four, yielding a node size of 512 bytes. For efficiency, set the sect value to create nodes equal to the page size for the platform. Most common would be 32, yielding a node size of 4K.

Return

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

Example

COUNT     retval;

if (retval = InitCTree(6,7,4))
    printf("\nCould not initialize c-tree: Error %d.", retval);
else {
    printf("\nc-tree initialized.");
    StopUser()
}

See also

CloseISAM(), StopUser(), CreateDataFile(), CreateIndexFile(), CreateIndexMember(),
InitCTreeXtd(), InitISAM()

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():

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

See also

InitCTree(), TransformKey(), GetCtTempFileName(), Begin(), OpenISAM(), CloseISAM()

InitISAM

Initialize file structures and index buffer area.

Short Name

INTISAM()

Type

ISAM function

Declaration

COUNT InitISAM(COUNT bufs, FILNO fils, COUNT sect) 

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

InitISAM() acquires the memory space necessary for the data and index file structures as well as the space for the index file buffers. Finally, it initializes this memory area, and prepares for incremental ISAM creates and opens.

Before any other ISAM functions can be used, InitISAM(), OpenISAM(), or CreateISAM() must be called. Further, these are mutually exclusive; only one of these routines can be called at a time. Once one of these has been called, you must call CloseISAM() before invoking one of these three functions again.

The InitISAM() parameters are defined as follows:

In a single user system, increasing bufs reduces the number of disk accesses necessary to retrieve a key value. The buffers are shared across all the index files via a “least recently used” scheme.

In Standalone Multi-user applications, the need to force updates back to the disk implies that local buffering is of little value. Rather, the shared hard disk should be cached in order to achieve global buffering of the index file. In a Standalone Multi-user application, bufs should be set around three, regardless of the number of index files in use.

sect * 128 determines how many bytes are available in each B‑Tree node. When an index file is created, the node size is fixed permanently. When an index file is opened, a check is made to be sure that the current node size is at least as large as when the index was created. That is, an index file can be opened if sect has been increased since file was created, but not if it has been reduced. Superfiles must be opened with the exact node size as when they were created.

Originally, the most common value used for sect is four, yielding a node size of 512 bytes. For efficiency, set the sect value to create nodes equal to the page size for the platform. Most common would be 32, yielding a node size of 4K.

Return

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

Example

COUNT     retval;

if (retval = InitISAM(6,7,4)) {
     printf("\nCould not initialize c-tree. Error #%d\n",
            retval);
     exit(2);
}

See also

OpenIFile(), CreateIFile(), OpenISAM(), CreateISAM(), InitISAMXtd(), CloseISAM()

InitISAMXtd

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

Short Name

INTISAMX()

Type

Extended ISAM function

Declaration

COUNT InitISAMXtd(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

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.

Return

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

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

See also

InitISAM(), OpenISAM(), CloseISAM(), TransformKey(), GetCtTempFileName(), Begin()

IOPERFORMANCE

Monitor Input/Output of data/index caching and count Low-Level file reads and writes.

Short Name

IOPERFORMANCE()

Type

Low-Level function

Declaration

LONG IOPERFORMANCE(pVOID bufptr)

Description

IOPERFORMANCE() monitors the data and index cache as well as the Low-Level file reads and writes. On return, bufptr points to a structure of 8 unsigned long values, defined as follows:

ULONG     ct_dbrqs;          /* data buffer requests       */
ULONG     ct_dbhit;          /* data buffer hits           */
ULONG     ct_ibrqs;          /* index buffer requests      */
ULONG     ct_ibhit;          /* index buffer hits          */
ULONG     ct_rdops;          /* number of read operations  */
ULONG     ct_rdbyt;          /* bytes read                 */
ULONG     ct_wrops;          /* number of write operations */
ULONG     ct_wrbyt;          /* bytes written              */

Note the element defines used in the example below.

Return

IOPERFORMANCE() always returns a 0 (zero) value indicating NO_ERROR. See c-tree Error Codes in the c-tree Programmer’s Reference Guide for a complete listing of valid c-tree error values.

Example

ULONG  ct[8]  /* array of 8 longs for performance value */

IOPERFORMANCE(ct)

printf("\n\n=================================================");
printf("\ndata buffer requests  = %ld",ct[DataBufferRequests]);
printf("\ndata buffer hits      = %ld",ct[DataBufferHits]);
printf("\nindex buffer requests = %ld",
                                      ct[IndexBufferRequests]);
printf("\nindex buffer hits     = %ld",ct[IndexBufferHits]);
printf("\n# of read operations  = %ld",ct[NbrReadOperations]);
printf("\nbytes read            = %ld",ct[NbrBytesRead]);
printf("\n# of write operations = %ld",ct[NbrWriteOperations]);
printf("\nbytes written         = %ld",ct[NbrBytesWritten]);    
printf("\n===================================================");  

See also

IOPERFORMANCEX()

IOPERFORMANCEX

Monitor Input/Output of data/index caching and count Low-Level file reads and writes (Extended version).

Short Name

IOPERFORMANCEX()

Type

Low-Level function

Declaration

LONG IOPERFORMANCEX(pVOID bufptr)

Description

IOPERFORMANCEX() is the extended version of IOPERFORMANCE(). In addition to the eight (8) values reported in IOPERFORMANCE(), IOPERFORMANCEX() reports the following eleven (11) additional values:

IOPERFORMANCE() Values:

IOPERFORMANCEX() Values:

The communication statistics ignore the traffic for the logon/logoff operations. In order to ensure proper statistics on multiple-processor hardware, add the following to the FairCom Server configuration file:

COMPATIBILITY  MULTI_PROCESSOR

IOPERFORMANCEX() accepts an array of ULONG (Unsigned Longs) in which to place the performance data. ctIXPLMT is the size of the array for IOPERFORMANCEX(). ctIOPLMT is the array size for the non-extended version, IOPERFORMANCE(). This array dimension size should be used when working with this function in case the array is increased with a future release.

Return

IOPERFORMANCEX() always returns a 0 (zero) value indicating NO_ERROR. See c-tree Error Codes in the c-tree Programmer’s Reference Guide for a complete listing of valid c-tree error values.

Example

ULONG iopx[ctIXPLMT];

IOPERFORMANCEX(iopx);
printf("\n# check points = %ld  time in seconds = %ld\n",
       iopx[NbrCheckPoints], iopx[SystemTimeValue]);

See also

IOPERFORMANCE()

KeyAtPercentile

Find key value located at about the given percentile.

Short Name

FRCKEY()

Type

Low-Level index file function

Declaration

LONG KeyAtPercentile(FILNO keyno, pVOID idxval, COUNT percnt)

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

KeyAtPercentile() finds the key value located, approximately, at the percentile specified by percnt. The key value is copied into the area pointed to by idxval. percnt should be in the range from zero (0) to one-hundred (100).

KeyAtPercentile() is very efficient since it does not traverse all of the key values in order to determine the key value located at the specified percentile. However, KeyAtPercentile() is only approximate because it assumes that the key values are uniformly distributed among all of the b-tree leaf nodes. For more accuracy, use GetORDKey() or NbrOfKeysInRange().

KeyAtPercentile() can be used to support scroll bar positioning, found in many windowing environments, in those cases when the position must be maintained in key sequential order.

See also Record Offsets Under Huge File Support.

Return

If KeyAtPercentile() is successful, it returns the data record position associated with the key value in the index which is located, approximately, at the specified percentile value. If an error occurs or the index is empty, then KeyAtPercentile() returns zero. After a call to KeyAtPercentile() returns zero, check the value of uerr_cod: if uerr_cod is non-zero, an error condition was detected; otherwise, the index is empty.

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

Example

FILNO     keyno;
TEXT      idxval[24];

if (KeyAtPercentile(keyno,idxval,75))
    printf("\n value at the 75th percentile is %.23s",idxval);
else if (uerr_cod)
    printf("\n error %d occurred",uerr_cod);
else
    printf("\n the index is empty");

Limitations

Since KeyAtPercentile() is only approximate, it may be necessary in scroll bar applications to ensure that the result of KeyAtPercentile() is consistent with the current location. For example, you may want to detect the direction of the scroll bar motion and ensure that the key value returned is consistent. For more accuracy, use GetORDKey() or NbrOfKeysInRange().

While KeyAtPercentile() is approximate, it is self-consistent. As you increase (decrease) percnt, the associated key values will increase (decrease) in value.

See also

EstimateKeySpan(), GetORDKey(), NbrOfKeysInRange()