FML also provides a facility called VIEWS that allows you to map fielded buffers to C structures (and the reverse as well).
VIEWS lets you perform lengthy manipulations of data in structures rather than in fielded buffers; applications will run faster if data is transferred to structures for manipulation.
VIEWS allows the data independence of fielded buffers to be combined with the efficiency and simplicity of classic record structures.
There are two “sizes” of FML. The original FML interface is based on 16-bit values for the length of fields and containing information identifying fields. In this introduction, it will be referred to as FML16. FML16 is limited to 8191 unique fields, individual field lengths of up to 64K bytes, and a total fielded buffer size of 64K. The definitions, types, and function prototypes for this interface are in fml.h which must be included in an application program using the FML16 interface; and functions live in
-lfml. A second interface, FML32, uses 32-bit values for the field lengths and identifiers. It allows for about 30 million fields, and field and buffer lengths of about 2 billion bytes. The definitions, types, and function prototypes for FML32 are in
fml32.h; and functions live in
-lfml32. All definitions, types, and function names for FML32 have a “32” suffix (for example,
MAXFBLEN32,
FLDID32,
Fchg32). Also the environment variables are suffixed with “32” (for example,
FLDTBLDIR32,
FIELDTBLS32,
VIEWFILES32, and
VIEWDIR32).
The field types can be any of the standard C language types: short,
long,
float,
double, and
char. The following types are also supported:
string (a series of characters ending with a NULL character),
carray (a character array),
mbstring (a multibyte character array—available in Oracle Tuxedo release 8.1 or later),
ptr (a pointer to a buffer),
fml32 (an embedded FML32 buffer), and
view32 (an embedded VIEW32 buffer). (The
ptr,
fml32, and
view32 types are supported only for the FML32 interface.) In
fml.h, the supported field types are defined as
FLD_SHORT,
FLD_LONG,
FLD_FLOAT,
FLD_DOUBLE,
FLD_CHAR,
FLD_STRING, and
FLD_CARRAY. In
fml32.h, the supported field types are defined as
FLD_SHORT,
FLD_LONG,
FLD_FLOAT,
FLD_DOUBLE,
FLD_CHAR,
FLD_STRING,
FLD_CARRAY,
FLD_MBSTRING,
FLD_PTR,
FLD_FML32, and
FLD_VIEW32.
For FML16, a fielded buffer pointer is of type FBFR *, a field length has the type
FLDLEN, and the number of occurrences of a field has the type
FLDOCC. For FML32, a fielded buffer pointer is of type
FBFR32 *, a field length has the type
FLDLEN32, and the number of occurrences of a field has the type
FLDOCC32.
VIEWS is a part of the Field Manipulation Language that allows the exchange of data between fielded buffers and C structures in a C language program, by specifying mappings of fields to members of C structures. If extensive manipulations of fielded buffer information are to be done, transferring the data to C structures will improve performance. Information in a fielded buffer can be extracted from the fields in a buffer and placed in a C structure using
VIEWS functions, manipulated, and the updated values returned to the buffer, again using
VIEWS functions.
A view description is created and stored in a source viewfile, as described in viewfile(5). The view description maps fields in fielded buffers to members in C structures. The source view descriptions are compiled, using
viewc() or
viewc32(), creating a view object file and can then be used to map data transferred between fielded buffers and C structures in a C program (see
viewc, viewc32(1) for details). The view compiler also creates C header files that can be included in applications programs to define the structures described in view descriptions. A view disassembler,
viewdis() or
viewdis32(), is provided to translate object view descriptions into readable form (that is, back into source view descriptions); the output of the disassembler can be reinput to the view compiler (see
viewdis, viewdis32(1) for details).
The object files are used at run time to manipulate the VIEW structures using the
VIEWFILES and
VIEWDIR environment variables.
VIEWFILES should contain a comma-separated list of object viewfiles for the application. Files given as full pathnames are used as is; files listed as relative pathnames are searched for through the list of directories specified by the
VIEWDIR variable (as described later in this section).
VIEWDIR specifies a colon-separated list of directories to be used to find view object files with relative filenames. For
VIEW32 structures,
VIEWFILES32 and
VIEWDIR32 are used.
A decimal data type is also supported in VIEWS. It is defined as a field of type
dec_t, and the size of the packed decimal value is given as the total number of bytes and the bytes to the right of the decimal point. While this field is not supported directly in FML, conversion of this field is automatic to/from any other field type supported in FML. Packed decimals exist in the COBOL environment as two decimal digits packed into one byte with the low-order half byte used to store the sign. In the C environment, the data type is defined by the
dec_t type definition, which contains the decimal exponent, sign, digits, and the packed decimal value.
An FML buffer can be converted to a view using Fvftos() or
Fvftos32(). A view can be converted to a fielded buffer using
Fvstof() or
Fvstof32(). When transferring data between fielded buffers and structures, the source data is automatically converted to the type of the destination data. Multiple field occurrences are supported; they are treated as an array in the structure. NULL values are used to indicate empty members in a structure, and can be specified by the user for each structure member in a viewfile. If the user does not specify a NULL value for a member, default NULL values are used. It is also possible to inhibit the transfer of data between a C structure member and a field in a fielded buffer, even though a mapping exists between them.
A VIEW can also be converted to and from a target record format. The default target format is IBM System/370 COBOL records. The
Fvstot() function takes care of converting byte ordering, floating point and decimal format, and character sets (ASCII to EBCDIC), and
Fvttos() converts back to the native format. 32-bit versions of these functions also exist. The
Fcodeset() function can be used to specify alternate ASCII/EBCDIC transaction tables.
The F_error and
F_error32 functions are provided to produce a message on the standard error output. They take one parameter, a string; print the argument string appended with a colon and a blank; and then print an error message followed by a newline character. The error message displayed is the one defined for the error number currently in
Ferror or
Ferror32, which is set when errors occur.
Fstrerror() can be used to retrieve from a message catalog the text of an error message; it returns a pointer that can be used to as an argument to
userlog(3c).
CFadd, CFadd32(3fml),
CFchg, CFchg32(3fml),
CFfind, CFfind32(3fml),
CFfindocc, CFfindocc32(3fml),
CFget, CFget32(3fml),
CFgetalloc, CFgetalloc32(3fml),
F_error, F_error32(3fml),
Fadd, Fadd32(3fml),
Fadds, Fadds32(3fml),
Falloc, Falloc32(3fml),
Fboolco, Fboolco32, Fvboolco, Fvboolco32(3fml),
Fboolev, Fboolev32, Fvboolev, Fvboolev32(3fml),
Fboolpr, Fboolpr32, Fvboolpr, Fvboolpr32(3fml),
Fchg, Fchg32(3fml),
Fchgs, Fchgs32(3fml),
Fchksum, Fchksum32(3fml),
Fcmp, Fcmp32(3fml),
Fconcat, Fconcat32(3fml),
Fcpy, Fcpy32(3fml),
Fdel, Fdel32(3fml),
Fdelall, Fdelall32(3fml),
Fdelete, Fdelete32(3fml),
Fextread, Fextread32(3fml),
Ffind, Ffind32(3fml),
Ffindlast, Ffindlast32(3fml),
Ffindocc, Ffindocc32(3fml),
Ffinds, Ffinds32(3fml),
Ffloatev, Ffloatev32, Fvfloatev, Fvfloatev32(3fml),
Ffprint, Ffprint32(3fml),
Ffree, Ffree32(3fml),
Fget, Fget32(3fml),
Fgetalloc, Fgetalloc32(3fml),
Fgetlast, Fgetlast32(3fml),
Fgets, Fgets32(3fml),
Fgetsa, Fgetsa32(3fml),
Fidnm_unload, Fidnm_unload32(3fml),
Fidxused, Fidxused32(3fml),
Fielded, Fielded32(3fml),
Findex, Findex32(3fml),
Finit, Finit32(3fml),
Fjoin, Fjoin32(3fml),
Fldid, Fldid32(3fml),
Fldno, Fldno32(3fml),
Fldtype, Fldtype32(3fml),
Flen, Flen32(3fml),
Fmkfldid, Fmkfldid32(3fml),
Fmove, Fmove32(3fml),
Fname, Fname32(3fml),
Fneeded, Fneeded32(3fml),
Fnext, Fnext32(3fml),
Fnmid_unload, Fnmid_unload32(3fml),
Fnum, Fnum32(3fml),
Foccur, Foccur32(3fml),
Fojoin, Fojoin32(3fml),
Fpres, Fpres32(3fml),
Fprint, Fprint32(3fml),
Fproj, Fproj32(3fml),
Fprojcpy, Fprojcpy32(3fml),
Fread, Fread32(3fml),
Frealloc, Frealloc32(3fml),
Frstrindex, Frstrindex32(3fml),
Fsizeof, Fsizeof32(3fml),
Fstrerror, Fstrerror32(3fml),
Ftypcvt, Ftypcvt32(3fml),
Ftype, Ftype32(3fml),
Funindex, Funindex32(3fml),
Funused, Funused32(3fml),
Fupdate, Fupdate32(3fml),
Fused, Fused32(3fml),
Fvall, Fvall32(3fml),
Fvals, Fvals32(3fml),
Fvftos, Fvftos32(3fml),
Fneeded, Fneeded32(3fml), Fvnull, Fvnull32(3fml),
Fvopt, Fvopt32(3fml),
Fvselinit, Fvselinit32(3fml),
Fvsinit, Fvsinit32(3fml),
Fvstof, Fvstof32(3fml),
Fwrite, Fwrite32(3fml),
field_tables(5),
viewfile(5)
CFadd(),
CFadd32() - convert and add field
#include <stdio.h>
#include "fml.h"
int CFadd(FBFR *fbfr, FLDID
fieldid, char *
value, FLDLEN
len, int
type)
#include fml32.h>
int
CFadd32(FBFR32 *
fbfr, FLDID32
fieldid, char *
value, FLDLEN32
len, int
type)
CFadd() acts like
Fadd() but first converts the
value from the user-specified type to the type of the
fieldid for which the field is added to the fielded buffer.
fbfr is a pointer to a fielded buffer.
fieldid is a field identifier.
value is a pointer to the value to be added.
len is the length of the value to be added; it is required only if type is
FLD_CARRAY.
type is the data type of the field in
value.
CFchg(),
CFchg32() - convert and change field
#include <stdio.h>
#include "fml.h"
int CFchg(FBFR *fbfr, FLDID
fieldid, FLDOCC
oc, char *
value,
FLDLEN
len, int
type)
#include "fml32.h"
int CFchg32(FBFR32 *
fbfr, FLDID32
fieldid, FLDOCC32
oc,
char *
value,
FLDLEN32
len, int
type)
CFchg() acts like
Fchg() but first converts the
value from the user-specified
type to the type of the
fieldid for which the field is changed in the fielded 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.
len is the length of the value to be changed; it is required only if type is
FLD_CARRAY.
type is the data type of
value.
CFfind(),
CFfind32() - find, convert, and return pointer
#include <stdio.h>
#include "fml.h"
char * CFfind(FBFR *fbfr, FLDID
fieldid, FLDOCC
oc, FLDLEN *
len,
int
type)
#include "fml32.h"
char *
CFfind32(FBFR32 *
fbfr, FLDID32
fieldid, FLDOCC32
oc, FLDLEN32 *
len,
int
type)
CFfind() finds a specified field in a buffer, converts it and returns a pointer to the converted value.
fbfr is a pointer to a fielded buffer.
fieldid is a field identifier.
oc is the occurrence number of the field.
len is used on output and is a pointer to the length of the converted value.
type is the data type the user wants the field to be converted to.
Like Ffind(), the pointer returned by the function should be considered read-only. The validity of the pointer returned by
CFfind() is guaranteed only until the next buffer operation, even if that operation is non-destructive, since the converted value is retained in a single private buffer. This differs from the value returned by
Ffins(), which is guaranteed until the next modification of the buffer. Unlike
Ffind(),
CFfind() aligns the converted value for immediate use by the caller.
CFfindocc(),
CFfindocc32() - find occurrence of converted value
#include <stdio.h>
#include "fml.h"
FLDOCC
CFfindocc(FBFR *fbfr, FLDID
fieldid, char *
value, FLDLEN
len, int
type)
#include "fml32.h"
FLDOCC32
CFfindocc32(FBFR32 *
fbfr, FLDID32
fieldid, char *
value, FLDLEN32
len, int
type)
CFfindocc() acts like
Ffindocc() but first converts the
value from the user-specified type to the type of
fieldid.
CFfindocc() looks for an occurrence of the specified field in the buffer that matches a user-supplied value, length and type.
CFfindocc() returns the occurrence number of the first field that matches.
fbfr is a pointer to a fielded buffer.
fieldid is a field identifier.
value is a pointer to the value being sought.
len is the length of the value to be compared to input value if type is
FLD_CARRAY.
type is the data type of the field in
value.
CFget(),
CFget32() - get field and convert
#include <stdio.h>
#include "fml.h"
int
CFget(FBFR *fbfr, FLDID fieldid, FLDOCC oc, char *buf, FLDLEN *len,
int type)
#include "fml32.h"
int
CFget32(FBFR32
*fbfr, FLDID32 fieldid, FLDOCC32 oc, char *buf,
FLDLEN32 *len, int type)
CFget() is the conversion analog of
Fget(). The main difference is that it copies a converted value to the user-supplied buffer.
fbfr is a pointer to a fielded buffer.
fieldid is a field identifier.
oc is the occurrence number of the field.
buf is a pointer to private data area. On input,
len is a pointer to the length of the private data area. On return,
len is a pointer to the length of the returned value. If the
len parameter is NULL on input, it is assumed that the buffer is big enough to contain the field value and the length of the value is not returned. If the
buf parameter is NULL, the field value is not returned.
type is the data type the user wants the returned value converted to.
CFgetalloc(),
CFgetalloc32() - get field, allocate space, convert
#include <stdio.h>
#include "fml.h"
char *
CFgetalloc(FBFR *fbfr, FLDID
fieldid, FLDOCC
oc, int
type, FLDLEN
*
extralen)
#include "fml32.h"
char *
CFgetalloc32(FBFR32 *
fbfr, FLDID32
fieldid, FLDOCC32
oc, int
type,
FLDLEN32 *
extralen)
CFgetalloc() gets a specified field from a buffer, allocates space, converts the field to the type specified by the user and returns a pointer to its location.
fbfr is a pointer to a fielded buffer.
fieldid is a field identifier.
oc is the occurrence number of the field.
type is the data type the user wants the field to be converted to. On call,
extralen is a pointer to the length of additional space that may be allocated to receive the value; on return, it is a pointer actual amount of space used. If
extralen is NULL, then no additional space is allocated and the actual length is not returned. The user is responsible for freeing the returned (converted) value.
On success, CFgetalloc() returns a pointer to the converted value. On error, the function returns NULL and sets
Ferror to indicate the error condition.
"malloc failed"
Allocation of space dynamically using
malloc() failed.
F_error(),
F_error32() - print error message for last error
The function F_error() works like
perror() for UNIX system errors; that is, it produces a message on the standard error output (file descriptor 2), describing the last error encountered during a call to a system or library function. The argument string
msg is printed first, then a colon and a blank, then the message and a newline. If
msg is a NULL pointer or points to a NULL string, the colon is not printed. To be of most use, the argument string should include the name of the program that incurred the error. The error number is taken from the external variable
Ferror, which is set when errors occur but not cleared when non-erroneous calls are made. In the MS-DOS and OS/2 environments,
Ferror is redefined to
FMLerror.
F_error() is declared a
void and as such does not have return values.
perror(3),
Uunix_err(3) in a UNIX system reference manual
F32to16(),
F16to32() - convert 16-bit FML to/from 32-bit FML buffer
F32to16() converts a 32-bit FML buffer to a 16-bit FML buffer. It does this by converting the buffer on a field-by-field basis and then creating the index for the fielded buffer. A field is converted by generating a
FLDID from a
FLDID32, and copying the field value (and field length for string, carray, and mbstring fields).
dest and
src are pointers to the destination and source fielded buffers respectively. The source buffer is not changed.
F16to32() converts a 16-bit FML buffer to a 32-bit FML buffer. It lives in the
fml32 library or shared object and sets
Ferror32 on error.
F32to16() lives in the FML library or shared object and sets
Ferror on error. Note that both
fml.h and
fml32.h must be included to use these functions;
fml1632.h may not be included in the same file.
F32to16() fails with
FBADFLD for the following field types:
FLD_PTR,
FLD_MBSTRING,
FLD_FML32, or
FLD_VIEW32.
F16to32() has no impact when performed on these field types.
Fadd(),
Fadd32() - add new field occurrence
#include stdio.h>
#include "fml.h"
int Fadd(FBFR *fbfr, FLDID
fieldid, char *
value, FLDLEN
len)
#include "fml32.h"
int Fadd32(FBFR32 *
fbfr, FLDID32
fieldid, char *
value, FLDLEN32
len)
Fadd() adds the specified field value to the given buffer.
fbfr is a pointer to a fielded buffer.
fieldid is a field identifier.
value is a pointer to a new value; the pointer’s type must be the same fieldid type as the value to be added.
len is the length of the value to be added; it is required only if type is
FLD_CARRAY or
FLD_MBSTRING.
In the “Synopsis” section above the value argument to Fadd() is described as a character pointer data type (
char * in C). Technically, this describes only one particular kind of value passable to
Fadd(). 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 added. 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
Fadd() assumes that the object pointed to by
value has the same type as the stored type of the field being added.
For values of type FLD_PTR,
Fadd32() 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,
Fadd32() stores the entire
FLD_FML32 field value, except the index. For values of type
FLD_VIEW32,
Fadd() stores a pointer to a structure of type
FVIEWFLD, which contains
vflags (a flags field, currently unused and set to 0),
vname (a character array containing the viewname), and
data (a pointer to the view data stored as a C structure). The application provides the
vname and
data to
Fadd32().
For values of type FLD_MBSTRING, the value is the
packed output argument of the
Fmbpack32() function, and the
len argument is the length of the value in the
size output argument of
Fmbpack32().
For values of type FLD_CARRAY, the
len argument is the length of the value. For all types other than
FLD_CARRAY or
FLD_MBSTRING, the length of the object referenced by
value is inferred from its type (for example, a value of type
FLD_FLOAT is of length
sizeof(float)), and the contents of
len are ignored.
Fadd32 is used with 32-bit FML.
Fadds(),
Fadds32() - convert value from type FLD_STRING and add to buffer
#include <stdio.h>
#include "fml.h"
int
Fadds(FBFR *fbfr, FLDID
fieldid, char *
value)
#include "fml32.h"
int
Fadds32(FBFR32 *
fbfr, FLDID32
fieldid, char *
value)
Fadds() has been provided to handle the case of conversion from a user type of
FLD_STRING to the field type of
fieldid and add it to the fielded buffer.
fbfr is a pointer to a fielded buffer.
fieldid is a field identifier.
value is a pointer to the value to be added.
Introduction to FML Functions,
CFchg, CFchg32(3fml),
CFfind, CFfind32(3fml),
CFget, CFget32(3fml),
Falloc, Falloc32(3fml),
Fchgs, Fchgs32(3fml),
Ffinds, Ffinds32(3fml),
Fgets, Fgets32(3fml),
Fgetsa, Fgetsa32(3fml)
Falloc(),
Falloc32() - allocate and initialize fielded buffer
#include <stdio.h>
#include "fml.h"
FBFR *
Falloc(FLDOCC F, FLDLEN
V)
#include "fml32.h"
FBFR32 *
Falloc32(FLDOCC32
F, FLDLEN32
V)
Falloc() dynamically allocates space using
malloc() for a fielded buffer and calls
Finit() to initialize it. The parameters are the number of fields,
F, and the number of bytes of value space,
V, for all fields that are to be stored in the buffer.
Falloc32() is used for larger buffers with more fields.
Introduction to FML Functions,
Ffree, Ffree32(3fml),
Fielded, Fielded32(3fml),
Finit, Finit32(3fml),
Fneeded, Fneeded32(3fml),
Frealloc, Frealloc32(3fml),
Fsizeof, Fsizeof32(3fml),
Funused, Funused32(3fml)
malloc(3) in a UNIX system reference manual
Fappend(),
Fappend32() - append new field occurrence
#include <stdio.h>
#include "fml.h"
int
Fappend(FBFR *fbfr, FLDID
fieldid, char *
value, FLDLEN
len)
#include "fml32.h"
int
Fappend32(FBFR32 *
fbfr, FLDID32
fieldid, char *
value, FLDLEN32
len)
Fappend() adds the specified field value to the end of the given buffer.
Fappend() is useful in building large buffers in that it does not maintain the internal structures and ordering necessary for general purpose FML access. The side effect of this optimization is that a call to
Fappend() may be followed only by additional calls to
Fappend(), calls to the FML indexing routines
Findex() and
Funindex(), or calls to
Free(),
Fused(),
Funused() and
Fsizeof(). Calls to other FML routines made before calling
Findex() or
Funindex() will result in an error with
Ferror set to
FNOTFLD.
fbfr is a pointer to a fielded buffer.
fieldid is a field identifier.
value is a pointer to a new value; the pointer’s type must be the same fieldid type as the value to be added.
len is the length of the value to be added; it is required only if type is
FLD_CARRAY or
FLD_MBSTRING.
In the “Synopsis” section above the value argument to
Fappend() is described as a character pointer data type (
char * in C). Technically, this describes only one particular kind of value passable to
Fappend(). 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 added. 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
Fappend() assumes that the object pointed to by
value has the same type as the stored type of the field being added.
For values of type FLD_MBSTRING, the value is the
packed output argument of the
Fmbpack32() function, and the
len argument is the length of the value in the
size output argument of
Fmbpack32().
For values of type FLD_CARRAY, the
len argument is the length of the value. For all types other than
FLD_CARRAY or
FLD_MBSTRING, the length of the object referenced by
value is inferred from its type (for example, a value of type
FLD_FLOAT is of length
sizeof(float)), and the contents of
len are ignored.
Introduction to FML Functions,
Fadd, Fadd32(3fml),
Ffree, Ffree32(3fml),
Findex, Findex32(3fml),
Fsizeof, Fsizeof32(3fml),
Funindex, Funindex32(3fml),
Funused, Funused32(3fml),
Fused, Fused32(3fml)
Fboolco(),
Fboolco32(),
Fvboolco(),
Fvboolco32() - compile expression, return evaluation tree
#include <stdio.h>
#include "fml.h"
char *
Fboolco(char *expression)
char *
Fvboolco(char *
expression, char *
viewname)
#include "fml32.h"
char *
Fboolco32(char *
expression)
char *
Fvboolco32(char *
expression, char *
viewname)
Fboolco() compiles a Boolean expression, pointed to by
expression, and returns a pointer to the evaluation tree. The expressions recognized are close to the expressions recognized in C. A description of the grammar can be found in the
Programming an Oracle Tuxedo ATMI Application Using FML.
Fvboolco() and
Fvboolco32() provide the same functionality for views. The
viewname parameter indicates the view from which the field offsets are taken.
Fboolev(),
Fboolev32(),
Fvboolev(),
Fvboolev32() - evaluate buffer against tree
#include stdio.h>
#include "fml.h"
int
Fboolev(FBFR *fbfr, char *
tree)
int
Fvboolev(char *
cstruct, char *
tree, char *
viewname)
#include "fml32.h"
int
Fboolev32(FBFR32 *
fbfr, char *
tree)
int
Fvboolev32(char *
cstruct, char *
tree, char *
viewname)
Fboolev() takes a pointer to a fielded buffer,
fbfr, and a pointer to the evaluation tree returned from
Fboolco(),
tree, and returns true (1) if the fielded buffer matches the specified Boolean conditions and false (0) if it does not. This function does not change either the fielded buffer or evaluation tree. The evaluation tree is one previously compiled by
Fboolco().
Fvboolev() and
Fvboolev32() provide the same functionality for views. The
viewname parameter indicates the view from which the field offsets are taken, and should be the same view specified for
Fvboolco() or
Fvboolco32().
Fboolev() returns 1 if the expression in the buffer matches the evaluation tree. It returns 0 if the expression fails to match the evaluation tree. This function returns -1 on error and sets
Ferror to indicate the error condition.
#include stdio.h>
#include "fml.h"
#include "fld.tbl.h"
FBFR *fbfr;
...
Fchg(fbfr,FIRSTNAME,0,"John",0);
Fchg(fbfr,SEX,0,"M",0);
if(Fboolev(fbfr,tree) > 0)
fprintf(stderr,"Buffer selected\\\\n");
else
fprintf(stderr,"Buffer not selected\\\\n");
Fboolpr(),
Fboolpr32(),
Fvboolpr(),
Fvboolpr32() - print Boolean expression as parsed
#include <stdio.h>
#include "fml.h"
void
Fboolpr(char *tree, FILE *
iop)
int
Fvboolpr(char *
tree, FILE *
iop, char *
viewname)
#include "fml32.h"
void
Fboolpr32(char *
tree, FILE *
iop)
int
Fvboolpr32(char *
tree, FILE *
iop, char *
viewname)
Fboolpr() prints a compiled expression to the specified output stream. The evaluation tree,
tree, is one previously created with
Fboolco().
iop is a pointer of type
FILE to the output stream. The output is fully parenthesized, as it was parsed (as indicated by the evaluation tree). The function is useful for debugging.
Fvboolpr() and
Fvboolpr32() provide the same functionality for views. The
viewname parameter indicates the view from which the field offsets are taken, and should be the same view specified for
Fvboolco() or
Fvboolco32().
Fboolpr() is declared as returning a
void, so there are no return values.
Fvboolpr() returns -1 if the viewname is not valid.
Fchg(),
Fchg32() - change field occurrence value
#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)
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 or
FLD_MBSTRING.
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, which contains
vflags (a flags field, currently unused and set to 0),
vname (a character array containing the viewname), and
data (a pointer to the view data stored as a C structure). The application provides the
vname and
data to
Fchg32().
For values of type FLD_MBSTRING, the value is the
packed output argument of the
Fmbpack32() function, and the
len argument is the length of the value in the
size output argument of
Fmbpack32().
For values of type FLD_CARRAY, the
len argument is the length of the value. For all types other than
FLD_CARRAY or
FLD_MBSTRING, the length of the object referenced by
value is inferred from its type (for example, a value of type
FLD_FLOAT is of length
sizeof(float)), and the contents of
len are ignored.
Fchgs(),
Fchgs32() - change field occurrence - caller presents string
#include <stdio.h>
#include "fml.h"
int
Fchgs(FBFR *fbfr, FLDID
fieldid, FLDOCC
oc, char *
value)
#include "fml32.h"
int
Fchgs32(FBFR32 *
fbfr, FLDID32
fieldid, int
oc, char *
value)
Fchgs(), is provided to handle the case of conversion from a user type of
FLD_STRING.
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 the string to be added. The function calls its non-string-function counterpart,
CFchg(), providing a
type of
FLD_STRING, and a
len of 0 to convert from a string to the field type of
fieldid.
Fchksum(),
Fchksum32() - compute checksum for fielded buffer
For values of type FLD_PTR, the name of the pointer field (rather than the pointer or the data referenced by the pointer) is included in the checksum calculation.
On success, Fchksum() returns the
checksum. This function returns -1 on error and sets
Ferror to indicate the error condition.
Fcmp(),
Fcmp32() - compare two fielded buffers
#include <stdio.h>
#include "fml.h"
int
Fcmp(FBFR *fbfr1, FBFR *
fbfr2)
#include "fml32.h"
int
Fcmp32(FBFR32 *
fbfr1, FBFR32 *
fbfr2)
Fcmp() compares the field identifiers and then the field values of two FML buffers.
fbfr1 and
fbfr2 are pointers to the fielded buffers to be compared.
For values of type FLD_PTR, two pointer fields are considered equal if the pointer values (addresses) are equal. For values of type
FLD_FML32, two fields are considered equal if all field occurrences and values are equal. For values of type
FLD_VIEW32, two fields are considered equal if the viewnames are the same, and if all structure member occurrences and values are equal.
|
•
|
The fieldid of a fbfr1 field is less than the fieldid of the corresponding field of fbfr2.
|
|
•
|
fbfr1 has fewer fields or field occurrences than fbfr2.
|
Fcmp() returns a 1 if any of the reverse set of conditions is true, for example, the fieldid of a
fbfr1 field is greater than the fieldid of the corresponding field of
fbfr2. The actual sizes of the buffers (that is, the sizes passed to
Falloc()) are not considered; only the data in the buffers. This function returns -2 on error and sets
Ferror to indicate the error condition.
Fconcat(),
Fconcat32() - concatenate source to destination buffer
#include <stdio.h>
#include "fml.h"
int
Fconcat(FBFR *dest, FBFR *
src)
#include "fml32.h"
int
Fconcat32(FBFR32 *
dest, FBFR32 *
src)
Fconcat() adds fields from the source buffer to the fields that already exist in the destination buffer.
dest and
src are pointers to the destination and source fielded buffers, respectively. Occurrences in the destination buffer, if any, are maintained and new occurrences from the source buffer are added with greater occurrence numbers for the field.
Fcpy(),
Fcpy32() - copy source to destination buffer
#include <stdio.h>
#include "fml.h"
int
Fcpy(FBFR *dest, FBFR *
src)
#include "fml32.h"
int
Fcpy32(FBFR32 *
dest, FBFR32 *
src)
Fcpy() is used to copy the contents of one fielded buffer to another fielded buffer.
dest and
src are pointers to the destination and source fielded buffers respectively.
Fcpy() expects the destination to be a fielded buffer, and thus can check that it is large enough to accommodate the data from the source buffer.
For values of type FLD_PTR,
Fcpy32() copies the buffer pointer. The application programmer must manage the reallocation and freeing of buffers when the associated pointer is copied.
Fdel(),
Fdel32() - delete field occurrence from buffer
#include stdio.h>
#include "fml.h"
int
Fdel(FBFR *fbfr, FLDID
fieldid, FLDOCC
oc)
#include "fml32.h"
int
Fdel32(FBFR32 *
fbfr, FLDID32
fieldid, FLDOCC32
oc)
Fdel() deletes the specified field occurrence from the buffer.
fbfr is a pointer to a fielded buffer.
fieldid is a field identifier.
oc is the occurrence number of the field.
For values of type FLD_PTR,
Fdel32() deletes the
FLD_PTR field occurrence without changing the referenced buffer or freeing the pointer. The data buffer is treated as an opaque pointer.
Fdelall(),
Fdelall32() - delete all field occurrences from buffer
#include <stdio.h>
#include "fml.h"
int
Fdelall(FBFR *fbfr, FLDID
fieldid)
#include "fml32.h"
int
Fdelall32(FBFR32 *
fbfr, FLDID32
fieldid)
Fdelall() deletes all occurrences of the specified field in the buffer.
fbfr is a pointer to a fielded buffer.
fieldid is a field identifier. If no occurrences of the field are found, it is considered an error.
For values of type FLD_PTR,
Fdelall32() deletes the
FLD_PTR field occurrence without changing the referenced buffer or freeing the pointer. The data buffer is treated as an opaque pointer.
Fdelete(),
Fdelete32() - delete list of fields from buffer
#include <stdio.h>
#include "fml.h"
int
Fdelete(FBFR *fbfr, FLDID *
fieldid)
#include "fml32.h"
int
Fdelete32(FBFR32 *
fbfr, FLDID32 *
fieldid)
Fdelete() deletes all occurrences of all fields listed in the array of field identifiers,
fieldid[]. The last entry in the array must be
BADFLDID.
fbfr is a pointer to a fielded buffer.
fieldid is a pointer to an array of field identifiers. This is a more efficient way of deleting several fields from a buffer instead of using several
Fdelall() calls. The update is done in-place. The array of field identifiers may be rearranged by
Fdelete() (they are sorted, if not already, in numeric order).
For values of type FLD_PTR,
Fdelete32() deletes the
FLD_PTR field occurrence without changing the referenced buffer or freeing the pointer. The data buffer is treated as an opaque pointer.
Fdelete() returns success even if no fields are deleted from the fielded buffer.
Fextread(),
Fextread32() - build fielded buffer from printed format
#include <stdio.h>
#include "fml.h"
int
Fextread(FBFR *fbfr, FILE *
iop)
#include "fml32.h"
int
Fextread32(FBFR32 *
fbfr, FILE *
iop)
Fextread() may be used to construct a fielded buffer from its printed format (that is, from the output of
Fprint()). The parameters are a pointer to a fielded buffer,
fbfr, and a pointer to a file stream,
iop. The input file format is basically the same as the output format of
Fprint(), that is:
If no flag is specified, a new occurrence of the field named by
fldname with value
fldval is added to the fielded buffer. A trailing newline (
-) must be provided after each completed input buffer.
For values of type FLD_FML32 and
FLD_VIEW32,
Fextread32() generates nested FML32 buffers and VIEW32 fields, respectively. This function ignores the
FLD_PTR field type. No error is returned if a value of type
FLD_PTR is supplied to the function.
Ffind(),
Ffind32() - find field occurrence in buffer
#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)
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.
For a specified fieldid of type
FLD_MBSTRING, the value returned by
Ffind32() may be analyzed using the
Fmbunpack(32) function.
Ffindlast(),
Ffindlast32() - find last occurrence of field in buffer
#include <stdio.h>
#include "fml.h"
char *
Ffindlast(FBFR *fbfr, FLDID
fieldid, FLDOCC *
oc, FLDLEN *
len) #include "fml32.h"
char *
Ffindlast32(FBFR32 *
fbfr, FLDID32
fieldid, FLDOCC32 *
oc, FLDLEN32 *
len)
Ffindlast() finds the last occurrence of a field in a buffer.
fbfr is a pointer to a fielded buffer.
fieldid is a field identifier.
oc is a pointer to an integer that is used to receive the occurrence number of the field.
len is the length of the value. If there are no occurrences of the field in the buffer, NULL is returned. Generally,
Ffindlast() acts like
Ffind(). The major difference is that with
Ffindlast the user does not supply a field occurrence. Instead, both the value and occurrence number of the last occurrence of the field are returned. In order to return the occurrence number of the last field, the occurrence argument,
oc, to
Ffindlast() is a pointer-to-integer, and not an integer, as it is to
Ffind(). If
oc is specified to be NULL, the occurrence number of the last occurrence is not returned. If the value of
len is NULL, then the field length is not returned.
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.
Ffindlast32() does not check for occurrences of the specified field in embedded buffers as provided by the
FLD_FML32 and
FLD_VIEW32 field types.
For a specified fieldid of type
FLD_MBSTRING, the value returned by
Ffindlast32() may be analyzed using the
Fmbunpack(32) function.
Introduction to FML Functions,
CFfind, CFfind32(3fml),
Fadd, Fadd32(3fml),
Fchg, Fchg32(3fml),
Ffind, Ffind32(3fml),
Ffindocc, Ffindocc32(3fml),
Ffinds, Ffinds32(3fml)
Ffindocc(),
Ffindocc32() - find occurrence of field value
#include <stdio.h>
#include "fml.h"
FLDOCC
Ffindocc(FBFR *fbfr, FLDID
fieldid, char *
value, FLDLEN
len) #include "fml32.h"
FLDOCC32
Ffindocc32(FBFR32 *
fbfr, FLDID32
fieldid, char *
value, FLDLEN32
len)
Ffindocc() looks at occurrences of the specified field in the buffer and returns the occurrence number of the first field occurrence that matches the user-specified field value.
fbfr is a pointer to a fielded buffer.
fieldid is a field identifier. The value to be found is contained in the location pointed to by the
value parameter.
len is the length of the value if its type is
FLD_CARRAY or
FLD_MBSTRING. If
fieldid is field type
FLD_STRING and if
len is not 0, pattern matching is done on the string. The pattern match supported is the same as the patterns described in
regcmp(3) (in UNIX reference manuals). In addition, the alternation of regular expressions is supported (for example, ''
A|B'' matches with ''
A'' or ''
B''). The pattern must match the entire field value (that is, the pattern ''
value'' is implicitly treated as ''
^value$''). The version of
Ffindocc() provided for use in the MS-DOS and OS/2 environments does not support the
regcmp() pattern matching for
FLD_STRING fields; it uses
strcmp() (in UNIX reference manuals).
In the “Synopsis” section above the value argument to Ffindocc() is described as a character pointer data type (
char * in C). Technically, this describes only one particular kind of value passable to
Ffindocc(). 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 found. 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
Ffindocc() assumes that the object pointed to by value has the same type as the stored type of the field being found.
For values of type FLD_PTR,
Ffindocc32() finds the occurrence of a field that matches a specified pointer value. For values of type
FLD_FML32, two fields are considered equal if all field occurrences and values are equal. For values of type
FLD_VIEW32, two fields are considered equal if the viewnames are the same, and if all structure member occurrences and values are equal.
For values of type FLD_MBSTRING, the value is the
packed output argument of the
Fmbpack32() function, and the
len argument is the length of the value in the
size output argument of
Fmbpack32().
Ffinds(),
Ffinds32() - return ptr to string representation
#include <stdio.h>
#include "fml.h"
char *
Ffinds(FBFR *fbfr, FLDID
fieldid, FLDOCC
oc)
#include "fml32.h"
char *
Ffinds32(FBFR32 *
fbfr, FLDID32
fieldid, FLDOCC32
oc)
Ffinds() is provided to handle the case of conversion to a user type of
FLD_STRING.
fbfr is a pointer to a fielded buffer.
fieldid is a field identifier.
oc is the occurrence number of the field. The specified field occurrence is found and converted from its type in the buffer to a NULL-terminated string. Basically, this macro calls its conversion function counterpart,
CFfind(), providing a
utype of
FLD_STRING, and a
ulen of 0. The duration of the validity of the pointer returned by
Ffinds() is the same as that described for
CFfind().
Ffloatev(),
Ffloatev32(),
Fvfloatev(),
Fvfloatev32() - return value of expression as a double
#include <stdio.h>
#include "fml.h"
double
Ffloatev(FBFR *fbfr, char *
tree)
double
Fvfloatev(char *
cstruct, char *
tree, char *
viewname)
#include "fml32.h"
double
Ffloatev32(FBFR32 *
fbfr, char *
tree)
double
Fvfloatev32(char *
cstruct, char *
tree, char *
viewname)
Ffloatev() takes a pointer to a fielded buffer,
fbfr, and a pointer to the evaluation tree returned from
Fboolco(),
tree, and returns the value of the (arithmetic) expression, represented by the tree, as a double. This function does not change either the fielded buffer or the evaluation tree.
Fvfloatev() and
Fvfloatev32() provide the same functionality for views. The
viewname parameter indicates the view from which the field offsets are taken, and should be the same view specified for
Fvboolco() or
Fvboolco32().
On success Ffloatev() returns the value of an expression as a double.
Ffprint(),
Ffprint32() - print fielded buffer to specified stream
#include <stdio.h>
#include "fml.h"
int
Ffprint(FBFR *fbfr, FILE *
iop)
#include "fml32.h"
int
Ffprint32(FBFR32 *
fbfr, FILE *
iop)
Ffprint() is similar to
Fprint(), except the text is printed to a specified output stream.
fbfr is a pointer to a fielded buffer.
iop is a pointer of type
FILE that points to the output stream.
For values of type FLD_PTR,
Ffprint32() prints the field name or field identifier and the pointer value in hexadecimal. Although this function prints pointer information, the
Fextread32() function ignores the
FLD_PTR field type.
For values of type FLD_FML32,
Ffprint32() recursively prints the FML32 buffer, with leading tabs added for each level of nesting. For values of type
FLD_VIEW32,
Ffprint32() prints the VIEW32 field name and structure member name/value pairs.
Ffree(),
Ffree32() - free space allocated for fielded buffer
Ffree() is used to recover space allocated to its argument fielded buffer.
fbfr is a pointer to a fielded buffer. The fielded buffer is invalidated, that is, it is made non-fielded, and then freed.
Ffree32() does not free the memory area referenced by a pointer in a
FLD_PTR field.
Ffree() is recommended as opposed to
free() (in UNIX system reference manuals), because
Ffree()invalidates a fielded buffer whereas
free() does not. It is important to invalidate fielded buffers because
malloc() (in UNIX system reference manuals) reuses memory that has been freed without clearing it. Thus, if
free() were used, it would be possible for
malloc() to return a piece of memory that looks like a valid fielded buffer but is not.
free(3),
malloc(3) in a UNIX system reference manual
Fget(),
Fget32() - get copy and length of field occurrence
#include <stdio.h>
#include "fml.h"
int
Fget(FBFR *fbfr, FLDID fieldid, FLDOCC oc, char *
loc, FLDLEN
*
maxlen)
#include "fml32.h"
int
Fget32(FBFR32 *
fbfr, FLDID32
fieldid, FLDOCC32
oc, char *
loc,
FLDLEN32 *
maxlen)
Fget() should be used to retrieve a field from a fielded buffer when the value is to be modified.
fbfr is a pointer to a fielded buffer.
fieldid is a field identifier.
oc is the occurrence number of the field. The caller provides
Fget() with a pointer to a private data area,
loc, as well as the length of the data area, *
maxlen, and the length of the field is returned in *
maxlen. If
maxlen is NULL when the function is called, then it is assumed that the data area for the field value
loc is big enough to contain the field value and the length of the value is not returned. If
loc is NULL, the value is not retrieved. Thus, the function call can be used to determine the existence of the field.
In the “Synopsis” section above the value argument to Fget() is described as a character pointer data type (
char * in C). Technically, this describes only one particular kind of value passable to
Fget(). 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 retrieved. 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
Fget() assumes that the object pointed to by value has the same type as the stored type of the field being retrieved.
For a specified fieldid of type
FLD_MBSTRING, the value returned by
Fget32() may be analyzed using the
Fmbunpack(32) function.
When Fget32() is used with the
FLD_VIEW32 field type, a pointer to the
FVIEWFLD structure is returned. This function returns -1 on error and sets
Ferror to indicate the error condition.
Introduction to FML Functions,
CFget, CFget32(3fml),
Fgetalloc, Fgetalloc32(3fml),
Fgetlast, Fgetlast32(3fml),
Fgets, Fgets32(3fml),
Fgetsa, Fgetsa32(3fml)
Fgetalloc(),
Fgetalloc32() - allocate space and get copy of field occurrence
#include <stdio.h>
#include "fml.h"
char *
Fgetalloc(FBFR *fbfr, FLDID
fieldid, FLDOCC
oc, FLDLEN *
extralen)
#include "fml32.h"
char *
Fgetalloc32(FBFR32 *
fbfr, FLDID32
fieldid, FLDOCC32
oc, FLDLEN32
*
extralen)
Like Fget(),
Fgetalloc() finds and makes a copy of a buffer field, but it acquires space for the field via a call to
malloc() (in UNIX system programmer’s reference manuals).
fbfr is a pointer to a fielded buffer.
fieldid is a field identifier.
oc is the occurrence number of the field. The last argument to
Fgetalloc(),
extralen, provides an extra amount of space to be acquired in addition to the field value size. It can be used if the retrieved value is to be expanded before reinsertion into the fielded-buffer. If
extralen is NULL, then no additional space is allocated and the actual length is not returned. It is the caller’s responsibility to
free() space acquired by
Fgetalloc(). The buffer will be aligned properly for any field type.
For a specified fieldid of type
FLD_MBSTRING, the value returned by
Fgetalloc32() may be analyzed using the
Fmbunpack(32) function.
In the “Synopsis” section above the return value to Fgetalloc() 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. When
Fgetalloc32() is used with the
FLD_VIEW32 field type, a pointer to the
FVIEWFLD structure is returned. This function returns NULL on error and sets
Ferror to indicate the error condition.
Introduction to FML Functions,
CFget, CFget32(3fml),
Fget, Fget32(3fml),
Fgetlast, Fgetlast32(3fml),
Fgets, Fgets32(3fml),
Fgetsa, Fgetsa32(3fml)
free(3),
malloc(3) in a UNIX system reference manual
Fgetlast(),
Fgetlast32() - get copy of last occurrence
#include <stdio.h>
#include "fml.h"
int
Fgetlast(FBFR *fbfr, FLDID
fieldid, FLDOCC *
oc, char *
value, FLDLEN
*
maxlen)
#include "fml32.h"
int
Fgetlast32(FBFR32 *
fbfr, FLDID32
fieldid, FLDOCC32 *
oc, char
*
value, FLDLEN32 *
maxlen)
Fgetlast() is used to retrieve both the value and occurrence number of the last occurrence of the field identified by
fieldid.
fbfr is a pointer to a fielded buffer. In order to return the occurrence number of the last field, the occurrence argument,
oc, is a pointer-to-integer, not an integer.
The caller provides Fgetlast() with a pointer to a private buffer,
loc, as well as the length of the buffer,
*maxlen, and the length of the field is returned in
*maxlen. If
maxlen is NULL when the function is called, then it is assumed that the buffer for the field value is big enough to contain the field value and the length of the value is not returned. If
loc is NULL, the value is not returned. If
oc is NULL, the occurrence is not returned.
In the “Synopsis” section above the value argument to Fgetlast() is described as a character pointer data type (
char * in C). Technically, this describes only one particular kind of value passable to
Fgetlast(). 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 retrieved. 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
Fgetlast()assumes that the object pointed to by value has the same type as the stored type of the field being retrieved.
For a specified fieldid of type
FLD_MBSTRING, the value returned by
Fgetlast32() may be analyzed using the
Fmbunpack(32) function.
Fgets(),
Fgets32() - get value converted to string
#include <stdio.h>
#include "fml.h"
int
Fgets(FBFR *fbfr, FLDID
fieldid, FLDOCC
oc, char *
buf)
#include "fml32.h"
int
Fgets32(FBFR32 *
fbfr, FLDID32
fieldid, FLDOCC32
oc, char *
buf)
Fgets() retrieves a field occurrence from the fielded buffer first converting the value to a user type of
FLD_STRING.
fbfr is a pointer to a fielded buffer.
fieldid is a field identifier.
oc is the occurrence number of the field. The caller of
Fgets() provides
buf, a pointer to a private buffer, which is used for the retrieved field value. It is assumed that
buf is large enough to hold the value. Basically,
Fgets() calls
CFget() with an assumed
utype of
FLD_STRING, and a
ulen of 0.
Introduction to FML Functions,
CFget, CFget32(3fml),
Fget, Fget32(3fml),
Fgetalloc, Fgetalloc32(3fml),
Fgetlast, Fgetlast32(3fml),
Fgetsa, Fgetsa32(3fml)
Fgetsa(),
Fgetsa32() - use
malloc() to allocate space and get converted value
#include <stdio.h>
#include "fml.h"
char *
Fgetsa(FBFR *fbfr, FLDID
fieldid, FLDOCC
oc, FLDLEN *
extra)
#include "fml32.h"
char *
Fgetsa32(FBFR32 *
fbfr, FLDID32
fieldid, FLDOCC32
oc, FLDLEN32
*
extra)
Fgetsa() is a macro that calls
CFgetalloc().
fbfr is a pointer to a fielded buffer.
fieldid is a field identifier.
oc is the occurrence number of the field. The function uses
malloc() (in UNIX system programmer’s reference manuals) to allocate space for the retrieved field value that has been converted to a string. If
extra is not NULL, it specifies the extra space to allocate in addition to the field value size; the total size is returned in
extra.
free(3),
malloc(3) in a UNIX system reference manual
Fidnm_unload(),
Fidnm_unload32() - recover space from
id->nm mapping tables
Fidnm_unload() recovers space allocated by
Fname() for field identifier to field name mapping tables.
Fidxused(),
Fidxused32() - return amount of space used
Fidxused() indicates the current amount of space used by the buffer’s index.
fbfr is a pointer to a fielded buffer.
Fielded(),
Fielded32() - return
true if buffer is fielded
Fielded() is used to test whether the specified buffer is fielded.
fbfr is a pointer to a fielded buffer.
Fielded() returns
true if the buffer is fielded. It returns
false if the buffer is not fielded and does not set
Ferror in this case.
Findex(),
Findex32() - index a fielded buffer
#include <stdio.h>
#include "fml.h"
int
Findex(FBFR *fbfr, FLDOCC
intvl)
#include "fml32.h"
int
Findex32(FBFR32 *
fbfr, FLDOCC32
intvl)
The function Findex() is called explicitly to index a fielded buffer.
fbfr is a pointer to a fielded buffer. The second parameter,
intvl, gives the indexing interval, that is, the ideal separation of indexed fields. If this argument has value 0, then the buffer’s current indexing value is used. If the current value itself is 0, the value
FSTDXINTVL (defaults to 16) is used. Using an indexing value of 1 will ensure that every field in the buffer is indexed. The size of the index interval and the amount of space allocated to a buffer’s index are inversely proportional: the smaller the interval, the more fields are indexed and thus the larger the amount of space used for indexing.
Finit(),
Finit32() - initialize fielded buffer
#include <stdio.h>
#include "fml.h"
int
Finit(FBFR *fbfr, FLDLEN
buflen)
#include "fml32.h"
int
Finit32(FBFR32 *
fbfr, FLDLEN32
buflen)
Finit() can be called to initialize a fielded buffer statically.
fbfr is a pointer to a fielded buffer.
buflen is the length of the buffer. The function takes the buffer pointer and buffer length, and sets up the internal structure for a buffer with no fields.
Finit() can also be used to reinitialize a previously used buffer.
Fjoin(),
Fjoin32() - join source into destination buffer
#include stdio.h>
#include "fml.h"
int
Fjoin(FBFR *dest, FBFR *
src)
#include "fml32.h"
int
Fjoin32(FBFR32 *
dest, FBFR32 *
src)
Fjoin() is used to join two fielded buffers based on matching fieldid/occurrence.
dest and
src are pointers to the destination and source fielded buffers respectively. For fields that match on fieldid/occurrence, the field value is updated in the destination buffer with the value in the source buffer. Fields in the destination buffer that have no corresponding fieldid/occurrence in the source buffer are deleted. If joining buffers results in the removal of a
FLD_PTR field, the memory area referenced by the pointer is not modified or freed.
if dest has fields A, B, and two occurrences of C, and
src has fields A, C, and D, the resultant
dest will have source field value A and source field value C.
Introduction to FML Functions,
Fconcat, Fconcat32(3fml),
Fojoin, Fojoin32(3fml),
Fproj, Fproj32(3fml),
Fprojcpy, Fprojcpy32(3fml),
Frealloc, Frealloc32(3fml)
Fldid(),
Fldid32() - map field name to field identifier
Fldid() provides a run-time translation of a field name to its field identifier and returns a
FLDID corresponding to its field
name parameter. The first invocation causes space to be dynamically allocated for the field tables and the tables to be loaded. To recover data space used by the field tables loaded by
Fldid(), the user may unload the files by a call to the
Fnmid_unload() function.
malloc(3) in a UNIX system reference manual
Fldno(),
Fldno32() - map field identifier to field number
Fldno() accepts a field identifier,
fieldid, as a parameter and returns the field number contained in the identifier.
Fldtype(),
Fldtype32() - map field identifier to field type
#include <stdio.h>
#include "fml.h"
int
Fldtype(FLDID fieldid)
#include "fml32.h"
int
Fldtype32(FLDID32
fieldid)
Fldtype() accepts a field identifier,
fieldid, and returns the field type contained in the identifier (an integer), as defined in
fml.h.
Flen(),
Flen32() - return
len of field occurrence in buffer
#include <stdio.h>
#include "fml.h"
int
Flen(FBFR *fbfr, FLDID
fieldid, FLDOCC
oc)
#include "fml32.h"
long
Flen32(FBFR32 *
fbfr, FLDID32
fieldid, FLDOCC32
oc)
Flen() finds the value of the specified field occurrence in the buffer and returns its length.
fbfr is a pointer to a fielded buffer.
fieldid is a field identifier.
oc is the occurrence number of the field.
For values of type FLD_PTR,
Flen32() returns a fixed length for a pointer field based on
sizeof(char*). For values of type
FLD_FML32,
Flen32() returns the value of
Fused32() for the length of the nested buffer. For values of type
FLD_VIEW32,
Flen32() returns the length of the view data plus the length of the viewname.
For values of type FLD_MBSTRING,
Flen32() returns the length of the packed output created by the
Fmbpack32() function.
Fmbpack32() - prepare encoding name and multibyte data information
int
Fmbpack32 (char *enc,void *
ind,FLDLEN32
indlen,void
*
packed,FLDLEN32 *
size,long
flags)
Fmbpack32() prepares the encoding name and multibyte data information for an
FLD_MBSTRING field input to an FML32 typed buffer.
Fmbpack32() is used before the
FLD_MBSTRING field is added to an FML32 buffer via FML32 APIs.
enc, if not NULL, is a NULL-terminated ASCII string containing the code-set encoding name for the
ind code-set multibyte data. If
enc is NULL and the
flags argument is 0, the encoding name that is to be included in the
packed output is obtained from the process
TPMBENC environment variable. If the
flags argument is
FBUFENC,
enc is ignored.
ind is the code-set multibyte data.
indlen is the number of bytes in
ind.
packed is a pointer to an output for
Fmbpack32(). It is used as an input value to FML32 APIs that include
FLD_MBSTRING fields in an FML32 buffer. The packed area must be aligned on a FLDLEN32(TM32U) boundary.
size, on input, is the size of memory pointed to by
packed. If the size is not large enough to handle the result of
Fmbpack32(),
FNOSPACE is returned and
size is reset to the number of bytes that
packed should be. After successful execution of
Fmbpack32(),
size is reset to the actual number of bytes used.
flags is 0 or
FBUFENC. If
flags is set to
FBUFENC,
Fmbpack32() ignores the
enc argument and includes
FBUFENC with the input data to
packed. Without the inclusion of an encoding name, the
packed output forces the FML32 API processing the
FLD_MBSTRING field to get the encoding name from the FML32 buffer. Therefore, usage of
FBUFENC also requires the application developer to use
tpsetmbenc() to set the encoding name for the FML32 buffer.
On success, Fmbpack32() returns a positive value. On error,
Fmbpack32() returns -1 and sets
Ferror32 to indicate the error condition.
ind,
packed, or
size is NULL.
enc or
indlen is not valid.
The size of packed is not sufficient to handle the result of
Fmbpack32().
Fmbunpack32() - extract encoding name and multibyte data information
int
Fmbunpack32 (void *packed,FLDLEN32
ilen,char *
enc,void
*
outd,FLDLEN32 *
olen,long
flags)
Fmbunpack32() extracts the encoding name and multibyte data information from an
FLD_MBSTRING field in an FML32 typed buffer.
Fmbunpack32() is used after the
FLD_MBSTRING field is extracted from an FML32 buffer via FML32 APIs (
Ffind32(),
Fget32(), ...).
packed is a pointer to the
FLD_MBSTRING field data output from an FML32 API.
ilen is the number of bytes for
packed.
enc is a NULL-terminated ASCII string in
packed containing the encoding name when the code-set encoding name for the
FLD_MBSTRING field is part of the
packed information. If the
FLD_MBSTRING field was created by
Fmbpack32() with flag
FBUFENC,
enc is set to NULL. For the latter case, the application developer must use
tpgetmbenc() on the FML32 buffer to get the encoding name for the
FLD_MBSTRING field.
outd contains the multibyte data extracted from
packed upon successful completion of
Fmbunpack32().
olen, on input, is the size of memory pointed to by
outd. If the size is not large enough to handle the result of
Fmbunpack32(),
FNOSPACE is returned and
olen is reset to the number of bytes that
outd should be. After successful execution of
Fmbunpack32(),
olen is reset to the actual number of bytes used.
flags is currently not used and should be set to 0.
On success, Fmbunpack32() returns a positive value. On error,
Fmbunpack32() returns -1 and sets
Ferror32 to indicate the error condition.
outd,
olen, or
packed is NULL.
packed or
ilen is not valid.
The size of outd is not sufficient to handle the result of
Fmbunpack32().
Fmkfldid(),
Fmkfldid32() - make a field identifier
#include <stdio.h>
#include "fml.h"
FLDID
Fmkfldid(int type, FLDID
num)
#include "fml.h"
FLDID32
Fmkfldid32(int
type, FLDID32
num)
Fmkfldid() allows the creation of a valid field identifier from a valid type (as defined in
fml.h) and a field number. This is useful for writing an application generator that chooses field numbers sequentially, or for recreating a field identifier.
type is a valid type (an integer; see
Fldtype, Fldtype32(3fml)).
num is a field number (it should be an unused field number to avoid confusion with existing fields).
Fmove(),
Fmove32() - move fielded buffer to destination
#include <stdio.h>
#include "fml.h"
int
Fmove(char *dest, FBFR *
src)
#include "fml32.h"
int
Fmove32(char *
dest, FBFR32 *
src)
Fmove() should be used when copying from a fielded buffer to any type of buffer.
dest and
src are pointers to the destination buffer and the source fielded buffers respectively.
The difference between Fmove() and
Fcpy() is that
Fcpy() expects the destination to be a fielded buffer and thus can make sure it is of sufficient size to accommodate the data from the source buffer.
Fmove() makes no such check, blindly moving
Fsizeof() bytes of data from the source fielded buffer to the target buffer. The destination buffer must be aligned on a short boundary.
For values of type FLD_PTR,
Fmove32() transfers the buffer pointer. The application programmer must manage the reallocation and freeing of buffers when the associated pointer is moved.
Fname(),
Fname32() - map field identifier to field name
#include <stdio.h>
#include "fml.h"
char *
Fname(FLDID fieldid)
#include "fml32.h"
char *
Fname32(FLDID32
fieldid)
Fname() provides a run-time translation of a field identifier,
fieldid, to its field name and returns a pointer to a character string containing the name corresponding to its argument. The first invocation causes space to be dynamically allocated for the field tables and the tables to be loaded. The table space used by the mapping tables created by
Fname() may be recovered by a call to the function
Fidnm_unload().
Fneeded(),
Fneeded32() - compute size needed for buffer
#include <stdio.h>
#include "fml.h"
long
Fneeded(FLDOCC F, FLDLEN
V)
#include "fml32.h"
long
Fneeded32(FLDOCC32
F, FLDLEN32
V)
Fneeded() is used to determine the space that must be allocated for a fielded buffer. The
F argument is the number of fields, and the
V argument is the space for all field values, in bytes.
Introduction to FML Functions,
Falloc, Falloc32(3fml),
Fielded, Fielded32(3fml),
Finit, Finit32(3fml),
Fsizeof, Fsizeof32(3fml),
Funused, Funused32(3fml),
Fused, Fused32(3fml)
Fnext(),
Fnext32() - get next field occurrence
#include <stdio.h>
#include "fml.h"
int
Fnext(FBFR *fbfr, FLDID *
fieldid, FLDOCC *
oc, char *
value, FLDLEN *
len)
#include "fml32.h"
int
Fnext32(FBFR32 *
fbfr, FLDID32 *
fieldid, FLDOCC32 *
oc, char *
value, FLDLEN32 *
len)
Fnext() finds the next field in the buffer after the specified field occurrence.
fbfr is a pointer to a fielded buffer.
fieldid is a pointer to a field identifier.
oc is a pointer to the occurrence number of the field.
value is a pointer to the value of the next field.
len is the length of the next value.
The field identifier, FIRSTFLDID, should be specified to get the first field in the buffer (for example, on the first call to
Fnext()). If
value is not NULL, the next field value is copied into
value;
*len is used to determine if the buffer has enough space allocated to contain the value. The value’s length is returned in
*len. If
len is NULL when the function is called, it is assumed that there is enough space and the new value length is not returned. If
value is NULL, the value is not retrieved and only
fieldid and
oc are updated. The
*fieldid and
*oc parameters are respectively set to the next found field and occurrence. If no more fields are found, 0 is returned (end of buffer) and
*fieldid,
*oc, and
*value are left unchanged. Fields are returned in field identifier order.
Fnext() returns 1 when the next occurrence is successfully found. It returns 0 when the end of the buffer is reached.
Fnmid_unload(),
Fnmid_unload32() - recover space from
nm->id mapping tables
Fnum(),
Fnum32() - return count of all occurrences in buffer
#include <stdio.h>
#include "fml.h"
FLDOCC
Fnum(FBFR *fbfr)
#include "fml32.h"
FLDOCC32
Fnum32(FBFR32 *
fbfr)
Fnum() returns the number of fields contained in the specified buffer.
fbfr is a pointer to a fielded buffer. The
FLD_FML32 and
FLD_VIEW32 fields are each counted as a single field, regardless of the number of fields they contain.
Foccur(),
Foccur32() - return count of field occurrences in buffer
#include <stdio.h>
#include "fml.h"
FLDOCC
Foccur(FBFR *fbfr, FLDID
fieldid)
#include "fml32.h"
FLDOCC32 Foccur32(FBFR32 *
fbfr, FLDID32
fieldid)
Foccur() is used to determine the number of occurrences of the field specified by
fieldid in the buffer referenced by
fbfr. Occurrences of a field within an embedded FML32 buffer are not counted, as in the
FLD_FML32 field type.
On success, Foccur() returns the number of occurrences; if none are found, it returns 0.
Fojoin(),
Fojoin32() - outer join source into destination buffer
#include <stdio.h>
#include "fml.h"
int
Fojoin(FBFR *dest, FBFR *
src)
#include "fml32.h"
int
Fojoin32(FBFR32 *
dest, FBFR32 *
src)
Fojoin() is similar to
Fjoin(), but it keeps fields from the destination buffer,
dest, that have no corresponding fieldid/occurrence in the source buffer,
src. Fields that exist in the source buffer that have no corresponding fieldid/occurrence in the destination buffer are not added to the destination buffer. If joining buffers results in the removal of a
FLD_PTR field, the memory area referenced by the pointer is not modified or freed.
As with Fjoin(), this function can fail for lack of space; it can be reissued to complete the operation after more space is allocated.
if dest has fields A, B, and two occurrences of C, and
src has fields A, C, and D, the resultant
dest will contain the source field value A, the destination field value B, the source field value C, and the second destination field value C.
Fpres(),
Fpres32() -
true if field occurrence is present in buffer
#include <stdio.h>
#include "fml.h"
int
Fpres(FBFR *fbfr, FLDID
fieldid, FLDOCC
oc)
#include "fml32.h"
int
Fpres32(FBFR32 *
fbfr, FLDID32
fieldid, FLDOCC32
oc)
Fpres() is used to detect whether a given occurrence (
oc) of a specified field (
fieldid) exists in the buffer referenced by
fbfr.
Fpres32() does not check for occurrences of the specified field within an embedded buffer, as in the
FLD_FML32 field type.
Fpres() returns
true if the specified occurrence exists and
false otherwise.
Fprint(),
Fprint32() - print buffer to standard output
Fprint() prints the specified buffer to the standard output.
fbfr is a pointer to a fielded buffer. For each field in the buffer, the output prints the field name and field value separated by a tab.
Fname() is used to determine the field name; if the field name cannot be determined, then the field identifier is printed. Non-printable characters in string and character array field values are represented by a backslash followed by their two-character hexadecimal value. A newline is printed following the output of the printed buffer.
For values of type FLD_PTR,
Fprint32() prints the field name or field identifier and the pointer value in hexadecimal. Although this function prints pointer information, the
Fextread32() function ignores the
FLD_PTR field type.
For values of type FLD_FML32,
Fprint32() recursively prints the FML32 buffer, with leading tabs added for each level of nesting. For values of type
FLD_VIEW32,
Fprint32() prints the VIEW32 field name and structure member name/value pairs.
Fproj(),
Fproj32() - projection on buffer
#include <stdio.h>
#include "fml.h"
int
Fproj(FBFR *fbfr, FLDID *
fieldid)
#include "fml32.h"
int
Fproj32(FBFR32 *
fbfr, FLDID32 *
fieldid)
Fproj() is used to update a buffer so as to keep only the desired fields.
fbfr is a pointer to a fielded buffer. The desired fields are specified in an array of field identifiers pointed to by
fieldid. The last entry in the array must be
BADFLDID. The update is done in place; fields that are not in the result of the projection are deleted from the fielded buffer. The array of field identifiers may be rearranged. (If they are not already in numeric order, they are sorted.) If updating buffers results in the removal of a
FLD_PTR field, the memory area referenced by the pointer is not modified or freed.
Fprojcpy(),
Fprojcpy32() - projection and copy on buffer
#include <stdio.h>
#include "fml.h"
int
Fprojcpy(FBFR *dest, FBFR *
src, FLDID *
fieldid)
#include "fml32.h"
int
Fprojcpy32(FBFR32 *
dest, FBFR32 *
src, FLDID32 *
fieldid)
Fprojcpy() is similar to
Fproj() but the projection is done into a destination buffer instead of in-place.
dest and
src are pointers to the destination and source fielded buffers respectively.
fieldid is a pointer to an array of field identifiers. Any fields in the destination buffer are first deleted and the results of the projection on the source buffer are put into the destination buffer. The source buffer is not changed. The array of field identifiers may be rearranged. (If they are not already in numeric order, they are sorted.) If updating buffers results in the removal of a
FLD_PTR field, the memory area referenced by the pointer is not modified or freed.
Fread(),
Fread32() - read fielded buffer
#include <stdio.h>
#include "fml.h"
int
Fread(FBFR *fbfr, FILE *
iop)
#include "fml32.h"
int
Fread32(FBFR32 *
fbfr, FILE32 *
iop)
Fielded buffers may be read from file streams using Fread().
fbfr is a pointer to a fielded buffer.
iop is a pointer of type
FILE to the input stream. (See
stdio(3S) in a UNIX system reference manual for a discussion of streams).
Fread() reads the fielded buffer from the stream into
fbfr, clearing any data previously stored in the buffer, and recreates the buffer’s index.
Fread32() ignores the
FLD_PTR field type. No error is returned if a value of type
FLD_PTR is supplied to the function.
"UNIX system call error"
The read() system call failed. The external integer
errno should have been set to indicate the error by the system call.
stdio(3S) in a UNIX system reference manual
Frealloc(),
Frealloc32() - reallocate fielded buffer
#include <stdio.h>
#include "fml.h"
FBFR *
Frealloc(FBFR *fbfr, FLDOCC
nf, FLDLEN
nv)
#include "fml32.h"
FBFR32 *
Frealloc32(FBFR32 *
fbfr, FLDOCC32
nf, FLDLEN32
nv)
Frealloc() can be used to reallocate space to enlarge a fielded buffer.
fbfr is a pointer to a fielded buffer. The second and third parameters are the new number of fields,
nf, and the new number of bytes value space,
nv. These are not increments.
On success, Frealloc() returns a pointer to the reallocated FBFR.
#include <stdio.h>
#include "fml.h"
int
Frstrindex(FBFR *fbfr, FLDOCC
numidx)
#include "fml32.h"
int
Frstrindex32(FBFR32 *
fbfr, FLDOCC32
numidx)
A fielded buffer that has been unindexed may be reindexed by either calling Findex() or
Frstrindx().
fbfr is a pointer to a fielded buffer. The former performs a total index calculation on the buffer, and is fairly expensive (requiring a full scan of the buffer). It should be used when an unindexed buffer has been altered, or the previous state of the buffer is unknown (for example, when it has been sent from one process to another without an index).
Frstrindex() is much faster, but may only be used if the buffer has not been altered since its previous unindexing operation. The second argument to
Frstrindx(),
numidx, is the return from the
Funindex() function.
In this case, transmit() is passed a memory pointer and a length. The data to be transmitted begins at the memory pointer and has
num_to_send number of significant bytes. Once the buffer has been sent, its index may be restored (assuming
transmit() does not alter it in any way) using
Frstrindex(). On the receiving end of the transmission, the process accepting the fielded buffer would index it with
Findex(), as in:
|
1.
|
It did not call Funindex() and so has no idea of what the value of the numidx argument to Frstrindex() should be.
|
The solution is to call Findex() explicitly. Of course, the user is always free to transmit the indexed versions of a fielded buffer (that is, send
Fsizeof(*fbfr) bytes) and avoid the cost of
Findex() on the receiving side.
Fsizeof(),
Fsizeof32() - return size of fielded buffer
Fsizeof() returns the size of a fielded buffer in bytes.
fbfr is a pointer to a fielded buffer.
Fstrerror(),
Fstrerror32() - get error message string for FML error
#include <fml.h>
char *
Fstrerror(int err)
#include <fml32.h>
char *
Fstrerror32(int
err)
Fstrerror() is used to retrieve the text of an error message from
LIBFML_CAT.
err is the error code set in
F_error when a FML function call returns a -1 or other failure value.
If err is an invalid error code,
Fstrerror() returns a NULL. On success, the function returns a pointer to a string that contains the error message text.
Fstrerror() returns a NULL on error, but does not set
F_error.
Ftypcvt(),
Ftypcvt32() - convert from one field type to another
#include <stdio.h>
#include "fml.h"
char *
Ftypcvt(FLDLEN *tolen, int
totype, char *
fromval, int
fromtype,
FLDLEN
fromlen)
#include "fml32.h"
char *
Ftypcvt32(FLDLEN32 *
tolen, int
totype, char *
fromval, int
fromtype,
FLDLEN32
fromlen)
Ftypcvt() converts the value
*fromval, which has type
fromtype, and length
fromlen (if
fromtype is
FLD_CARRAY; otherwise,
fromlen is inferred from
fromtype), to a value of type
totype.
Ftypcvt() returns a pointer to the converted value, and sets
*tolen to the converted length, upon success. Upon failure,
Ftypcvt() returns NULL.
Ftypcvt32() fails if any of the following field types is used:
FLD_PTR,
FLD_MBSTRING,
FLD_FML32, or
FLD_VIEW32. If one of these field types is encountered,
Ferror is set to
FEBADOP.
Introduction to FML Functions,
CFadd, CFadd32(3fml),
CFchg, CFchg32(3fml),
CFfind, CFfind32(3fml),
CFget, CFget32(3fml),
CFgetalloc, CFgetalloc32(3fml)
Ftype(),
Ftype32() - return pointer to type of field
#include <stdio.h>
#include "fml.h"
char *
Ftype(FLDID fieldid)
#include "fml32.h"
char *
Ftype32(FLDID32
fieldid)
Ftype() returns a pointer to a string containing the name of the type of a field, given a field identifier,
fieldid. For example, if the
FLDID of a field of type
short is supplied to
Ftype(), a pointer is returned to the string “short.” This data area is “read-only.”
On success, Ftype() returns a pointer to a character string that identifies the field type.
Funindex(),
Funindex32() - discard fielded buffer’s index
#include <stdio.h>
#include "fml.h"
FLDOCC
Funindex(FBFR *fbfr)
#include "fml32.h"
FLDOCC32
Funindex32(FBFR32 *
fbfr)
Funindex() discards a fielded buffer’s index.
fbfr is a pointer to a fielded buffer. When the function returns successfully, the buffer is unindexed. As a result, none of the buffer’s space is allocated to an index and more space is available to user fields (at the cost of potentially slower access time). Unindexing a buffer is useful when it is to be stored on disk or to be transmitted somewhere. In the first case disk space is conserved, in the second, transmission costs may be reduced.
Funindex() returns the number of index elements the buffer has before the index is stripped.
Funused(),
Funused32() - return number of unused bytes in fielded buffer
Funused() returns the amount of space currently unused in the buffer. Space is unused if it contains neither user data nor overhead data such as the header and index.
fbfr is a pointer to a fielded buffer.
Fupdate(),
Fupdate32() - update destination buffer with source
#include <stdio.h>
#include "fml.h"
int
Fupdate(FBFR *dest, FBFR *
src)
#include "fml32.h"
int
Fupdate32(FBFR32 *
dest, FBFR32 *
src)
Fupdate() updates the destination buffer with the field values in the source buffer.
dest and
src are pointers to fielded buffers. For fields that match on fieldid/occurrence, the field value is updated in the destination buffer with the value in the source buffer. Fields in the destination buffer that have no corresponding field in the source buffer are left untouched. Fields in the source buffer that have no corresponding field in the destination buffer are added to the destination buffer.
For values of type FLD_PTR,
Fupdate32() 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,
Fupdate32() stores the entire
FLD_FML32 field value, except the index. For values of type
FLD_VIEW32,
Fupdate32() stores a pointer to a structure of type
FVIEWFLD, which contains
vflags (a flags field, currently unused and set to 0),
vname (a character array containing the viewname), and
data (a pointer to the view data stored as a C structure). The application provides the
vname and
data to
Fupdate32().
Fused(),
Fused32() - return number of used bytes in fielded buffer
Fused() returns the amount of used space in a fielded buffer in bytes, including both user data and the header (but not the index, which can be dropped at any time).
fbfr is a pointer to a fielded buffer.
Fvall(),
Fvall32() - return long value of field occurrence
#include <stdio.h>
#include "fml.h"
long
Fvall(FBFR *fbfr, FLDID
fieldid, FLDOCC
oc)
#include "fml32.h"
long
Fvall32(FBFR32 *
fbfr, FLDID32
fieldid, FLDOCC32
oc)
Fvall() works like
Ffind() for long and short values, but returns the actual value of the field as a long, instead of a pointer to the value.
fbfr is a pointer to a fielded buffer.
fieldid is a field identifier.
oc is the occurrence number of the field.
Fvals(),
Fvals32() - return string value of field occurrence
#include <stdio.h>
#include "fml.h"
char *
Fvals(FBFR *fbfr, FLDID
fieldid, FLDOCC
oc)
#include "fml32.h"
char *
Fvals32(FBFR32 *
fbfr, FLDID32
fieldid, FLDOCC32
oc)
Fvals() works like
Ffind() for string values but guarantees that a value is returned.
fbfr is a pointer to a fielded buffer.
fieldid is a field identifier.
oc is the occurrence number of the field.
Fvftos(),
Fvftos32() - copy from fielded buffer to C structure
#include <stdio.h>
#include "fml.h"
int
Fvftos(FBFR *fbfr, char *
cstruct, char *
view)
#include "fml32.h"
int
Fvftos32(FBFR32 *
fbfr, char *
cstruct, char *
view)
The Fvftos() function transfers data from a fielded buffer to a C structure.
fbfr is a pointer to a fielded buffer.
cstruct is a pointer to a C structure.
view is a pointer to the name of a compiled view description.
Fvneeded(),
Fvneeded32() - computes size needed for
VIEW buffer
#include <stdio.h>
#include "fml.h"
long
Fvneeded(char *subtype)
#include "fml32.h"
long
Fvneeded32(char *
subtype)
Fvneeded() returns the size of the
VIEW C structure.
subtype is the name of the
VIEW. You can call
Fvneeded() to determine the size of a
VIEW buffer to allocate.
Fvneeded32() is used with 32-bit
VIEWs.
Fvneeded() returns the size of the
VIEW in number of bytes. This function returns -1 on error and sets
Ferror to indicate the error condition.
Fvnull(),
Fvnull32() - check if a structure element is NULL
#include <stdio.h>
#include "fml.h"
int
Fvnull(char *cstruct, char *
cname, FLDOCC
oc, char *
view)
#include "fml32.h"
int
Fvnull32(char *
cstruct, char *
cname, FLDOCC32
oc, char *
view)
Fvnull() is used to determine if an occurrence of a structure element is NULL.
cstruct is a pointer to a C structure.
cname is a pointer to the name of an element within
cstruct.
oc is the occurrence number of the element.
view is a pointer to the name of a compiled view description.
Options of Fvopt() such as do not affect this function.
Fvnull32() is used for views defined with
viewc32 or
VIEW32 typed buffers for larger views with more fields.
Fvnull() returns 1, if the specified
cname in a C structure is NULL and returns 0 if not NULL. This function returns -1 on error and sets
Ferror to indicate the error condition.
Fvopt(),
Fvopt32() - change flag options of a mapping entry
#include <stdio.h>
#include "fml.h"
int
Fvopt(char *cname, int
option, char *
view)
#include "fml32.h"
int
Fvopt32(char *
cname, int
option, char *
view)
Fvopt() allows users to specify buffer-to-structure mapping options at run time.
cname is a pointer to the name of an element in a view description,
view.
option specifies the desired setting for the mapping option. Valid options and their meanings are:
Fvopt32() is used for views defined with
viewc32 or
VIEW32 typed buffers for larger views with more fields.
Fvrefresh(),
Fvrefresh32() - copy from C structure to fielded buffer
Fvrefresh() clears and reinitializes the internal cache of view structure mappings. This is necessary only when frequently accessed views are updated dynamically.
Fvrefresh32() is used for views defined with
viewc32 or
VIEW32 typed buffers for larger views with more fields.
Fvselinit(),
Fvselinit32() - initialize structure element to NULL
#include <stdio.h>
#include "fml.h"
int
Fvselinit(char *cstruct, char *
cname, char *
view)
#include "fml32.h"
int
Fvselinit32(char *
cstruct, char *
cname, char *
view)
Fvselinit() initializes an individual element of a C structure to its appropriate NULL value.
cstruct is a pointer to a C structure.
cname is a pointer to the name of an element of
cstruct.
view is a pointer to the name of a compiled view description.
Fvselinit() sets the associated count member of the element to 0 if the
C flag was used when the view was compiled, and sets the associated length member to the length of the associated NULL value if the
L flag was used in the viewfile.
Fvselinit32() is used for views defined with
viewc32 or
VIEW32 typed buffers for larger views with more fields.
Fvsinit(),
Fvsinit32() - initialize C structure to NULL
#include <stdio.h>
#include "fml.h"
int
Fvsinit(char *cstruct, char *
view)
#include "fml32.h"
int
Fvsinit32(char *
cstruct, char *
view)
Fvsinit() initializes all members in a C structure to the NULL values specified in the view description,
view.
cstruct is a pointer to a C structure.
view is a pointer to a compiled view description.
Fvsinit() sets the associated count member of an element to 0 if the
C flag was used when the view was compiled, and sets the associated length member to the length of the associated NULL value if the
L flag was used in the viewfile.
Fvsinit32() is used for views defined with
viewc32 or
VIEW32 typed buffers for larger views with more fields.
Fvstof(),
Fvstof32() - copy from C structure to fielded buffer
#include <stdio.h>
#include "fml.h"
int
Fvstof(FBFR *fbfr, char *
cstruct, int
mode, char *
view)
#include "fml32.h"
int
Fvstof32(FBFR32 *
fbfr, char *
cstruct, int
mode, char *
view)
Fvstof() transfers data from a C structure to a fielded buffer.
fbfr is a pointer to a fielded buffer.
cstruct is a pointer to a C structure.
mode specifies the manner in which the transfer is made.
view is a pointer to a compiled view description.
mode has four possible values:
The action of these modes are the same as that described in Fupdate(),
Fojoin(),
Fjoin(), and
Fconcat(). One can even think of
Fvstof() as the same as these functions, except that where they specify a source buffer,
Fvstof() specifies a C structure. Bear in mind that
FUPDATE does not move structure elements that have NULL values.
Fvstof32() is used for views defined with
viewc32 or
VIEW32 typed buffers for larger views with more fields.
Introduction to FML Functions,
Fconcat, Fconcat32(3fml),
Fjoin, Fjoin32(3fml),
Fojoin, Fojoin32(3fml),
Fupdate, Fupdate32(3fml),
Fvftos, Fvftos32(3fml)
Fvstot(),
Fvttos() - convert C structure to/from target record type
#include <stdio.h>
#include "fml.h"
long
Fvstot(char *cstruct, char *
trecord, long
treclen, char *
viewname)
long
Fvttos(char *
cstruct, char *
trecord, char *
viewname)
#include "fml32.h"
int
Fvstot32(char *cstruct, char *trecord, long treclen, char *viewname)
int
Fvttos32(char *cstruct, char *trecord, char *viewname)
int Fcodeset(char *translation_table)
The Fvstot() function transfers data from a C structure to a target record type. The
Fvttos() function transfers data from a target record to a C structure.
trecord is a pointer to the target record.
cstruct is a pointer to a C structure.
viewname is a pointer to the name of a compiled view description. The
VIEWDIR and
VIEWFILES are used to find the directory and file containing the compiled view description.
Fvttos32() and
Fvstot32() are used with 32-bit VIEWS.
To convert from an FML buffer to a target record, first call Fvftos() to convert the FML buffer to a C structure, and call
Fvstot() to convert to a target record. To convert from a target record to an FML buffer, first call
Fvttos() to convert to a C structure and then call
Fvstof() to convert the structure to an FML buffer.
Packed decimals are supported in C structures using the dec_t field type. The
dec_t field has a defined size consisting of two numbers separated by a comma. The number to the left of the comma is the total number of bytes that the decimal occupies. The number to the right is the number of digits to the right of the decimal point. The formula for conversion is:
dec_t(m, n) => S9(2*
m-(
n+1))V9(
n)COMP-3
An alternate character translation table can be used at run time by calling Fcodeset(). The
translation_table must point to 512 bytes of binary data. The first 256 bytes of data are interpreted as the ASCII to EBCDIC translation table. The second 256 bytes of data are interpreted as the EBCDIC to ASCII table. Any data after the 512th byte is ignored. If the pointer is NULL, the default translation is used.
On success, Fvstot() returns the length of the target record and
Fvttos() returns the length of the C structure.
VIEW test.v
VIEW test
#type cname fbname count flag size null
float float1 FLOAT1 1 - - 0.0
double double1 DOUBLE1 1 - - 0.0
long long1 LONG1 1 - - 0
short short1 SHORT1 1 - - 0
int int1 INT1 1 - - 0
dec_t dec1 DEC1 1 - 4,2 0
char char1 CHAR1 1 - - ''
string string1 STRING1 1 - 20 ''
carray carray1 CARRAY1 1 - 20 ''
END
Equivalent COBOL Record
02 OUTPUT-REC.
05 FLOAT1 USAGE IS COMP-1.
05 DOUBLE1 USAGE IS COMP-2.
05 LONG1 PIC S9(9) USAGE IS COMP.
05 SHORT1 PIC S9(4) USAGE IS COMP.
05 INT1 PIC S9(9) USAGE IS COMP.
05 DEC1 PIC S9(5)V9(2) COMP-3.
05 CHAR1 PIC X(01).
05 STRING1 PIC X(20).
05 CARRAY1 PIC X(20).
C Program
#include "test.h"
#include "decimal.h"
main()
{
struct test s1;
char data[100];
s1.float1 = 1.0;
s1.double1 = 2.0;
s1.long1 = 3;
s1.short1 = 4;
s1.int1 = 5;
deccvdbl(6.0,s1.dec1);
s1.char1 = '7';
(void) strcpy(s1.string1, "eight");
(void) strcpy(s1.carray1, "nine");
if (Fvstot((char *)&s1, data, reclen, "test") == -1) {
printf("Fvstot failed: %sn", Fstrerror(Ferror));
exit(0);
}
/* transfer to target machine and get response */
...
/* translate back */
if (Fvttos(data, (char *)&s1, "test") == -1) {
printf("Fvttos failed: %sn", Fstrerror(Ferror));
exit(0);
}
/* use the structure */
.....
exit(0);
}
decimal(3) in a UNIX system reference manual
Fwrite(),
Fwrite32() - write fielded buffer
#include <stdio.h>
#include "fml.h"
int
Fwrite(FBFR *fbfr, FILE *
iop)
#include "fml32.h"
int
Fwrite32(FBFR32 *
fbfr, FILE *
iop)
fbfr is a pointer to a fielded buffer.
iop is a pointer of type
FILE to the output stream.
For the FLD_PTR field type, only the pointer, not the data being pointed to, is written to the output stream. For the
FLD_VIEW32 field type, only the
FVIEWFLD structure, not the data in the VIEW32 buffer, is written to the output stream.
"UNIX system call error"
The write system call failed. The external integer
errno should have been set to indicate the error by the system call, and the external integer
Uunixerr (values defined in
Uunix.h) is set to the system call that returned the error.
stdio(3S) in a UNIX system reference manual
tpconvfmb32() - convert multibyte characters from source encoding to target encoding
int
tpconvfmb32 (FBFR32 **bufp, FLDID32 *
ids, char *
target_encoding,
long
flags)
tpconvfmb32() converts the multibyte characters in an
FLD_MBSTRING field in an FML32 typed buffer to a named target encoding. Specifically,
tpconvfmb32() compares the source encoding name specified for the
FLD_MBSTRING field
with the target encoding name defined in
target_encoding; if the encoding names are different,
tpconvfmb32() converts the
FLD_MBSTRING field data to the target encoding.
tpconvfmb32() is an alternative to system-initiated encoding conversion. System-initiated encoding conversion of
FLD_MBSTRING field data is done automatically when the process
TPMBACONV environment variable is set to a non-NULL value.
bufp is a pointer to an FML32 typed buffer. It is reallocated internally if the size associated with the pointer is insufficient to handle the converted output data of the FML32 buffer.
bufp must be defined using the
tpalloc() function, not the
Falloc() function. If
bufp contains
FLD_FML32 fields, they are checked recursively for
FLD_MBSTRING fields. If
bufp contains
FLD_PTR fields, they are skipped.
ids contains a pointer to an array of field ids that are to be converted. If
ids is NULL, all
FLD_MBSTRING fields found in
bufp are converted to the target encoding if required. The array, if used, must be terminated with 0 (i.e.,
BADFLDID).
target_encoding is the target code-set encoding name used to convert the
FLD_MBSTRING fields in the
bufp message. If
target_encoding is NULL,
tpconvfmb32() uses the encoding name defined in the process
TPMBENC environment variable.
flags is not used by
tpconvfmb32(). It is passed to the buffer type switch function for user-defined conversion functions.
On success, tpconvfmb32() returns 0. On error,
tpconvfmb32() returns -1 and sets
tperrno to indicate the error condition.
bufp translates to a Tuxedo buffer that does not have a buffer type switch conversion function.
tpconvvmb32() - converts the multibyte characters in an MBSTRING field in an VIEW32 typed buffer to a named target encoding
Specifically, tpconvvmb32() compares the source encoding name specified for the MBSTRING field with the target encoding name defined in
target_encoding; if the encoding names are different,
tpconvvmb32() converts the MBSTRING field data to the target encoding.
tpconvvmb32() is an alternative to system-initiated encoding conversion. System-initiated encoding conversion of MBSTRING field data is done automatically when the process
TPMBACONV environment variable is set to a non-
NULL value.
|
Note:
|
bufp must be defined using the tpalloc() function, not Falloc().
|
Contains a pointer to an array of field ids that are to be converted. If
ids is
NULL, all MBSTRING fields found in
bufp are converted to the target encoding if required. The array, if used, must be terminated with 0 (i.e.,
BADFLDID).
Not used by tpconvvmb32(). It is passed to the buffer type switch function for user-defined conversion functions.
On success, tpconvvmb32() returns
0. On error,
tpconvvmb32() returns
-1 and sets
tperrno to indicate the error condition.
