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
| Value | Symbolic Constant | Explanation |
|---|---|---|
| 0 | NO_ERROR | Successful addition of a new data record. |
| 2 | KDUP_ERR | Duplicate key value found in index file number isam_fil. Data record not added and no key values inserted. |
| 31 | DELFLG_ERR | Attempt to re-use data record whose first byte is not set to ff (hex). Either the data file is corrupted,, in which case you should rebuild the ISAM files,, or the C255 constant defined in ctcmpl.h is not set properly. |
| 33 | DNUL_ERR | recptr is null. No action taken. |
| 37 | WRITE_ERR | Most likely disk or directory is full. Files are left in an indeterminate state and should be rebuilt. |
| 48 | FMOD_ERR | datno is assigned to a variable record length file. |
| 199 | NSCH_ERR | Key segment refers to schema, but schema not defined. |
| 433 | SSCH_ERR | Segment definition inconsistent with schema. |
| 445 | SDAT_ERR | Not enough data to assembly key. |
| 446 | BMOD_ERR | Invalid key mode. |
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 fileThis 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