Running Sample Applications

# Running Sample Applications

The information in this section is designed to help you start and run a sample application. This section contains the following information:

- Step 1: Copy the simpxml Files

- Step 2: Set Up Environment Files

- Step 3: Edit the TUXEDO Configuration File

- Step 4: Load the TUXEDO Configuration File

- Step 5: Edit the Adapter Configuration File

- Step 6: Boot the Application

- Step 7: Send an XML2FML Conversion Request

- Step 8: Send an FML2XML Conversion Request

- Step 9: Send an FML to XML Conversion Request Using an MTI File

- Step 10: Shutdown the Application

## Step 1: Copy the simpxml Files

Perform two primary tasks to copy the `simpxml` files:

- Make a directory for `simpxml`

- Copy the `simpxml` files

  Step 1.1: Make a Directory for simpxml

Make a directory for the `simpxml` and `cd` to it so you can see clearly the `simpxml` files you have at the start and the additional files you create along the way. Use the standard shell (`/bin/sh`) or the Korn shell, not `csh`.

To make a directory, type the following:

>     mkdir simpxml
>     cd simpxml

Step 1.2: Copy the simpxml Files

Later in the process you will edit some of the files and make them executable, so it is best to begin with a copy of the files rather than the originals delivered with the software. To copy the `simpxml` files for the Unix platform, type the following:

