> Configuring the eLink Adapter for XML # Configuring the eLink Adapter for XML This chapter consists of the following topics: Adding the elinkxml Server to the UBBCONFIG File Creating the eLink Adapter Configuration File The SERVER Section The SERVICE Section Creating the Meta-Type file for the FMLMTI2XML Service ## Adding the elinkxml Server to the UBBCONFIG File The `elinkxml` server must be added to the UBBCONFIG file. To define this server, add `elinkxml` to the SERVERS section of the UBBCONFIG file. The `CLOPT` parameter must be specified to indicate the name of the configuration file that the adapter is to use at run-time. Where `elinkxml.cfg` is an arbitrary name that was chosen for the adapter configuration file, the CLOPT parameter should be specified as: `CLOPT="-- -C elinkxml.cfg"` Listing 3-1 shows the syntax for the server definition in the UBBCONFIG file. Listing 3-1 Syntax for elinkxml Server Definition in the UBBCONFIG File
>     *SERVERS

>     elinkxml
>     	SRVGRP=groupname			SRVID=n
>     	CLOPT="-- -C elinkxml.cfg"
> For information about the `SRVGRP`, `SRVID`, and `CLOPT` parameter syntax and definitions, refer to the BEA TUXEDO Reference Manual. Listing 3-2 is a sample UBBCONFIG file for Windows NT. In this sample, the `elinkxml` server is defined in the SERVERS section with the required `CLOPT` option specified. Listing 3-2 Sample UBBCONFIG File for XML/FML Conversion
>     *RESOURCES

>     IPCKEY		123791
>     DOMAINID		simpapp
>     MASTER		simple

>     *MACHINES

>     DALNT6
>     	LMID= simple
>     	TUXDIR= "\tuxedo"
>     	TUXCONFIG= "\myappdir\tuxconfig"
>     	APPDIR= "\myappdir"
>     	FIELDTBL = "sample.fml"
>     	FIELDTBL32= "sample.fml"
>     	FLDTBLDIR= "\myappdir"
>     	FLDTBLDIR32= "\myappdir"
>     	ULOGPFX= "\myappdir\ULOG"

>     *GROUPS

>     eLINK
>              LMID=simple		 GRPNO=1

>     *SERVERS

>     DEFAULT:
>            	CLOPT="-A"

>     elinkxml
>     	       SRVGRP=eLINK			SRVID=10
>     	       CLOPT="-- -C config.file"
>     *SERVICES

