Configuring the eLink Adapter for XML

This chapter consists of the following topics:

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

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

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]