NewData

Get next available fixed length data record position.

Short Name

NEWREC()

Type

Low-level data file function

Declaration

LONG NewData(COUNT datno)

Description

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” in the c-tree Plus 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.

Each data file starts with a header record which contains information about its size, record length and deleted records. The header record begins at byte position zero. The first usable data record position is given by the following expression, where we assume the integer division truncates the result:

((128 + record_length - 1) / record_length) * record_length

For example, a record length of 30 bytes means that the first actual data record will start at byte position 150. The above expression guarantees that the first usable record always starts after the first 128 bytes of the file AND on a record length boundary. If resources are defined, this equation will be off by any resource records located prior to the first record. Resource records are identified by a 0xFEFE record mark. The length of the resource is determined by the retot element to the RESHDR structure located in ctstrc.h.

Note: Superfile members do not satisfy the above expression, nor do they fall on record length boundaries.

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 Plus Error Codes for a complete listing of valid c-tree Plus error values.

Example

LONG      recd;

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