GetAltSequence

Retrieve information from a data file relating to an alternate collating sequence that has been stored as a Resource.

Short Name

GETALTSEQ()

Type

Low-Level index file resource function

Declaration

COUNT GetAltSequence(FILNO keyno, pCOUNT altseq)

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

GetAltSequence() returns the alternative collating sequence into the array of 256 short integers pointed to by altseq.

Return

See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

See also

SetAlternateSequence()

GETCBRBLST

Returns the current rebuild callback state.

Declaration

ctCONV pctRBCBST ctDECL GETCBRBLST (VOID)

Description

Specific rebuild callback information can be passed back to the calling client via this structure. This is a useful feature that allows canceling a rebuild from the rebuild callback function. A call to this function returns a pointer to the rebuild callback state structure ctrbcbst.

typedef struct ctrbcbst {
LONG rcblen; /* number of data bytes in structure */
LONG rcbhw; /* counter high word value */
COUNT rcbrc; /* rebuild callback return code */
} ctRBCBST, ctMEM * pctRBCBST;

/* Size of rebuild callback state structure, version 1 */
#define ctRCBLEN_V01 10

Return Values

Returns a pointer to the ctrcbst state structure.

Example

To enable a clean rebuild cancel from within a callback, consider the following.

void myRebuildCallback( LONG counter, TEXT event, pTEXT message ) {
 
    pctRBCBST state;
    extern int cancel;

    if( cancel ) {
        state = GETCBRBLST();
        /* stop the rebuild */
        state->rcbrc = 1;
    }

}

See Also

SetCallbackOnRebuild

getcndxmem

Get memory required to process and store conditional index expressions (allows the proper memory allocation routines to be used on the client and server sides).

Declaration

pTEXT getcndxmem( UINT sizobj );

Description

The macros getcndxmem() and putcndxmem(), used to get and put memory required to process and store conditional index expressions, allow the proper memory allocation routines to be used on the client and server sides. (These substitute for the internal mballc() and mbfree() calls.)

Return Values

getcndxmem() returns a pointer to the newly allocated object on success. A NULL pointer is returned if memory could not be allocated.

Example

/* Allocate a run-time stack for the expression analyzer (first time only). */
if (!ctcidxStk)  {
    ctcidxStk = (pVOID) getcndxmem(CNDX_MAX_STACK * ctSIZE(PLEAF));
    if (!ctcidxStk)  {
        printf("Unable to allocate memory for run-time stack.\n");
        ctrt_exit(1);
    }
}

if (ctcidxStk)
putcndxmem(ctcidxStk);

See also

cndxeval(), cndxfree(), cndxparse(), ctparsedoda(), cndxrun(), putcndxmem()

getChangeIDfieldNumber

Get the relative field number of the specified data file's change id field.

Declaration

ctCONV NINT ctDECL getChangeIDfieldNumber (FILNO datno, pNINT pFieldNumber); 

Description

[IN] datno- Data file number.

[OUT] pFieldNumber- On success, the zero-based field number in the DODA for the change ID field is returned here. If the data file has no change id field, -1 is returned.

Return Values

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

getChangeIDheaderValue

Get the value of the specified data file's change id header field.

Declaration

ctCONV NINT ctDECL getChangeIDheaderValue(FILNO datno, ctCHGID *pChangeIdValue);
CTREE

Description

[IN] datno- Data file number.

[OUT] pChangeIdValue- On success, the change id header value is returned here.

Return Values

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

GetConditionalIndex

Get the conditional index resource from a data file.

Short Name

GETCIDX()

Type

ISAM function

Declaration

VRLEN GetConditionalIndex(FILNO keyno, LONG bufsiz, pVOID idxcnd)

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

GetConditionalIndex() returns the length of the NULL terminated ASCII string, including the NULL byte, containing the symbolic conditional expression for index keyno. This assumes an ISAM mapping exists between keyno and a data file.

Return

If idxcnd is non-NULL and bufsiz is greater than or equal to the length returned, the string is returned to the address specified by idxcnd. If idxcnd is NULL or bufsiz is too small, the length is returned by GetConditionalIndex(), no error is raised, and no string is returned. A zero return indicates no conditional expression or an error condition returned in isam_err, as follows:

See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

LONG      i;
FILNO     keyno;
LONG      bufsiz = INPBUFSIZ;
VRLEN     returnvalue;
pTEXT     tempbuffer;
TEXT      inpbuf[INPBUFSIZ];

printf(
"\nEdit condition for (1) Name or (2) Customer Number index: "
);

ctsfill(inpbuf,0,INPBUFSIZ);   /* Select an index */
gets(inpbuf);

if (inpbuf[0] != '\0') {
    sscanf(inpbuf,"%d",&i);
    keyno = (FILNO) i;
    printf("\n\nEnter a conditional expression, such as ");

    if (keyno == 1)
        printf("strncmp(LastName, \"S\", 1) == 0." );
    else
        printf("Customer >= 50." );

    ctsfill(inpbuf, 0, INPBUFSIZ);

    if ((returnvalue =
         GetConditionalIndex(keyno, bufsiz, inpbuf)) == 0) {
               /* Retrieve the current condition */
        if (isam_err) {              
            printf("Error %d getting conditional expression.", isam_err);
            return;
        }
    }
    else if (returnvalue > (VRLEN) bufsiz) {
                                      /* If buffer too small */
        bufsiz = (LONG) returnvalue + 1;
                                      /* Set a new size      */
        mbfree(inpbuf);
        tempbuffer = (pTEXT) mballc(1, (UINT)bufsiz);
                                      /* Allocate space      */
        inpbuf = (pTEXT) mballc(1, (UINT)bufsiz);

        if (!tempbuffer || !inpbuf) {  
            printf("Error allocating space for buffers\n");
            return;
        }

        GetConditionalIndex(keyno, bufsiz, tempbuffer);
                                   /* Retrieve the condition */

        cpybuf(inpbuf, tempbuffer, bufsiz);
        mbfree(tempbuffer);
    }

    printf("\nThe conditional expression is %s.", inpbuf);
}   

See also

UpdateConditionalIndex()

GetCtFileInfo

Retrieve information from a file header.

Short Name

GETFIL()

Type

Low-Level function

Declaration

LONG GetCtFileInfo(FILNO filno, COUNT mode)

Description

A variety of information about a file is stored in the file header. In FairCom DB the header is accessible only by using GetCtFileInfo() to access certain items of information from the header of file filno. Use mode to specify the type of information to be returned. The following values can be used for mode:

Return

The return value depends on the mode used in the function call. The value returned is based on the mode selected. A value of -1L means that uerr_cod contains an error.

See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

FILNO datfil;
printf("\nThe record length is %ld",
       GetCtFileInfo(datfil,RECLEN));

See also

GetSymbolicNames()

GetCtreePointer

Return a pointer to a FairCom DB state variable structure (CTGVAR).

Short Name

GETCTREE()

Type

Low-Level function

Declaration

pVOID GetCtreePointer(pTEXT regid)  

Description

GetCtreePointer() returns a pointer to the FairCom DB state variable structure, CTGVAR, based on the name used in a call to RegisterCtree(). The function declaration returns a pVOID, which should be cast by the application to a pCTGVAR.

This function is useful for obtaining the error variables when ctNOGLOBALS is defined, or when utilizing FairCom DB as a DLL (Dynamic Loadable Library). The most commonly accessed variables from the CTGVAR structure are:

COUNT    suerr_cod;      /* user error cod, uerr_cod   */
COUNT    ssysiocod;      /* system error cod, errno    */
COUNT    sisam_err;      /* isam error, isam_err       */
FILNO    sisam_fil;      /* isam file number, isam_fil */

The complete global structure, CTGVAR, is located in ctgvar.h.

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

Return

If the name used in the call to GetCtreePointer() does not exist, then a NULL is returned, otherwise the pointer to the files CTGVAR structure is returned. No error code is set (or reset) by this call whether successful or not. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

pCTGVAR     ctWNGV;

ctWNGV = GetCtreePointer(WhichCtree());
isam_err = ctWNGV->sisam_err

See also

NextCtree(), SwitchCtree(), RegisterCtree(), WhichCtree(), UnRegisterCtree()

GetCtResource

Get Resource record from data file.