>     cp $TUXDIR/eLink/xml/simpxml/* ./

The directory shown in Listing 4-1 contains sample files for configuring the eLink Adapter for XML.

> Listing 4-1 Description of Sample Files

> File Name | Description
> --- | ---
> elinkxml.ubb | sample TUXEDO ubbconfig file
> elinkxml.env | sample TUXEDO ENVFILE for eLink for XML adapter
> elinkxml.cfg | sample eLink for XML adapter configuration file
> setenv.sh | sample UNIX Korn Shell script to set environment
> xmlcl.c | sample XML client application
> oagis_license.txt | Open Applications Group license file
> 002_confirm_bod_002.xml | sample XML file from Open Applications Group
> 002_confirm_bod_002.dtd | sample DTD file from Open Applications Group
> confirm_bod.fml | sample FML file defining FML fields
> bank.fgf | sample FML Group Format file
> bank.ud | sample ud32 script to send FML32 data to XML adapter
> bank_mti.ud | sample ud32 script to send FML32 data to XML adapter
> bankflds | sample FML file defining fields to be sent to/from the XML adapter

## Step 2: Set Up Environment Files

The information in this section is designed to help you perform the following two setup tasks on both platforms:

- Setting up and exporting environment variables for the Unix platform

- Editing the adapter environment for the Unix platform

  Step 2.1 Set and Export Environment Variables for the Unix Platform

To set and export the environment variables, you must edit the `setenv.sh` file if you are using a Unix platform. You need the `TUXDIR` and `PATH` to access files in the TUXEDO System/T directory structure and execute TUXEDO System/T commands. With HPUX on the HP9000, use `SHLIB_PATH` instead of `LD_LIBRARY_PATH`. Listing 4-2 shows a sample of the environment variables for the Unix platform.

Note: You must set up the TUXCONFIG to be able to load the configuration file.

To set and export the environment variables for a Unix platform, edit the provided file `setenv.sh`. Using a standard text editor, follow these steps:

1. Bring up `setenv.sh` in your text editor.

2. Replace the fields delimited with `<' and `>' signs.

3. Set the shared library path for Unix:
   `SHLIB_PATH=$(TUXDIR)/lib:$(SHLIB_PATH)`

4. Set the environment by executing this script:
   `. . /setenv.sh`

   > Listing 4-2 Sample Environment Variables File for the Unix Platform

   >     #!/bin/sh
   >     APPDIR=<your eLink app directory>
   >     export APPDIR
   >     TUXDIR=<your TUXEDO install directory>
   >     export TUXDIR
   >     TUXCONFIG=${APPDIR}/tuxconfig
   >     export TUXCONFIG
   >     BDMCONFIG=${APPDIR}/bdmconfig
   >     export BDMCONFIG
   >     FIELDTBLS32=elinkxml.fml,Usysfl32,bankflds,confirm_bod.fml
   >     export FIELDTBLS32
   >     FLDTBLDIR32=${APPDIR}:${TUXDIR}/udataobj
   >     export FLDTBLDIR32
   >     PATH=${TUXDIR}/bin:${PATH}

   Step 2.2 Edit the Adapter Environment File

You must edit the adapter environment file to allow the adapter to access system and user-defined FML field tables. Table 4-1 provides a description of the two environment variables to access FML tables. Listing 4-3 shows a sample adapter environment file.

Using a standard text editor, follow these steps:

1. Access the environment file `elinkxml.env`.

2. Replace the fields delimited with `<' and `>' signs.

   > Table 4-1 Environment Variables to Access FML Tables

   > Variable Name | Description
   > --- | ---
   > FIELDTBLS32 | Lists the FML field tables that are to be access by the XML adapter.
   > FLDTBLDIR32 | Lists the directories to be searched for these FML field tables.

   > Listing 4-3 Sample Adapter Environment File

   >     FIELDTBLS32=Usysfl32,elinkxml.fml,bankflds,confirm_bod.fml

   >     FLDTBLDIR32=<your eLink app directory>:<your TUXEDO install directory>/udataobj

## Step 3: Edit the TUXEDO Configuration File

To define the `elinkxml` server, add the `elinkxml` information in the SERVERS section of the UBBCONFIG file. The following parameters are required for defining the `elinkxml` server. Listing 4-4 shows the parameters for defining the server.

> Listing 4-4 Parameters for Defining the elinkxml Server

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

CLOPT= "-- -C `configfile`"
  specifies the adapter's configuration file.

Listing 4-5 shows a sample configuration file.

> Listing 4-5 Sample Configuration File

>     #################################################################
>     # This is a skeletal TUXEDO configuration file - "ePS.ubb" designed
>     # to be used for BEA eLink Adapter for elinkxml.ubb
>     #
>     ################################################################## @(#)$Header: /repos/efx/sample/simpxml/elinkxml.ubb,v 1.1 1999/10/04 22:27:18 schupbac Exp $
>     # Copyright )1999, BEA Systems, Inc., all rights reserved.

>     *RESOURCES
>     IPCKEY          33248        # ( 32768 < IPCKEY < 262143 )
>     MASTER          eLink
>     DOMAINID        eLink
>     MODEL           SHM
>     MAXSERVERS      20
>     SECURITY        NONE
>     #SECURITY       USER_AUTH

>     *MACHINES
>     "<uname>" LMID="eLink"
>             TUXDIR="<your TUXEDO install directory>"
>             APPDIR="<your eLink app directory>"
>             TUXCONFIG="<your eLink app directory>/tuxconfig"
>             ENVFILE="<your eLink app directory>/elinkxml.env"
>             TYPE="HP-UX"
>             MAXACCESSERS=80

>     *GROUPS
>     EXMLGRP	LMID=eLink

>     	GRPNO=1

>     # ----------------------------------------------------------------------

>     *SERVERS

>     DEFAULT:
>            CLOPT="-A"       # Advertise all services.
>              REPLYQ=N         # Reply queue not needed for our simple setup.
>              MAXGEN=3         # Max number of restarts in the grace period.
>            GRACE=60         # Ten minutes grace period.
>            RESTART=Y
>             SYSTEM_ACCESS=FASTPATH

>     elinkxml
>     		SRVGRP=EXMLGRP
>                     SRVID=200
>                     CLOPT="-A -- -C elinkxml.cfg"

>     *SERVICES

## Step 4: Load the TUXEDO Configuration File

Perform two primary tasks to load the TUXEDO configuration file:

- Run `tmloadcf` to load the file.

- Check the configuration file to ensure that it is called `tuxconfig.`

  Step 4.1: Load the File

Run `tmloadcf` to load the configuration file.

`$ tmloadcf elinkxml.ubb
Initialize TUXCONFIG file: /usr/me/simpxml/tuxconfig [y, q] ? y
$`

Step 4.2: Check the Results

Check to ensure that a file called `tuxconfig` is a new file under the control of TUXEDO System/T. Listing 4-6 shows a sample TUXEDO configuration file.

> Listing 4-6 Sample TUXEDO Configuration File

`$ ls -l tuxconfig
total 216
-rw-r----- 1 userid grpid 106496 May 29 09:26 tuxconfig`

## Step 5: Edit the Adapter Configuration File

Examine the sample adapter configuration file shown in Listing 4-7, and use the descriptions provided in Table 4-2 to help you understand the file's contents.

Use the following steps to access the source code:

1. Access the `elinkxml.cfg` file using your text editor.

2. Page through the configuration file and look for the following information detailed in table 4-2.

   > Table 4-2 Parameters in the Sample Adapter Configuration File

   > Parameter Name | Description
   > --- | ---
   > NAME | Defines this specific instance of the XML adapter to be `myelinkxml`.
   > TRACE | Indicates that additional debug messages are not logged.
   > *SERVICE | Examine three defined services. These services are advertised when the server `elinkxml` is booted. The first service BANKFLDS is defined as an FML2XML service. This service converts data from FML format to XML format. The LIST_TAG_SUFFIX '_LIST' is appended to FML field names to create a XML tag that indicates a list of such values is following. The second service CONFIRM_BOD is defined as an XML2FML service. This service converts data from XML format to FML format. The third service BANKFLDS_MTI is defined as an FMLMTI2XML service. This service converts data from FML format to XML format. The service uses the MTI File `bank.mti` to preserve grouping information in the generated XML data.

   > Listing 4-7 Sample Adapter Configuration File

   >     *SERVER
   >     NAME=myelinkxml
   >     TRACE=N

   >     *SERVICE
   >     NAME=BANKFLDS
   >     CONVERSION_TYPE=FML2XML
   >     LIST_TAG_SUFFIX=_LIST

   >     *SERVICE
   >     NAME=CONFIRM_BOD
   >     CONVERSION_TYPE=XML2FML

   >     *SERVICE
   >     NAME=BANKFLDS_MTI
   >     CONVERSION_TYPE=FMLMTI2XML
   >     MTI_NAME=bank.mti

## Step 6: Boot the Application

BBL is the administrative process that monitors the application shared memory structures. The server (`elinkxml)` runs continuously awaiting requests. Executing `tmboot` brings up the adapter. Listing 4-8 shows a sample boot process. To execute `tmboot`, type the following:

`tmboot -y`.

> Listing 4-8 Sample Boot Process

>     INFO: TUXEDO(r) System Release 6.5
>     INFO: Serial #: 1000039580, Expiration 2000-02-16, Maxusers 10000
>     INFO: Licensed to: FOO SYSTEMS

>     Booting admin processes ...

>     exec BBL -A :
>     	process id=20993 ... Started.

>     Booting server processes ...

>     exec elinkxml -A -- -C elinkxml.cfg :
>     	process id=20994 ... Started.
>     2 processes started.

## Step 7: Send an XML2FML Conversion Request

Included with the XML adapter is a sample TUXEDO client program. This supplied client `xmlcl.c` reads a string of XML data from standard input and sends the data to a TUXEDO service via the TUXEDO ATMI function tpcall (). The XML data is put in an FML32 buffer as a single field `ELINK_XML_DATA`. The response received from the adapter is an FML32 buffer that is printed to standard out using the FML function `Fprint32()`. Perform three primary tasks to send an XML2FML service request:

- Examine the XML client program.

- Build the XML client program.

- Run the XML client program.

  Step 7.1 Examine the XML Client Program

Before you build the XML client program, examine the program for several important considerations. Table 4-3 provides a key to some important information for you to consider as you examine the XML client program. Listing 4-9 shows a sample source code. Use the following steps to access the source code:

1. Access the source code by typing:
   `$ more xmlcl.c`

2. Page through the client program and look for the following information:

   > Table 4-3 Significant Information in the XML Client Program

   > Line Number | Significant Information
   > --- | ---
   > 43 | The XML adapter conversion service to invoke is accepted as the first command line parameter.
   > 107-127 | XML data is added to the FML buffer as `ELINK_XML_DATA`.
   > 135 | The XML adapter service is invoked via `tpcall`.
   > 149 | Fprint32 is used to print out the FML buffer returned by the XML adapter.

   > Listing 4-9 Sample Source Code (xmlcl.c)

   >     1:/*	Copyright 1999 BEA Systems, Inc.	*/
   >     2:/*	THIS IS UNPUBLISHED PROPRIETARY SOURCE CODE OF     	*/
   >     3:/*	BEA Systems, Inc.                     	*/
   >     4:/*	The copyright notice above does not evidence any   	*/
   >     5:/*	actual or intended publication of such source code.	*/
   >     6:
   >     7:#include <stdio.h>
   >     8:#include <string.h>
   >     9:#include <malloc.h>
   >     10:#include "atmi.h		"/* TUXEDO  Header File */
   >     11:#include "fml32.h"              /* FML32 Header File */
   >     12:
   >     13:#define NF 200
   >     14:#define FLDBUFSIZE 20000
   >     15:#define MAX_XML_DATA 32760
   >     16:
   >     17:#if defined(__STDC__) || defined(__cplusplus)
   >     18:main(int argc, char *argv[])
   >     19:#else
   >     20:main(argc, argv)
   >     21:int argc;
   >     22:char *argv[];
   >     23:#endif
   >     24:{
   >     25:        char temp[BUFSIZ];
   >     26:	char   *service;
   >     27:	char   *xmldata;
   >     28:        FBFR32 *xmlbuf;
   >     29:        FBFR32 *rcvbuf;
   >     30:	FLDID32 fldid;
   >     31:        FLDLEN32 fbfr_len;
   >     32:	long sendlen;
   >     33:	int ret;
   >     34:
   >     35:	/*-------------------------*/
   >     36:	/* Check command line args */
   >     37:	/*-------------------------*/
   >     38:	if(argc != 2)
   >     39:	{
   >     40:		(void) fprintf(stderr, "Usage: xmlcl service\n");
   >     41:		exit(1);
   >     42:	}
   >     43:	service = argv[1];
   >     44:
   >     45:	/*----------------------------------------*/
   >     46:	/* Attach to System/T as a Client Process */
   >     47:	/*----------------------------------------*/
   >     48:	if (tpinit((TPINIT *) NULL) == -1)
   >     49:	{
   >     50:		(void) fprintf(stderr, "Tpinit failed\n");
   >     51:		exit(1);
   >     52:	}
   >     53:
   >     54:	/*-----------------------------------------*/
   >     55:	/* Allocate string buffer to hold XML data */
   >     56:	/*-----------------------------------------*/
   >     57:	if ((xmldata = (char *) malloc(MAX_XML_DATA)) == NULL)
   >     58:        {
   >     59:		(void) fprintf(stderr,"Error allocating xml buffer\n");
   >     60:		tpterm();
   >     61:		exit(1);
   >     62:	}
   >     63:
   >     64:	/*-------------------------*/
   >     65:        /* Loop reading from stdin */
   >     66:	/*-------------------------*/
   >     67:        while(gets(temp) != NULL)
   >     68:        {
   >     69:          strcat(xmldata,temp);
   >     70:        }
   >     71:
   >     72:
   >     73:	/*----------------------------------------------------*/
   >     74:	/* Allocate FML buffers for the request and the reply */
   >     75:	/*----------------------------------------------------*/
   >     76:        if ((xmlbuf = (FBFR32 *) tpalloc("FML32",NULL,Fneeded32(1,strlen(xmldata) + 1)))== (FBFR32 *) NULL)
   >     77:	{
   >     78:		(void) fprintf(stderr,"Error allocating send buffer\n");
   >     79:		free(xmldata);
   >     80:		tpterm();
   >     81:		exit(1);
   >     82:	}
   >     83:
   >     84:	/*--------------------------*/
   >     85:        /* Allocate response buffer */
   >     86:	/*--------------------------*/
   >     87:        if ((rcvbuf = (FBFR32 *) tpalloc("FML32",NULL,Fneeded32(NF,FLDBUFSIZE)))== (FBFR32 *) NULL)
   >     88:	{
   >     89:                (void) fprintf(stderr,"unable to allocate buffer: %s\n",
   >     90:                        tpstrerror(tperrno));
   >     91:                free(xmldata);
   >     92:		tpfree((char *) xmlbuf);
   >     93:		tpterm();
   >     94:                exit(1);
   >     95:        }
   >     96:
   >     97:	/*------------------------*/
   >     98:	/* Initialize FML buffers */
   >     99:	/*------------------------*/
   >     100:        fbfr_len = Fneeded32(NF,FLDBUFSIZE);
   >     101:        Finit32(xmlbuf, fbfr_len);
   >     102:        Finit32(rcvbuf, fbfr_len);
   >     103:
   >     104:	/*--------------------------*/
   >     105:	/* Add ELINK_XML_DATA field */
   >     106:	/*--------------------------*/
   >     107:	fldid = Fldid32("ELINK_XML_DATA");
   >     108:
   >     109:	if (fldid == BADFLDID)
   >     110:	{
   >     111:                (void) fprintf(stderr,"Failed to get ID for ELINK_XML_DATA field\n");
   >     112:                free(xmldata);
   >     113:		tpfree((char *) xmlbuf);
   >     114:		tpfree((char *) rcvbuf);
   >     115:		tpterm();
   >     116:                exit(1);
   >     117:	}
   >     118:        if (Fadd32(xmlbuf, fldid, xmldata, (strlen(xmldata) + 1)) < 0)
   >     119:	{
   >     120:                userlog("Failed to add field ELINK_XML_DATA (error: %s)\n",
   >     121:                                 Fstrerror32(Ferror32));
   >     122:                free(xmldata);
   >     123:		tpfree((char *) xmlbuf);
   >     124:		tpfree((char *) rcvbuf);
   >     125:		tpterm();
   >     126:                exit(1);
   >     127:        }
   >     128:
   >     129:        printf("\n --- Sending XML Data --- \n");
   >     130:        Fprint32(xmlbuf);
   >     131:
   >     132:	/*--------------------------------------------*/
   >     133:	/* Request the service, waiting for the reply */
   >     134:	/*--------------------------------------------*/
   >     135:	ret = tpcall(service, (char *)xmlbuf, fbfr_len, (char **)&rcvbuf, (long *) &fbfr_len, (long)0);
   >     136:
   >     137:	if(ret == -1)
   >     138:	{
   >     139:		(void) fprintf(stderr, "Can't send request to service %s\n", service);
   >     140:		(void) fprintf(stderr, "Tperrno = %s\n", tpstrerror(tperrno));
   >     141:		free(xmldata);
   >     142:		tpfree((char *) xmlbuf);
   >     143:		tpfree((char *) rcvbuf);
   >     144:		tpterm();
   >     145:		exit(1);
   >     146:	}
   >     147:
   >     148:        printf("\n --- Received FML Data --- \n");
   >     149:        Fprint32(rcvbuf);
   >     150:
   >     151:	/*-------------------------------------*/
   >     152:	/* Free Buffers & Detach from System/T */
   >     153:	/*-------------------------------------*/
   >     154:	free(xmldata);
   >     155:	tpfree((char *) xmlbuf);
   >     156:	tpfree((char *) rcvbuf);
   >     157:	tpterm();
   >     158:	return(0);
   >     159:}

   Step 7.2 Build the XML Client Program

