FairCom ISAM for C

ReadIsamVData

ISAM read variable-length data at record position.

Short Name

REDIVREC()

Type

ISAM function

Declaration

COUNT ReadIsamVData(FILNO datno, LONG recbyt, pVOID recptr, pVRLEN plen)

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

ReadIsamVData() reads a variable-length ISAM record and is the variable-length analog to ReadIsamData(). ReadIsamVData() reads the data at record position recbyt for data file datno into the buffer pointed to by recptr for plen bytes.

plen acts as both an input and output parameter:

On input, plen contains the length of the output buffer.
On output, the contents of plen is the actual data-record length. If the length of the output buffer is less than the actual record length, a partial read is performed. If an error occurs, plen is unspecified.

ReadIsamVData() decreases network traffic by eliminating the need to make two separate function calls as follows:

Retrieve the fixed-length portion of the record with an ISAM search routine, such as FirstRecord(),
Call ReReadVRecord() to retrieve the variable-length component.

As with the other variable-length ISAM functions, ReadIsamVData() can read all or a portion of the variable-length record, potentially further reducing network traffic.

Return

Value	Symbolic Constant	Explanation
0	NO_ERROR	Successful ISAM read operation.
33	DNUL_ERR	recptr is NULL. No data file read performed.
36	READ_ERR	Read error occurred. Bad record byte value.
42	DLOK_ERR	Could not get lock on data record. No data file read performed.
160	ITIM_ERR	Record deleted by another user.
633	NPLN_ERR	plen is NULL.
634	NLEN_ERR	*plen is negative on input.

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

Example

FILNO datno;

LONG recbyt[16];

TEXT recptr[1024];

VRLEN varlen;

/* fill in an array of record positions */

FillRecordByteArray(recbyt);

varlen = 64; /* set plen to 64 bytes */

/* read *plen bytes of the 10th record in the array */

if (ReadIsamVData(datno,recbyt[9],recptr,&varlen))

printf("\nCould not read 10th record, error = %d", isam_err);

else

printf("\nSuccessful record read at offset %ld", recbyt[10]);

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.