Short Name

GETRES()

Type

Low-Level data file resource function

Declaration

LONG GetCtResource(FILNO datno, pVOID resptr, pVOID bufptr,
                   VRLEN bufsiz, COUNT resmode)

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

GetCtResource() retrieves a Resource from data file datno, returns a long integer corresponding to the byte offset of the Resource, and places the value of the Resource in the buffer pointed to by bufptr. bufsiz is the size of the buffer area. The buffer will contain the entire Resource Data Block. See AddCtResource() for information.

resmode specifies the method of searching for the Resource. resptr points to the identifying information used in the search. The resmode choices are:

See also Record Offsets Under Huge File Support.

Return

If no error occurs, GetCtResource() returns the byte offset for the Resource record. On RBUF_ERR (404), GetCtResource() returns the resource offset and sets uerr_cod to 404. Otherwise, GetCtResource() returns a zero and uerr_cod is set as follows:

See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example: 1 RES_NAME

struct {                    /* Resource Data Block structure */
    ULONG     resource_type;
    ULONG     resource_number;
    TEXT      variable_info[1016]; /* This holds the         */
} my_resource;                     /* Resource Name and Data */

my_resource.resource_type    = 0x10001L;            /* 65537 */
my_resource.resource_number  = 0xffffffffL;         /* FairCom DB assigns number*/

strcpy(my_resource.variable_info,"MY!resource");
strcpy(my_resource.variable_info+12,"Actual Resource Data");

if (AddCtResource(datno,&my_resource,
   (VRLEN)(8 + 12 + strlen(my_resource.variable_info+12))) == 0)
{
    printf("\nThe resource has been assigned number %ld",
           my_resource.resource_number);
    printf("\nThe resource is located at byte offset %ld.",
           GetCtResource(datno, "MY!resource", &my_resource,
                         1024L, RES_NAME));
} else
    printf("\nCould not add resource. Error #%d",uerr_cod);

Example 2: RES_LENGTH

struct {
    ULONG     resource_type;
    ULONG     resource_number;
    TEXT      variable_info[504];
} sample;

LONG     ret;          /* length returned from GetCtResource */

sample.resource_type = 0x10001L;                    /* 65537 */
sample.resource_number = 0xffffffffL;               /* FairCom DB assigned number  */
strcpy(sample.variable_info,"SAMPLE1!resource");    /* assign resource name */
strcpy(sample.variable_info+18,
       "This is the first resource record.");

if (AddCtResource(datno, &sample,
    (VRLEN)(8 + 18 + strlen(sample.variable_info+18))) != 0)
    printf("\nError adding first resource!, error = %d", uerr_cod);
else
    printf("\nSuccessful addition of first Resource Record");

strcpy(sample.variable_info,"SAMPLE2!resource"); 
                                     /* assign resource name */        
strcpy(sample.variable_info+18,
       "This is the second resource record.");

if (AddCtResource(datno,&sample,
    (VRLEN)(8 + 18 + strlen(sample.variable_info+18))) != 0)
    printf("\nError adding second resource!, error = %d", uerr_cod);
else
    printf("\nSuccessful addition of second Resource Record");

strcpy(sample.variable_info,"SAMPLE3!resource");
 /* assign resource name */         strcpy(sample.variable_info+18,
       "This is the third resource record.");

if (AddCtResource(datno, &sample,
    (VRLEN)(8 + 18 + strlen(sample.variable_info+18))) != 0)
    printf("\nError adding third resource!, error = %d", uerr_cod);
else
    printf("\nSuccessful addition of third Resource Record");

if ((ret=GetCtResource(datno, "SAMPLE1!resource", &sample, 512,
                       RES_NAME | RES_LENGTH)) != 0)
{
    cpybuf(&ret,sample.variable_info, sizeof(LONG));
    printf("\nFirst resource name is %ld bytes long",ret);
}
else
    printf("\n\nError on First resource length = %d",uerr_cod);

Example 3: RES_NEXT

    if ((ret = GetCtResource(datno, "SAMPLE1!resource", &sample,
                         512, RES_NAME)) !=0)
    printf("\nFirst resource is %s",sample.variable_info);
else
    printf("\n\nError on First resource = %d",uerr_cod);

if ((ret = GetCtResource(datno, &sample, &sample, 512, RES_NEXT)) !=0)
    printf("\nNext resource is %s",sample.variable_info);
else
    printf("\n\nError on Next resource = %d",uerr_cod);

See also

LockCtData(), LockISAM(), ctSETHGH(), ctGETHGH(), UpdateCtResource(), AddCtResource(), DeleteCtResource()

GetCtTempFileName

Create a file name that is guaranteed to be unique. Can also specify the path for the creation of temporary files.

Short Name

TMPNAME()

Type

Low-level function

Declaration

COUNT GetCtTempFileName(pVOID bufptr, VRLEN bufsiz)

Description

GetCtTempFileName() by default returns a unique file name in the parameter bufptr. Set bufsiz to the length of the buffer at bufptr, minimum 10 bytes.

Three c-tree configuration settings influence how GetCtTempFileName() functions:

• ct_tmppth -- A c-tree global variable to set the temporary files directory path in standalone operation.
• TMPNAME_PATH -- A FairCom Server configuration keyword specifying a directory name to use for the temporary files.
• USERPRF_PTHTMP -- An initialization parameter to InitCTreeXtd() toggling the functionality of the GetCtTempFileName() operation. When specified, bufptr specifies the temporary file directory, and must be nul terminated.

The usage of this function varies by c-tree model and how you configure these three c-tree operational values.

Standalone Usage

To specify a directory name where temporary files are to reside in the standalone model set the global variable, ct_tmppth, to the path desired.

Previously, the user profile mask, USERPRF_PTHTMP, was documented for use in the InitCTreeXtd() call. This use of USERPRF_PTHTMP in standalone mode should be considered legacy support. Setting the path with ct_tmppth is the FairCom recommended approach in standalone mode.

Client Server Usage

The client-server model becomes more complicated as there are two values to consider. The FairCom Server allows specifying a directory name with the TMPNAME_PATH server configuration keyword. In addition, the user profile mask, USERPRF_PTHTMP, will change the behavior of the GetCtTempFileName() function to allow setting the temp path directory location.

In the client-server model, the user profile mask takes precedence over the TMPNAME_PATH server configuration setting. Together, the combination of these two settings determine the action taken by the FairCom Server.

The following table summarizes the behavior of GetCtTempFileName():

Table 6-5:

Return

See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example Standalone Usage

#define  MAX_SIZE 255
TEXT     temp_path[MAX_NAME] = "/usr/fairtemp/";
pTEXT    path_buffer;

if (InitISAMXtd(32, /* index buffers       */
                12, /* files               */
                 8, /* # 128 bytes sectors */
                32, /* data cache pages    */
                 0, NULL,NULL,NULL)) {
    printf("\nCould not initialize FairCom DB\n");
    exit(2);
}

/* Allocate buffer for temporary file path. */
if (!(ct_tmppth = mballc(1, MAX_SIZE)))
     printf("Error: Failed to allocate %d bytes for temp path buffer\n",
          MAX_SIZE);

/* Allocate buffer for temporary file buffer. */
if (!(path_buffer = mballc(1, MAX_SIZE)))
     printf("Error: Failed to allocate %d bytes for temp path buffer\n",
          MAX_SIZE);

/* Specify the path /usr/fairtemp/ for temporary files */
strncpy(ct_tmppth, temp_path, MAX_SIZE);

/* Request a temporary file name */
if(GetCtTempFileName(path_buffer,200L)) {
    printf("\nError on GetCtTempFileName, uerr_cod =%d", uerr_cod);
    exit(2);
}

printf("\nUsing temporary pathname: %s\n", path_buffer);

/* Done with temp path buffers, so free them. */
if (ct_tmppth) {
     mbfree(ct_tmppth);
     ct_tmppth = NULL;
}
if (path_buffer) {
     mbfree(path_buffer);
     path_buffer = NULL;
}

CLISAM();
Client Server Usage with USERPRF_PTHTMP
#define  MAX_SIZE 255
TEXT     temp_path[MAX_NAME] = "/usr/fairtemp/";
pTEXT    path_buffer;

