Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic


Assign an IDENTITY attribute to a DODA field.


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


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.


  • 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.



Symbolic Constant





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


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

Previous Topic

Next Topic

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



Old files behave as before, no overflow/under-flow 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.


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.


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.


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.


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,

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

IDfield_xtdatr_noovrflw IDfield overflow detection is disabled

IDfield_xtdatr_signed signed IDfield [remaining DODA field types]


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:






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.


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)






Invalid IDfield extended attribute (xtdatr)

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


validation issue


mutually exclusive attributes


specified version incompatible with other attributes


if version reset to 0, no other attributes allowed


cannot turn off overflowed indicator unless the no overflow detection attribute is turned on


cannot turn on the overflowed indicator unless the no overflow detection attribute is off


IDfield_xtdatr_versn__1 requires IDfield_xtdatr_noovrflw

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.