NbrOfKeyEntries

Number of entries in index file.

Short Name

IDXENT()

Type

Low-Level index file function

Declaration

LONG NbrOfKeyEntries(FILNO keyno)

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

NbrOfKeyEntries() returns the number of entries in index file number keyno.

Note: A huge file may return values greater than 4 GB. This function returns the low-order 4-byte word of the 8-byte number of keys. To get the high-order 4-byte word, call ctGETHGH(). A return of zero is not necessarily an error if there are exactly a multiple 4 GB worth of key values.

Return

If an error occurs or the index file is empty, NbrOfKeyEntries() returns zero. Otherwise, NbrOfKeyEntries() returns the number of entries in the index file. When NbrOfKeyEntries() returns a zero, check uerr_cod: if uerr_cod is non-zero, an error condition was detected; otherwise, no key values are in the index. 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     keyno;

scanf("%d",&keyno);
printf("\nThere are %ld entries in index #%d.",
       NbrOfKeyEntries(keyno),keyno);

Limitations

With Standalone Multi-user systems, or when updates are immediately forced to disk, the time to add or delete an index entry can be reduced if the number of index entries is not maintained. By default, c-tree maintains this information. To disable this feature, add #define NO_IDXENT to the bottom of ctoptn.h/ctree.mak. By adding this define, multi-user, non-server applications may experience a performance gain. Therefore, we suggest you only use this function if it is very important to quickly determine the number of index entries.

NbrOfKeysInRange

Return the number of active index entries found between two targets .

Short Name

RNGENT()

Type

Low-Level index file function

Declaration

LONG NbrOfKeysInRange(FILNO keyno, pVOID idxval1, pVOID idxval2)

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

NbrOfKeysInRange() returns the number of active index entries found between idxval1 and idxval2 for index file keyno. idxval1 and idxval2 must be properly formed keys, as is necessary with any c-tree function that retrieves data using indexes. This function is very helpful for controlling list boxes requiring “thumb operations”.

Note: A huge file may return values greater than 4 GB. This function returns the low-order 4-byte word of the 8-byte number of keys. To get the high-order 4-byte word, call ctGETHGH(). A return of zero is not necessarily an error if there are exactly a multiple 4 GB worth of key values.

Return

On success, NbrOfKeysInRange() returns the number of active index entries found between the given targets. If an error occurs or the index file is empty, NbrOfKeysInRange() returns zero. When NbrOfKeysInRange() returns zero, check uerr_cod: if uerr_cod is non-zero, an error condition was detected; otherwise, no key values are in the index. 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 uses a duplicate allowed index over customer name. The code prompts the user for a beginning name and an ending name for the range. ActiveRange() takes the number of active index entries between the two values entered by the user.

Example

#define maxbuf 40

TEXT      idxval1[maxbuf];             /* input buffer one */
TEXT      idxval2[maxbuf];             /* input buffer two */
LONG      ActiveRange;

memset(idxval1,' ',maxbuf);
printf("\n\tEnter first name for range:");
gets(idxval1);
TransformKey(2,idxval1);      /* properly form index value 1 */

memset(idxval2,' ',maxbuf);
printf("\n\tEnter last name for range:");
gets(idxval2);
TransformKey(2,idxval2);      /* properly form index value 2 */

ActiveRange = NbrOfKeysInRange(2,idxval1,idxval2);
printf("\nRNGENT for Parent Key is %ld uerr_cod = %d", ActiveRange,uerr_cod);

See also

GetORDKey(), NbrOfKeyEntries()

NbrOfRecords

Get the number of active records in fixed-length data file.

Short Name

DATENT()

Type

Low-Level fixed-length data file function

Declaration