if (InitISAMXtd(32, /* index buffers       */
                12, /* files               */
                 8, /* # 128 bytes sectors */
                32, /* data cache pages    */
                USRPRF_PTHTMP, /* GetCtTempFileName sets path */
                "ADMIN","ADMIN","FAIRCOMS")) {
    printf("\nCould not initialize FairCom DB\n");
    exit(2);
}

/* Allocate buffer for temporary file path. */
if (!(path_buffer = mballc(1, MAX_SIZE)))
     printf("Error: Failed to allocate %d bytes for temp path buffer\n",
          MAX_SIZE);

/* Specify the path /usr/fairtemp/ for temporary files */
strncpy(path_buffer, temp_path, MAX_SIZE);

/* Set the temporary file name */
if(GetCtTempFileName(path_buffer, MAX_SIZE)) {
    printf("\nError on GetCtTempFileName, uerr_cod =%d", uerr_cod);
    exit(2);
}

printf("\nUsing temporary pathname: %s\n", path_buffer);

/* Done with temp path buffer, so free it. */
if (path_buffer) {
     mbfree(path_buffer);
     path_buffer = NULL;
}

CLISAM();

Limitations

If a client process on a heterogeneous network sends a GetCtTempFileName() path with an improper directory separator, GetCtTempFileName() returns an error, since the name will not be well defined, instead of automatically changing the separators to match the Server conventions.

See also

TMPNAME_PATH configuration keyword in the FairCom Server Administrator’s Guide.

InitCTreeXtd()

GetDODA

Retrieve information from a record schema stored as a resource.

Short Name

GETDODA()

Type

Low-Level data file resource function

Declaration

VRLEN GetDODA(FILNO datno, LONG bufsiz, pVOID bufptr, COUNT mode)

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

GetDODA() returns various forms of the records schema, if any are included in the data file as a resource, into the buffer pointed to by bufptr.

bufsiz specifies the length of the buffer. The value returned by GetDODA() is the actual length of the information requested. If bufsiz is too small, GetDODA() still returns the actual size, but no data is transferred into the buffer. Another call to GetDODA() with a proper size buffer is required.

mode indicates the form of the return information. mode may take on one of the following values.

If SCHEMA_MAP is requested, a map, as described in Record Schemas, is returned in the buffer.

If SCHEMA_NAMES is requested only the names, in the form described in Record Schemas, are returned in the buffer.

If SCHEMA_MAPandNAMES is requested the buffer contains the schema map followed immediately by the schema name. The maplen member of the schema map is the offset from the beginning of the buffer to the names. See Record Schemas.

If SCHEMA_DODA is requested, the map and names are converted to the form of a DODA where the fadr member of the DATOBJ structure is filled with the offset of the field from the beginning of the record.

Return

In the event of an error, GetDODA() returns a zero value and uerr_cod is typically set to one of the following values:

See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

See also

PutDODA()

GetFileRegions

Calculates offsets and lengths of a specified number of regions in a data file, accounting for resource locations, such that starting region offsets correspond to an active or deleted record at the time this function is called. A region is defined by a starting data file offset and the region length in bytes. (V11.8 and later)

Type

ISAM Function

NINT ctDECL GetFileRegions (pFILE_REGION_REQUEST pFileRegionRequest);

Description

• [INOUT] pFileRegionRequest - Data structure used to pass information in and out of the function, defined below.

Description

Structure Definitions

typedef struct fileRegionRequest_t {
    COUNT structVersion;  
    FILNO dataFileNumber; 
    LONG numberOfRegions; 
    pFILE_REGION fileRegions; 
} FILE_REGION_REQUEST, *pFILE_REGION_REQUEST;

• [IN] structVersion - Structure version (consult ctport.h for current versions).
• [IN] dataFileNumber - c-tree data file number
• [IN] numberOfRegions - Number of FILE_REGION structures in the array, which is the number of regions you desire.

fileRegions must have enough memory for that number of FILE_REGION structures.

• [OUT] fileRegions - Array of FILE_REGION structures.

Offset and length values are set on successful output.

Note: Your code is responsible for allocating before calling the function and deallocating afterwards.

typedef struct fileRegion_t {
 ULONG8 offset; 
 ULONG8 length; 
} FILE_REGION, *pFILE_REGION;

• [OUT] offset - starting record offset for region in the data file
• [OUT] length - size of this region in bytes

Region Definition

FairCom DB calculates the starting offset of each region by dividing the data file into equally sized regions corresponding to the number of regions specified by numberOfRegions in the fileRegionRequest_t structure. It aligns the offset of each region in fileRegion_t to the record offset of the first record in the region. It aligns the length to the offset of the last byte of the last record in the region.

Because the data file may contain resources, FairCom DB determines the locations of resource records in the data file. If any region offset lands on or within a resource record, FairCom DB adjusts the offset to start on the first record after the resource.

If the adjusted starting offset is no longer inside the specified region (which is only likely for small files), the offset and length of the region are returned as zero. Thus, you must ignore regions with zero length.

Example

NINT numberOfRegions = 10;               /* specify number of regions */
pFILE_REGION fileRegions = NULL;         /* array returned with region information */
FILNO datno;                             /* data file number */

/* structure used to request and receive region information */
FILE_REGION_REQUEST fileRegionRequest; 
NINT i, rc;


/* Allocate memory for the array of regions that GetFileRegions() will populate */
if (!(fileRegions = (pFILE_REGION) mballc(numberOfRegions, sizeof(FILE_REGION)))) {
    printf("Error: Failed to allocate memory for the region array.\n");
    return -1;
}

/* Open the data file */
if ((datno = OPNRFIL(-1, "MyDataFile.dat", ctSHARED)) < 0) {
    rc = isam_err;
    printf("Error: failed to open file: %d\n", rc);
    if (fileRegions)
        mbfree(fileRegions);
    return -1;
}

/* Prepare structure returning file regions */
fileRegionRequest.structVersion = FILE_REGION_REQUEST_VERS_V01;
fileRegionRequest.dataFileNumber = datno;            /* The data file */
fileRegionRequest.numberOfRegions = numberOfRegions; /* Requested regions */
fileRegionRequest.fileRegions = fileRegions;         /* Allocated array */
if ((rc = GetFileRegions(&fileRegionRequest))) {
    printf("Error: failed to get region information: %d\n", rc);
    if (fileRegions)
        mbfree(fileRegions);
    return -1;
}

/* Now print the region information */
printf("offset      length\n");
for (i=0; i<numberOfRegions; i++) {
    printf(ctLLnd(10) " " ctLLnd(10) "\n",fileRegions[i].offset,fileRegions[i].length);
}

if (fileRegions)
    mbfree(fileRegions); /* Free region array */

return(0);

Limitations

• This function is not supported for variable-length record data files.
• This function is not supported for memory files.
• This function is not supported for superfiles (superfile hosts or members).
• This function is not available for Multi-user Multi-threaded Standalone model. It is available for Multi-user and Single-user Standalone.

Coding Considerations

• The number of records in one region may be less than another region because the function does not take into consideration deleted records when it divides the data into regions. For this reason, it is unlikely, but possible, that a region could be occupied solely by records that were previously deleted.
• In data files containing few records that are divided into many regions, it is possible for a region to contain no records. This will cause FILE_REGION.length and FILE_REGION.offset to be zero.
• Multiple threads can speed data processing as long as the storage system has enough I/O bandwidth and the CPU has enough processing power. When data processing becomes I/O or CPU bound, adding more threads can slow data processing.
• Batch record processing, such as DoBatch(), does NOT stay within the current region. Instead, batch functions stop when the end of file is reached or the batch buffer is full. This means batch functions can return records that are past the end of a region, and this can cause the same record to be processed by more than one thread. To prevent this, use the BAT_RET_REC option instead of BAT_RET_BLK to return the record offset with each record. You can write threads to stop processing records as soon as they find a record whose offset is outside of that thread’s region.
• When adding resources to a data file while using this function, the application should first acquire a table lock. Otherwise, if a resource is added, deleted, or updated after the function has determined resource offsets, the function can return an offset that corresponds to a resource or to a location within a resource.
• The GetFileRegions() function does not automatically provide read isolation to a region. It does not protect a region from being updated by other processes. This is because the function does not acquire locks on the records in a region. If you require read consistency for an entire region, the safest way is to lock the entire table. Alternatively, you can lock individual records in a region with the possibility that another process may lock some of them first.

