Tutorials for Developing Oracle Tuxedo ATMI Applications

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Tutorial for xmlfmlapp: A Full C XML/FML32 Conversion Application

This topic includes the following sections:


What Is xmlfmlapp?

xmlfmlapp is a sample ATMI stock application that demonstrates how to query, buy and sell stocks via client request. The application runs three services, "QUERY", "BUY" and "SELL" on a single server. These three services are written using C language and accept FML32 buffers for input and output.

This documentation leads you, step-by-step, through the procedures you must perform to develop the xmlfmlapp application. Once you have “developed” xmlfmlapp with this tutorial, you will be ready to start developing applications of your own.

The xmlfmlapp tutorial is presented in three sections:

Note: This information is geared towards system users with some experience in application development, administration, or programming. We assume some familiarity with the Oracle Tuxedo system software. A development license is required to build Oracle Tuxedo applications.


Familiarizing Yourself with xmlfmlapp

This sample demonstrates how to use XML to FML32 automatic and on-demand conversion functions to operate XML data instead of using Xerces parser APIs. To use Xerces parser APIs in a Tuxedo client/server application written in C, a dynamic library needs to be written using CPP and wrapped for use with a C program (for more information, see What Is XMLSTOCKAPP?). Using XML to FML32 on-demand and automatic conversion functionality, provides the developer with the freedom to manipulate FML32 buffer data as desired. For more information on the XML to FML/FML32 on-demand and automatic conversion functionality, see Converting XML Data To and From FML/FML32 Buffers in Programming Oracle Tuxedo ATMI Applications Using C.

In this sample, the client will send requests (query, buy or sell) to corresponding services. The client sends and receives XML buffers. To communicate with server, all three services use the "BUFTYPECONV=XML2FML32" parameter, which converts the input XML buffers to FML32 before sending the request to the corresponding service. Before returning information back to the client, this parameter then converts FML32 buffers to XML buffers. The server handles FML32 data directly.

The requesting XML buffer uses a schema to validate the XML document, thus ensuring that the request sends valid data.

The server in this sample reads stock information from an XML document and converts it to an FML32 buffer directly using the tpxmltofml32(3c) function. After that, it can get information from this buffer based on requested FML32 data, and returns the required FML32 data.

This documentation provides a tour of the files, client, and services that make up the xmlfmlapp application. The following activities for more information about that part of the tour.

Learning About the xmlfmlapp Files

The files that make up the xmlfmlapp application are delivered in the samples/atmi/xmlfmlapp directory. The xmlfmlapp directory contains the following files:

TExamining the xmlfmlapp Client

In the ATMI client-server architecture of the Oracle Tuxedo system, there are two modes of communication:

The xmlfmlapp implements the request/response mode using the following three services:

Request/Response Client

stockclient.c is a client program that uses input from the specified XML files. It calls the QUERY, BUY, and SELL services and returns the executed results. As an executable, it is invoked as follows:

See Also

Examining the xmlfmlapp Server

ATMI servers are executable processes that offer one or more services. In the Oracle Tuxedo system, they continually accept requests (from processes acting as clients) and dispatch them to the appropriate services. It is the services accessing a resource manager that provide the functionality for which your Oracle Tuxedo system transaction processing application is being developed. Service routines are one part of the application that must be written by the Oracle Tuxedo system programmer (user-defined clients being another part).

The QUERY service in the xmlfmlapp program accepts FML32 buffers. It uses functions provided in the Application-to-Transaction Monitor Interface (ATMI) to query stock information and then returns the results to the client using FML32 buffers.

The BUY service in the xmlfmlapp program accepts FML32 buffers. It uses functions provided in the Application-to-Transaction Monitor Interface (ATMI) to buy stock.

The SELL service in the xmlfmlapp program accepts FML32 buffers. It uses functions provided in the Application-to-Transaction Monitor Interface (ATMI) to sell stock.


Preparing xmlfmlapp Files and Resources

This section leads you through the procedures you must complete to create the files and other resources you need to run xmlfmlapp.

Step 1: Copy the xmlfmlapp Files to a New Directory

It is recommended that you copy the xmlfmlapp files to your own directory prior to editing any of the files or running the sample.

Step 2: Set Environment Variables

You will need to edit the environment variables file.

  1. Ensure that TUXDIR is set. If it is not set, execution of the file fails with the following message:
  2. TUXDIR: parameter null or not set
  3. Set TUXDIR to the root directory of your Oracle Tuxedo system directory structure, and export it.
  4. Set APPDIR to the directory {TUXDIR}/samples/atmi/xmlfmlapp which is the directory where xmlfmlapp source files are located. APPDIR is a directory where the Oracle Tuxedo system looks for your application-specific files. If you copied the xmlfmlapp files to a different directory to safeguard the original source files, then enter the directory there. It does not have to be under TUXDIR.
  5. When you have made all necessary changes to the environment variables file, execute it as follows:
  6. . ./setenv.cmd

    where setenv.cmd is the executable for Windows. Use setenv.sh on Unix systems.