LONG NbrOfRecords(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

NbrOfRecords() returns the number of active data records for the fixed length data file designated by datno.

Each time a new record is added to the file, the count of active records is incremented. Each time a record is deleted, the active count is decremented. A record is added by the Low-Level function NewData() or the ISAM function AddRecord(). A record is deleted by the Low-Level function ReleaseData() or the ISAM function DeleteRecord().

Note: A huge file may return values greater than 4 GB. This function returns the low-order 4-byte word of the 8-byte number of keys. To get the high-order 4-byte word, call ctGETHGH(). A return of zero is not necessarily an error if there are exactly a multiple 4 GB worth of key values.

Return

If an error occurs or if there are no active data records, NbrOfRecords() returns a value of zero. Otherwise, NbrOfRecords() returns the number of active fixed data records in the data file. After a call to NbrOfRecords() returns a zero, check the value of uerr_cod: if uerr_cod is non-zero, an error condition was detected; otherwise, no active records are in the file. 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;

scanf("%d",&datno);
printf("\nThere are %ld active records in file #%d.",
NbrOfRecords(datno),datno);

See also

NewData(), AddRecord(), DeleteRecord(), ReleaseData()

NewData

Get next available fixed-length data record position.

Short Name

NEWREC()

Type

Low-Level data file function

Declaration

LONG NewData(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

NewData() determines the next available data record position for fixed-length data file datno. If records have been deleted via ReleaseData, they are reused by NewData() before the file size is extended.

Each call to NewData() increments the serial number associated with the file. The ISAM level key segment mode of three (SRLSEG) permits this serial number to be part of a key value to enable chronologically, or reverse chronologically, ordered key values. See ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) in the c-tree Programmer’s Reference Guide.

Note: In multi-user systems, NewData() automatically acquires a data record lock on the newly acquired record. This lock should be released using LockCtData() after writing the contents of the new record.

Return

NewData() returns the data record position of the next available record. If an error occurs, NewData() returns a zero and uerr_cod is set to a non-zero value.

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

Example

LONG      recd;
FILNO     dfil;
pTEXT     recptr;

if (recd = NewData(dfil))
    if (WriteData(dfil, recd, recptr) == 0)
        if (LockCtData(dfil, ctFREE, recd) == 0)
            printf("\nSuccessful addition of new record.");
        else
            printf("\nError %d unlocking record.", uerr_cod);
    else
        printf("\nError %d writing record.", uerr_cod);
else
    printf("\nError %d getting new record pointer.", uerr_cod);

Limitations

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

ReleaseData(), LockCtData(), NewVData()

Data File Layout

NewVData

Get next available variable-length data record position.

Short Name

NEWVREC()

Type

Low-Level data file function

Declaration

LONG NewVData(FILNO datno, VRLEN varlen)

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

NewVData() determines the next available data record position for variable-length data file datno. If records have been deleted via ReleaseVData(), and if they are large enough, they are reused by NewVData() before the file size is extended.

Each call to NewVData() increments the serial number associated with the file. The ISAM level key segment mode of three (SRLSEG) permits this serial number to be part of a key value to enable chronologically, or reverse chronologically, ordered key values. See ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) in the c-tree Programmer’s Reference Guide.

Note: In multi-user systems, NewVData() automatically acquires a data record lock on the newly acquired record. This lock should be released using LockCtData() after writing the contents of the new record.

A 10-byte control block specifying the record length and the length used precedes each variable-length record whether the record is active or not.

Return

NewVData() returns the data record position of the next available record. If an error occurs, NewVData() returns a zero and uerr_cod is set to a non-zero value.

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

Example

LONG      recd;
FILNO     dfil;
VRLEN     varlen;
pTEXT     recptr;

varlen = strlen(recptr);

if (recd = NewVData(dfil, varlen))
    if (WriteVData(dfil, recd, recptr, varlen) == 0)
        if (LockCtData(dfil, ctFREE, recd) == 0)
            printf("\nSuccessful addition of new record.");
        else
            printf("\nError %d unlocking record.", uerr_cod);
    else
        printf("\nError %d writing record.", uerr_cod);
else
    printf("\nError %d getting new record pointer.", uerr_cod);

Limitations

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

ctSETHGH(), ctGETHGH(), ReleaseVData(), LockCtData(), NewData()

NextCtree

Change to the next registered c-tree instance.

Short Name

NXTCTREE()

Type