Return

• Success: NO_ERROR(0)
• Failure: Non-zero c-tree error code:

Programming Errors

• 10 - SPAC_ERR - Out of space. Parameters require too much space. Check the parameters passed in to make sure they are correct.
• 43 - FVER_ERR - Check the versions specified in the structures passed in to the function. They must match the versions in use in the data file as set at file creation or last version update. structVersion must be FILE_REGION_REQUEST_VERS_V01
• 47 - FINT_ERR - c-tree has not been initialized. You need to call InitISAM() first.
• 48 - FMOD_ERR - File mode error. Make sure the data file type is compatible with this function. File types such as superfile host, superfile member, memory file, or variable-length record data file are incompatible with this function.
• 78 - TABN_ERR - Transaction has become too large. Re-try in smaller pieces.
• 82 - UALC_ERR - User allocation error. Check the parameters, our memory allocation based on the parameters failed.
• 540 - PNUL_ERR - Null parameter error. One or more required parameters passed to the function is null.
• 634 - NLEN_ERR - Negative length specified. Check the lengths you passed into the function.

Incorrect File Usage Errors

• 22 - FNUM_ERR - filno out of range. You may be attempting to open more files than the server is configured for. Increase the file limit of the server and try again. This error may also occur if c-tree has not been initialized.
• 26 - FACS_ERR - File number is not in use. This occurs when you specify an invalid data file number or the file has been closed.

Handleable File Errors

• 643 - DPND_ERR - File is being deleted.
• 798 - FBLK_ERR - File is blocked, retry later.
• 799 - FBLK_RDO - File block cleared: close/reopen file.

See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Compatibility Note: This new functionality involves changes to both the client library and the server, so, in addition to installing a new server executable, the client program must be re-linked.

GetFilterVersion

Returns the version of the filter callback API that the DLL uses.

Declaration

LONG GetFilterVersion (VOID)

Description

This function is defined in the ctuserx.c module used to build a filter callback function.

When loading a filter callback DLL, FairCom DB calls this function and fails to load the DLL with error CBKV_ERR (870) if the filter callback API version returned by the DLL doesn't match the filter callback DLL API version that FairCom DB is using.

Return Values

Filter version found in the SDK.

See also

ctfiltercbAddFilter(), EvaluateFilter(), ctfiltercbRemoveFilter(), UnloadFilter(), SetDataFilter()

GetGTEKey

Search index file for entry equal to or greater than target.

Short Name

GTEKEY()

Type

Low-Level index file function

Declaration

LONG GetGTEKey(FILNO keyno, pVOID target, pVOID idxval) 

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

GetGTEKey searches index file keyno for the first entry which is equal to, or greater than, the key value pointed to by target. If such an entry exists, it is copied into the area pointed to by idxval.

GetGTEKey() is frequently used to start searching an index file that accepts duplicate keys. GetKey() cannot be used since the index entries have suffixes appended. If index file keyno accepts duplicate entries, pad the target key value with null bytes to ensure the entry with the smallest suffix is found.

Return

If GetGTEKey() is successful, it returns the data record position associated with the entry found in the index. If an error occurs or no such entry exists, (either the index is empty or the target key value exceeds all entries in the index), GetGTEKey() returns a zero. When GetGTEKey() returns a zero, check the value of uerr_cod: if uerr_cod is non-zero, an error condition was detected; otherwise, no key value satisfied the search. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

FILNO        keyno;
TEXT         target[24],*idxval;
pLONG        suffix;

/* Key length = 23. Assuming duplicates are allowed, the last
 * four bytes are for the suffix.                            */
scanf("%19s",target);
suffix = target + 20;      /* pointer to the last four bytes */
*suffix = 0L;              /* set suffix to zero.            */
    /* Assumes no alignment restrictions.  */

idxval = "12345678901234567890123";/*reserve space for idxval*/
if (GetGTEKey(keyno,target,idxval))
    printf("\nthe key value >= %.19s is %.19s",target,idxval);

Limitations

No check is made to determine if idxval points to a region sufficiently large to accept a key value from the index file. If the area is too small, either code or data will be clobbered.

Note: The key value returned by this function will be a properly formatted key value (i.e., HIGH_LOW order, forced to upper case, etc.). The main issue this presents is if binary key values will be displayed on a LOW_HIGH machine, it will be necessary to reverse any numeric segments.

The recbyt parameter in this function is a 4-byte value capable of addressing at most 4 gigabytes. If your application supports HUGE files (greater than 4 gigabytes), you must use the ctSETHGH() and ctGETHGH() functions to set or get the high-order 4 bytes of the file offset. See also Record Offsets Under Huge File Support.

See also

GetKey(), GetGTKey(), GetLTEKey(), GetLTKey()

GetGTERecord

Read the record with key greater than or equal to target.

Short Name

GTEREC()

Type

ISAM function

Declaration

COUNT GetGTERecord(FILNO keyno, pVOID target, pVOID recptr)

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

GetGTERecord() reads the first data record whose key value in keyno is equal to, or greater than, the key value pointed to by target into the buffer area pointed to by recptr. If successful, the record becomes the current ISAM record for the data file associated with keyno.

GetGTERecord() is frequently used to start searching a file via an index file that accepts duplicate keys. GetRecord() cannot be used since the index entries have suffixes appended. If index file keyno accepts duplicate entries, pad the target key value with null bytes to ensure that the entry with the smallest suffix is found. See the example for GetGTEKey().

An alternative to GetGTERecord() is FirstInSet(), which reads the first data record whose key value matches the significant bytes in a target key; it is not necessary to pad the target when using FirstInSet(). The main difference between GetGTERecord() and FirstInSet() is that GetGTERecord() does not require any match with the target.

If the associated data file has variable-length records, then only the fixed-length portion (defined by dreclen in the original call to CreateIFile()) is actually read into the buffer pointed to by recptr. If you wish to read the entire variable-length record into the same or a different buffer, call ReReadVRecord() after GetGTERecord(). ReReadVRecord() requires the specific size of the buffer area so that it can check if sufficient space is available.

Notice that the data file number involved is not directly identified. The ISAM structure definition described in ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) contains the relationship between the index file number and the associated data file.

Return

See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

LONG      cust_number;
FILNO     keyno;
pTEXT     recptr;

scanf("%ld",cust_number);
if (GetGTERecord(keyno,&cust_number,recptr))
    printf("\nUnsuccessful search. Code = %d on file %d.", isam_err,isam_fil);

Limitations

No check is made to determine if recptr points to a region sufficiently large to accept a data record. If the area is too small, either code or data will be clobbered.

See also

GetRecord(), FirstInSet(), TransformKey(), CreateIFile(), ReReadVRecord()

To double performance, see ChangeISAMContext.

GetGTEVRecord

Read the variable-length record with key greater than or equal to target.

Short Name

GTEVREC()

Type

ISAM function

Declaration

COUNT GetGTEVRecord(FILNO keyno, pVOID target, pVOID recptr, pVRLEN plen)

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

GetGTEVRecord() is the same as its fixed-length counterpart, GetGTERecord(), except one new argument has been added: plen.

plen acts as both an input and output parameter:

• On input, plen contains the length of the output buffer.
• On output, the contents of plen is the actual data-record length. If the length of the output buffer is less than the actual record length, a partial read is performed. If an error occurs, plen is unspecified.

See the GetGTERecord() function description for additional important information.

Return

See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

See also

GetGTVRecord(), GetLTEVRecord(), GetLTVRecord(), TransformKey()

To double performance, see ChangeISAMContext.

GetGTKey

Search index file for entry greater than target.

Short Name

GTKEY()

Type

Low-Level index file function

Declaration

LONG GetGTKey(FILNO keyno, pVOID target, pVOID idxval) 

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

GetGTKey() searches index file keyno for the first entry that is strictly greater than the key value pointed to by target. If such an entry exists, then it is copied into the area pointed to by idxval.

Return

If GetGTKey() is successful, it returns the data record position associated with the entry found in the index. If an error occurs or no such entry exists, (either the index is empty, or the target key value exceeds all entries in the index), then GetGTKey() returns a zero. When GetGTKey() returns a zero check the value of uerr_cod: if uerr_cod is non-zero, an error was detected; otherwise, no key value satisfied the search. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

