Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	http://www.oracle.com/technology/documentation/index.html   |   Search   |   PDF Files   |   Contact   |   Glossary
eLink Adapter Development Kit Doc Home   |   Previous Topic   |   Next Topic   |   Contents   |

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

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 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.

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

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.

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. 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.

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

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.

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, 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.

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.

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.

Get copy and length of field occurrence

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

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.

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

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.

Return true if buffer is fielded

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

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.

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.

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

Finit32 is used with 32-bit FML.

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

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.

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

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

Map field name to field identifier

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

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.

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

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.

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() 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.

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

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

Return size of fielded buffer

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

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.

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

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().

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

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