NewVData

Get next available variable length data record position.

Short Name

NEWVREC()

Type

Low-level data file function

Declaration

LONG NewVData(COUNT datno, VRLEN varlen)

Description

NewVData() determines the next available data record position for variable-length data file datno. If records have been deleted via ReleaseVData(), and if they are large enough, they are reused by NewVData() before the file size is extended.

Each call to NewVData() 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, NewVData() 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.

A 10-byte control block specifying the record length and the length used precedes each variable-length record whether the record is active or not.

Return

NewVData() returns the data record position of the next available record. If an error occurs, NewVData() returns a zero and uerr_cod is set to a non-zero value.

Value	Symbolic Constant	Explanation
0	NO_ERROR	Successful lock/unlock operation.
48	FMOD_ERR	NewVData() called for an index file.
147	VDLFLG_ERR	The record to be reused is not marked deleted. The file is corrupt and must be rebuilt.

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.

Example

LONG      recd;

COUNT     dfil;

VRLEN     varlen;

pTEXT     recptr;


varlen = strlen(recptr);


if (recd = NewVData(dfil, varlen))

    if (WriteVData(dfil, recd, recptr, varlen) == 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.