FILNO   keyno;
TEXT    target[24],idxval[23];
LONG    recbyt;

ctsfill(target,0,24);
ctsfill(idxval,0,23);
scanf("%23s",target);
recbyt = GetGTEKey(keyno,target,idxval);
while (recbyt) {
    printf("\nIndex entry = %23s Record # = %ld",
           idxval,recbyt);
    cpybuf(target,idxval,23);
    recbyt = GetGTKey(keyno,target,idxval);
}

Limitations

No check is made to determine if idxval points to a region sufficiently large to accept a key value from the index file. If the area is too small, either code or data will be clobbered.

The key value returned will be a properly formatted key value (i.e., HIGH_LOW order, forced to upper case, etc.). The main issue this presents is if binary key values will be displayed on a LOW_HIGH machine, it will be necessary to reverse any numeric segments.

The recbyt parameter in this function is a 4-byte value capable of addressing at most 4 gigabytes. If your application supports HUGE files (greater than 4 gigabytes), you must use the ctSETHGH() and ctGETHGH() functions to set or get the high-order 4 bytes of the file offset. See also Record Offsets Under Huge File Support.

See also

GetGTEKey(), GetKey(), GetLTEKey(), GetLTKey()

GetGTRecord

Read the record with key greater than target.

Short Name

GTREC()

Type

ISAM function

Declaration

COUNT GetGTRecord(FILNO keyno, pVOID target, pVOID recptr)

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

GetGTRecord() reads the first data record whose key value in keyno is greater than the key value pointed to by target into the buffer area pointed to by recptr. If successful, the record becomes the current ISAM record for the data file associated with keyno.

GetGTRecord() is frequently used to search for the next value greater than target. If index file keyno accepts duplicate entries, pad the target key value with null bytes to ensure that the entry with the smallest suffix is found. See the example for GetGTEKey().

If the associated data file has variable-length records, then only the fixed-length portion (defined by dreclen in the original call to CreateIFile()) is actually read into the buffer pointed to by recptr. If you wish to read the entire variable-length record into the same or a different buffer, call ReReadVRecord() after GetGTRecord(). ReReadVRecord() requires the specific size of the buffer area so that it can check if sufficient space is available.

Notice that the data file number involved is not directly identified. The ISAM structure definition described in ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) contains the relationship between the index file number and the associated data file.

Return

See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

LONG      cust_number;
FILNO     keyno;
pTEXT     recptr;

scanf("%ld",cust_number);
if (GetGTRecord(keyno,&cust_number,recptr))
    printf("\nUnsuccessful search. Code = %d on file %d.",
           isam_err,isam_fil);

Limitations

No check is made to determine if recptr points to a region sufficiently large to accept a data record. If the area is too small, either code or data will be clobbered.

See also

GetGTEKey(), GetRecord(), FirstInSet(), CreateIFile(), TransformKey(), ReReadVRecord()

To double performance, see ChangeISAMContext.

GetGTVRecord

Read the variable-length record with key greater than target.

Short Name

GTVREC()

Type

ISAM function

Declaration

COUNT GetGTVRecord(FILNO keyno, pVOID target, pVOID recptr, pVRLEN plen)

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

GetGTVRecord() is the same as its fixed-length counterpart, GetGTRecord(), except one new argument has been added: plen.

plen acts as both an input and output parameter:

• On input, plen contains the length of the output buffer.
• On output, the contents of plen is the actual data-record length. If the length of the output buffer is less than the actual record length, a partial read is performed. If an error occurs, plen is unspecified.

Read the function description for GetGTRecord() for additional important information.

Return

See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

See also

GetGTEVRecord(), GetLTEVRecord(), GetLTVRecord(), TransformKey()

To double performance, see ChangeISAMContext.

getIDfield

Return IDENTITY attribute information from a file.

Declaration

NINT getIDfield(FILNO datno, NINT mode, pLONG8 retval)

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

getIDfield() returns information about an IDfield (IDENTITY) value.

Where:

• datno is the data file number
• mode is the next value to be assigned to the field on add.
• retval is the value to increment each addition.

mode can take one of the following values:

• updateValue - return is set to the next IDfield value, and the IDfield is updated
• reportValue - return is set to the next IDfield value, but the IDfield remains unchanged
• startingValue - return is set to the starting value for the IDfield
• deltaValue - return is set to the IDfield change value (delta in IDfield)

IDfield requires a DAR resource (Direct Access Resource) embedded in the file. The DAR is a specialized high-speed resource.

Return

See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

retval = getIDfield(fileno, reportValue, &idval);
if (retval) {
printf("\tERROR: Failed to retrieve ID information with error %d\n", retval);
}
  else
         printf("Next IDENTITY value is %d\n", idval);

Override IDENTITY Values

PUTHDR() using the ctIDfieldOverRide mode can turn on and off the ability to override the automatic IDfield values. The override is on a per user, per file basis. A nonzero hdrval turns on the override, and a zero hdrval restores the standard operation. When the override is on for a data file that supports an IDfield, then an add record operation does not fill-in the IDfield value. Whatever is passed in the record buffer is used for the IDfield. And a rewrite permits the IDfield value to change instead of generating the IDFL_CHG error. When the override is enabled, add record operations do not consume IDfield values.

See also

addIDfield(), delIDfield(), wchIDfield(), resetIDfield(), IDfields - Extended support

GetIFile

Retrieve an IFIL structure from a data file

Short Name

GETIFIL()

Type

ISAM resource function

Declaration

VRLEN GetIFile(FILNO datno, LONG bufsiz, pVOID bufptr) 

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

GetIFile() returns a complete IFIL structure into the buffer pointed to by bufptr. bufsiz contains the size of the buffer. If bufsiz is too small, GetIFile() returns a required buffer size, but no IFIL information is returned. Call GetIFile() again with the required buffer size. If bufsiz is sufficiently large, the value returned by GetIFile() is the actual length of the IFIL structure and its subsidiary IIDX and ISEG structures, which are included in the buffer. In some cases the actual size may be less than the required buffer size.

It is permissible to cast the buffer pointer to a pointer of type pIFIL.

Return

GetIFile() returns either the required or the actual size of the IFIL structure (including associated IIDX and ISEG structures) from the data file referred by datno.

In case of error, GetIFile() returns a zero value. The error code can be found in isam_err. Possible errors are described in the following table.

See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Refer to the following sections for additional details regarding IFIL structures.

IFIL Structure

IIDX Structure

ISEG Structure

Limitations

Resources are required.

See also

OpenFileWithResource(), PutIFile()

GetKey

Search index file for entry equal to target value.

Short Name

EQLKEY()

Type

Low-Level index file function

Declaration

LONG GetKey(FILNO keyno, pVOID target) 

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

GetKey() searches index file number keyno for an entry equal to the key value pointed to by target.

See also Record Offsets Under Huge File Support.

Return

If GetKey() finds an exact match for target, then it returns the data record position associated with the entry. If an exact match is not found, or if an error occurs, then GetKey() returns a zero, and the global variable uerr_cod is set to the appropriate value. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

LONG      recbyt;
FILNO     keyno;
TEXT      target[11];

scanf("%10s %d",target,&keyno);
if (!(recbyt = GetKey(keyno,target))) {
    if (uerr_cod)
        printf("\nError while searching.");
    else
        printf("\nKey value not found.");
}
else
    printf("\nKey value is in record at position %ld.", recbyt);

Limitations

FairCom DB will not pad the target key value. Ensure that target points to a properly formed key value. This function is not appropriate for indexes allowing duplicates. Use a function from below in that case.

See also

GetGTEKey(), GetGTKey(), GetLTEKey(), GetLTKey()

GetLTEKey

Search index file for entry equal to or less than target.

Short Name

LTEKEY()

Type

Low-Level index file function

Declaration

LONG GetLTEKey(FILNO keyno, pVOID target, pVOID idxval) 

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

GetLTEKey() searches index file keyno for the last entry which is equal to, or less than, the key value pointed to by target. If such an entry exists, it is copied into the area pointed to by idxval.

Return

