Skip navigation.
Downloads | Product Documentation | Support

WebLogic Tuxedo Connector Programmer's Guide

# Using FML with WebLogic Tuxedo Connector

The following sections discuss the Field Manipulation Language (FML) and describe how the WebLogic Tuxedo Connector uses FML.

- Overview of FML
- The WebLogic Tuxedo Connector FML API
- FML Field Table Administration
- tBridge XML/FML32 Translation

# Overview of FML

Note: For more information about using FML, see Programming a BEA Tuxedo Application Using FML.

FML is a set of java language functions for defining and manipulating storage structures called fielded buffers. Each fielded buffer contains attribute-value pairs in fields. For each field:

- The attribute is the field's identifier.
- The associated value represents the field's data content.
- An occurrence number.

There are two types of FML:

- FML16 based on 16-bit values for field lengths and identifiers. It is limited to 8191 unique fields, individual field lengths of 64K bytes, and a total fielded buffer size of 64K bytes.
- FML32 based on 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 WebLogic Tuxedo Connector FML API

Note: The WebLogic Tuxedo Connector implements a subset of FML functionality. For more information regarding FML32, refer to FML32 Considerations.

The FML application program interface (API) is documented in the `weblogic.wtc.jatmi` package included in the Javadocs for WebLogic Server Classes.

# FML Field Table Administration

Field tables are generated in a manner similar to Tuxedo field tables. The field tables are text files that provide the field name definitions, field types, and identification numbers that are common between the two systems. To interoperate with a Tuxedo system using FML, the following steps are required:

1. Copy the field tables from the Tuxedo system to WebLogic Tuxedo Connector environment.

For example: Your Tuxedo distribution contains a bank application example called `bankapp`. It contains a file called `bankflds` that has the following structure:

>     #Copyright (c) 1990 Unix System Laboratories, Inc.
>     #All rights reserved
>     #ident  "@(#) apps/bankapp/bankflds     $Revision: 1.3 $"
>     # Fields for database bankdb

>     # name                         number  type    flags   comments
>     ACCOUNT_ID                     110     long    -       -
>     ACCT_TYPE                      112     char    -       -
>     ADDRESS                        109     string  -       -
>     .

>     .

>     .

1. Converted the field table definition into Java source files. Use the `mkfldclass` utility supplied in the `weblogic.wtc.jatmi` package. This class is a utility function that reads a FML32 Field Table and produces a Java file which implements the FldTbl interface. There are two instances of this utility:

- `mkfldclass`
- `mkfldclass32`

Use the correct instance of the command to convert the `bankflds` field table into FML32 java source. The following example uses mkfldclass.

>     java weblogic.wtc.jatmi.mkfldclass bankflds

The resulting file is called`` `bankflds``.java` and has the following structure:

>     import java.io.*;
>     import java.lang.*;
>     import java.util.*;
>     import weblogic.wtc.jatmi.*;

