Abort

Abort the current transaction in progress.

Short Name

TRANABT()

Type

Low-Level function

Declaration

COUNT Abort()

Description

Abort() aborts the current transaction. All file update actions since the last Begin() will not be committed. All known locks are released, and the transaction ends.

Return

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

Example

COUNT     savepoint;

void domaster() {
    Begin(ctENABLE|ctTRNLOG);   /* start transaction with locks  */
    while(another()); {     /* get next record to add        */
        savepoint = SetSavePoint(); /* get save point at
                             beginning of each master record */
        if (add_master() < 0)
            Abort();        /* abort if can't add master rec */
        dodetail();         /* process detail records        */
    }
    if (Commit(ctFREE)0)
        printf("\nError %d in transaction",uerr_cod);
    return;
}

void dodetail() {
    while(moredetail()); {   /*get next detail record to add */
        if (add_detail()<0) {    /* add details, if possible */
            RestoreSavePoint(savepoint)
                             /* with error, return to savept */
            return;
        }
    }
}

See also

AbortXtd, Begin, ClearSavePoint, Commit, RestoreSavePoint, SetSavePoint, TRANRDY

AbortXtd

Abort the current transaction in progress (extended version).

Short Name

TRANABTX()

Type

Low-Level function

Declaration

COUNT AbortXtd(COUNT lokmod)

Description

AbortXtd() is an extended version of Abort that permits control of locks on abort. AbortXtd() accepts mode arguments similar to Commit(). lokmod values are described in the following table.

Return

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

See also

Abort, Begin, ClearSavePoint, Commit, LockISAM, RestoreSavePoint, SetSavePoint, TRANRDY

AddAutoSysTimeFields

Define which of the fields are automatically set by the server using the current server system time (in GMT time zone).

Type

ISAM Function

Declaration

NINT AddAutoSysTimeFields(FILNO datno, pA_STFIELDS defs)

Description

• datno - the data file number. 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 TypeDef Change
• defs - pointer to fields definition structure:

typedef struct astfields {
 COUNT version;                     /* Version of this structure   */
 COUNT entries;                     /* number of entries in fields array  */
 LONG pad;                          /* padding to ensure struct alignment */
 pA_STFIELD fields;                 /* fields array */
} A_STFIELDS, *pA_STFIELDS;

• version - the version of the structure. must be set to A_STFIELDS_VERS_V01.
• entries - the number of fields that needs to be automatically set with the system time. It must match the number of entries in the fields array.
• fields - pointer to an array of field settings 

typedef struct astfield {
 LONG fieldno;                      /* field number */
 TEXT mode;                         /* set time  */
} A_STFIELD, *pA_STFIELD;

• fieldno - the field number in the DODA for the field that is set to auto setting with system time stamp.
• mode - in which condition the field gets populated. Possible values:

CT_AUTOSYSTIME_CREATE 0x01 - when the record gets added

CT_AUTOSYSTIME_UPDATE 0x02 - when the record gets rewritten/updated.

Return

NO_ERROR on success

addChangeIDfield

Add a change ID field to the specified data file.

Declaration

ctCONV NINT ctDECL addChangeIDfield (FILNO datno, NINT fieldno);

Description

[IN] datno- Data file number.

[IN] fieldno- The field number in the DODA for the change ID field.

Return Values

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

AddCtResource

Add a Resource to a data file.

Short Name

ADDRES()

Type

Low-Level file resource function

Declaration

COUNT AddCtResource(FILNO filno, pVOID resptr, 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 TypeDef Change

AddCtResource() is used to add a Resource to filno. Every Resource is identified by a unique combination of a Resource Type and a Resource Number. The Resource Number can optionally be assigned by FairCom DB during the call to AddCtResource(). In addition, each Resource can be identified by a Resource Name. The Resource Name is not guaranteed to be unique.

resptr points to a resource data block. This block contains the following fields:

The Resource Type must be a value greater than 65536. 0 through 65536 are reserved for FairCom use.

If the Resource Number is a value of 0xffffffffL, FairCom DB assigns this Resource the next available Resource Number for this Resource Type in the specified data file. AddCtResource() places assigned Resource Number in the Resource Data Block.

The Resource Name is optional. FairCom DB does not guarantee unique Resource Names. Names starting with “FC!” or “RD!”, are reserved for FairCom use.

The Resource Information is any collection of data that you wish to store as a Resource. It can be a character string, a structure, or any variable type.

Return

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

Example

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);

See also

GetCtResource, UpdateCtResource, and DeleteCtResource. Also refer to Resources.

addIDfield

Assign an IDENTITY attribute to a DODA field.

Declaration

NINT addIDfield(FILENO datno, LONG8 startval, LONG delta, NINT fieldno)

Description

addIDfield() assigns an IDfield (IDENTITY) auto-numbering attribute to a numeric field in a record. The field number is determined from the DODA. This value is incremented on each record addition. This IDfield concept is similar to a SRLSEG, however, requires no implicit index, which allows it to be much better performing.

Where:

• datno is the data file number - 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 TypeDef Change
• startval is the next value to be assigned to the field on add.
• delta is the value to increment each addition.
• fieldno is the DODA field offset (starting at zero).

IDfields 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 = addIDfield(fileno, nextid, 1, fldnum);
if (retval) {
printf("\tERROR: Failed to add ID field with error %d\n", retval);
}

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

delIDfield, getIDfield, wchIDfield, resetIDfield, IDfields - Extended support

IDfields - Extended support

Several aspects of IDfield behavior have been improved.

An issue was corrected in which rebuild did not properly set the IDfield state variable when records were added with IDfields already set and internal support disabled.

Additional changes were made to two aspects of IDfield support: overflow detection and unsigned IDfield support. Prior to these modifications, IDfields were treated as signed fields (regardless of the associated DODA properties for the IDfield), and the issue of overflow was ignored. These modifications affect how a new file supporting IDfields behaves and how an existing file (whose IDfield was created before these enhancements) behaves.

New Files

When a new file has an IDfield added, the associated DODA entry for the IDfield determines (a) whether the IDfield is signed or unsigned, and (b) the length of the IDfield for the purposes of detecting an overflow (or underflow) condition.

Overflow and underflow are reported as error IDVR_ERR (1002).

Existing Files

An old file with an existing IDfield that is opened (for update) for the first time has its IDfield resource updated to the new version. The IDfield remains signed unless the associated DODA entry is for an unsigned field type (as noted above), and overflow detection is enabled using the DODA field length to determine the IDfield size (for the purposes of overflow detection).

If the COMPATIBILITY keyword NO_IDFIELD_OVERFLOW_CONVERSION (see below) is in use, then the behavior of the IDfield will not change.

Note: It is possible that when the old file is upgraded to the new/enhanced IDfield support that it will be in overflow/underflow status. This can occur because operations on the old file caused an overflow or underflow (which was not being checked), evidence of the problem still remains after conversion to the IDfield support, and the update detects this unless NO_IDFIELD_OVERFLOW_DETECTION is in use (see below).

COMPATIBILITY KEYWORDS

NO_IDFIELD_OVERFLOW_CONVERSION

Old files behave as before, no overflow/under-flow detection

NO_IDFIELD_OVERFLOW_DETECTION

All tests for overflow/under-flow are ignored

Summary of keyword behavior:

None of the keywords:

Old files that are opened for update and new files have new IDfield with signed/unsigned fields (per DODA), and overflow/under-flow detection turned on.

NO_IDFIELD_OVERFLOW_CONVERSION only:

Old files behave as before and new files have new IDfield support with signed/unsigned fields (per DODA) and overflow/under-flow detection turned on.

NO_IDFIELD_OVERFLOW_DETECTION only:

Same as "None of the keywords" except that all tests for overflow/under-flow are skipped; but tables with the new IDfield support will have overflow detection enforced if this keyword is removed.

NO_IDFIELD_OVERFLOW_CONVERSION and NO_IDFIELD_OVERFLOW_DETECTION:

Old files behave as before and new files have new IDfield support with signed/unsigned fields (per DODA) and overflow/under-flow detection turned on, but all tests for overflow/under-flow are skipped.

The new function described below can be used to modify the IDfield signed/unsigned setting and the overflow detection setting on a table.

xtdatrIDfield(datno,xtdatr)

The new routine xtdatrIDfield( FILENO datno, LONG xtdatr ) can be used to (a) return the current bit fields for the extended attribute (when xtdatr is passed in as -1 on the call); or (b) set the bit fields as specified in xtdatr. In the event of an error, xtdatrIDfield() returns ‑1.

The extended attribute bit fields are defined in ctport.h:

IDfield_xtdatr_unsigned    unsigned IDfield [DODA field types: CT_CHARU, CT_INT2U,
                           CT_INT4U, CT_INT8U]
IDfield_xtdatr_overflwd    IDfield overflowed
IDfield_xtdatr_versn__2    IDfield with xtdatr support
IDfield_xtdatr_versn__1    IDfield without active xtdatr support: an old IDfield
                           with an up-to-date resource, but no overflow/under-flow
                           detection
IDfield_xtdatr_noovrflw    IDfield overflow detection is disabled
IDfield_xtdatr_signed      signed IDfield [remaining DODA field types]
 

Example

Given a DODA field as the 5th field {"cm_identity",NULL,CT_INT4U}:

printf("Setting ID field\n");
   if(rc = addIDfield(custmast_ifil.tfilno, 0, 1, 4))
  printf("addIDfield failed %d\n", rc);

   printf("Setting xtdatrID\n");
   if (xtdatrIDfield(custmast_ifil.tfilno, IDfield_xtdatr_versn__2 | IDfield_xtdatr_noovrflw ) == -1)
  printf("xtdatrID failed with %d\n", sysiocod);

Using xtdatrIDfield() as part of a TRANDEP file create sequence such as:

TRANBEG
CREIFILX()
addIDfield()
xtdatrIDfield()
TRANEND

would allow changing the default behavior of the IDfield (as described in New File section above). The signed/unsigned nature of the field could be changed or overflow/under-flow detection could be disabled (by turning on IDfield_xtdatr_noovrflw).

Note: xtdatrIDfield() could be called with an xtdatr of zero which would make the file appear, on its next open, as an old file not opened with the new support. It is also possible to explicitly set either of the IDfield_xtdatr_versn__1/2 bits. Calls to xtdatrIDfield will return an error, IDXA_ERR (1003), if the new xtdatr settings are not internally consistent. For example, both "versn" bits cannot be turned on, or one cannot clear the IDfield_xtdatr_overflwd bit unless the IDfield_xtdatr_noovrflw bit is turned on.

Return

When called with a xtdatr mode of -1, xtdatrIDfield() returns the currently assigned ID field extended bit mask.

When called with a supplied xtdatr mode, xtdatrIDfield() returns either:

• Success: - the new extended bit mask assigned, or;
• Error: -1

If -1 is returned then uerr_cod is set as follows and sysiocod contains one of the values as shown below (found in cterrc.h)

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

Note: If xtdatrIDfield is called, and IDfield_xtdatr_versn__2 is on, then if neither IDfield_xtdatr_signed/unsigned is specified, xtdatrIDfield() will use the associated DODA to determine the signed/unsigned attribute.

AddKey

Add key value to index file.

Short Name

ADDKEY()

Type

Low-Level index file function

Declaration

  COUNT AddKey(FILNO keyno, pVOID target, LONG recbyt, COUNT typadd)

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 TypeDef Change

AddKey() inserts the key value pointed to by target and the associated data record position recbyt into index file number keyno. typadd determines how a full B-Tree node is split. The symbolic constants defined in ctport.h, REGADD, INCADD, and DECADD, represent the three node splitting options:

Return

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

Example

TEXT target[11];
LONG recbyt;
COUNT name_key;

if (AddKey(name_key,target,recbyt,REGADD))
    printf("\nAddKey error = %d",uerr_cod);

Limitations

AddKey() does not pad key values. If passed a key value which is not completely specified to its full length, AddKey() uses whatever “garbage” follows the key value in memory up to the key length.

Key values added to an index allowing duplicate keys, (keydup = 1 in CreateIndexFile() or CreateIndexMember()), have their last 4 bytes overwritten by the associated data record position. In this way, identical key values become distinguishable.

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 Record Offsets Under Huge File Support.

See also

CreateIndexFile and CreateIndexMember specify the key value characteristics of length, type, and allowance for duplicate values at index file creation.

AddRecord

Add a new fixed-length data record and corresponding key values to ISAM files.

Short Name

ADDREC()

Type

ISAM function fixed-length record

Declaration

COUNT AddRecord(FILNO datno, 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 TypeDef Change

AddRecord(), short name ADDREC(), adds the fixed-length data record pointed to by recptr to data file number datno. It automatically adds the key values defined for the data file to their respective index files. If successful, the new data record becomes the current ISAM record for data file datno.

In multi-user applications, AddRecord() automatically causes a data record lock to be placed on the new record. Therefore, LockISAM(ctENABLE) and LockISAM(ctFREE) should be called before and after AddRecord(). However, with transaction processing locks are enabled and freed using Begin() and Commit(). LockCtData(ctFREE) can also be used if the record offset is known, to provide individual record lock control. Optionally, the SetOperationState() status_word OPS_UNLOCK_ADD automatically unlocks after each AddRecord().

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 of previous record.

Return

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

Example

FILNO invfil
struct invd {
   TEXT     delflg;
   LONG     part_no;
   TEXT     part_name[60];
   LONG     on_hand;
} recbuf;

scanf("%ld %59s %ld",&recbuf.part_no,recbuf.part_name, &recbuf.on_hand);
recbuf.delflg = '\0'; /* clear delete flag */
if (LockISAM(ctENABLE) || AddRecord(invfil,&recbuf) ||
      LockISAM(ctFREE))
    printf("\nAddRecord error %d in file %d",
         isam_err,isam_fil);

ADDREC DELFLG_ERR (31)

In extremely rare situations, it was possible for the delete stack to become corrupted on a data file after it went through automatic recovery. In these obscure scenarios, ADDREC could return a DELFLG_ERR error (31) following recovery. ADDREC and NEWREC failed with error 31 until the table was rebuilt. Instead of returning DELFLG_ERR, c-tree now discards its list of deleted records and retries the operation. This should prevent the error and allow the call to proceed normally. The following is logged to CTSTATUS:

WARNING: an invalid delete stack has been reset to zero for fixed length data file

This message indicates that all the space occupied by deleted records in that file at that point in time is lost and will not be re-used until the file is rebuilt or compacted.

Note: This is a Compatibility Change.

See also

ISAM Functions discusses how the relationship among the data files and their corresponding index files is specified. Begin, Commit, LockCtData, LockISAM, SetOperationState

AddVRecord

Add a new variable-length data record, and its corresponding key values, to ISAM files.

Short Name

ADDVREC()

Type

ISAM function variable-length record

Declaration

COUNT AddVRecord(FILNO datno, pVOID recptr, 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 TypeDef Change

AddVRecord() adds the data record with length in bytes given by varlen and pointed to by recptr to data file number datno. It automatically adds the key values defined for the data file to their respective index files. If successful, the new data record becomes the current ISAM record for datno. In multi-user applications, AddVRecord() automatically causes a data record lock to be placed on the new record. Therefore, LockISAM(ctENABLE) and LockISAM(ctFREE) should be called before and after AddVRecord(). However, if you are using transaction processing, (single-user and client/server models only), you will usually enable and free locks during the Begin() and Commit() functions.

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 of previous record.

Return

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

Example

FILNO invfil;
struct invd {
  LONG part_no;
  LONG on_hand;
  TEXT part_name[120];
} recbuf;

scanf("%ld %ld %119s",&recbuf.part_no,&recbuf.on_hand,
      recbuf.part_name);

if (LockISAM(ctENABLE) || AddVRecord(invfil,&recbuf,8 +
   strlen(recbuf.part_name)) || LockISAM(ctFREE))
     printf("\nAddVRecord error %d in file %d",isam_err, isam_fil);

See also

ISAM Functions discusses how the relationship among the data files and their corresponding index files is specified. Begin, Commit, LockCtData, LockISAM, SetOperationState, Commit, LockISAM

AllocateBatch

Optionally allocates buffer space for multiple batches (groups of records).

Short Name

ALCBAT()

TYPE

ISAM function

Declaration

COUNT AllocateBatch(COUNT numbat)

Description

AllocateBatch() is an optional part of the API called internally by ChangeBatch().

AllocateBatch() allocates data structures for multiple, simultaneous batches. Ordinarily the FairCom DB batch function, DoBatch(), is used for only one batch at a time. Each time ChangeBatch() is called with a previously unused numbat, a new batch structure is allocated and maintained by FairCom DB. Therefore, calling AllocateBatch() is optional, as it is automatically called by ChangeBatch().

Prior to c-tree V6.4B, the numbat parameter was a unique batch identification number. numbat is ignored by c‑tree V6.4B and after. See ChangeBatch() for more information.

Return

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

Example

See the ChangeBatch example.

See also

ChangeBatch, FreeBatch, DoBatch

AllocateRange

Establishes a new index range for ISAM record retrieval.

Short Name

ALCRNG()

Type

ISAM function

Declaration

COUNT AllocateRange(FILNO keyno, NINT segcount, pVOID lrange, pVOID urange, pNINT operators)

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

An index range is defined by specifying a range of values for one or more key segments.

AllocateRange() allocates buffer space and establishes a new range based on the segment values passed for the lower bound, upper bound and operators for each segment. keyno identifies the index file that should be used to establish the range. segcount indicates the number of index segment values for the range, and implicitly, the number of operators. lRange is a buffer with the lower range segment values, while uRange is a buffer with the upper range segment values. operators is an array of operators for each segment value.

The operators CTIX_EQ, CTIX_NE, CTIX_GT, CTIX_GE, CTIX_LE, CTIX_LT are open ended and use only the lRange buffer for range values. The uRange buffer is ignored and may be set to NULL for these operators.

The operators CTIX_BET, CTIX_BET_IE, CTIX_BET_EI, CTIX_BET_EE and CTIX_NOTBET use both lRange and uRange buffers to establish the lower and upper bound key values. The range is set for all index entries that are situated between the lower bound and upper bound values.

Segment values are stored in lRange and uRange buffers in the same order and type as the index segment definition.

If a previous range exists for this index, the previous range is released and the new range is established.

Return

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

Example

  /*
  ** 3 segment example for keyno 12
  */
  NINT ops[3] = {CTIX_LT,CTIX_BET,CTIX_NE};
  TEXT lbuf[22];
  TEXT ubuf[22]; 
  COUNT rc;

  memcpy(lbuf,"TUVWXYZ   ",10);
  memcpy(lbuf + 10,"00001000",8);
  memcpy(lbuf + 18,"AX00",4);

  memset(ubuf,0,22);
  memcpy(ubuf + 10,"00001999",8);

  rc = ALCRNG(12,3,lbuf,ubuf,ops);

See also

EstimateRange, FreeRange, FirstInRange, FirstInVRange, LastInRange, LastInVRange, NextInRange, NextInVRange, PreviousInRange, PreviousInVRange

AllocateSet

Optionally allocate key buffers for multiple, simultaneous sets.

Short Name

ALCSET()

Type

ISAM function

Declaration

COUNT AllocateSet(COUNT numset)

Description

AllocateSet() is called internally by ChangeSet() and is an optional part of the API.

AllocateSet() allocates key buffers for multiple, simultaneous sets. Ordinarily, the FairCom DB sequence set functions, FirstInSet(), NextInSet(), etc., are used for only one set at a time. Each call to ChangeSet() with a unique value allocates a new set maintained by FairCom DB. Calling AllocateSet() is optional, as ChangeSet() automatically calls AllocateSet() when necessary.

Prior to c-tree V6.4B, the numset parameter was a unique set identification number. numset is ignored by c-tree V6.4B and after.

See ChangeSet() for more information

Return

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

Example

See the ChangeSet example.

See also

ChangeSet, FreeSet, FirstInSet, LastInSet, PositionSet, NextInSet, PreviousInSet

AvailableFileNbr

Return next available FairCom DB file number.

Short Name

AVLFILNUM()

Type

Low-Level data file function

Declaration

COUNT AvailableFileNbr(COUNT numfils)

Description

AvailableFileNbr() returns a valid FairCom DB file number that is available for use (i.e., not presently assigned to a file). numfils is the number of consecutive file numbers required. If numfils consecutive file numbers are not available, AvailableFileNbr() returns -1.

This function does not consume the file number(s) returned. The file number is consumed only if you subsequently create or open a file with the returned file number. Therefore, two calls in succession to AvailableFileNbr(), without any intervening creates, opens, or closes, will return the same file number. However, the scope is local to your application. No multi-user interference is possible, since each application only references file numbers internally.

If used for a host superfile, remember to use an argument of 2.

Return

AvailableFileNbr() returns the first file number in the series requested. If the requested block of file numbers is not available, it returns -1. Check uerr_cod for the error value.

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

Example

FILENO super_number;
COUNT  retval;

super_number = AvailableFileNbr(2);
if (super_number == -1) {
    printf("\nNot enough file numbers available");
    exit(1);
}

retval = OpenCtFile(super_number,"superfil",
         ctPERMANENT | ctEXCLUSIVE | ctSUPERFILE);