To run `buildclient` where the output file is `xmlcl` and the input source file is `xmlcl.c,` type the following:

`buildclient -o xmlcl -f xmlcl.c`

Step 7.3 Run the XML Client Program

With TUXEDO booted, the `xmlcl` program can be run by specifying the service to invoke as the first command line parameter and by redirecting standard input to read a file that contains an XML string. The name of the service (from the adapter configuration file) is `CONFIRM_BOD`. The file `002_confirm_bod_002.xml` is the file that contains XML data.

The XML adapter returns an FML buffer that has FML fields for each XML tag-value set found in the XML request data. The adapter uses the FML field definitions defined in the supplied file `confirm_bod.fml`. Listing 4-10 shows sample client program output. To execute the client, enter the following:

>     xmlcl CONFIRM_BOD < 002_confirm_bod_002.xml

> Listing 4-10 Sample XML Client Program Output

>     <!DOCTYPE CONFIRM_BOD_002 SYSTEM "002_confirm_bod_002.dtd">

>     <CONFIRM_BOD_002>
>     	<CNTROLAREA>
>     		<BSR>
>     			<VERB>CONFIRM</VERB>
>     			<NOUN>BOD</NOUN>
>     			<REVISION>001</REVISION>
>     		</BSR>
>     		<SENDER>
>     			<LOGICALID>XXX1234YYY</LOGICALID>
>     			<COMPONENT>G/L</COMPONENT>
>     			<TASK>CONFIRM</TASK>
>     			<REFERENCEID>REF1</REFERENCEID>
>     			<CONFIRMATION>0</CONFIRMATION>
>     			<LANGUAGE>EN</LANGUAGE>
>     			<CODEPAGE>CP001</CODEPAGE>
>     			<AUTHID>JOE DOE</AUTHID>
>     		</SENDER>
>     		<DATETIME qualifier = "CREATION">
>                 <YEAR>1998</YEAR>
>     			<MONTH>12</MONTH>
>     			<DAY>31</DAY>
>     			<HOUR>17</HOUR>
>     			<MINUTE>59</MINUTE>
>     			<SECOND>00</SECOND>
>     			<SUBSECOND>0000</SUBSECOND>
>     			<TIMEZONE>-0500</TIMEZONE>
>     		</DATETIME>
>     	</CNTROLAREA>
>     	<DATAAREA>
>     		<CONFIRM_BOD>
>     			<CONFIRM>
>                     <CNTROLAREA>
>                         <BSR>
>                             <VERB>UPDATE</VERB>
>                             <NOUN>INVENTORY</NOUN>
>                             <REVISION>002</REVISION>
>                         </BSR>
>                         <SENDER>
>                             <LOGICALID>XX141HG09</LOGICALID>
>                             <COMPONENT>INVENTORY</COMPONENT>
>                             <TASK>RECEIPT</TASK>
>                             <REFERENCEID>95129945823449</REFERENCEID>
>                             <CONFIRMATION>0</CONFIRMATION>
>                             <LANGUAGE>EN</LANGUAGE>
>                             <CODEPAGE>CP001</CODEPAGE>
>                             <AUTHID>KURTC</AUTHID>
>                         </SENDER>
>                         <DATETIME qualifier = "CREATION">
>                             <YEAR>1998</YEAR>
>                             <MONTH>06</MONTH>
>                             <DAY>15</DAY>
>                             <HOUR>08</HOUR>
>                             <MINUTE>14</MINUTE>
>                             <SECOND>00</SECOND>
>                             <SUBSECOND>0000</SUBSECOND>
>                             <TIMEZONE>-0600</TIMEZONE>
>                         </DATETIME>
>                     </CNTROLAREA>
>     				<STATUSLVL>00</STATUSLVL>
>     				<DESCRIPTN>THIS BOD HAS BEEN PROCESSED WITHOUT ERRORS</DESCRIPTN>

