Tutorials for Developing Oracle Tuxedo ATMI Applications

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Tutorial for STOCKAPP, a Full COBOL Application

This topic includes the following sections:

 


What Is STOCKAPP?

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.

 


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.

STOCKAPP Requests

 


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:

STOCKAPP Requests

Exploring the Stock Application Files

The STOCKAPP directory contains the following files:

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.

Table 5-1 Purpose of the Stock Application Files 
Source File
Generated File
Contents
BUY.cbl
BUY.o
BUY
Client
BUYSR.cbl
BUYSR.o
BUYSR
Contains BUY service
ENVFILE
 
ENVFILE used by tmloadcf
FILES
 
Descriptive list of all the files in STOCKAPP
FUNDPR.cbl
FUNDPR.o FUNDPR
Client
FUNDPRSR.cbl
FUNDPRSR.o FUNDPRSR
Contains PRICE QUOTE service
FUNDUP.cbl
FUNDUP.o FUNDUP
Client
FUNDUPSR.cbl
FUNDUPSR.o FUNDUPSR
Contains FUND UPDATE service
README
 
Online version of the installation and boot procedures
SELL.cbl
SELL.o SELL
Client
SELLSR.cbl
SELLSR.o SELLSR
Contains SELL service
STKVAR
 
Contains variable settings, except for those within ENVFILE
STOCKAPP.mk
 
Application makefile
UBBCBSHM
TUXCONFIG
Sample UBBCONFIG file for use in a SHM mode configuration
cust
CUST.cbl cust.V cust.h
View used to define the structure passed between the BUY and SELL clients and the BUYSR and SELLSR servers
quote
QUOTE.cbl quote.V quote.h
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

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

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:

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.

See Also

 


Examining the STOCKAPP Servers

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:

STOCKAPP Services

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

Buys a fund/stock record; offered by the BUYSELL server; accepts a VIEW record as input, inserts a CUSTFILE record

SELLSR

Sells a fund/stock record; offered by the BUYSELL server; accepts a VIEW record as input, inserts a CUSTFILE record

FUNDPRSR

Price quote; offered by the PRICEQUOTE server; accepts a VIEW record as input

FUNDUPSR

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.

STOCKAPP Requests

 


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.

  1. 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:
  2. TUXDIR: parameter null or not set
  3. Set TUXDIR to the root directory of your Oracle Tuxedo system directory structure, and export it.
  4. 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.
  5. 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.
  6. When you have made all necessary changes to STKVAR, execute STKVAR as follows:
  7. . ./STKVAR
    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
    #
    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

Additional Requirements

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 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.)

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.

  1. Create the BUYSELL.o file (performed for you in STOCKAPP.mk). The buildserver command that was used to build the BUYSELL server follows:
  2. 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 STOCKAPP.mk

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 STOCKAPP.mk 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 STOCKAPP.mk 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 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.

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 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.

How to Run the STOCKAPP.mk File

  1. When you have completed the changes you wish to make to STOCKAPP.mk, run it with the following command line:
  2. nohup make -f STOCKAPP.mk install &
  3. 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.

  1. In a text editor, familiarize yourself with the configuration file for STOCKAPP.
  2. 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.
          *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
  3. To enable the application password feature, add the following line to the RESOURCES section of UBBCBSHM:
  4. SECURITY   APP_PW
  5. 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.
  6. Table 5-2 Explanation of Values 
    Line
    String to Be Replaced
    Purpose
    001
    UID
    The effective user ID for the owner of the bulletin board IPC structures. In a multiprocessor configuration, the value must be the same on all machines. You avoid problems if this is the same as the owner of the Oracle Tuxedo software.
    002
    GID
    The effective group ID for the owner of the bulletin board IPC structures. In a multiprocessor configuration, the value must be the same on all machines. Users of the application should share this group ID.
    003
    SITE1 name
    The node name of the machine. Use the value produced by the UNIX command:
    uname -n
    004
    TUXDIR
    The absolute pathname of the root directory for the Oracle Tuxedo system software. Make this a global change to put the value in all occurrences of <TUXDIR1> in the file.
    005
    APPDIR
    The absolute pathname of the directory where the application runs. Make this a global change to put the value in all occurrences of <APPDIR1> in the file.
    006
    machine type
    This parameter is important in a networked application where machines of different types are present. The Oracle Tuxedo system checks for the value on all communication between machines. Only if the values are different are the message encode/decode routines called to convert the data.

See Also

 


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.

  1. Go to the directory in which your STOCKAPP files are located.
  2. Set the environment variables by entering:
  3. . ./STKVAR

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.

  1. To create TUXCONFIG, enter the following command:
  2.     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.

  3. If you want the amount of IPC resources needed by your application to be calculated by the Oracle Tuxedo system, include the -c option on the command line.
  4. 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

 


Running STOCKAPP

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 Requests

 


Step 1: How to Prepare to Boot

  1. 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.
  2. Listing 5-3 IPC Report
        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.
  3. You should add the number of application client used per processor to each MSGMNI value. MSGMAP should be twice MSGMNI.
  4. Compare the minimum IPC requirements to the parameters set for your machine. The location of these parameter settings is platform-dependent:
    • On many UNIX system platforms, machine parameters are defined in /etc/conf/cf.d/mtune.
    • On Windows 2003 platforms, machine parameters are set and displayed through a control panel.

See Also

 


Step 2: How to Boot STOCKAPP

  1. Set the environment:
  2. ../STKVAR 
  3. Boot the application by entering the following:
  4.     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.

See Also

 


Step 3: How to Test STOCKAPP Services

  1. If you are logging in cold to a running system, you must set your environment for STOCKAPP. To do so, enter the following command:
  2. ../STKVAR
  3. Run the BUY client program. To execute the BUY client program, enter the following command:
  4. BUY
  5. 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.

    tmshutdown

Running this command (or the shutdown command of tmadmin) causes the following results:

See Also


  Back to Top       Previous  Next