Tutorial for XMLSTOCKAPP

e-docs > Tuxedo > Tutorials for Developing Tuxedo ATMI Applications > Tutorial for XMLSTOCKAPP

Tutorials for Developing Tuxedo ATMI Applications

Tutorial for XMLSTOCKAPP

This topic includes the following sections:

What Is XMLSTOCKAPP?

XMLSTOCKAPP is a sample ATMI stock application that is provided with the BEA 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 BEA Tuxedo system software. A development license is required to build BEA 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:

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
Files provided to facilitate the use of STOCKAPP as an example:

Examining the XMLSTOCKAPP Clients

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

Request/response mode, which is characterized by the sending of a single request for a service to be performed by the server and getting back a single response.
Conversational mode; in this mode a dedicated connection is established between a client (or a server acting like a client) and a server. The connection remains active until terminated. While the connection is active, messages containing service requests and responses can be sent and received between the two participating processes.

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

A request for a stock price for BEAS or MSFT.
The client, which is run with a single argument in an XML file, calls the STOCKQUOTE service.
The service updates the XML buffer with the stock price.
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

"What You Can Do Using the ATMI" on page 2-4 in Introducing BEA Tuxedo ATMI
"What Are Typed Buffers?" on page 2-23 in Introducing BEA Tuxedo ATMI
ATMI commands and functions in BEA Tuxedo Command Reference and BEA Tuxedo ATMI C Function Reference

Examining the XMLSTOCKAPP Servers

ATMI servers are executable processes that offer one or more services. In the BEA 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 BEA Tuxedo system transaction processing application is being developed. Service routines are one part of the application that must be written by the BEA 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 BEA 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 BEA 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.
When you have made all necessary changes to the environment variables file, execute it as follows:
```
. ./<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.

On AIX, set LIBPATH instead of LD_LIBRARY_PATH.
On HP-UX, set SHLIB_PATH instead of LD_LIBRARY_PATH.
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:

For Solaris:
```
export CC=CC
```
For HP-UX:
```
export CC=aCC
```
For Digital Unix:
```
export CC=cxx
```
For AIX:
```
export CC=xlC_r
```
For Linux:
```
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 a BEA 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 BEA 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 BEA 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 a BEA Tuxedo Application at Run Time and Setting Up a BEA 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

1$
2
3 #Skeleton UBBCONFIG file for the BEA Tuxedo Simple Application.
4 #Replace the <bracketed> items with the appropriate values.
5 RESOURCES
6 IPCKEY            <Replace with valid IPC Key greater than 32,768>
7
8  #Example:
9
10 #IPCKEY         62345
11
12 MASTER          simple
13 MAXACCESSERS    5
14 MAXSERVERS      5
15 MAXSERVICES     10
16 MODEL           SHM
17 LDBAL           N
18 
19 *MACHINES
20
21 DEFAULT:
22
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"
30
31 <Machine-name>  LMID=simple
32 #Example:
33 #tuxmach        LMID=simple
34 *GROUPS
35 GROUP1
36              LMID=simple   GRPNO=1  OPENINFO=NONE
37
38 *SERVERS
39  DEFAULT:
40              CLOPT="-A"
41  stockxml    SRVGRP=GROUP1 SRVID=1
42  stockxml_c  SRVGRP=GROUP1 SRVID=1
43 *SERVICES
44  STOCKQUOTE

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

See Also

Preparing XMLSTOCKAPP Files and Resources
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.
Set the environment variables by entering:
```
. ./<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 BEA 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.
If you want the amount of IPC resources needed by your application to be calculated by the BEA Tuxedo system, include the -c 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

Preparing XMLSTOCKAPP Files and Resources
tmloadcf(1) in BEA Tuxedo Command Reference

Running XMLSTOCKAPP

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

Set the environment:
```
../<variable_file> 
```

Boot the application by entering the following:

    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 BEA Tuxedo Command Reference
USERLOG(3cbl) in the BEA Tuxedo ATMI COBOL Function Reference

Step 3: How to Test XMLSTOCKAPP Services

If you are logging in cold to a running system, you must set your environment for XMLSTOCKAPP. To do so, enter the following command:
```
../<variable_file>
```
Run the client program. To execute the client program, enter the following command:
```
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:

All application servers, gateway servers, TMS servers, and administrative servers are shut down.
All associated IPC resources are removed.

See Also

tmadmin(1) in the BEA Tuxedo Command Reference
tmshutdown(1) in the BEA Tuxedo Command Reference