|
|
|
|
|
|
Fchg, Fchg32(3fml)
Name
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.
For values of type FLD_PTR, Fchg32() stores the pointer value. The buffer pointed to by a FLD_PTR field must be allocated using the tpalloc() call. For values of type FLD_FML32, Fchg32() stores the entire FLD_FML32 field value, except the index. For values of type FLD_VIEW32, Fchg() stores a pointer to a structure of type FVIEWFLD, that contains vflags (a flags field, currently unused and set to 0), vname (a character array containing the view name), and data (a pointer to the view data stored as a C structure). The application provides the vname and data to Fchg32().
Fchg32() is used with 32-bit FML.
A thread in a multithreaded application may issue a call to Fchg() or Fchg32() while running in any context state, including TPINVALIDCONTEXT.
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:
The buffer does not begin on the proper boundary.
The buffer is not a fielded buffer or has not been initialized by Finit().
A field occurrence is requested for deletion but the specified field and/or occurrence was not found in the 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.
A field identifier is specified which is not valid.
See Also
Introduction to FML Functions, CFchg, CFchg32(3fml), Fadd, Fadd32(3fml), Fcmp, Fcmp32(3fml), Fdel, Fdel32(3fml)
|
|
|
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|