>     public final class bankflds
>             implements weblogic.wtc.jatmi.FldTbl
>     {
>             /** number: 110  type: long */
>             public final static int ACCOUNT_ID = 33554542;
>             /** number: 112  type: char */
>             public final static int ACCT_TYPE = 67108976;
>             /** number: 109  type: string */
>             public final static int ADDRESS = 167772269;
>             /** number: 117  type: float */

>     .

>     .

>     .

1. Compile the resulting `bankflds.java` file using the following command:

>     javac bankflds.java

The result is a`bankflds.class` file. When loaded, the WebLogic Tuxedo Connector uses the class file to add, retrieve and delete field entries from an FML32 field.

2. Add the field table class file to your application CLASSPATH.
3. Update your `WTCServer` MBean.

- Update the `WTCResources` MBean to reflect the fully qualified location of the field table class file.
- Use the keywords required to describe the FML buffer type: fml16 or fml32.
- You can enter multiple field table classes in a comma separated list.

For example:

>     <WTCResources
>          FldTbl16Classes="my.bankflds,your.bankflds,more.bankflds"
>          Name="BankappResources"/>

4. Restart your WebLogic Server to load the field table class definitions.

## Using the DynRdHdr Property for mkfldclass32 Class

WebLogic Tuxedo Connector provides a property that provides an alternate method to compile FML tables. You may need to use the `DynRdHdr` utility if:

- You are using very large FML tables and the `.java` method created by the mkfldclass32 class exceeds the internal Java Virtual Machine limit on the total complexity of a single class or interface.
- You are using very large FML tables and are unable to load the class created when compiling the `.java` method.

Use the following steps to use the `DynRdHdr` property when compiling your FML tables:

1. Convert the field table definition into Java source files.

>     java -DDynRdHdr=Path_to_Your_FML_Table weblogic.wtc.jatmi.mkfldclass32 userTable

The arguments for this command are defined as follows:``

Attribute | Description
--- | ---
-DDynRdHdr | WebLogic Tuxedo Connector property used to compile an FML table.
Path_to_Your_FML_Table | Path name of your FML table. This may be either a fully qualified path or a relative path that can be found as a resource file using the server's CLASSPATH.
weblogic.wtc.jatmi.mkfldclass32 | This class is a utility function that reads an FML32 Field Table and produces a Java file which implements the FldTbl interface.
userTable | Name of the `.java` method created by the mkfldclass32 class`.`

1. Compile the userTable file using the following command:

>     javac userTable.java

2. Add the userTable`.class` file to your application CLASSPATH.
3. Update the `WTCResources` MBean to reflect the fully qualified location of the userTable`.class` file.
4. Target your WTCServer. The userTable`.class` is loaded when the WTCServer service starts.

Once you have created the userTable`.class` file, you can modify the FML table and deploy the changes without having to manually create an updated userTable`.class`. When the WTC Service is started, Weblogic Tuxedo Connector will load the updated FML table using the location specified in the Resources tab of your WTC service configuration. If the Path_to_Your_FML_Table attribute changes, you will need to use the preceding procedure to update your userTable`.java` and userTable`.class` files.

# tBridge XML/FML32 Translation

Note: The data type specified must be FLAT or NO. If any other data type is specified, the redirection fails.

The `TranslateFML` element of the WTCtBridgeRedirect MBean is used to indicate if FML32 translation is performed on the message payload. There are two types of FML32 translation: FLAT and NO.

## FLAT

The message payload is translated using the WebLogic Tuxedo Connector internal FML32/XML translator. Fields are converted field-by-field values without knowledge of the message structure (hierarchy) and repeated grouping.

In order to convert an FML32 buffer to XML, the tBridge pulls each instance of each field in the FML32 buffer, converts it to a string, and places it within a tag consisting of the field name. All of these fields are placed within a tag consisting of the service name. For example, an FML32 buffer consisting of the following fields:

>     NAME          JOE
>     ADDRESS       CENTRAL CITY
>     PRODUCTNAME   BOLT
>     PRICE         1.95
>     PRODUCTNAME   SCREW
>     PRICE         2.50

The resulting XML buffer would be:

>     <FML32>
>       <NAME>JOE</NAME>
>       <ADDRESS>CENTRAL CITY</ADDRESS>
>       <PRODUCTNAME>BOLT</PRODUCTNAME>
>       <PRODUCTNAME>SCREW</PRODUCTNAME>
>       <PRICE>1.95</PRICE>
>       <PRICE>2.50</PRICE>
>     </FML32>

## NO

No translation is used. The tBridge maps a JMS TextMessage into a Tuxedo TypedBuffer (TypedString) and vice versa depending on the direction of the redirection. JMS BytesMessage are mapped into Tuxedo TypedBuffer (TypedCarray) and vice versa.

## FML32 Considerations

Remember to consider the following information when working with FML32:

- For XML input, the root element is required but ignored.
- For XML output, the root element is always <FML32>.
- The field table names must be loaded as described in FML Field Table Administration.
- The tBridge translator is capable of only "flat" or linear grouping. This means that information describing FML32 ordering is not maintained, therefore buffers that contain a series of repeating data could be presented in an unexpected fashion. For example, consider a FML32 buffer that contains a list of parts and their associated price. The expectation would be PART A, PRICE A, PART B, PRICE B, etc. however since there is no structural group information contained within the tBridge, the resulting XML could be PART A, PART B, etc., PRICE A, PRICE B, etc.
- When translating XML into FML32, the translator ignores blank values. For example, `<STRING></STRING>` is skipped in the resulting FML32 buffer.
- Embedded FML is not supported in this release.
- Embedded VIEW fields within FML32 buffers are not supported.
- TypedCArray is not supported for FML to XML conversion. Select from the following list of supported field types:

- SHORT
- LONG
- CHAR
- FLOAT
- DOUBLE
- STRING
- INT (FML32)
- DECIMAL (FML32)

- If you have TypedCArray in your FML, encode to TypedString and decode the XML to TypedCArray.
- If you need to pass binary data, encode to a field type of your choice and decode the XML on the receiving side.