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 XMLSTOCKAPP: a C and C++ XML Parser Application

This topic includes the following sections:



XMLSTOCKAPP is a sample ATMI stock application that is provided with the Oracle Tuxedo system software. The application runs two servers on a single machine and illustrates invoking the parser from a C and a C++ Tuxedo server and routing of XML buffers. One server is a Tuxedo server written in C++ (stockxml) and the other server is written in C (stockxml_c). The two servers offer the same STOCKQUOTE service. The client calls the service and returns the stock price and the client then prints the XML buffer.

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

The XMLSTOCKAPP tutorial is presented in three sections:

Note: This information is focused on 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 XMLSTOCKAPP

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

Learning About the XMLSTOCKAPP Files

The files that make up the XMLSTOCKAPP application are delivered in the samples/atmi/xmlstockapp directory. The files that are delivered with this sample are:

The XMLSTOCKAPP directory contains the following files:

Examining the XMLSTOCKAPP Clients

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

The XMLSTOCKAPP implements the request/response mode and uses the STOCKQUOTE service to request a stock price.

  1. A request for a stock price for BEAS or MSFT.
  2. The client, which is run with a single argument in an XML file, calls the STOCKQUOTE service.
  3. The service updates the XML buffer with the stock price.
  4. The client prints the XML buffer.

A Request/Response Client: stock_quote_beas.xml

Client.cpp is a client program that uses input from one of the XML files, stock_quote_beas.xml or stock_quote_msft.xml. It makes an inquiry that calls on the service STOCKQUOTE and returns the stock price for BEAS or MSFT. As an executable, it is invoked as follows:

Client stock_quote_beas.xml


Client stock_quote_msft.xml

See Also

Examining the XMLSTOCKAPP Servers

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 STOCKQUOTE service in the XMLSTOCKAPP program uses functions provided in the Application-to-Transaction Monitor Interface (ATMI) to return a stock price to the client as an XML buffer.


Preparing XMLSTOCKAPP Files and Resources

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

Step1: Copy the XMLSTOCKAPP Files to a New Directory

It is recommended that you copy the XMLSTOCKAPP 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/XMLSTOCKAPP which is the directory where XMLSTOCKAPP source files are located: APPDIR is a directory where the Oracle Tuxedo system looks for your application-specific files. If you copied the XMLSTOCKAPP 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. . ./<VARFILE>

    where <VARFILE> is the name of your environment variable file.

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: Building Clients

To build the client:

export CFLAGS=-I

Use the following commands for the specified opearting system:

The following command builds the client:

buildclient -o Client -f Client.cpp -f SAXPrint.cpp -f SAXPrintHandlers.cpp -f -ltxml

Step 4: Building Servers in XMLSTOCKAPP

In the XMLSTOCKAPP sample, two servers are provided for you. However, if you want to build the servers for this example, you will need to follow the directions inn the README file.

buildserver is used to put together an executable ATMI server. Options identify the names of the output file, the input files provided by the application, and various libraries that permit you to run an Oracle Tuxedo system application in a variety of ways.

The key buildserver command-line options are illustrated in the examples that follow.

The buildserver command is used in a .mk file to compile and build each server in the stock application. (Refer to buildserver(1) in the Oracle Tuxedo Command Reference for complete details.)

How to Build the stockxml and stockxml_c Servers

The buildserver command that was used to build the stockxml server and the stockxml_c server follows:

buildserver -s STOCKQUOTE -o stockxml -f stockxml.cpp -f DOMTreeErrorReporter.cpp -f -ltxml
buildserver -s STOCKQUOTE -f stockxml_c.c -o stockxml_c -f xmlWrapper.cpp -f DOMTreeErrorReporter.cpp -f -ltxml

The explanation of the command-line options follows:

See Also

Step 5: How to 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 6-1 The ubbsimple Configuration File
3 #Skeleton UBBCONFIG file for the BEA Tuxedo Simple Application.
4 #Replace the <bracketed> items with the appropriate values.
6 IPCKEY <Replace with valid IPC Key greater than 32,768>
8 #Example:
10 #IPCKEY 62345
12 MASTER simple
23 APPDIR="<Replace with the current pathname>"
24 TUXCONFIG="<Replace with TUXCONFIG Pathname>"
25 TUXDIR="<Root directory of Tuxedo (not /)>"
26 #Example:
27 # APPDIR="/usr/me/simpdir"
28 # TUXCONFIG="/usr/me/simpdir/tuxconfig"
29 # TUXDIR="/usr/tuxedo"
31 <Machine-name> LMID=simple
32 #Example:
33 #tuxmach LMID=simple
40 CLOPT="-A"
41 stockxml SRVGRP=GROUP1 SRVID=1
42 stockxml_c SRVGRP=GROUP1 SRVID=1
  1. For each <string> (that is, for each string shown between angle brackets), substitute an appropriate value.

See Also

Step 6: Creating a Binary Configuration File

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

  1. Go to the directory in which your XMLSTOCKAPP files are located.
  2. Set the environment variables by entering:
  3. . ./<variable_file>

    where <variable_file> is the name of your variables file.

How to Load 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 XMLSTOCKAPP.

  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



This documentation leads you through the procedures for booting XMLSTOCKAPP, testing it by running various client programs and transactions, and shutting it down when you have finished.

Step 1: How to Prepare to Boot

Before booting XMLSTOCKAPP, 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: How to Boot XMLSTOCKAPP

  1. Set the environment:
  2. ../<variable_file> 
  3. Boot the application by entering the following:
  4.     tmboot -y

    When you enter -y, a running report, such as the following, is displayed on the screen:

    Booting all admin and server processes in /usr/me/appdir/tuxconfig
    Booting all admin processes
    exec BBL -A:
    process id=24223 Started.

The report continues until all servers in the configuration have been started. It ends by reporting the total number of servers started.

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.

In addition to reporting on the number of servers booted, tmboot also sends messages to the ULOG.

See Also

Step 3: How to Test XMLSTOCKAPP Services

  1. If you are logging in cold to a running system, you must set your environment for XMLSTOCKAPP. To do so, enter the following command:
  2. ../<variable_file>
  3. Run the client program. To execute the client program, enter the following command:
  4. Client stock_quote_beas.xml

Step 4: How to Shut Down XMLSTOCKAPP

To bring down XMLSTOCKAPP, 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