If GetLTEKey() is successful, it returns the data record position associated with the entry found in the index. If an error occurs or no such entry exists, (either the index is empty or the target key value exceeds all entries in the index), GetLTEKey() returns a zero. When GetLTEKey() returns a zero, check the value of uerr_cod: if uerr_cod is non-zero, an error condition was detected; otherwise, no key value satisfied the search. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

FILNO        keyno;
TEXT         target[24], idxval[24];
pTEXT        suffix;

/* Key length = 23. Assuming duplicates are allowed, the     *
 * last four bytes are for the suffix.                       */
memset(target, NULL, 24);
scanf("%19s",target);
suffix = target + 20;      /* pointer to the last four bytes */

for (i = 0;i++ < 4;)       /* set suffix to highest possible */
    *suffix++ = C255;      /* value                          */

if (GetLTEKey(keyno,target,idxval))
  printf("\nthe key value >= %.19s is %.19s", target, idxval);

Limitations

No check is made to determine if idxval points to a region sufficiently large to accept a key value from the index file. If the area is too small, either code or data will be clobbered.

Note: The key value returned by this function will be a properly formatted key value (i.e., HIGH_LOW order, forced to upper case, etc.). The main issue this presents is if binary key values will be displayed on a LOW_HIGH machine, it will be necessary to reverse any numeric segments.

The recbyt parameter in this function is a 4-byte value capable of addressing at most 4 gigabytes. If your application supports HUGE files (greater than 4 gigabytes), you must use the ctSETHGH() and ctGETHGH() functions to set or get the high-order 4 bytes of the file offset. See also Record Offsets Under Huge File Support.

See also

GetKey(), GetGTEKey(), GetGTKey(), GetLTKey(), ctSETHGH(), ctGETHGH().

GetLTERecord

Read the record with key less than or equal to target.

Short Name

LTEREC()

Type

ISAM function

Declaration

COUNT GetLTERecord(FILNO keyno, pVOID target, pVOID recptr)

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

GetLTERecord() reads the last data record whose key value in keyno is equal to, or less than, the key value pointed to by target into the buffer area pointed to by recptr. If successful, the record becomes the current ISAM record for the data file associated with keyno.

GetLTERecord() is frequently used to start searching a file via an index file that accepts duplicate keys. GetRecord() cannot be used since the index entries have suffixes appended. If index file keyno accepts duplicate entries, pad the target key value with null bytes to ensure that the entry with the smallest suffix is found. See the example for GetGTEKey().

An alternative to GetLTERecord() is LastInSet(), which reads the last data record whose key value matches the significant bytes in a target key; it is not necessary to pad the target when using LastInSet(). The main difference between GetLTERecord() and LastInSet() is that GetLTERecord() does not require any match with the target.

If the associated data file has variable-length records, then only the fixed-length portion (defined by dreclen in the original call to CreateIFile()) is actually read into the buffer pointed to by recptr. If you wish to read the entire variable-length record into the same or a different buffer, call ReReadVRecord() after GetLTERecord(). ReReadVRecord() requires the specific size of the buffer area so that it can check if sufficient space is available.

Notice that the data file number involved is not directly identified. The ISAM structure definition described in ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) contains the relationship between the index file number and the associated data file.

Return

See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

LONG      cust_number;
FILNO     keyno;
pTEXT     recptr;

scanf("%ld",cust_number);
if (GetLTERecord(keyno,&cust_number,recptr))
    printf("\nUnsuccessful search. Code = %d on file %d.", isam_err,isam_fil);

Limitations

No check is made to determine if recptr points to a region sufficiently large to accept a data record. If the area is too small, either code or data will be clobbered.

See also

GetGTEKey(), GetRecord(), LastInSet(), TransformKey(), CreateIFile(), ReReadVRecord()

To double performance, see ChangeISAMContext.

GetLTEVRecord

Read the variable-length record with key less than or equal to target.

Short Name

LTEVREC()

Type

ISAM function

Declaration

COUNT GetLTEVRecord(FILNO keyno, pVOID target, pVOID recptr, pVRLEN plen)

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

GetLTEVRecord() is the same as its fixed-length counterpart, GetLTERecord(), except one argument has been added: plen.

plen acts as both an input and output parameter:

• On input, plen contains the length of the output buffer.
• On output, the contents of plen is the actual data-record length. If the length of the output buffer is less than the actual record length, a partial read is performed. If an error occurs, plen is unspecified.

Read the function description for GetLTERecord() for additional important information.

Return

See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

See also

GetGTEVRecord(), GetGTVRecord(), GetLTVRecord(), TransformKey()

To double performance, see ChangeISAMContext.

GetLTKey

Search index file for entry less than target.

Short Name

LTKEY()

Type

Low-Level index file function

Declaration

LONG GetLTKey(FILNO keyno, pVOID target, pVOID idxval) 

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

GetLTKey() searches index file keyno for the last entry that is strictly less than the key value pointed to by target. If such an entry exists, it is copied into the area pointed to by idxval.

Return

If GetLTKey() is successful, it returns the data record position associated with the entry found in the index. If an error occurs or no such entry exists, (either the index is empty or the target key value is smaller than all entries in the index), GetLTKey() returns a zero. When GetLTKey() returns a zero, check the value of uerr_cod: if uerr_cod is non-zero, an error condition was detected; otherwise, no key value satisfied the search. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

FILNO        keyno;
TEXT         target[24], idxval[24];
pTEXT        suffix;

/* Key length = 23. Assuming duplicates are allowed, the     *
 * last four bytes are for the suffix.                       */
scanf("%19s",target);
suffix = target + 20;      /* pointer to the last four bytes */
for (i = 0;i++ < 4;)       /* set suffix to highest possible */
    *suffix++ = C255;      /* value                          */
if (GetLTKey(keyno,target,idxval))
     printf("\nthe key value >= %.19s is %.19s", target, idxval);

Limitations

No check is made to determine if idxval points to a region sufficiently large to accept a key value from the index file. If the area is too small, either code or data will be clobbered.

Note: The key value returned by this function will be a properly formatted key value (i.e., HIGH_LOW order, forced to upper case, etc.). The main issue this presents is if binary key values will be displayed on a LOW_HIGH machine, it will be necessary to reverse any numeric segments.

The recbyt parameter in this function is a 4-byte value capable of addressing at most 4 gigabytes. If your application supports HUGE files (greater than 4 gigabytes), you must use the ctSETHGH() and ctGETHGH() functions to set or get the high-order 4 bytes of the file offset. See also Record Offsets Under Huge File Support.

See also

GetKey(), GetGTEKey(), GetGTKey(), GetLTEKey()

GetLTRecord

Read the record with key less than target.

Short Name

LTREC()

Type

ISAM function

Declaration

COUNT GetLTRecord(FILNO keyno, pVOID target, pVOID recptr)

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

GetLTRecord() reads the last data record whose key value in keyno is less than, the key value pointed to by target into the buffer area pointed to by recptr. If successful, the record becomes the current ISAM record for the data file associated with keyno.

GetLTRecord() is frequently used to start searching a file via an index file that accepts duplicate keys. GetRecord() cannot be used since the index entries have suffixes appended. If index file keyno accepts duplicate entries, pad the target key value with null bytes to ensure that the entry with the smallest suffix is found. See the example for GetGTEKey().

An alternative to GetLTRecord() is LastInSet(), which reads the last data record whose key value matches the significant bytes in a target key; it is not necessary to pad the target when using LastInSet(). The main difference between GetLTRecord() and LastInSet() is that GetLTRecord() does not require any match with the target.

If the associated data file has variable-length records, then only the fixed-length portion (defined by dreclen in the original call to CreateIFile()) is actually read into the buffer pointed to by recptr. If you wish to read the entire variable-length record into the same or a different buffer, call ReReadVRecord() after GetLTRecord(). ReReadVRecord() requires the specific size of the buffer area so that it can check if sufficient space is available.

Notice that the data file number involved is not directly identified. The ISAM structure definition described in ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) contains the relationship between the index file number and the associated data file.

Return

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

Example

LONG      cust_number;
FILNO     keyno;
pTEXT     recptr;

scanf("%ld",cust_number);
if (GetLTRecord(keyno,&cust_number,recptr))
    printf("\nUnsuccessful search. Code = %d on file %d.",
           isam_err,isam_fil);

Limitations