>     				<ORIGREF>RCPT#12550699</ORIGREF>
>     				<USERAREA>USER1=FOO</USERAREA>
>     				<CONFIRMMSG>
>     			        <DESCRIPTN>SYSTEM X SCREEN 123 OK 0.234SEC</DESCRIPTN>
>     		            <REASONCODE>MISC</REASONCODE>
>     	            </CONFIRMMSG>
>     			</CONFIRM>
>     		</CONFIRM_BOD>
>     	</DATAAREA>
>     </CONFIRM_BOD_002>

>      --- Received FML Data ---
>     CONFIRMATION    0
>     CONFIRMATION    0
>     YEAR	1998
>     YEAR	1998
>     MONTH	12
>     MONTH	6
>     DAY	31
>     DAY	15
>     HOUR	17
>     HOUR	8
>     MINUTE	59
>     MINUTE	14
>     SECOND	0
>     SECOND	0
>     SUBSECOND       0
>     SUBSECOND       0
>     TIMEZONE        -500
>     TIMEZONE        -600
>     STATUSLVL       0
>     VERB	 CONFIRM
>     VERB	 UPDATE
>     NOUN	 BOD
>     NOUN	 INVENTORY
>     REVISION        001
>     REVISION        002
>     LOGICALID       XXX1234YYY
>     LOGICALID       XX141HG09
>     COMPONENT       G/L
>     COMPONENT       INVENTORY
>     TASK	 CONFIRM
>     TASK	 RECEIPT
>     LANGUAGE        EN
>     LANGUAGE        EN
>     CODEPAGE        CP001
>     CODEPAGE        CP001
>     AUTHID	 JOE DOE
>     AUTHID	 KURTC
>     DESCRIPTN       THIS BOD HAS BEEN PROCESSED WITHOUT ERRORS
>     DESCRIPTN      SYSTEM X SCREEN 123 OK 0.234SEC
>     ORIGREF	RCPT#12550699
>     REFERENCEID    REF1
>     REFERENCEID    95129945823449
>     USERAREA       USER1=FOO
>     REASONCODE     MISC

