This topic includes the following sections:
STOCKAPP
is a sample ATMI stocks application that is provided with the Oracle Tuxedo system software. The application performs the following stock brokering functions: validates and updates a customer’s account information, and executes buy and sell orders for stocks and/or funds.
This documentation leads you, step-by-step, through the procedure you must perform to develop the STOCKAPP
application. Once you have “developed” STOCKAPP
through this tutorial, you will be ready to start developing applications of your own.
The STOCKAPP
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. |
This documentation provides a tour of the files, client, and services that make up the STOCKAPP
application. Click on any of the following activities for more information about that part of the tour.
The files that make up the STOCKAPP
application are delivered in a directory called STOCKAPP
, which is positioned as follows:
The STOCKAPP
directory contains the following files:
.cbl
filesBUY.cbl
, SELL.cbl
, FUNDPR.cbl
and FUNDUP.cbl
FUNDUPSR.cbl
STOCKAPP
as an example
The following table lists the files that make up STOCKAPP
. The table lists the source files delivered with the Oracle Tuxedo system software, files that are generated when the stock application is built, and a summary of the contents of each file.
In the ATMI client-server architecture of the Oracle Tuxedo system, there are two modes of communication:
The following figure shows the hierarchy for STOCKAPP
. The user selects one of the four service requests. The oval shapes in the illustration represent application services.
Typed buffers are an essential part of the Oracle Tuxedo system. In the Oracle Tuxedo system, a typed buffer is designed to hold a specific data type. Six types are defined: VIEW
, STRING
, CARRAY
, X_OCTET
, X_COMMON
, and XML
. Applications have the ability to define additional types.
BUY
is an example of a client program. It makes account inquiries that call on the service BUYSR
. As an executable, it is invoked as follows:
BUY
Review the following sections of the BUY.cbl
program.
* Now register the client with the system
* Issue a TPCALL
* Clean up
The indicated sections contain all of the places in BUY.cbl
where the Oracle Tuxedo ATMI functions are used. Similar to csimpl.cbl
, BUY.cbl
needs to call TPINITIALIZE
to join the application; call TPCALL
to make an RPC request to a service; and call TPTERM
to leave an application. Note also that BUY.cbl
is an example of a program that uses a VIEW
typed record and a structure that is defined in the cust
file. The source code for the structure can be found in the view description file, cust.V
.
View description files, of which cust
is an example, are processed by the view compiler, viewc(1)
. Run view
(c) to compile the view:
viewc-C-n
cust.v
where viewc
has three output files: a COBOL file (CUST.cbl
), a binary view description file (cust.V
), and a header file (cust.h
).
The client programs, BUY.cbl
, FUNDPR.cbl
, FUNDUP.cbl
, and SELL.cbl
, are processed by buildclient(1)
to compile them and/or link edit them with the necessary Oracle Tuxedo libraries.
You can use any of these commands individually, if you choose, but rules for all these steps are included in STOCKAPP.mk
.
This topic provides the following information:
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. Services are subroutines of COBOL language code written specifically for an application. 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).
All STOCKAPP
services use functions provided in the Application-to-Transaction Monitor Interface (ATMI) for performing the following tasks:
There are four services in STOCKAPP
. Each STOCKAPP
service matches a COBOL function name in the source code of a server as shown in the following list:
BUYSR
BUYSELL
server; accepts a VIEW
record as input, inserts a CUSTFILE
record
SELLSR
BUYSELL
server; accepts a VIEW
record as input, inserts a CUSTFILE
record
FUNDPRSR
FUNDUPSR
This documentation leads you through the procedures you must complete to create the files and other resources you need to run STOCKAPP
.
Click on each task for instructions on completing that task.
Environment variables required for STOCKAPP
are defined in the STKVAR
file. The file is large (approximately 100 lines) because it includes extensive comments.
STKVAR
file. Line 9 ensures that 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 Oracle Tuxedo system directory structure, and export it.STKVAR
sets APPDIR
to the directory {TUXDIR}/samples/atmi/STOCKAPP
which is the directory where STOCKAPP
source files are located: APPDIR
is a directory where the Oracle Tuxedo system looks for your application-specific files. You might prefer to copy the STOCKAPP
files to a different directory to safeguard the original source files. If you do, then enter the directory there. It does not have to be under TUXDIR
.Note: | Other variables specified in STKVAR play various roles in the sample application; you need to be aware of them when you are developing your own application. By including them in STKVAR , we provide you with a template that you may want to adapt at a later time for use with a real application. |
STKVAR
, execute STKVAR
as follows:. ./STKVAR
#ident "@(#)samples/atmi
:STOCKAPP/STKVAR
#
# This file sets all the environment variables needed by the TUXEDO software
# to run the STOCKAPP
#
# This directory contains all the TUXEDO software
# System administrator must set this variable
#
TUXDIR=${TUXDIR:?}
#
# This directory contains all the user written code
#
# Contains the full path name of the directory that the application
# generator should place the files it creates
#
APPDIR=${HOME}/STOCKAPP
#
# Environment file to be used by tmloadcf
#
COBDIR=${COBDIR:?}
#
# This directory contains the cobol files needed
# for compiling and linking.
#
LD_LIBRARY_PATH=$COBDIR/coblib:${LD_LIBRARY_PATH}
#
# Add coblib to LD_LIBRARY_PATH
#
ENVFILE=${APPDIR}/ENVFILE
#
# List of field table files to be used by CBLVIEWC, tmloadcf, etc.
#
FIELDTBLS=fields,Usysflds
#
# List of directories to search to find field table files
#
FLDTBLDIR=${TUXDIR}/udataobj:${APPDIR}
#
# Set device for the transaction log; this should match the TLOGDEVICE
# parameter under this site's LMID in the *MACHINES section of the
# UBBCBSHM file
#
TLOGDEVICE=${APPDIR}/TLOG
#
# Device for the configuration file
#
UBBCBSHM=$APPDIR/UBBCBSHM
#
# Device for binary file that gives /T all its information
#
TUXCONFIG=${APPDIR}/TUXCONFIG
#
# Set the prefix of the file which is to contain the central user log;
# this should match the ULOGPFX parameter under this site's LMID in the
# *MACHINES section of the UBBCONFIG file
#
ULOGPFX=${APPDIR}/ULOG
#
# List of directories to search to find view files
#
VIEWDIR=${APPDIR}
#
# List of view files to be used by CBLVIEWC, tmloadcf, etc.
#
VIEWFILES=quote.V,cust.V
#
# Set the COBCPY
#
COBCPY=$TUXDIR/cobinclude
#
# Set the COBOPT
#
COBOPT="-C ANS85 -C ALIGN=8 -C NOIBMCOMP -C TRUNC=ANSI -C OSEXT=cbl"
#
# Set the CFLAGS
#
CFLAGS="-I$TUXDIR/include -I$TUXDIR/sysinclude"
#
# Export all variables just set
#
export TUXDIR APPDIR ENVFILE
export FIELDTBLS FLDTBLDIR TLOGDEVICE
export UBBCBSHM TUXCONFIG ULOGPFX LD_LIBRARY_PATH
export VIEWDIR VIEWFILES COBDIR COBCPY COBOPT CFLAGS
#
# Add TUXDIR/bin to PATH if not already there
#
a="`echo $PATH | grep ${TUXDIR}/bin`"
if [ x"$a" = x ]
then
PATH=${TUXDIR}/bin:${PATH}
export PATH
fi
#
# Add APPDIR to PATH if not already there
#
a="`echo $PATH | grep ${APPDIR}`"
if [ x"$a" = x ]
then
PATH=${PATH}:${APPDIR}
export PATH
fi
#
# Add COBDIR to PATH if not already there
#
a="`echo $PATH | grep ${COBDIR}`"
if [ x"$a" = x ]
then
PATH=${PATH}:${COBDIR}
export PATH
fi
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.
buildserver
with the -C
option invokes the cobcc
command. The environment variables ALTCC
and ALTCFLAGS
can be set to name an alternative compile command and to set flags for the compile and link edit phases. The key buildserver
command-line options are illustrated in the examples that follow.
The buildserver
command is used in STOCKAPP.mk
to compile and build each server in the stock application. (Refer to buildserver(1) in the Oracle Tuxedo Command Reference for complete details.)
The BUYSELL
ATMI server is derived from files that contain the code for the BUYSR
and SELLSR
functions. The BUYSELL
server is first compiled to a BUYSELL.o
file before supplying it to the buildserver
command so that any compile-time errors can be clearly identified and dealt with before this step.
BUYSELL.o
file (performed for you in STOCKAPP.mk
). The buildserver
command that was used to build the BUYSELL
server follows: buildserver -C -v -o BUYSELL -s SELLSR -f SELLSR.cbl -s BUYSR -f BUYSR.cbl
The explanation of the command-line options follows:
-C
option is used to build servers with COBOL modules.-v
option is used to specify the verbose mode. It writes the cc
command to its standard output.-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 STOCKAPP
, 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.-f
option specifies the files that are used in the link-edit phase. Also refer to the -l
option on the buildserver
reference page. For more detail information on both of these options, refer to the
“Building Servers” in Programming Oracle Tuxedo ATMI Applications Using COBOL. 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. If these are .cbl
files, they are first compiled. 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 SELLSR
and BUYSR
services to be the services that comprise the BUYSELL
server. The -o
option assigns the name BUYSELL
to the executable output file and the -f
option specifies that the SELLSR.cbl
and the BUYSR.cbl
files are to be used in the link edit phase of the build.
The topics on creating the STOCKAPP
servers are important to your understanding of how the buildserver
command is specified. However, in actual practice you are apt to incorporate the build into a makefile; that is the way it is done in STOCKAPP
.
STOCKAPP includes a makefile
that makes all scripts executable, converts the view description file to binary format, and does all the precompiles, compiles, and builds necessary to create the application servers. It can also be used to clean up when you want to make a fresh start.
As STOCKAPP.mk is delivered, there are a few fields you may want to edit, and some others that may benefit from some explanation.
Go to the following comment in STOCKAPP.mk
and to the TUXDIR parameter:
#
# Root directory of TUXEDO System. This file must either be edited to set
# this value correctly, or the correct value must be passed via "make -f
# STOCKAPP.mk TUXDIR=/correct/rootdir", or the build of STOCKAPP will fail.
#
TUXDIR=../..
You should set the TUXDIR parameter to the absolute pathname of the root directory of your Oracle Tuxedo system installation.
You may want to give some thought to the setting of the APPDIR parameter. As STOCKAPP is delivered, APPDIR is set to the directory in which the STOCKAPP files are located, relative to TUXDIR. The following section of STOCKAPP.mk defines and describes the setting of APPDIR
.
#
# Directory where the STOCKAPP application source and executables live.
# This file must either be edited to set this value correctly, or the
# correct value must be passed via "make -f STOCKAPP.mk
# APPDIR=/correct/appdir", or the build of STOCKAPP will fail.
#
APPDIR=$(TUXDIR)/samples/atmi
/STOCKAPP
#
If you have copied the files to another directory, as suggested in the README file, you should set APPDIR
to the name of the directory to which you copied the files. When you run the makefile
, the application will be built in this directory.
The STOCKAPP
configuration file defines how an application runs on a set of machines. STOCKAPP
is delivered with a configuration file in text format described in UBBCONFIG(5)
. UBBCBSHM
, defines an application on a single computer.
STOCKAPP
.#Copyright (c) 1992 Unix System Laboratories, Inc.
#All rights reserved
#Skeleton UBBCONFIG file for the TUXEDO COBOL Sample Application.
*RESOURCES
IPCKEY 5226164
DOMAINID STOCKAPP
001 UID <user id from id(1)
>
002 GID <group id from id(1)
>
MASTER SITE1
PERM 0660
MAXACCESSERS 20
MAXSERVERS 15
MAXSERVICES 30
MODEL SHM
LDBAL Y
MAXGTT 100
MAXBUFTYPE 16
MAXBUFSTYPE 32
SCANUNIT 10
SANITYSCAN 12
DBBLWAIT 6
BBLQUERY 180
BLOCKTIME 10
TAGENT “TAGENT"
#
*MACHINES
003 <SITE1's uname
> LMID=SITE1
004 TUXDIR="<TUXDIR1
>"
005 APPDIR="<APPDIR1
>"
ENVFILE="<APPDIR1
>/ENVFILE"
TUXCONFIG="<APPDIR1
>/TUXCONFIG"
TUXOFFSET=0
006 TYPE="<machine type
>"
ULOGPFX="<APPDIR
>/ULOG"
MAXWSCLIENTS=5
#
*GROUPS
COBAPI LMID=SITE1 GRPNO=1
#
#
*SERVERS
FUNDUPSR SRVGRP=COBAPI SRVID=1 CONV=Y ENVFILE="<APPDIR1>/ENVFILE"
FUNDPRSR SRVGRP=COBAPI SRVID=2 ENVFILE="<APPDIR1>/ENVFILE"
BUYSELL SRVGRP=COBAPI SRVID=3 ENVFILE="<APPDIR1>/ENVFILE"
#
#
*SERVICES
RESOURCES
section of UBBCBSHM
:SECURITY APP_PW
RESOURCES
, MACHINES
, and GROUPS
sections in the file. The following table describes the values with which you must replace the angle-bracketed strings. For each string
, substitute an appropriate value.
Before creating the binary configuration file, you need to be in the directory in which your STOCKAPP
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 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 STOCKAPP
.
TUXCONFIG
, enter the following command: tmloadcf UBBCBSHM
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.
If you have specified SECURITY
as an option for the configuration, tmloadcf
prompts you to enter an application password. The password you select can be up to 30 characters long. Client processes joining the application are required to supply the password.
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 STOCKAPP
, testing it by running various client programs and transactions, and shutting it down when you have finished.
Click on each task for instructions on completing that task.
STOCKAPP
, 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. Ipc sizing (minimum /T values only)
Fixed Minimums Per Processor
SHMMIN: 1
SHMALL: 1
SEMMAP: SEMMNI
Variable Minimums Per Processor
SEMUME, A SHMMAX
SEMMNU, * *
Node SEMMNS SEMMSL SEMMSL SEMMNI MSGMNI MSGMAP SHMSEG
------ ------ ------ ------ ------ ------ ------ ------
machine 1 60 1 60 A + 1 10 20 76K
machine 2 63 5 63 A + 1 11 22 76K
where 1 <= A <= 8.
MSGMNI
value. MSGMAP
should be twice MSGMNI
.
../STKVAR
tmboot
The following prompt is displayed:
Boot all admin and server processes? (y/n): y
When you enter y
after the prompt, 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
.
STOCKAPP
. To do so, enter the following command:../STKVAR
BUY
client program. To execute the BUY
client program, enter the following command:BUY
STOCKAPP
. While STOCKAPP
is running, run the tmadmin
subcommands and try various commands with it to see the kind of status information you can produce.
To bring down STOCKAPP
, enter the tmshutdown(1)
command with no arguments, from the MASTER
machine, as follows.
tmshutdown
Running this command (or the shutdown command of tmadmin
) causes the following results: