Table of Contents Previous Next PDF

Tutorial for STOCKAPP, a Full COBOL Application

Tutorial for STOCKAPP, a Full COBOL Application
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:
Familiarizing Yourself with STOCKAPP
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.
Learning About the STOCKAPP Files
The files that make up the STOCKAPP application are delivered in a directory called STOCKAPP, which is positioned as follows:
Exploring the Stock Application Files
The STOCKAPP directory contains the following files:
Eight .cbl files
Four clients: BUY.cbl, SELL.cbl, FUNDPR.cbl and FUNDUP.cbl
Table 5‑1 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.
Contains BUY service
ENVFILE used by tmloadcf
Contains PRICE QUOTE service
Contains FUND UPDATE service
Contains SELL service
Sample UBBCONFIG file for use in a SHM mode configuration
View used to define the structure passed between the BUY and SELL clients and the BUYSR and SELLSR servers
View used to define the structure passed between the FUNDPR and FUNDUP clients and all the servers
See Also
Examining the STOCKAPP Clients
In the ATMI client-server architecture of the Oracle Tuxedo system, there are two modes of communication:
System Client Programs
Figure 5‑1 shows the hierarchy for STOCKAPP. The user selects one of the four service requests. The oval shapes in the illustration represent application services.
Figure 5‑1 STOCKAPP Requests
Typed Buffers
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.
A Request/Response Client: BUY.cbl
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.cbl Source Code
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.
Building Clients
View description files, of which cust is an example, are processed by the view compiler, viewc(1). Run view(c) to compile the view:
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
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 STOCKAPP Servers
This topic provides the following information:
Information on the buildserver command options used to compile and build each server
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:
Buys a fund/stock record; offered by the BUYSELL server; accepts a VIEW record as input, inserts a CUSTFILE record
Sells a fund/stock record; offered by the BUYSELL server; accepts a VIEW record as input, inserts a CUSTFILE record
Price quote; offered by the PRICEQUOTE server; accepts a VIEW record as input
Fund update; conversational service; offered by FUNDUPDATE server; accepts a VIEW record as input
Preparing STOCKAPP Files and Resources
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.
Step 1: How to Set Environment Variables
Environment variables required for STOCKAPP are defined in the STKVAR file. The file is large (approximately 100 lines) because it includes extensive comments.
In a text editor, familiarize yourself with the 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
Set TUXDIR to the root directory of your Oracle Tuxedo system directory structure, and export it.
Another line in 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.
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.
When you have made all necessary changes to STKVAR, execute STKVAR as follows:
Listing 5‑1 STKVAR: Environment Variables for STOCKAPP
#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
# 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
# Environment file to be used by tmloadcf
# This directory contains the cobol files needed
# for compiling and linking.
# Add coblib to LD_LIBRARY_PATH
# List of field table files to be used by CBLVIEWC, tmloadcf, etc.
# List of directories to search to find field table files
# Set device for the transaction log; this should match the TLOGDEVICE
# parameter under this site's LMID in the *MACHINES section of the
# Device for the configuration file
# Device for binary file that gives /T all its information
# 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
# List of directories to search to find view files
# List of view files to be used by CBLVIEWC, tmloadcf, etc.
# Set the COBCPY
# Set the COBOPT
# Set the CFLAGS
CFLAGS="-I$TUXDIR/include -I$TUXDIR/sysinclude"
# Export all variables just set
# Add TUXDIR/bin to PATH if not already there
a="`echo $PATH | grep ${TUXDIR}/bin`"
if [ x"$a" = x ]
export PATH
# Add APPDIR to PATH if not already there
a="`echo $PATH | grep ${APPDIR}`"
if [ x"$a" = x ]
export PATH
# Add COBDIR to PATH if not already there
a="`echo $PATH | grep ${COBDIR}`"
if [ x"$a" = x ]
export PATH
Additional Requirements
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.
See Also
Step 2: Building Servers in STOCKAPP
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 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 BUYSELL Server
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.
Create the BUYSELL.o file (performed for you in 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:
The -C option is used to build servers with COBOL modules.
The -v option is used to specify the verbose mode. It writes the cc command to its standard output.
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 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.
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. 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.
The -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.
Servers Built in
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.
See Also
Step 3: Editing the File
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 is delivered, there are a few fields you may want to edit, and some others that may benefit from some explanation.
How to Edit the TUXDIR Parameter
Go to the following comment in 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
# TUXDIR=/correct/rootdir", or the build of STOCKAPP will fail.
You should set the TUXDIR parameter to the absolute pathname of the root directory of your Oracle Tuxedo system installation.
How to Edit the APPDIR Parameter
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 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
# APPDIR=/correct/appdir", or the build of STOCKAPP will fail.
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.
How to Run the File
When you have completed the changes you wish to make to, run it with the following command line:
nohup make -f install &
Check the nohup.out file to make sure the process completed successfully.
See Also
Step 4: How to Edit the Configuration File
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.
Listing 5‑2 UBBCBSHM Configuration File Fields to Be Replaced
      #Copyright (c) 1992 Unix System Laboratories, Inc.
      #All rights reserved
      #Skeleton UBBCONFIG file for the TUXEDO COBOL Sample Application.
      IPCKEY 5226164
001 UID <
user id from id(1)>
002 GID <group id from id(1)>
      PERM 0660
      LDBAL Y
      MAXGTT 100
      SCANUNIT 10
      DBBLWAIT 6
      BBLQUERY 180
      BLOCKTIME 10
003 <SITE1's uname> LMID=SITE1
004                       TUXDIR="<TUXDIR1>"
005                       APPDIR="<APPDIR1>"
006                       TYPE="<machine type>"
You may notice that the values of some parameters are enclosed in angle brackets (<>). Values shown in angle brackets are generic; you need to replace them with values that pertain to your installation. All of these fields occur within the RESOURCES, MACHINES, and GROUPS sections in the file. Table 5‑2 describes the values with which you must replace the angle-bracketed strings. For each string, substitute an appropriate value.
See Also
UBBCONFIG(5) in File Formats, Data Descriptions, MIBs, and System Processes Reference
Step 5: Creating a Binary Configuration File
Before Creating the Binary Configuration File
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.
Go to the directory in which your STOCKAPP files are located.
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 STOCKAPP.
To create 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.
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.
See Also
tmloadcf(1) in Oracle Tuxedo Command Reference
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.
Step 1: How to Prepare to Boot
Before booting 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.
Listing 5‑3 IPC Report
Ipc sizing (minimum /T values only)
                    Fixed Minimums Per Processor
                    Variable Minimums Per Processor
                    SEMUME, A SHMMAX
                    SEMMNU, * *
------ ------ ------ ------ ------ ------ ------ ------
machine 1 60 1 60 A + 1 10 20 76K
machine 2 63 5 63 A + 1 11 22 76K
where 1 <= A <= 8.
See Also
Step 2: How to Boot STOCKAPP
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.
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 STOCKAPP Services
Run the BUY client program. To execute the BUY client program, enter the following command:
Monitor 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.
See Also
Step 4: How to Shut Down STOCKAPP
To bring down STOCKAPP, enter the tmshutdown(1) command with no arguments, from the MASTER machine, as follows.
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.