Note: The file `002_confirm_bod_002.xml` was created by the Open Applications Group. The Open Applications Group is a non-profit industry consortium whose purpose is to promote the easy and cost-effective integration of key business application software components for enterprise and supply chain functions for end-user organizations. Additional XML examples are available at www.openapplications.org.

## Step 8: Send an FML2XML Conversion Request

The XML adapter also can convert FML data to XML format. BEA TUXEDO provides a client program, `ud32`, that creates FML buffers and invokes TUXEDO services via `tpcall`. `ud32` is a TUXEDO utility that reads tab delimited text from its standard input. This text indicates what fields to populate in an FML buffer and what TUXEDO service should be invoked. The XML adapter provides text files to use with the `ud32` utility. For more information on `ud32`, see the BEA TUXEDO Reference Manual, Section 1. Perform two primary tasks to send an FML2XML service request:

- Examine the FML data.

- Execute `ud32.`

  Step 8.1: Examine the FML Data

To demonstrate the FML2XML conversion, the `bank.ud` text file is provided. Listing 4-11 shows this sample FML data file. Use the following steps to access the source file:

1. Access the text file by typing:
   `more bank.ud`

2. Page through the file to see an example of FML data.

   > Listing 4-11 Sample FML Data File

   >     SRVCNM  BANKFLDS
   >     ACCOUNT_ID      1019
   >     ACCT_TYPE       C
   >     ADDRESS Two Preston Park Blvd. Plano  TX 75093
   >     AMOUNT  1000.0
   >     BALANCE 123456.78
   >     BRANCH_ID       14
   >     FIRST_NAME      John
   >     LAST_ACCT       101
   >     LAST_NAME       Doe
   >     LAST_TELLER     Wilma
   >     MID_INIT        C
   >     PHONE   (972)-555-1234
   >     SSN     999-99-9999
   >     TELLER_ID       1001
   >     ACCOUNT_ID      1020
   >     ACCT_TYPE       C
   >     ADDRESS Three Preston Park Blvd. Plano  TX 75093
   >     AMOUNT  999.99
   >     BALANCE 100.0
   >     BRANCH_ID       15
   >     FIRST_NAME      Jane
   >     LAST_ACCT       102
   >     LAST_NAME       Doe
   >     LAST_TELLER     Betty
   >     MID_INIT        D
   >     PHONE	(214)-555-4321
   >     SSN	999-99-9999
   >     TELLER_ID       1002

   Step 8.2: Execute ud32

