|
|
|
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:
IDfields requires a DAR resource (Direct Access Resource) embedded in the file. The DAR is a specialized high-speed resource.
Return
Value |
Symbolic Constant |
Explanation |
|---|---|---|
0 |
NO_ERROR |
Success |
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
|
|
|
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:
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)
Value |
uerr_cod |
Explanation |
|---|---|---|
1003 |
IDXA_ERR |
Invalid IDfield extended attribute (xtdatr) |
See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.
sysiocod |
validation issue |
1 |
mutually exclusive attributes |
2 |
specified version incompatible with other attributes |
3 |
if version reset to 0, no other attributes allowed |
4 |
cannot turn off overflowed indicator unless the no overflow detection attribute is turned on |
5 |
cannot turn on the overflowed indicator unless the no overflow detection attribute is off |
6 |
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.
