|
|
Ffind, Ffind32(3fml)
Name
Ffind(), Ffind32() - find field occurrence in buffer
Synopsis
#include <stdio.h>
#include "fml.h"
char *
Ffind(FBFR *fbfr, FLDID fieldid, FLDOCC oc, FLDLEN *len)
#include "fml32.h"
char *
Ffind32(FBFR32 *fbfr, FLDID32 fieldid, FLDOCC32 oc, FLDLEN32 *len)
Description
Ffind() finds the value of the specified field occurrence in the buffer. fbfr is a pointer to a fielded buffer. fieldid is a field identifier. oc is the occurrence number of the field. If the field is found, its length is set into *len, and its location is returned as the value of the function. If the value of len is NULL, then the field length is not returned. Ffind() is useful for gaining read-only access to a field. In no case should the value returned by Ffind() be used to modify the buffer.
In general, because proper alignment within a buffer is not guaranteed, the locations in which the values of types FLD_LONG, FLD_FLOAT, FLD_DOUBLE, FLD_PTR, FLD_FML32, and FLD_VIEW32 are stored prevents these values from being used directly as their stored type. Such values must be copied first to a suitably aligned memory location. Accessing such fields through the conversion function CFfind() does guarantee the proper alignment of the found converted value. Buffer modification should be done only by the Fadd()or Fchg() function. The values returned by Ffind()and Ffindlast() are valid only so long as the buffer remains unmodified.
Ffind32() does not check for occurrences of the specified field in embedded buffers as provided by the FLD_FML32 and FLD_VIEW32 field types.
Ffind32() is used with 32-bit FML.
A thread in a multithreaded application may issue a call to Ffind() or Ffind32() while running in any context state, including TPINVALIDCONTEXT.
Return Values
In the "Synopsis" section above the return value to Ffind() is described as a character pointer data type (char * in C). Actually, the pointer returned points to an object that has the same type as the stored type of the field.
This function returns a pointer to NULL on error and sets Ferror to indicate the error condition.
Errors
Under the following conditions, Ffind() 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 but the specified field and/or occurrence was not found in the fielded buffer.
A field identifier is specified which is not valid.
See Also
Introduction to FML Functions, Ffindlast, Ffindlast32(3fml), Ffindocc, Ffindocc32(3fml), Ffinds, Ffinds32(3fml)
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|