Each occurrence of an FML Field has been converted to an XML tag-value set. For example, the original FML buffer had two occurrences of the field FIRST_NAME. The corresponding XML string has a list called <FIRST_NAME_LIST> with each occurrence of FIRST_NAME data tagged as <FIRST_NAME>. Listing 4-12 shows a sample `ud32` file.

Notice that the implied grouping of the FML data is not represented in the XML string. Occurrences of the field FIRST_NAME and LAST_NAME are not listed together as a unit, instead they are listed in separate lists. In order to preserve grouping information, we must use a Meta-Type Information file. Use the FML2XML conversion only used when there is not an implied grouping of FML data. To execute the `ud32` using `bank.ud,` enter the following:

`ud32 < bank.ud`

> Listing 4-12 Sample FML2XML Invocation

>     SENT pkt(1) is :
>     BRANCH_ID        14
>     BRANCH_ID        15
>     LAST_ACCT        101
>     LAST_ACCT        102
>     LAST_TELLER      0
>     LAST_TELLER      0
>     ACCOUNT_ID       1019
>     ACCOUNT_ID       1020
>     TELLER_ID        1001
>     TELLER_ID        1002
>     ACCT_TYPE        C
>     ACCT_TYPE        C
>     MID_INIT         C
>     MID_INIT         D
>     BALANCE 123457
>     BALANCE 100
>     AMOUNT  1000
>     AMOUNT  999.99
>     SRVCNM  BANKFLDS
>     PHONE   (972)-555-1234
>     PHONE   (214)-555-4321
>     ADDRESS Two Preston Park Blvd. Plano  TX 75093
>     ADDRESS Three Preston Park Blvd. Plano  TX 75093
>     SSN     999-99-9999
>     SSN     999-99-9999
>     LAST_NAME       Doe
>     LAST_NAME       Doe
>     FIRST_NAME      John
>     FIRST_NAME      Jane

>     RTN pkt(1) is :
>     ELINK_XML_DATA
>     <BRANCH_ID_LIST>\0d\0a<BRANCH_ID>14</BRANCH_ID>\0d\0a<BRANCH_ID>15</BRANCH_ID>\0d\0a</BRANCH_ID_LIST>\0d\0a
>     <LAST_ACCT_LIST>\0d\0a<LAST_ACCT>101</LAST_ACCT>\0d\0a<LAST_ACCT>102</LAST_ACCT>\0d\0a</LAST_ACCT_LIST>\0d\0a
>     <LAST_TELLER_LIST>\0d\0a<LAST_TELLER>0</LAST_TELLER>\0d\0a<LAST_TELLER>0</LAST_TELLER>\0d\0a</LAST_TELLER_LIST>\0d\0a
>     <ACCOUNT_ID_LIST>\0d\0a<ACCOUNT_ID>1019</ACCOUNT_ID>\0d\0a<ACCOUNT_ID>1020</ACCOUNT_ID>\0d\0a</ACCOUNT_ID_LIST>\0d\0a
>     <TELLER_ID_LIST>\0d\0a<TELLER_ID>1001</TELLER_ID>\0d\0a<TELLER_ID>1002</TELLER_ID>\0d\0a</TELLER_ID_LIST>\0d\0a
>     <ACCT_TYPE_LIST>\0d\0a<ACCT_TYPE>C</ACCT_TYPE>\0d\0a<ACCT_TYPE>C</ACCT_TYPE>\0d\0a</ACCT_TYPE_LIST>\0d\0a
>     <MID_INIT_LIST>\0d\0a<MID_INIT>C</MID_INIT>\0d\0a<MID_INIT>D</MID_INIT>\0d\0a</MID_INIT_LIST>\0d\0a
>     <BALANCE_LIST>\0d\0a<BALANCE>123456.8</BALANCE>\0d\0a<BALANCE>100.0000</BALANCE>\0d\0a</BALANCE_LIST>\0d\0a
>     <AMOUNT_LIST>\0d\0a<AMOUNT>1000.000</AMOUNT>\0d\0a<AMOUNT>999.9900</AMOUNT>\0d\0a</AMOUNT_LIST>\0d\0a
>     <SRVCNM_LIST>\0d\0a<SRVCNM>BANKFLDS</SRVCNM>\0d\0a</SRVCNM_LIST>\0d\0a
>     <PHONE_LIST>\0d\0a<PHONE>(972)-555-1234</PHONE>\0d\0a<PHONE>(214)-555-4321</PHONE>\0d\0a</PHONE_LIST>\0d\0a
>     <ADDRESS_LIST>\0d\0a<ADDRESS>Two Preston Park Blvd. Plano  TX 75093</ADDRESS>\0d\0a
>     <ADDRESS>Three Preston Park Blvd. Plano  TX 75093</ADDRESS>\0d\0a</ADDRESS_LIST>\0d\0a
>     <SSN_LIST>\0d\0a<SSN>999-99-9999</SSN>\0d\0a<SSN>999-99-9999</SSN>\0d\0a</SSN_LIST>\0d\0a
>     <LAST_NAME_LIST>\0d\0a<LAST_NAME>Dough</LAST_NAME>\0d\0a<LAST_NAME>Dough</LAST_NAME>\0d\0a</LAST_NAME_LIST>\0d\0a
>     <FIRST_NAME_LIST>\0d\0a<FIRST_NAME>John</FIRST_NAME>\0d\0a<FIRST_NAME>Jane</FIRST_NAME>\0d\0a</FIRST_NAME_LIST>\0d\0a