>     *ROUTING
> ## Creating the eLink Adapter Configuration File The elink Adapter for XML reads a configuration file at startup to advertise user-defined conversion services. This file contains ASCII text that you have created. The name of this file is arbitrarily chosen by the user, but it must match what is specified in the UBBCONFIG file (as described in the previous section). This configuration file must be located in the application directory (APPDIR) of the end-user's application. The adapter configuration file contains two important sections: The SERVER Section The SERVICE Section ### The SERVER Section In this section you can specify NAME and TRACE parameters. Table 3-1 provides descriptions for the these parameters. Table 3-1 *SERVER Parameters
> Parameter Name | Description
> --- | ---
> NAME = <Name> | A unique identifier for a specific instance of the `elinkxml` adapter. This value should be alphanumeric text.
> TRACE=<Y/N> | Indicates that the adapter is to log additional diagnostic information in order to troubleshoot problems. The TRACE parameter should have a value of 'Y' or 'N' to indicate whether additional error messages should be logged.
> Listing 3-3 illustrates the use of these parameters. Listing 3-3 The SERVER Section of the Configuration File
>     # This is a comment
>     *SERVER
>     NAME=EA4FML
>     TRACE=Y
>     *SERVICE
>     NAME=CONVERT_WITHDRAWAL
>     CONVERSION_TYPE=FMLMTI2XML
>     MTI_NAME=withdraw.mti
>     *SERVICE
>     NAME=CONVERT_DEPOSIT
>     CONVERSION_TYPE=FML2XML
>     LIST_TAG_SUFFIX=_LIST
> ### The SERVICE Section The eLink Adapter for XML performs data format conversion between FML and XML data formats. For each conversion, you must create a SERVICE section in the adapter configuration file. This SERVICE section describes a TUXEDO service that the adapter advertises in order to perform a conversion. End-user applications then request this service to perform the necessary conversion. The SERVICE definition maps a TUXEDO service name to a specific type of conversion. The service name is arbitrarily chosen. These SERVICE definitions allow different conversions to be represented by different TUXEDO service names. For example, you could define services CONVERT_A, MAKEXML, or MYFMLXML that are all FML2XML conversions. This allows many conversions to be mapped to one implementation. However, these SERVICE names cannot equal the CONVERSION type parameter. You must define services in the SERVICE sections of the configuration file. Each defined service has two required parameters, NAME, and CONVERSION_TYPE. Table 3-2 provides descriptions for the these parameters. Table 3-2 SERVICES Parameters
> Parameter Name | Description
> --- | ---
> NAME=<Name> | Defines the TUXEDO service name that is to be advertised
> CONVERSION_TYPE=<FML2XML> | Indicates what type of data format conversion is to be performed. The CONVERSION_TYPE parameter must have one of the following values: XML2FML, FML2XML, FMLMTI2XML.
The XML2FML conversion type denotes that this service converts XML data to FML. The FML2XML conversion type denotes that this service converts FML to XML format. The FMLMTI2XML conversion type denotes that this service converts FML to XML and use Meta Type Information (MTI) to maintain hierarchical structure. For each different conversion type, additional parameters may be specified. The FML2XML conversion type service can optionally specify a LIST_TAG_SUFFIX parameter. If the parameter is supplied, it is used to generate an XML tag that denotes a list of values. For example, if several occurrences of an FML field FOO exist in an FML buffer, the corresponding XML contains an XML tag indicating that a list of FOO values follow. This XML list tag contains the FML field name with a suffix appended. If no LIST_TAG_SUFFIX parameter is supplied, then the default LIST_TAG_SUFFIX is be _SET. The FMLMTI2XML conversion type service must specify an MTI_NAME parameter. The MTI_NAME parameter should contain the name of the file containing Meta-Type Information (MTI). This Meta-Type Information is used to preserve hierarchical information when FML is converted to XML. Refer to "Creating the Meta-Type file for the FMLMTI2XML Service" on page 3-8 for detailed information on MTI files. Table 3-3 lists which parameters are required or optional. Listing 3-4 illustrates examples of defined SERVICE sections

> Table 3-3 Conversion Service Parameters

| FML2XML | FMLMTI2XML | XML2FML
--- | --- | --- | ---
NAME | Required | Required | Required
CONVERSION TYPE | Required | Required | Required
LIST_TAG_SUFFIX | Optional | N/A | N/A
MTI_NAME | N/A | Required | N/A
> Listing 3-4 Example of a Configuration File for XML2FML and FML2XML Services
>     # This is a comment
>     *SERVER
>     NAME=EA4FML

