This topic includes the following sections:
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. |
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.
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:
In the ATMI client-server architecture of the BEA 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.
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
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.
This documentation leads you through the procedures you must complete to create the files and other resources you need to run XMLSTOCKAPP
.
It is recommended that you copy the XMLSTOCKAPP files to your own directory prior to editing any of the files or running the sample.
You will need to edit the environment variables file.
TUXDIR
is set. If it is not set, execution of the file fails with the following message: TUXDIR: parameter null or not set
TUXDIR
to the root directory of your BEA Tuxedo system directory structure, and export it.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
.. ./<VARFILE>
where <VARFILE>
is the name of your environment variable file.
LD_LIBRARY_PATH
must include $TUXDIR/lib
on systems that use shared libraries, with the exception of HP-UX and AIX.
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
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.)
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:
-o
option is used to assign a name to the executable output file. If no name is provided, the file is named SERVER
.-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.-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.-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.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.
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
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.
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
.
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.
-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.
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.
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.
../<variable_file>
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
.
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: