Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	http://www.oracle.com/technology/documentation/index.html   |   Site Map   |   Search   |   PDF Files   |   Contact   |   Glossary
Tuxedo Doc Home   |   Programming   |   Topic List   |   Previous   |   Next   |   Contents

   Programming a BEA Tuxedo Application Using FML

The functions described in this section are provided for writing stand-alone FML programs. If you are using the BEA Tuxedo ATMI functions, keep in mind that for tasks such as allocating and freeing message buffers, you must call ATMI functions such as tpalloc(3c), tprealloc(3c), and tpfree(3c), instead of FML functions such as Falloc, Falloc32(3fml), Frealloc, Frealloc32(3fml), and Ffree, Ffree32(3fml).

Most FML functions require a pointer to a fielded buffer as an argument. The typedef FBFR is available for declaring such pointers, as shown in the following example.

FBFR *fbfr;

In this section, the variable fbfr refers to a pointer to a fielded buffer. Never attempt to declare fielded buffers themselves; declare only pointers to fielded buffers.

When a server receives a request that contains an FML buffer, it allocates space for that FML buffer and for any embedded views or buffers referenced by FLD_PTR fields. A pointer to the new FML buffer is passed to the user-written code. Once the server processing is complete, all buffers allocated when the message was received must be destroyed. The BEA Tuxedo system checks the FML buffer and all subsidiary buffers, and deletes any buffers to which it finds references. As a programmer writing server code, you should be aware of the following situations:

• If you add, change, or update a view or pointer field so that it references a buffer allocated by the server, the newly allocated buffer is deleted during the cleanup triggered when the tpreturn(3c) or tpforward(3c) function is called.

• If you change, update, or delete a field so that a buffer is no longer referenced by the FML buffer, the user-written code must free that buffer explicitly, using the tpfree(3c) function. If the buffer is not explicitly freed, the server process leaks memory.

• In some cases, the user-written code can allocate and return another buffer, rather than simply call tpreturn(3c). If this is done, the FML buffer passed to tpreturn() is freed, but any buffers referenced by FLD_PTR or FLD_VIEW32 fields are not freed.

The functions used to reserve space for fielded buffers are explained in the following text, but first we describe a function that can be used to determine whether a given buffer is, in fact, a fielded buffer.

Fielded (or Fielded32) is used to test whether the specified buffer is fielded.

int
Fielded(FBFR *fbfr)

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 but does not set Ferror.

For more information, refer to Fielded, Fielded32(3fml) in the BEA Tuxedo FML Function Reference.

The amount of memory to allocate for a fielded buffer depends on the maximum number of fields the buffer will contain and the total amount of space needed for all the field values. The function Fneeded can be used to determine the amount of space (in bytes) needed for a fielded buffer; it takes the number of fields and the space needed for all field values (in bytes) as arguments.

long
Fneeded(FLDOCC F, FLDLEN V)

Here:

• F is the number of fields.

• V is the space, in bytes, for field values.

The space needed for field values is computed by estimating the amount of space that is required by each field value if stored in standard structures (for example, a long is stored as a long and needs four bytes). For variable length fields, estimate the average amount of space needed for the field. The space calculated by Fneeded includes a fixed overhead for each field; it adds that to the space needed for the field values.

For more information, refer to Fneeded, Fneeded32(3fml) in the BEA Tuxedo FML Function Reference.

The Fvneeded function determines the amount of space (in bytes) needed for a VIEW buffer. The function takes a pointer to the name of the VIEW as an argument.

long
Fvneeded(char *subtype)

The Fvneeded function returns the size of the VIEW in number of bytes.

For more information, refer to Fvneeded, Fvneeded32(3fml) in the BEA Tuxedo FML Function Reference.

The Finit function initializes an allocated memory space as a fielded buffer.

int
Finit(FBFR *fbfr, FLDLEN buflen)

Here:

• fbfr is a pointer to an uninitialized fielded buffer.

• buflen is the length of the buffer, in bytes.

A call to Finit to initialize the memory space allocated in the previous example looks like the following code.

Now fbfr points to an initialized, empty fielded buffer. Up to Fneeded(NF, NV) bytes minus a small amount (F_OVHD as defined in fml.h) are available in the buffer to hold fields.

Note: The numbers used in the malloc(3) call (as described in the previous section) and Finit call must be the same.

For more information, refer to Finit, Finit32(3fml) in the BEA Tuxedo FML Function Reference.

Calls to Fneeded, malloc(3) and Finit may be replaced by a single call to Falloc, which allocates the desired amount of space and initializes the buffer.

FBFR *
Falloc(FLDOCC F, FLDLEN V)

Here:

• F is the number of fields.

• V is the space for field values, in bytes.

A call to Falloc that provides the same functionality created by the calls to Fneeded, malloc(), and Finit described in the previous three sections, must be written as follows.

extern FBFR *Falloc;
. . .
 if((fbfr = Falloc(NF, NV)) == NULL)
      F_error("pgm_name");   /* couldn't allocate buffer */

Storage allocated with Falloc (or Fneeded, malloc(3), and Finit) should be freed with Ffree. (See Ffree, Ffree32(3fml) in the BEA Tuxedo FML Function Reference.)

For more information, refer to Falloc, Falloc32(3fml) in the BEA Tuxedo FML Function Reference.

Ffree is used to free memory space allocated as a fielded buffer. Ffree32 does not free the memory area referenced by a pointer in a FLD_PTR field.

int
Ffree(FBFR *fbfr)

Here fbfr is a pointer to a fielded buffer. Consider the following example.

#include  <fml.h>
. . .
if(Ffree(fbfr) < 0)
      F_error("pgm_name");     /* not fielded buffer */

Ffree is preferable to free(3), because Ffree invalidates a fielded buffer, whereas free(3) does not. It is necessary to invalidate fielded buffers because malloc(3) re-uses memory that has been freed without clearing it. Thus, if free(3) is used, malloc can return a piece of memory that looks like a valid fielded buffer, but is not.

Space for a fielded buffer may also be reserved directly. The buffer must begin on a short boundary. You must allocate at least F_OVHD bytes (defined in fml.h) for the buffer; if you do not, Finit returns an error.

The following code is analogous to the preceding example but Fneeded cannot be used to size the static buffer because it is not a macro.

/* the first line aligns the buffer */
static short buffer[500/sizeof(short)];
FBFR *fbfr=(FBFR *)buffer;
. . .
Finit(fbfr, 500);

Be careful not to enter code such as the following!

FBFR badfbfr;
. . .
Finit(&badfbfr, Fneeded(NF, NV));

This code is wrong: the structure for FBFR is not defined in the user header files. As a result, a compilation error will be produced.

For more information, refer to Ffree, Ffree32(3fml) in the BEA Tuxedo FML Function Reference.

Fsizeof returns the size of a fielded buffer in bytes.

long
Fsizeof(FBFR *fbfr)

Here fbfr is a pointer to a fielded buffer. In the following code, for example, Fsizeof returns the same number that Fneeded returned when the fielded buffer was originally allocated.

long bytes;
. . .
bytes = Fsizeof(fbfr);

For more information, refer to Fsizeof, Fsizeof32(3fml) in the BEA Tuxedo FML Function Reference.

Funused may be used to determine how much space is available in a fielded buffer for additional data.

long
Funused(FBFR *fbfr)

Here fbfr is a pointer to a fielded buffer. Consider the following example.

long unused;
. . .
unused = Funused(fbfr);

Note that Funused does not indicate the location, in the buffer, of the unused bytes; only the number of unused bytes is specified.

For more information, refer to Funused, Funused32(3fml) in the BEA Tuxedo FML Function Reference.

Fused may be used to determine how much space is used in a fielded buffer for data and overhead.

long
Fused(FBFR *fbfr)

Here fbfr is a pointer to a fielded buffer. Consider the following example.

long used;
. . .
used = Fused(fbfr);

Note that Fused does not indicate the location, in the buffer, of the used bytes; only the number of used bytes is specified.

For more information, refer to Fused, Fused32(3fml) in the BEA Tuxedo FML Function Reference.

This function enables you to change the size of a buffer for which you have allocated space by calling Falloc.

If you have allocated space with tpalloc(3c), you must call tprealloc(3c) to reallocate that space.) Being able to re-size the buffer can be useful if, for example, a buffer runs out of space while a new field value is being added. Simply by calling Frealloc you can increase the size of the buffer. In other situations you may want to call Frealloc to decrease the size of the buffer.

FBFR *
Frealloc(FBFR *fbfr, FLDOCC nf, FLDLEN nv)

Here:

• fbfr is a pointer to a fielded buffer.

• nf is the new number of fields or 0.

• nv is the new space for field values, in bytes.

Consider the following example.

You do not need to know the number of fields or the value space size with which the buffer was last initialized. Thus, the easiest way to increase the size is to use the current size plus the increment as the value space. The previous example can be executed as many times as needed without remembering past executions or values. You do not need to call Finit after calling Frealloc.

If the amount of additional space requested in the call to Frealloc is contiguous to the old buffer, newfbfr and fbfr in the previous examples are the same. However, defensive programming dictates that you should declare newfbfr as a safeguard in case either a new value or NULL is returned. If Frealloc fails, do not use fbfr again.

Note: The buffer size can be decreased only to the number of bytes currently being used in the buffer.

For more information, refer to Frealloc, Frealloc32(3fml) in the BEA Tuxedo FML Function Reference.