FairCom ISAM for C

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.

Value	Symbolic Constant	Explanation
0	NO_ERROR	Successful lock/unlock operation.
31	DELFLG_ERR	First byte of record about to be reused does not equal the delete flag (ff hex).
48	FMOD_ERR	NewData() called for an index file.

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.