Low-Level function

Declaration

pTEXT NextCtree() 

Description

NextCtree() cycles to the next available c-tree instance.

When multiple instances of c-tree are established with RegisterCtree(), control blocks are connected via a link list. The last control block points back to the first. Therefore, a NextCtree() call when the last instance is current results in the first instance becoming current.

Repeated calls to NextCtree() result in continually looping through all c-tree instances. In the example program ctlxmg, the reference name of the first instance is saved to determine the “end-of-instances”.

Return

A successful NextCtree() call returns the pointer to the instance reference name. Each instance reference name, up to 31 bytes and a NULL terminator in length, is originally registered with c-tree using RegisterCtree(). If there are no active instances, a NULL will be returned.

See also

SwitchCtree(), RegisterCtree(), WhichCtree(), GetCtreePointer(), UnRegisterCtree()

NextInRange

Read the next data record in a range

Short Name

NXTRNG()

Type

ISAM function

Declaration

COUNT NextInRange(FILNO keyval, 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

Read the next data record in a range established by a call to AllocateRange(). If successful, the record becomes the current ISAM record for the associated data file. A successful NextInRange() defines a current key value set, and subsequent calls to NextInRange() or PreviousInRange() will read the other records in the range.

If the data file has variable-length records, only the fixed-length portion of the record is actually read. You can use ReReadVRecord() to retrieve the whole record, including the variable-length portion. You can use NextInVRange() to read the whole variable-length record with one function call.

Return

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

See also

AllocateRange(), EstimateRange(), FirstInRange(), FirstInVRange(), FreeRange(), LastInRange(), LastInVRange(), NextInVRange(), PreviousInRange(), PreviousInVRange()

NextInSet

Read the next data record in the set defined by target.

Short Name

NXTSET()

Type

ISAM function

Declaration

COUNT NextInSet(FILNO keyno, 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

NextInSet() reads the next data record in the set of data records whose keys match the set created by an earlier set function call. If successful, this record becomes the current ISAM record for the associated data file. If an error occurs or no key value matches the target, the current ISAM record is not updated, and no key value set is defined.

If the data file has variable-length records, 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 NextInSet(). Note that ReReadVRecord() requires 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 ISAM parameter file described in c-tree Error Codes of the c-tree Programmer’s Reference Guide contains the correspondence 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

FILNO        keyfil;
TEXT         target[24],recbuf[320];

printf("\nEnter set value:");
scanf("%23s",target);
FirstInSet(keyfil,target,recbuf,strlen(target));
while (isam_err == NO_ERROR) {
   process_data();
   NextInSet(keyfil,recbuf);
}

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

FirstInSet(), PreviousInSet(), LastInSet(), PositionSet(), ChangeSet(), CreateIFile(), ReReadVRecord(), TransformKey()

NextInVRange

Read the next data record in a range

Short Name

NXTVRNG()

Type

ISAM function

Declaration

COUNT NextInVRange(FILNO keyval, 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

Read the next data record in a range established by a call to AllocateRange(). If successful, the record becomes the current ISAM record for the associated data file. A successful NextInVRange() defines a current key value set, and subsequent calls to NextInVRange() or PreviousInVRange() will read the other records in the range.

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.

Return

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

See also

AllocateRange(), EstimateRange(), FirstInRange(), FirstInVRange(), FreeRange(), LastInRange(), LastInVRange(), NextInRange(), PreviousInRange(), PreviousInVRange()

NextInVSet

Read the next variable-length data record in the set defined by target.

Short Name

NXTVSET()

Type

ISAM function

Declaration

COUNT NextInVSet(FILNO filno, 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

NextInVSet() is identical to it’s fixed-length counterpart, NextInSet(), except that it reads the next variable-length data record in the set defined by target and siglen. If successful, this record becomes the current ISAM record for the associated data file.

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 NextInSet() for additional important information.

Return

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

See also

NextInSet(), FirstInVSet(), PreviousInVSet(), TransformKey()

NextKey

Find the next entry in an index file.

Short Name

NXTKEY()

Type

Low-Level index file function

Declaration

LONG NextKey(FILNO keyno, 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

NextKey() searches index file keyno for the next entry in the index. If successful, it copies the index entry into the space pointed to by idxval. NextKey() fails if it is the first index search routine called after the index is opened, or if the entry found before the call to NextKey() is the last entry in the index. Repeated calls to NextKey() move through the index in ascending key value order.

Return

NextKey() returns the data record position associated with the next entry in the index file. If the index is empty or an error is detected, NextKey() returns zero. If NextKey() returns zero, check uerr_cod to see if an error occurred: if uerr_cod is also zero, then the index is empty; otherwise, an error condition was detected. See c-tree Error Codes in the c-tree Programmer’s Reference Guide for a complete listing of valid c-tree error values.

Example

LONG      recbyt;
TEXT      idxval[10];  /* 10 byte key, no duplicates */
FILNO     keyno;

recbyt = FirstKey(keyno,idxval);
while (recbyt) {
    printf("\nIndex Entry %.10s found in record #%ld",
            idxval,recbyt);
    recbyt = NextKey(keyno,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. Use GetCtFileInfo() to determine the key length.

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 is if binary key values will be displayed on a LOW_HIGH machine, it will be necessary to reverse any numeric segments. Key Segment Modes (Key Segment Modes, /doc/ctreeplus/30863.htm) in the c-tree Programmer’s Reference Guide contains suggestions for manipulating the key value.

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(), GetCtFileInfo(), LastKey(), PreviousKey()

NextRecord

Read the next data record.

Short Name

NXTREC()

Type

ISAM function

Declaration

COUNT NextRecord(FILNO filno, 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

NextRecord() retrieves the next data record found. If filno designates an index file, NextRecord() reads the next data record based on the key sequential order of entries in index file number filno. If filno designates a data file, NextRecord() reads the next active data record, in physical sequential order. If successful, the next record becomes the current ISAM record for the associated data file. If an error occurs or there are no entries, the current ISAM record is not updated.

If filno designates a data file that is a member of a Superfile, NextRecord() may not reliably return the next physical active data record, though it will retrieve a record.

If the data file has variable-length records, 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 NextRecord(). Note that ReReadVRecord() requires the size of the buffer area so that it can check if sufficient space is available.

If NextRecord() is called with an index number, the data file number involved is not directly described. The ISAM parameters described in ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) of the c-tree Programmer’s Reference Guide contain the correspondence between the index number and the associated data file.

NextRecord() can move sequentially through a data file based on one index then switch to another index. For example, moving through an inventory file in part number order before switching to part name order by changing the keyno parameter in the NextRecord() call.

As of c-tree V8.14, c-tree sets the current ISAM position after a record is added such that the next or previous record can be read without having to re-read the record just added. Prior to V8.14, the current ISAM position was not set to a newly-added record and an INOT_ERR (101) error would result if you tried to read either the next or previous record.

Return

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

Example

FILNO     acct_idx, test;
TEXT      recbuf[320];

test = FirstRecord(acct_idx,recbuf);
while (test == NO_ERROR) {
    post_interest(recbuf);
    test = NextRecord(acct_idx,recbuf);
}

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

FirstRecord(), PreviousRecord(), LastRecord(), CreateIFile(), ReReadVRecord()

NextVRecord

Read the next variable-length data record in the data file.

Short Name

NXTVREC()

Type

ISAM function

Declaration

COUNT NextVRecord(FILNO filno, 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

NextVRecord() is identical to it’s fixed-length counterpart, NextRecord(), except that it reads the next variable-length data record. If successful, this record becomes the current ISAM record for the associated data file.

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 NextRecord() for additional important information.

As of c-tree V8.14, c-tree sets the current ISAM position after a record is added such that the next or previous record can be read without having to re-read the record just added. Prior to V8.14, the current ISAM position was not set to a newly-added record and an INOT_ERR (101) error would result if you tried to read either the next or previous record.

Return

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

See also

NextRecord(), PreviousVRecord(), TransformKey()