FairCom ISAM for C

ReWritePartialRecord

Rewrites a partial fixed or variable-length record.

Declaration

COUNT ReWritePartialRecord (FILNO datno, pVOID recptr, VRLEN varlen);

Short Name

RWTPREC()

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

ReWritePartialRecord() permits a fixed or variable-length record to be updated (i.e., rewritten) without passing back an entire record image. It is only necessary to pass enough bytes to hold the fields that have been modified. As a matter of good practice, varlen should end on a field boundary. This routine is especially effective for files whose records start with status fields and end with potentially large variable-length fields. For example, for a record containing ID fields and status fields followed by a very large binary field, say a graphic image, and one desired to only change a status or ID field, it is not necessary to pass the entire record to ReWritePartialRecord() rather, only the first few bytes at the beginning of the record. This significantly reduces network traffic and improves performance.

There is a subtle difference between ReWriteVRecord() and ReWritePartialRecord() called with a varlen equal to the original record length: ReWritePartialRecord() assumes a well formed record and will permit a variable-length field to be truncated by the end of the record. ReWriteVRecord() assumes it must avoid field truncation, and would return error SDAT_ERR (445) under the same circumstance. Practically, ReWritePartialRecord() should not be used to perform a full rewrite and good practices would not permit a truncated record image for ReWriteVRecord().

ReWritePartialRecord() can only be used to rewrite with a partial record image that is less than or equal to the full record image length. An attempt to grow the existing record results in error VMAX_ERR (140). When updating records with ReWritePartialRecord() the partial record image must contain enough data to enable c-tree to construct all key segments for all indexes of the data file. ReWriteVRecord().should be used instead of ReWritePartialRecord() if any variable-length field of the record was resized, even if the resulting record length remains unchanged.

Return

Value	Symbolic Constant	Explanation
0	NO_ERROR	No error occurred.
2	KDUP_ERR	Duplicate key value detected in index file number isam_fil. Record update not performed.
22	FNUM_ERR	File number is out of range.
26	FACS_ERR	File number is not assigned to a file in use.
57	DADV_ERR	Proper lock not found by FairCom Server.
100	ICUR_ERR	No current ISAM record.
105	IUND_ERR	Could not undo a rejected ISAM update.
140	VMAX_ERR	Variable record length too long.
199	NSCH_ERR	Key segment refers to schema, but schema not defined.
433	SSCH_ERR	Segment definition inconsistent with schema.
445	SDAT_ERR	Not enough data to assemble key.
446	BMOD_ERR	Bad key segment mode.

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

Example

If a data file has a record structure that contains three fields: id (CT_INT4), status (CT_INT4) and description (CT_STRING), and the id field is never updated, but the status or the description field may be updated, the ReWritePartialRecord() or ReWriteVRecord() may be used, depending on which field was updated.

Example

typedef struct

{

LONG id;

LONG status;

TEXT description[MAX_DESCRIPTION];

} MYRECORD;

NINT UpdateMyRecord(FILNO datno, LONG id, LONG status, pTEXT description)

{

NINT eRet;

NINT partial = YES;

VRLENvarlen = sizeof(LONG)*2;

MYRECORD recbuf;

/* set the fixed portion of the record */

recbuf.id = id;

recbuf.status = status;

/* check if we need to set the description field */

if (description)

{

strcpy(recbuf.description, description);

partial = NO;

varlen += strlen(description) + 1;

}

/* update/rewrite the record */

if (partial)

eRet = ReWritePartialRecord(datno, &recbuf, varlen);

else

eRet = ReWriteVRecord(datno, &recbuf, varlen);

return eRet;

}

Limitations

An issue remains for how to perform the rewrite, partial or full, if the prior read of the record was itself partial (only the fixed portion of a variable-length record was read) and did not permit all of the internal key buffers to be updated. This issue remains in a pending state and you are advised to not attempt this sequence of operations. In addition, support for row level call callbacks has not been enabled for partitioned files during full or partial rewrites.