FairCom ISAM for C

NewVData

Get next available variable-length data record position.

Short Name

NEWVREC()

Type

Low-Level data file function

Declaration

LONG NewVData(FILNO datno, VRLEN varlen)

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

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 (ISAM Database Technology, /doc/ctreeplus/30841.htm) in the c-tree 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 Error Codes for a complete listing of valid c-tree error values.

Example

LONG recd;

FILNO 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. See also Record Offsets Under Huge File Support.