PURPOSE

Fchg, Fchg32 - change field occurrence value

SYNOPSIS

#include <stdio.h>
#include "fml.h"
int
Fchg(FBFR *fbfr, FLDID fieldid, FLDOCC oc, char *value, FLDLEN len)
#include "fml32.h"
int
Fchg32(FBFR32 *fbfr, FLDID32 fieldid, FLDOCC32 oc, char *value, FLDLEN32 len)

DESCRIPTION

Fchg() changes the value of a field in the buffer. fbfr is a pointer to a fielded buffer. fieldid is a field identifier. oc is the occurrence number of the field. value is a pointer to a new value, its type must be the same type as the value to be changed (see below). len is the length of the value to be changed; it is required only if field type is FLD_CARRAY.

If an occurrence of -1 is specified, then the field value is added as a new occurrence to the buffer. If the specified field occurrence is found, then the field value is modified to the value specified. If a field occurrence is specified that does not exist, then NULL values are added for the missing occurrences until the desired occurrence can be added (for example, changing field occurrence 4 for a field that does not exist on a buffer will cause 3 NULL values to be added followed by the specified field value). NULL values consist of the NULL string (1 byte in length) for string and character values, 0 for long and short fields, 0.0 for float and double values, and a zero-length string for a character array. The new or modified value is contained in value and its length is given in len if it is a character array (ignored in other cases). If value is NULL, then the field occurrence is deleted. A value to be deleted that is not found, is considered an error.

In the SYNOPSIS section above the value argument to Fchg() is described as a character pointer data type (char * in C). Technically, this describes only one particular kind of value passable to Fchg(). In fact, the type of the value argument should be a pointer to an object of the same type as the type of the fielded-buffer representation of the field being changed. For example, if the field is stored in the buffer as type FLD_LONG, then value should be of type pointer-to-long (long * in C). Similarly, if the field is stored as FLD_SHORT, then value should be of type pointer-to-short (short * in C). The important thing is that Fchg() assumes that the object pointed to by value has the same type as the stored type of the field being changed.

Fchg32 is used with 32-bit FML.

RETURN VALUES

This function returns -1 on error and sets Ferror to indicate the error condition.

ERRORS

Under the following conditions, Fchg() fails and sets Ferror to:

[FALIGNERR]

"fielded buffer not aligned"
The buffer does not begin on the proper boundary.

 

[FNOTFLD]

"buffer not fielded"
The buffer is not a fielded buffer or has not been initialized by Finit().

 

[FNOTPRES]

"field not present"
A field occurrence is requested for deletion but the specified field and/or occurrence was not found in the fielded buffer.

 

[FNOSPACE]

"no space in fielded buffer"
A field value is to be added or changed in a fielded buffer but there is not enough space remaining in the buffer.

 

[FBADFLD]

"unknown field number or type"
A field identifier is specified which is not valid.

SEE ALSO

CFchg(3c),
Fintro(3fml),
Fadd(3fml),
Fcmp(3fml),
Fdel(3fml)