Corporate Info | News | Solutions | Products | Partners | Services | Events | Download | How To Buy
eLink Adapter Development Kit Doc Home | Previous Topic | Next Topic | Contents |

FML32 API

The following information is excerpted from the Tuxedo Online Documentation. These are some of the most commonly used Tuxedo FML32 API functions used for adapter development. For additional details and a complete list of Tuxedo functions and commands, see http://edocs.beasys.com/tuxedo/tux65/index.htm.

Following is an alphabetical list of the the functions described in this section.

####

Refer to
Fadd, Fadd32
Fchg, Fchg 32
Ffind, Ffind32
Fget, Fget32
Fielded, Fielded32
Finit, Finit32
Fldid, Fldid32
Fneeded, Fneeded32
Fsizeof, Fsizeof32

Fadd, Fadd32

Function

Add new field occurrence

Synopsis

>     #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)

Description

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 The value to be added is contained in the location pointed to by the value parameter. If one or more occurrences of the field already exist, then the value is added as a new occurrence of the field, and is assigned an occurrence number 1 greater than the current highest occurrence (to add a specific occurrence, Fchg must be used). 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_CARRAY, the length of the value is given in the len argument.For all types other than FLD_CARRAY, the length of the object pointed to by value is inferred from its type (e.g. 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.

Return Values

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

Errors

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

[FALIGNERR] "fielded buffer not aligned"

  The buffer does not begin on the proper boundary.

[FNOTFLD] "buffer not fielded"

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

[FEINVAL] "invalid argument to function"

  One of the arguments to the function invoked was invalid. (For example, specifying a NULL value parameter to Fadd.)

[FNOSPACE] "no space in fielded buffer"

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

[FBADFLD] "unknown field number or type"

  A field number is specified which is not valid.

Fchg, Fchg 32

Function

Change field occurrence value

Synopsis

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

Description

Fchg() changes the value of a field in the buffer. fbfr is a pointer to a fielded buffer. fieldid is a field identifier. oc is the occurrence number of the field. value is a pointer to a new value, its type must be the same type as the value to be changed (see below). len is the length of the value to be changed; it is required only if field type is FLD_CARRAY. If an occurrence of -1 is specified, then the field value is added as a new occurrence to the buffer. If the specified field occurrence is found, then the field value is modified to the value specified. If a field occurrence is specified that does not exist, then NULL values are added for the missing occurrences until the desired occurrence can be added (for example, changing field occurrence 4 for a field that does not exist on a buffer will cause 3 NULL values to be added followed by the specified field value). NULL values consist of the NULL string (1 byte in length) for string and character values, 0 for long and short fields, 0.0 for float and double values, and a zero-length string for a character array. The new or modified value is contained in value and its length is given in len if it is a character array (ignored in other cases). If value is NULL, then the field occurrence is deleted. A value to be deleted that is not found, is considered an error. In the SYNOPSIS section above the value argument to Fchg() is described as a character pointer data type (char * in C). Technically, this describes only one particular kind of value passable to Fchg(). In fact, the type of the value argument should be a pointer to an object of the same type as the type of the fielded-buffer representation of the field being changed. For example, if the field is stored in the buffer as type FLD_LONG, then value should be of type pointer-to-long (long * in C). Similarly, if the field is stored as FLD_SHORT, then value should be of type pointer-to-short (short * in C). The important thing is that Fchg() assumes that the object pointed to by value has the same type as the stored type of the field being changed.

Fchg32 is used with 32-bit FML.

Return Values

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

Errors

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

[FALIGNERR] "fielded buffer not aligned"

  The buffer does not begin on the proper boundary.

[FNOTFLD] "buffer not fielded"

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

[FNOTPRES] "field not present"

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

[FNOSPACE] "no space in fielded buffer"

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

[FBADFLD] "unknown field number or type"

  A field identifier is specified which is not valid.

Ffind, Ffind32

Function

Find field occurrence in buffer

Synopsis

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

Description

Ffind() finds the value of the specified field occurrence in the buffer. fbfr is a pointer to a fielded buffer. fieldid is a field identifier. oc is the occurrence number of the field. If the field is found, its length is set into *len, and its location is returned as the value of the function. If the value of len is NULL, then the field length is not returned. Ffind() is useful for gaining read-only access to a field. In no case should the value returned by Ffind() be used to modify the buffer. In general, the locations of values of types FLD_LONG, FLD_FLOAT, and FLD_DOUBLE are not suitable for direct use as their stored type, since proper alignment within the buffer is not guaranteed. 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 only be done by the functions Fadd or Fchg. The values returned by Ffind() and Ffindlast() are valid only so long as the buffer remains unmodified.

Ffind32 is used with 32-bit FML.

Return Values

In the SYNOPSIS section above, the return value to Ffind() is described as a character pointer data type (char* in C). Actually, the pointer returned points to an object that has the same type as the stored type of the field. This function returns a pointer to NULL on error and sets Ferror to indicate the error condition.

Errors

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

[FALIGNERR] "fielded buffer not aligned"

  The buffer does not begin on the proper boundary.

[FNOTFLD] "buffer not fielded"

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

[FNOTPRES] "field not present"

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

[FBADFLD] "unknown field number or type"

  A field identifier is specified which is not valid.

Fget, Fget32

Function

Get copy and length of field occurrence

Synopsis

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

Description

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.

Fget32 is used with 32-bit FML.

Return Values

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

Errors

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

[FALIGNERR] "fielded buffer not aligned"

  The buffer does not begin on the proper boundary.

[FNOTFLD] "buffer not fielded"

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

[FNOSPACE] "no space"

  The size of the data area, as specified in maxlen, is not large enough to hold the field value.

[FNOTPRES] "field not present"

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

[FBADFLD] "unknown field number or type"

  A field identifier is specified which is not valid.

Fielded, Fielded32

Function

Return true if buffer is fielded

Synopsis

>     #include stdio.h>
>     #include "fml.h"
>     int
>     Fielded(FBFR *fbfr)
>     #include "fml32.h"
>     int
>     Fielded32(FBFR32 *fbfr)

Description

Fielded() is used to test whether the specified buffer is fielded. fbfr is a pointer to a fielded buffer.

Fielded32 is used with 32-bit FML.

Return Values

Fielded() returns true (1) if the buffer is fielded. It returns false (0) if the buffer is not fielded and does not set Ferror in this case.

Finit, Finit32

Function

Initialize fielded buffer

Synopsis

>     #include <stdio.h>
>     #include "fml.h"
>     int
>     Finit(FBFR *fbfr, FLDLEN buflen)
>     #include "fml32.h"
>     int
>     Finit32(FBFR32 *fbfr, FLDLEN32 buflen)

Description

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 re-initialize a previously used buffer.

Finit32 is used with 32-bit FML.

Return Values

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

Errors

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

[FALIGNERR] "fielded buffer not aligned"

  The buffer does not begin on the proper boundary.

[FNOTFLD] "buffer not fielded"

  The buffer pointer is NULL.

[FNOSPACE] "no space in fielded buffer"

  The buffer size specified is too small for a fielded buffer.

Example

The correct way to re-initialize a buffer to have no fields is:

>     Finit(fbfr,
>     (FLDLEN)Fsizeof(fbfr));

Fldid, Fldid32

Function

Map field name to field identifier

Synopsis

>     #include <stdio.h>
>     #include "fml.h"
>     FLDID
>     Fldid(char *name)
>     #include "fml32.h"
>     FLDID32
>     Fldid32(char *name)

Description

Fldid() provides a runtime 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.

Fldid32 is used with 32-bit FML.

Return Values

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

Errors

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

[FBADNAME] "unknown field name"

  A field name is specified which cannot be found in the field tables.

[FMALLOC] "malloc failed"

  Allocation of space dynamically using malloc(3) failed.

Fneeded, Fneeded32

Function

Compute size needed for buffer

Synopsis

>     #include <stdio.h>
>     #include "fml.h"
>     long
>     Fneeded(FLDOCC F, FLDLEN V)
>     #include "fml32.h"

>     long
>     Fneeded32(FLDOCC32 F, FLDLEN32 V)

Description

Fneeded() if used to determine the space that must be allocated for F fields and V bytes of value space.

Fneeded32 is used with 32-bit FML.

Return Values

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

Errors

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

[FEINVAL] "invalid argument to function"

  One of the arguments to the function invoked was invalid, (for example, number of fields is less than 0, V is 0 or total size is greater than 65534).

Fsizeof, Fsizeof32

Function

Return size of fielded buffer

Synopsis

>     #include "fml32.h"
>     long
>     Fsizeof32(FBFR32 *fbfr)

Description

Fsizeof() returns the size of a fielded buffer in bytes. fbfr is a pointer to a fielded buffer. Fsizeof32 is used with 32-bit FML.

Return Values

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

Errors

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

[FALIGNERR] "fielded buffer not aligned"

  The buffer does not begin on the proper boundary.

[FNOTFLD]"buffer not fielded"

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

Example of a Server that Uses FML32

The following server receives an FML32 buffer as the data field in a TPSVRINFO struct, deletes the contents of all of the fields, than repopulates them in the opposite order

Listing 0-1 Example of Server that Uses FML32

>     #include <stdio.h>
>     #include <ctype.h>
>     #include "atmi.h"
>     #include "fml32.h"
>     #include "userlog.h"

>     #define TEST_STRING "STRTEST"
>     #define TEST_LONG   70001
>     #define TEST_CHAR   'Z'
>     #define TEST_SHORT  911
>     #define TEST_CARRAY "TESTC"

>     FMLFOO(msg)
>     TPSVCINFO *msg;
>     {
>             FBFR32 *fbfr;	/* data to be sent */
>             FLDLEN32 fbfr_len;
>             FLDID32 fieldid;

>             long  test_long;
>             char  test_char;
>             short test_short;

>             fbfr = (FBFR32 *) msg->data;

>             /*-----------------------------------*/
>             /* Delete all fields in FML32 buffer */
>             /*-----------------------------------*/
>             fieldid = Fldid32("MYSTRING");
>             if (Fdel32(fbfr, fieldid, 0) < 0)
>             {
>               userlog("Fdel32 MYSTRING failed:  ");
>             }
>            fieldid = Fldid32("MYLONG");
>             if (Fdel32(fbfr, fieldid, 0) < 0)
>             {
>               userlog("Fdel32 MYLONG failed:  ");
>             }
>             fieldid = Fldid32("MYCHAR");
>             if (Fdel32(fbfr, fieldid, 0) < 0)
>             {
>               userlog("Fdel32 MYCHAR failed:  ");
>             }
>             fieldid = Fldid32("MYSHORT");
>             if (Fdel32(fbfr, fieldid, 0) < 0)
>             {
>               userlog("Fdel32 MYSHORT failed:  ");
>             }
>             fieldid = Fldid32("MYCARRAY");
>             if (Fdel32(fbfr, fieldid, 0) < 0)
>             {
>               userlog("Fdel32 MYCARRAY failed:  ");
>             }
>             /*-----------------------------------*/
>             /* Add all fields to FML32 buffer in opposite order */
>             /*-----------------------------------*/
>             fieldid = Fldid32("MYCARRAY");
>             if (Fadd32(fbfr, fieldid, TEST_CARRAY, (FLDLEN32) sizeof(TEST_CARRAY)) < 0)

>             {
>               userlog("Fadd32 MYCARRAY failed:  ");
>             }
>             fieldid = Fldid32("MYSHORT");
>             test_short = TEST_SHORT;
>             if (Fadd32(fbfr, fieldid, (char *) &test_short, (FLDLEN32)
>                  sizeof(test_short)) < 0)
>             {
>               userlog("Fadd32 MYSHORT failed:  ");
>             }
>             fieldid = Fldid32("MYCHAR");
>             test_char = TEST_CHAR;
>             if (Fadd32(fbfr, fieldid, (char *) &test_char, (FLDLEN32)
>                  sizeof(test_char)) < 0)
>             {
>               userlog("Fadd32 MYCHAR failed:  ");
>             }
>             fieldid = Fldid32("MYLONG");
>             test_long = TEST_LONG;
>             if (Fadd32(fbfr, fieldid, (char *) &test_long, (FLDLEN32)
>                  sizeof(test_long)) < 0)
>             {
>               userlog("Fadd32 MYLONG failed:  ");
>             }
>             fieldid = Fldid32("MYSTRING");
>              if (Fadd32(fbfr, fieldid, TEST_STRING, (FLDLEN32) strlen(TEST_STRING))
>                   < 0)

>             {
>               userlog("Fadd32 MYSTRING failed:  ");
>             }
>             tpreturn(TPSUCCESS, 0, msg->data, 0L, 0);
>     }

Copyright © 2000 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.