## Step 9: Send an FML to XML Conversion Request Using an MTI File

The XML adapter can convert FML data to XML format and maintain grouping information using a Meta-Type Information (MTI) file. The examples in this section use the TUXEDO utility `ud32` as described in the previous section. This example demonstrates the use of the FML Group Format language and the `fgf2mti` utility that converts this language to an MTI file that the XML adapter can understand. Perform four primary tasks to send and FMLMTI2XML service request:

- Examine the FML data

- Examine the FGF file

- Create the MTI file

- Execute `ud32`

  Step: 9.1: Examine the FML Data

The `bank_mti.ud` text file demonstrates the FML to XML data conversion. This FML data is exactly the same as the `bank.ud` file except the service to invoke (SRVCNM field) is BANKFLDS_MTI. This service is configured in the provided configuration file `elinkxml.cfg`. Listing 4-13 shows a sample FML data file. Use the following steps to examine the sample FML file.

1. Access the text file by typing:
   `more bank_mti.ud`

2. Page through the file to see an example of FML data.

   > Listing 4-13 Sample FML Data

   >     SRVCNM BANKFLDS_MTI
   >     ACCOUNT_ID      1019
   >     ACCT_TYPE       C
   >     ADDRESS Two Preston Park Blvd. Plano  TX 75093
   >     AMOUNT  1000.0
   >     BALANCE 123456.78
   >     BRANCH_ID       14
   >     FIRST_NAME      John
   >     LAST_ACCT       101
   >     LAST_NAME       Doe
   >     LAST_TELLER     Wilma
   >     MID_INIT        C
   >     PHONE   (972)-555-1234
   >     SSN     999-99-9999
   >     TELLER_ID       1001
   >     ACCOUNT_ID      1020
   >     ACCT_TYPE       C
   >     ADDRESS Three Preston Park Blvd. Plano  TX 75093
   >     AMOUNT  999.99
   >     BALANCE 100.0
   >     BRANCH_ID       15
   >     FIRST_NAME      Jane
   >     LAST_ACCT       102
   >     LAST_NAME       Doe
   >     LAST_TELLER     Betty
   >     MID_INIT        D
   >     PHONE  (214)-555-4321
   >     SSN    999-99-9999
   >     TELLER_ID       1002

   Step 9.2: Examine the FGF Group File

FML Group Format (FGF) is a small language (three keywords) that is used to describe how FML fields should be grouped together when extracted into a hierarchical structure. FGF allows the nesting of groups and even nesting of occurrence information within a group.

The GROUP keyword denotes the start of a list of fields that should be converted together. The END keyword denotes the end of such a list. In the example below, notice that the ACCOUNT group indicates that occurrences of the fields ACCOUNT_ID, ACCT_TYPE, etc. should be converted to XML as a group called `ACCOUNT'. The OCCURS 2 clause tells the XML adapter to expect two instances of the ACCOUNT group. Listing 4-14 shows a sample of FGF data. Use the following steps to examine the sample FGF file.

1. Access the text file by typing:
   `more bank.fgf`

2. Page through the file to see an example of FML and FGF data.

   > Listing 4-14 Sample FGF Data

   >     GROUP ACCOUNTS
   >         GROUP ACCOUNT OCCURS 2
   >           long ACCOUNT_ID
   >           char ACCT_TYPE
   >           string FIRST_NAME
   >           char MID_INIT
   >           string LAST_NAME
   >           string SSN
   >           string ADDRESS
   >           string PHONE
   >           float AMOUNT
   >           float BALANCE
   >           long BRANCH_ID
   >           long TELLER_ID
   >           long LAST_TELLER
   >           long LAST_ACCT
   >         END
   >     END

   Step 9.3: Create the MTI File

The FML Importer utility (FGF2MTI) must process the FGF file in order for the eLink Adapter to use grouping information. The FGF2MTI utility takes two parameters. The FGF file (`bank.fgf` in this example) and the FML Field Definition File (`bankflds` in this example) are needed in order the generate the Meta-Type Information (MTI) file. The eLink Adapter then uses the MTI file at run time to convert the FML data to XML. The outcome for this example is a file called `bank.mti`. Listing 4-15 shows a sample MTI file.

Errors appear in a file with the same name as the FGF file but using an `.err` extension. The `.err` file is generated when you complete the process of creating an MTI file. If no errors occurred, the `.err` file provides a log entry that indicates that no errors were found.

Use the following steps to generate the MTI file.

1. Run the `fgf2mti` utility by typing:
   `fgf2mti bank.fgf bankflds`

2. Page through the file to see the resulting `bank.mti` file.

   > Listing 4-15 Sample MTI File

   >     10 7 10 Thu Oct  7 09:25:43 1999
   >     11 3
   >     14 LAST_ACCT 1 0
   >     11 3
   >     14 LAST_TELLER 3 2
   >     11 3
   >     14 TELLER_ID 5 4
   >     11 3
   >     14 BRANCH_ID 7 6
   >     11 4
   >     14 BALANCE 9 8
   >     11 4
   >     14 AMOUNT 11 10
   >     11 6
   >     14 PHONE 13 12
   >     11 6
   >     14 ADDRESS 15 14
   >     11 6
   >     14 SSN 17 16
   >     11 6
   >     14 LAST_NAME 19 18
   >     11 1
   >     14 MID_INIT 21 20
   >     11 6
   >     14 FIRST_NAME 23 22
   >     11 1
   >     14 ACCT_TYPE 25 24
   >     11 3
   >     14 ACCOUNT_ID 27 26
   >     13 ACCOUNT 14 28
   >     12 0 2 29
   >     14 ACCOUNT 30 0
   >     13 ACCOUNTS 1 31
   >     15 7 10 32

   Step 9.4: Execute ud32

Use the bank_mti.ud file with ud32 to invoke the conversion service BANKFLDS_MTI. This service is configured in the XML adapter configuration file (elinkxml.cfg)to use the MTI file `bank.mti`. Since we have generated this MTI file we are now ready to send conversion requests to this service. Listing 4-16 shows the `ud32` request you must issue with the TUXEDO system and the XML adapter booted.

Notice that the grouping of information has been maintained. Each field of the ACCOUNT group has been converted in the order specified in the FGF file, `bank.fgf`. Each occurrence of FIRST_NAME field is not listed together in a FIRST_NAME list (see FML2XML example), instead each field of the ACCOUNT group is listed, and fields are grouped as occurrences of ACCOUNT information.

> Listing 4-16 Sample .mti.ud File

>     ud32 < bank_mti.ud

>     SENT pkt(1) is :
>     BRANCH_ID       14
>     BRANCH_ID       15
>     LAST_ACCT       101
>     LAST_ACCT       102
>     LAST_TELLER     0
>     LAST_TELLER     0
>     ACCOUNT_ID      1019
>     ACCOUNT_ID      1020
>     TELLER_ID       1001
>     TELLER_ID       1002
>     ACCT_TYPE       C
>     ACCT_TYPE       C
>     MID_INIT        C
>     MID_INIT        D
>     BALANCE 123457
>     BALANCE 100
>     AMOUNT  1000
>     AMOUNT  999.99
>     SRVCNM  BANKFLDS_MTI
>     PHONE   (972)-555-1234
>     PHONE   (214)-555-4321
>     ADDRESS Two Preston Park Blvd. Plano  TX 75093
>     ADDRESS Three Preston Park Blvd. Plano  TX 75093
>     SSN     999-99-9999
>     SSN     999-99-9999
>     LAST_NAME       Doe
>     LAST_NAME       Doe
>     FIRST_NAME      John
>     FIRST_NAME      Jane

>     RTN pkt(1) is :
>     ELINK_XML_DATA
>     <Message>
>     <ACCOUNTS_GROUP>\0d\0a
>     <ACCOUNT_GROUP>\0d\0a
>     <ACCOUNT_ID>1019</ACCOUNT_ID>\0d\0a
>     <ACCT_TYPE>C</ACCT_TYPE>\0d\0a
>     <FIRST_NAME>John</FIRST_NAME>\0d\0a
>     <MID_INIT>C</MID_INIT>\0d\0a
>     <LAST_NAME>Dough</LAST_NAME>\0d\0a
>     <SSN>999-99-9999</S
>     SN>\0d\0a
>     <ADDRESS>Two Preston Park Blvd. Plano  TX 75093</ADDRESS>\0d\0a
>     <PHONE>(972)-555-1234</PHONE>\0d\0a
>     <AMOUNT>1000.000</AMOUNT>\0d\0a
>     <BALANCE>123456.8</BALANCE>\0d\0a
>     <BRANCH_ID>14</BRANCH_ID>\0d\0a
>     <TELLER_ID>1001</TELLER_ID>\0d\0a
>     <LAST_TELLER>0</LAST_TELLER>\0d\0a
>     <LAST_ACCT>101</LAST_ACCT>\0d\0a
>     </ACCOUNT_GROUP>\0d\0a
>     <ACCOUNT_GROUP>\0d\0a
>     <ACCOUNT_ID>1020</ACCOUNT_ID>\0d\0a
>     <ACCT_TYPE>C</ACCT_TYPE>\0d\0a
>     <FIRST_NAME>Jane</FIRST_NAME>\0d\0a
>     <MID_INIT>D</MID_INIT>\0d\0a
>     <LAST_NAME>Dough</LAST_NAME>\0d\0a
>     <SSN>999-99-9999</SSN>\0d\0a
>     <ADDRESS>Three Preston Park Blvd. Plano  TX 75093</ADDRESS>\0d\0a
>     <PHONE>(214)-555-4321</PHONE>\0d\0a
>     <AMOUNT>999.9900</AMOUNT>\0d\0a
>     <BALANCE>100.0000</BALANCE>\0d\0a
>     <BRANCH_ID>15</BRANCH_ID>\0d\0a
>     <TELLER_ID>1002</TELLER_ID>\0d\0a
>     <LAST_TELLER>0</LAST_TELLER>\0d\0a
>     <LAST_ACCT>102</LAST_ACCT>\0d\0a
>     </ACCOUNT_GROUP>\0d\0a
>     </ACCOUNTS_GROUP>\0d\0a
>     </Message>

## Step 10: Shutdown the Application

Run `tmshutdown` to bring the eLink Adapter down. Listing 4-17 illustrates this process.

> Listing 4-17 Sample Shutdown Procedure

>     $ tmshutdown
>     Shutdown all admin and server processes? (y/n): y
>     Shutting down all admin and server process in /usr/me/simpxml/tuxconfig
>     Shutting down server processes . . .
>       Server Id = 200 Group Id = EXMLGRP Machine = elink: shutdown succeeded.
>     Shutting down admin processes . . .
>       Server Id = 0 Group Id = elink Machine = elink: shutdown succeeded.
>     2 processes stopped.

[Table of Contents] [Prev] [Next]