No check is made to determine if recptr points to a region sufficiently large to accept a data record. If the area is too small, either code or data will be clobbered.

See also

GetGTEKey(), GetRecord(), LastInSet(), TransformKey(), CreateIFile(), ReReadVRecord()

To double performance, see ChangeISAMContext.

GetLTVRecord

Read the variable-length record with a key less than target.

Short Name

LTVREC()

Type

ISAM function

Declaration

COUNT GetLTVRecord(FILNO keyno, pVOID target, pVOID recptr, pVRLEN plen)

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

GetLTVRecord() is the same as its fixed-length counterpart, GetLTRecord(), except one argument has been added: plen.

plen acts as both an input and output parameter:

• On input, plen contains the length of the output buffer.
• On output, the contents of plen is the actual data-record length. If the length of the output buffer is less than the actual record length, a partial read is performed. If an error occurs, plen is unspecified.

Read the GetLTRecord() function description for additional important information.

Return

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

See also

GetGTEVRecord(), GetGTVRecord(), GetLTRecord(), GetLTEVRecord(), TransformKey()

To double performance, see ChangeISAMContext.

GetORDKey

Return the record offset (recbyt) to the nth offset past the given target.

Short Name

ORDKEY()

Type

Low-Level index file function

Declaration

ctRECPT GetORDKey(FILNO keyno, pVOID target, LONG offset, pVOID idxval)

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

GetORDKey() returns the record offset, recbyt, for the nth active index entry, offset, past the given target for index number keyno. The target must be properly formed as is necessary with any c-tree function that retrieves data using indexes. This function is intended to aid developers programming “list boxes” in a GUI environment.

In V11.8 and later, the GetORDKey() function is supported for partitioned files.

Return

GetORDKey(), if successful, returns the record offset, recbyt, for the nth active index entry, offset, past the given target and the idxval argument contains the index value found at the index location target + offset.

If an error occurs or no active entries are found, GetORDKey() returns zero. When GetORDKey() returns zero, if uerr_cod is non-zero, an error condition was detected; otherwise no active key values were detected. See c-tree Error Codes in the c-tree Programmer’s Reference Guide for a complete listing of valid c-tree error values.

The following example contains a duplicate allowed index over customer name. The code prompts the user for a beginning name and the number of active key values to skip. The value recbyt returned by GetORDKey() is the record offset in the data file for the key value found.

Example

FILNO  keyno=4;
LONG   maxbuf=40;

LONG ret_long, recbyt;
TEXT target[maxbuf];   /* target value to start search with */
TEXT idxval1[maxbuf];  /* input buffer for RNGENT function  */
TEXT idxval2[maxbuf];  /* input buffer for RNGENT function  */

printf("\n\tEnter name for GetORDKey:");
memset(target,' ',maxbuf);
gets(target);

TransformKey(4,target);    /* properly form search target */
printf("\n\tEnter offset to find with ORDKEY:");
memset(idxval1,0x0,maxbuf);
gets(idxval1);
ret_long = atol(idxval1);

if (!(recbyt = GetORDKey(keyno,target,ret_long,idxval2)))
    printf("\nError on GetORDKey, error = %d",uerr_cod);
else
    printf("\nSuccessful GetORDKey, recbyt =%ld, idxval2 = %s",recbyt, idxval2);

Limitations

The value of offset must be positive.

The recbyt parameter in this function is a 4-byte value capable of addressing at most 4 gigabytes. If your application supports HUGE files (greater than 4 gigabytes), you must use the ctSETHGH() and ctGETHGH() functions to set or get the high-order 4 bytes of the file offset. See also Record Offsets Under Huge File Support.

See also

NbrOfKeysInRange(), NbrOfKeyEntries()

GetRecord

Get data record with key equal to target value.

Short Name

EQLREC()

Type

ISAM function

Declaration

COUNT GetRecord(FILNO keyno, pVOID target, pVOID recptr)

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

GetRecord() searches index file number keyno for an entry matching the key value pointed to by target. If an exact match is found, GetRecord() reads the associated data record into the buffer area pointed to by recptr, and this record becomes the current ISAM record. If no match is found or an error occurs, the current ISAM record remains unchanged.

If the associated data file has variable-length records, then only the fixed-length portion, defined by dreclen in the original call to CreateIFile(), is actually read into the buffer pointed to by recptr. If you wish to read the entire variable-length record into the same or a different buffer, issue a call to ReReadVRecord() after the call to GetRecord(). Note that ReReadVRecord() requires you to specify the size of the buffer area so that it can check if sufficient space is available.

Notice that you do not directly identify the data file number involved. The IFIL structures described in ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) of the c-tree Reference Guide contain the correspondence between the index file number (keyno) and the associated data file.

Does not support duplicate allowed (non-unique) indexes if 4-byte record offset is not known. Use GetGTERecord(), or a similar function, with duplicate keys.

Return

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

Example

FILNO    part_idx;
TEXT     part_key[25];

struct invd {
    TEXT     delflg[4];
    LONG     part_no;
    LONG     on_hand;
    LONG     on_order;
    TEXT     part_name[60];
} recbuf;

printf("\nEnter part name: ");
scanf("%24s",part_key);

switch (GetRecord(part_idx,part_key,&recbuf)) {

case NO_ERROR:
    printf("\nParts on order for %s = %ld",
           recbuf.part_name,recbuf.on_order);
    break;

case DLOK_ERR:
    printf("\nCould not get record lock.");
    break;

case INOT_ERR:
    printf("\nPart name not on file.");
    break;

default:
    printf("\nProgramming Error (code = %d file = %d)", isam_err,isam_fil);
}

Limitations

No check is made to determine if recptr points to a region sufficiently large to accept a data record. If the area is too small, either code or data will be clobbered.

Does not support duplicate allowed (non-unique) indexes if 4-byte record offset is not known. Use GetGTERecord(), or a similar function, with duplicate keys.

See also

GetGTERecord(), TransformKey(), CreateIFile(), ReReadVRecord()

To double performance, see ChangeISAMContext.

GetSerialNbr

Get current data file sequence number.

Short Name

SERIALNUM()

Type

Low-Level data file function

Declaration

LONG GetSerialNbr(FILNO datno) 

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

GetSerialNbr() returns the current sequence number for data file datno used in ISAM applications using a SRLSEG key segment mode. Use ctGETHGH() to retrieve the high-word portion of an 8-byte sequence number.

When the SRLSEG key segment mode is used in an index, each call to NewData() or NewVData() increments the sequence number in the header of the associated data file. Calls to AddRecord() and AddVRecord() automatically invoke NewData() and NewVData(), respectively.

To manually manage serial numbers, use the OPS_SERIAL_UPD status_word described in the SetOperationState() function description.

Return

GetSerialNbr() returns a long integer containing the current sequence number. If an error occurs (such as data file not in use), GetSerialNbr() returns a zero value. Check uerr_cod for the error code. See c-tree Error Codes in the c-tree Programmer’s Reference Guide for a complete listing of valid c-tree error values.

Example

FILNO     datno;

if (OpenCtFile(datno,"MYDATA.DAT",(ctVIRTUAL | ctEXCLUSIVE))){
    printf("\nCould not open data file with error %d", uerr_cod);
    exit(2);
}
printf("\n Last used sequence number for MYDATA is %ld.",
       GetSerialNbr(datno));
exit(0);

Limitations

Serial numbers are not guaranteed to be sequential.

See also

ctGETHGH(), NewData(), NewVData(), AddRecord(), AddVRecord(), SetOperationState and ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) in the c-tree Programmer’s Reference Guide.

GetServerInfo

Listen for server information via TCP/IP.

Short Name

GetServerInfo()

Type

Low-Level function

Declaration

NINT GetServerInfo(pTEXT buffer, NINT bufsiz)

Description

On the client side, GetServerInfo() listens on the default port and stores the broadcast string in buffer. If the default port is not used, change the value for the client by altering the following define in ctcomm.h:

#define ctsrvBROADCAST_PORT  5595

By default, GetServerInfo() times out after 90 seconds. Adjust this timeout value by setting the following define in ctoptn.h or ctree.mak:

#define myWAIT_SEC 90

Return

This routine returns NO_ERROR (0) if it executed properly, -1 if the buffer was smaller than the string it received, or the value of the system-level errno if an error occurred. Check your compiler’s documentation for valid errno values.