>     TRACE=Y
>     *SERVICE
>     NAME=CONVERT_WITHDRAWAL
>     CONVERSION_TYPE=FMLMTI2XML
>     MTI_NAME=withdraw.mti
>     *SERVICE
>     NAME=CONVERT_DEPOSIT
>     CONVERSION_TYPE=FML2XML
>     LIST_TAG_SUFFIX=_LIST
>     *SERVICE
>     NAME=CONVERT_BALANCE
>     CONVERSION_TYPE=XML2FML
> ## Creating the Meta-Type file for the FMLMTI2XML Service The FMLMTI2XML service requires a file containing Meta-Type Information in order to preserve hierarchical information when converting FML to XML. To create a file containing Meta-Type Information, perform the following two steps: Create an FML Group Format File Create the MTI File ### Create an FML Group Format File An FML32 Group Format file (`*.fgf`) is used with an FML32 Field Definition Table to apply structure to FML32 fields received by the eLink Adapter in an FML input buffer. Data structures applied to input FML32 buffers can range from simple to complex. A simple structure may be an FML Group Format that supplies the order of individual FML32 fields received by a service request. An example of a complex structure could have nested groups of data items with multiple occurrences of some or all of the groups or data items. Listing 3-5 is the syntax for the FML Group Format file. Listing 3-5 Syntax for FML Group Format File
>     GROUP <groupname> [OCCURS n | s]
>           field-type FML-field-name  [OCCURS n | s]
>     END
> GROUP specifies a collection of data items that should be treated as an individual unit. The GROUP keyword marks the beginning of a group. Groups are terminated by the END keyword. GROUPS can be nested. The outermost group (or root) contains all of the fields or groups used in the FML32 buffer. Note: The top GROUP (or root) cannot have an OCCURS clause. <groupname> specifies the name for the group. You can use the name of the FML Field Definition file as the `groupname` for the top GROUP. <field-type> <FML-field-name> specifies fields within an FML Group Format file. Fields are identified using the field type and the FML field name. Valid field types are string, long, short, char, double, float, or carray. The FML field name must match the name specified in the FML Field Definition file or an error will occur. Note: Group names and field names must be unique within an FML Group Format file. OCCURS n | S specifies the number of occurrences of a group or data item within a group. specifying a number (`n` ) denotes the number of times the specific group or data item occurs in an input FML32 buffer. specifying the keyword `S` indicates that a group or data item has an indefinite number of occurrences. The number of groups or data items processed may vary from one service call to the next. The eLink Adapter product determines how many occurrences of a group or data item exist in the input FML32 buffer and process the data accordingly. Only use the keyword S at the top group level under the outermost group. The default is a single occurrence. FML Group Format File Examples Listing 3-6 is a simple FML Group Format file. This sample file supplies the order in which individual FML Fields are formatted for input to the data mapping process. This FML Group Format file specifies the structure to build using the FML32 data items in the input buffer with names that match the FML Group Format field names. Listing 3-6 Simple FML Group Format File Example
>     GROUP NAME
>           string FIRST_NAME
>           char MIDDLE_INIT
>           string LAST_NAME
>           int AGE
>     END
> Listing 3-8 is a sample FML Group Format file with nested groups and occurrences. The GAA_ARRAY is the outermost group and will not support an OCCURS S clause. The valid top level groups in the following example are GAA_UPPER and GAA_SECOND. The OCCURS S definition in GAA_UPPER indicates that this top level group has an indefinite number of occurrences. GAA_UPPER contains another group, GAA_LOWER. Groups nested within groups other than the outermost group must have a fixed number of occurrences. GAA_LOWER occurs five times within each occurrence of GAA_UPPER. Listing 3-7 Sample FML Group Format File
>     GROUP GAA_ARRAY OCCURS
>           GROUP GAA_UPPER OCCURS S
>                 short EMA_S_SHORT
>                 GROUP GAA_LOWER OCCURS 5
>                       string  EMA_S_STR OCCURS 2
>                       long EMA_L_LONG OCCURS 4
>                 END
>                 string EMA_S_STR2
>           END
>           GROUP GAA_SECOND OCCURS 3
>                 short EMA_S_SHORT
>                 short EMA_S_CHAR
>           END
>     END
### Create the MTI File Together, an FML Field Table Definition, and an FGF file are used to create Meta-Type Information that the XML adapter can access. Figure 3-1 illustrates this process. Figure 3-1 Creation of the MTI File The FML importer (FGF2MTI) is used to create an MTI file from an FML Field Table Definition and an FGF`` file. This stand-alone utility expects two command line arguments, the FGF File, and the FML Field Table Definition file. Listing 3-8 shows a sample execution of the FML importer (FGF2MTI) to generate an MTI file. Listing 3-8 Sample Code to Generate an MTI file `fgf2mti my.fgf myflds` In this example `my.fgf` is the name of the FGF file, and `myflds` is the name of the FML Field Table Definition. Any detected errors are output in a file named the same as the FGF`` file, but with an `.err` extension. In the example, errors are output in a file named `my.err.` The new MTI file is called `my.mti`. Once the MTI file is generated and configured as the MTI_NAME parameter of an FMLMTI2XML service, you can execute conversion requests for this FMLMTI2XML service. Refer to Chapter 4, "Running Sample Applications" in this guide for examples and instructions using sample applications that come with the eLink Adapter. [Table of Contents] [Prev] [Next]