Additional Requirements

LD_LIBRARY_PATH must include $TUXDIR/lib on systems that use shared libraries, with the exception of HP-UX and AIX.

Step 3: Create FML32 Field Table

To create the FML32 field table, use the following:

mkfldhdr32 stockflds

Step 4: Build the xmlfmlapp Binaries

The following command builds the xmlfmlapp binary files:

On windows:

    nmake -f make.nt


    make -f make.mk

Step 5: Edit the Configuration File

The sample configuration file, ubbsimple, must be edited to replace the bracketed items with values appropriate to your installation. Your TUXDIR and TUXCONFIG environment variables must match the values in the configuration file.

Listing 7-1 The ubbsimple Configuration File

# (c) 2005 BEA Systems, Inc. All Rights Reserved.
#ident "@(#) samples/atmi/xmlfmlapp/ubbsimple $Revision: 1.3 $"

#Skeleton UBBCONFIG file for the TUXEDO Simple Application.
#Replace the <bracketed> items with the appropriate values.

IPCKEY <Replace with a valid IPC Key>

#IPCKEY 123456

DOMAINID simpapp
MASTER simple


APPDIR="<Replace with the current directory pathname>"
TUXCONFIG="<Replace with your TUXCONFIG Pathname>"
TUXDIR="<Directory where TUXEDO is installed>"
# APPDIR="/home/me/simpapp"
# TUXCONFIG="/home/me/simpapp/tuxconfig"
# TUXDIR="/usr/tuxedo"

<Machine-name> LMID=simple
#beatux LMID=simple



stockserver SRVGRP=GROUP1 SRVID=1


Note: For each <string> (that is, for each string shown between angle brackets), substitute an appropriate value.

See Also

Step 6: Create the Binary Configuration File

Before creating the binary configuration file, you need to be in the directory in which your xmlfmlapp files are located and you must set the environment variables. Complete the following tasks.

  1. Go to the directory in which your xmlfmlapp files are located.
  2. Set the environment variables by entering:
  3. . ./setenv.cmd

    where setenv.cmd is the executable for Windows. Use setenv.sh on Unix systems.

Loading the Configuration File

Once you have finished editing the configuration file, you must load it into a binary file on your MASTER machine. The name of the binary configuration file is TUXCONFIG; its path name is defined in the TUXCONFIG environment variable. The file should be created by a person with the effective user ID and group ID of the Oracle Tuxedo system administrator, which should be the same as the UID and GID values in your configuration file. If this requirement is not met, you may have permission problems in running xmlfmlapp.

  1. To create TUXCONFIG, enter the following command:
  2.     tmloadcf ubbsimple

    While the configuration file is being loaded, you are prompted several times to confirm that you want to install this configuration, even if doing so means an existing configuration file must be overwritten. If you want to suppress such prompts, include the -y option on the command line.

  3. If you want the amount of IPC resources needed by your application to be calculated by the Oracle Tuxedo system, include the -c option on the command line.
  4. TUXCONFIG can be installed only on the MASTER machine; it is propagated to other machines by tmboot when the application is booted.

    tmloadcf parses the text configuration file (UBBCONFIG) for syntax errors before it loads it, so if there are errors in the file, the job fails.

See Also


Running xmlfmlapp

This section leads you through the procedures for booting xmlfmlapp, testing it by running the client program with several arguments, and shutting it down when you have finished.

Step 1: xmlfmlapp Boot Preparation

Before booting xmlfmlapp, verify that your machine has enough IPC resources to support your application. To generate a report on IPC resources, run the tmboot command with the -c option.

Step 2: Boot xmlfmlapp

  1. Set the environment:
  2. ../setenv.cmd 
  3. Boot the application by entering the following:
  4.     tmboot -y

If you prefer, you can boot only a portion of the configuration. For example, to boot only administrative servers, include the -A option. If no options are specified, the entire application is booted.

See Also

Step 3: Test xmlfmlapp Services

  1. Each time you log-in to the system, you must set your environment for xmlfmlapp. To do so, enter the following command:
  2. ../setenv.cmd
  3. Run the client program. To execute the client program, enter the following command:
  4. stockclient stock_query_bea.xml
    stockclient stock_query_msft.xml
    stockclient stock_buy_bea.xml
    stockclient stock_sell_msft.xml

Step 4: Shut Down xmlfmlapp

To bring down xmlfmlapp, enter the tmshutdown(1) command with no arguments, from the MASTER machine, as follows.

    tmshutdown -y

Running this command (or the shutdown command of tmadmin) causes the following results:

See Also

  Back to Top       Previous  Next