Example

TEXT      info_buf[128];
NINT      retval;
pTEXT     wptr;

ctrt_printf("Checking for Broadcast Servers .........\n");

if (retval = GetServerInfo(info_buf, (NINT)sizeof(info_buf))) {
    ctrt_printf("Error getting available servers [%ld] \n",
                (LONG)retval);
}

if ((ctrt_strlen(info_buf) < 1) && !retval) {
    printf("No Broadcasting Servers Available \n");
} else {
    if ((wptr = strchr(info_buf,'|')))
        *wptr = '@';
    if ((wptr = strchr(info_buf,'|')))
        *wptr = '\0';
    ctrt_printf("We will attempt a connection to [%s] on port
               [%s].\n", info_buf, ++wptr);
    *svn = info_buf;
}

See also

• Server Name Broadcast Feature

GetServerInfoXtd

Listen for server information via TCP/IP, Extended Version.

Short Name

GetServerInfoXtd()

Type

Low-Level function

Declaration

NINT GetServerInfoXtd(pTEXT buffer, NINT bufsiz, UCOUNT port, LONG sec)

Description

GetServerInfoXtd() listens for a broadcasting FairCom Server on TCP/IP port port for sec seconds before timing out. The port value should match the TCP/IP port set in the Server BROADCAST_PORT keyword. A negative sec defaults to 90 seconds. If a broadcast is received, up to bufsiz bytes are stored at buffer.

Return

This routine returns NO_ERROR (0) if executed properly, -1 if the buffer was smaller than the string it received, or the value of the system-level errno if an error occurred. Check your compiler’s documentation for valid errno values.

Example

TEXT      info_buf[128];
NINT      retval;
pTEXT     wptr;
UCOUNT    port = myBroadcastPort;
LONG      sec = myBroadcastTimout;

ctrt_printf("Checking for Broadcast Servers .........\n");

if (retval = GetServerInfoXtd(info_buf, (NINT) sizeof(info_buf), port, sec)) {
    ctrt_printf("Error getting available servers [%ld] \n",
                (LONG)retval);
}

if ((ctrt_strlen(info_buf) < 1) && !retval) {
    printf("No Broadcasting Servers Available \n");
} else {
    if ((wptr = strchr(info_buf,'|')))
        *wptr = '@';
    if ((wptr = strchr(info_buf,'|')))
        *wptr = '\0';
    ctrt_printf("We will attempt a connection to [%s] on port
               [%s].\n", info_buf, ++wptr);
    *svn = info_buf;
}

See also

GetServerInfo()

• Server Name Broadcast Feature

GetSuperFileNames

Retrieve superfile member name.

Short Name

GETMNAME()

Type

Low-Level function

Declaration

COUNT GetSuperFileNames(FILNO filno, pTEXT nambuf,
                        VRLEN buflen, COUNT memberNo)

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

GetSuperFileNames() retrieves the superfile member name for member number memberNo in superfile filno. After successful execution, the nambuf array, which is buflen bytes long, contains the superfile member name for member number memberNo.

Return

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

Example

LON   buflen=64
TEXT  nambuf[buflen];   /* superfile member name buffer */
COUNT ret=0;           /* function return           */
FILNO membno;          /* member # for loop control    */

/*list superfile member names for superfile number 5   */
for (membno =1; ret == 0; membno ++)
{
    if (ret=GetSuperFileNames(5,nambuf,buflen, membno))
        printf("\nError on GETMNAME, error = %d decimal",
               ret) ;
    else
        printf("\n%s is member #%d of superfile #5", nambuf, membno);
}

GetSymbolicNames

Retrieve symbolic information about file.

Short Name

GETNAM()

Type

Low-Level function

Declaration

COUNT GetSymbolicNames(FILNO filno, pTEXT nambuf, VRLEN buflen, COUNT mode);

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 s

GetSymbolicNames() accesses items of information relating to file filno. Use mode to specify the type of information to return in nambuf. The following values can be used for mode:

Modes >= 128 do NOT require a valid file number

The ctTM structure is as shown below:

    typedef struct cttm {
        LONG    tm_sec;
        LONG    tm_min;
        LONG    tm_hour;
        LONG    tm_mday;
        LONG    tm_mon;
        LONG    tm_year;
        LONG    tm_wday;
        LONG    tm_yday;
        LONG    tm_isdst;
        } ctTM;

Return

The return value will be NO_ERROR (0) if no error has occurred. The information will be returned in nambuf. Otherwise, an error code will be returned.

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

Example

FILNO filnum;
TEXT  buffer[128];

if (GetSymbolicNames(filnum, buffer, 128L, FILNAM) == NO_ERROR)
    printf("\nFile Name is %s",buffer);

See also

GetCtFileInfo()

GetVRecord

Read the variable-length record with a key equal to target.

Short Name

EQLVREC()

Type

ISAM function

Declaration

COUNT GetVRecord(FILNO keyno, pVOID target, pVOID recptr, pVRLEN plen)

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

GetVRecord() is the same as its fixed-length counterpart, GetRecord(), except one argument has been added: plen.

plen acts as both an input and output parameter:

• On input, plen contains the length of the output buffer.
• On output, the contents of plen is the actual data-record length. If the length of the output buffer is less than the actual record length, a partial read is performed. If an error occurs, plen is unspecified.

Read the function description for GetRecord() for additional important information.

Return

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

See also

GetRecord(), GetGTEVRecord(), GetGTVRecord(), GetLTEVRecord(), TransformKey()

To double performance, see ChangeISAMContext.

GetXtdCreateBlock

Retrieves the extended file creation block, XCREblk.

Short Name

GETXCREBLK()

Type

Utility Function

Declaration

NINT GetXtdCreateBlock(FILNO filno, pXCREblk pxcreblk)

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

GetXtdCreateBlock() fills the structure pointed to by pxcreblk with the contents of an XCREblk corresponding to the extended create attributes for filno. Use GetXtdCreateBlock() to retrieve the XCREblk for an existing file so that a file can be created with the same extended create attributes.

Note: It is legitimate to call GetXtdCreateBlock() for files created using the Standard or Extended format. The resulting XCREblk from a call for a Standard format file can be used in a call to an extended create routine, and the result should be a Standard format (V6 compatible) file.

Return

If pxcreblk is NULL, then PNUL_ERR (540) is returned. If filno is not opened, FACS_ERR (26) is returned. If filno corresponds to an index member, KMEM_ERR (23) is returned. Otherwise, the structure is filled in and NO_ERROR (0) is returned.

Limitations

Must be called for each physical file.

See also

SetFileSegments()

GetXtdKeySegmentDef

Retrieves the requested extended key segment definition.

Short Name

GETKSEGDEF()

Type

ISAM data definition

Declaration

NINT GetXtdKeySegmentDef(FILNO filno, NINT segno, pctKSEGDEF pkdef) 

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

GetXtdKeySegmentDef() retrieves (i.e., fills in the elements of a ctKSEGDEF structure for) the requested extended key segment definition to pkdef, except that the kseg_type member of the pkdef structure should be set on input to the type of segment to be retrieved.

For example, to retrieve an ICU Unicode definition, set the kseg_type member to ctKSEG_Type_UNICODE before calling GetXtdKeySegmentDef(). If GetXtdKeySegmentDef() is called with ctKSEGhandle for the filno parameter and the handle value is passed in via the segno parameter (as shown in the third row in the table below), then the kseg_type member of the structure is ignored on input since the handle uniquely identifies the particular definition. On output, the kseg_type member will be set to the type of segment.

One of the main reasons to call GetXtdKeySegmentDef() is to be able to examine the actual locale being used for the ICU collation routines.

The filno and segno values determine which definition is returned, as follows:

Return

If successful, GetXtdKeySegmentDef() returns the handle associated with the definition. GetXtdKeySegmentDef() returns a negative value upon error, where the absolute value of the return value is the error code. The most common errors are shown below. See c-tree Error Codes in the c-tree Reference Guide for a complete listing of valid c-tree error values.

Example

See the API example in “Unicode Support”.

See also

PutXtdKeySegmentDef() (PutXtdKeySegmentDef, PutXtdKeySegmentDef), TransformXtdSegment()