Table of Contents Previous Next PDF

Tutorial for XMLSTOCKAPP: a C and C++ XML Parser Application

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:
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:
Two .xml input files to the client: stock_quote_beas.xml and stock_quote_msft.xml
One client: Client.cpp
Two files that are servers: stockxml and stockxml_c
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.
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
“What You Can Do Using the ATMI” in Introducing Oracle Tuxedo ATMI
“What Are Typed Buffers?” in Introducing Oracle Tuxedo ATMI
ATMI commands and functions in Oracle Tuxedo Command Reference and Oracle Tuxedo ATMI C Function Reference
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.
Ensure that TUXDIR is set. If it is not set, execution of the file fails with the following message:
TUXDIR: parameter null or not set
Set TUXDIR to the root directory of your Oracle Tuxedo system directory structure, and export it.
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.
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.
If your operating system is Sun Solaris, you need to: put /usr/5bin at the beginning of your PATH. The following command can be used:
PATH=/usr/5bin:$PATH;export PATH
Use /bin/sh rather than csh for your shell.
Step 3: Building Clients
To build the client:
export CFLAGS=-I
Use the following commands for the specified opearting system:
export CC=CC
export CC=aCC
export CC=cxx
export CC=xlC_r
export CC=g++
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:
The -o option is used to assign a name to the executable output file. If no name is provided, the file is named SERVER.
The -s option is used to specify the service names in the server that are available to be advertised when the server is booted. If the name of the function that performs a service is different from the service name, the function name becomes part of the argument of the -s option. In the XMLSTOCKAPP, the function name is the same as the name of the service so only the service names themselves need to be specified. It is our convention to specify all uppercase for the service name. However, the -s option of buildserver does allow you to specify an arbitrary name for the processing function for a service within a server. Refer to the buildserver(1) in the Oracle Tuxedo Command Reference for details. It is also possible for the administrator to specify that only a subset of the services that were used to create the server with the buildserver command is to be available when the server is booted. For more information, refer to Administering an Oracle Tuxedo Application at Run Time and Setting Up an Oracle Tuxedo Application.
The -f option specifies the files that are used in the link-edit phase. Also refer to the -l option on the buildserver reference page. There is a significance to the order in which the files are listed. The order is dependent on function references and in what libraries the references are resolved. Source modules should be listed ahead of libraries that might be used to resolve their references. Object files can be either separate .o files or groups of files in archive (.a) files. If more than a single filename is given as an argument to a -f, the syntax calls for a list enclosed in double quotes. You can use as many -f options as you need.
The -s option names the STOCKQUOTE service to be the services that comprise the stockxml and stockxml_c servers. The -o option assigns the name stockxml and stockxml_c to the executable output file and the -f option specifies that the stockxml.cpp, DOMTreeErrorReporter.cpp, and the xmlWrapper.cpp files are to be used in the link edit phase of the build.
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.
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
For each <string> (that is, for each string shown between angle brackets), substitute an appropriate value.
See Also
UBBCONFIG(5) in File Formats, Data Descriptions, MIBs, and System Processes Reference
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.
Go to the directory in which your XMLSTOCKAPP files are located.
. ./<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.
To create TUXCONFIG, enter the following command:
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.
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
tmloadcf(1) in Oracle Tuxedo Command Reference
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
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
tmboot(1) in the Oracle Tuxedo Command Reference
USERLOG(3cbl) in the Oracle Tuxedo ATMI COBOL Function Reference
Step 3: How to Test XMLSTOCKAPP Services
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
tmadmin(1) in the Oracle Tuxedo Command Reference
tmshutdown(1) in the Oracle Tuxedo Command Reference

Copyright © 1994, 2017, Oracle and/or its affiliates. All rights reserved.