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 CSIMPAPP, a Simple COBOL Application

This topic includes the following sections:

 


What Is CSIMPAPP?

CSIMPAPP is a basic sample ATMI application delivered with the Oracle Tuxedo system. While instructions are written for the Microfocus COBOL compiler, these may vary depending on your specific compiler. To find out which COBOL platforms are supported by the Oracle Tuxedo system, consult Appendix A, “Oracle Tuxedo 10.0 Platform Data Sheets,” in Installing the Oracle Tuxedo System.

CSIMPAPP includes one client and one server. The server performs only one service: it accepts a string from the client and returns the same string in uppercase.

 


Preparing CSIMPAPP Files and Resources

This topic leads you through the procedures you must complete to develop CSIMPAPP. Figure 4-1 summarizes this procedure.

Click on each task for instructions on completing that task.

Figure 4-1 csimpapp Development Process

csimpapp Development Process

Before You Begin

Before you can run this tutorial, the Oracle Tuxedo ATMI client and server software must be installed so that the files and commands referred to are available. If you are responsible for installing the Oracle Tuxedo system software, refer to Installing the Oracle Tuxedo System for installation instructions. If the installation has already been done by someone else, you need to find out the pathname of the directory in which the software is installed (TUXDIR). You also need to have read and execute permissions on the directories and files in the Oracle Tuxedo system directory structure so you can copy CSIMPAPP files and execute Oracle Tuxedo system commands.

What You Will Learn

After you complete this procedure, you will be able to understand the tasks clients and servers can perform, edit a configuration file for your own environment, and invoke tmadmin to check on the activity of your application. In short, you will understand the basic elements of all Oracle Tuxedo applications—client processes, server processes, and a configuration file—and you will know how to use Oracle Tuxedo system commands to manage your application.

 


Step 1: How to Copy the CSIMPAPP Files

  1. Make a directory for CSIMPAPP and change the directory to it:
  2. mkdir CSIMPDIR
    cd CSIMPDIR
Note: This step is suggested so you can see the CSIMPAPP files you have at the start and the additional files you create along the way. Use the standard shell (/bin/sh) or the Korn shell; do not use csh.
  1. Set and export environment variables:
  2. TUXDIR=<pathname of the BEA Tuxedo System root directory>
    APPDIR=<pathname of your present working directory>
    TUXCONFIG=$APPDIR/TUXCONFIG
    COBDIR=<pathname of the COBOL compiler directory>
    COBCPY=$TUXDIR/cobinclude
    COBOPT="-C ANS85 -C ALIGN=8 -C NOIBMCOMP -C TRUNC=ANSI -C OSEXT=cbl"
    CFLAGS="-I$TUXDIR/include"
    PATH=$TUXDIR/bin:$APPDIR: $PATH
    LD_LIBRARY_PATH=$COBDIR/coblib:${LD_LIBRARY_PATH}
    export TUXDIR APPDIR TUXCONFIG UBBCONFIG COBDIR COBCPY
    export COBOPT CFLAGS PATH LD_LIBRARY_PATH

    You need TUXDIR and PATH to be able to access files in the Oracle Tuxedo directory structure and to execute Oracle Tuxedo commands:

    • On Sun Solaris, /usr/5bin must be the first directory in your PATH.
    • On an AIX platform on the RS/6000, use LIBPATH instead of LD_LIBRARY_PATH.
    • On an HP-UX platform on the HP 9000, use SHLIB_PATH instead of LD_LIBRARY_PATH. You need to set TUXCONFIG to be able to load the configuration file as shown in step 4.
  3. Copy the CSIMPAPP files:
  4. cp TUXDIR/samples/atmi/CSIMPAPP/* .
    Note: Later, you will edit some files and make them executable, so we recommend using copies of the files rather than the originals delivered with the software.
  5. List the files:
  6. $ ls
    CSIMPCL.cbl
    CSIMPSRV.cbl
    README
    TPSVRINIT.cbl
    UBBCSIMPLE
    WUBBCSIMPLE
    envfile
    ws
    $

    The files that make up the application are:

    • CSIMPCL.cbl—the source code for the client program.
    • CSIMPSRV.cbl—the source code for the server program.
    • TPSVRINIT.cbl—the source code for the server initialization program.
    • UBBCSIMPLE—the text form of the configuration file for the application.
    • WUBBCSIMPLE—the configuration file for the Workstation example.
    • ws—a directory with .MAK files for client programs for three workstation platforms.

 


Step 2: Examining and Compiling the Client

How to Examine the Client

Review the client program source code:

$ more CSIMPCL.cbl

The output is shown in the following list.

Listing 4-1 Source Code for CSIMPCL.cbl
1      IDENTIFICATION DIVISION.
2 PROGRAM-ID. CSIMPCL.
3 AUTHOR. Tuxedo DEVELOPMENT.
4 ENVIRONMENT DIVISION.
5 CONFIGURATION SECTION.
6 WORKING-STORAGE SECTION.
7 *****************************************************
8 * Tuxedo definitions
9 *****************************************************
10 01 TPTYPE-REC.
11 COPY TPTYPE.
12 *
13 01 TPSTATUS-REC.
14 COPY TPSTATUS.
15 *
16 01 TPSVCDEF-REC.
17 COPY TPSVCDEF.
18 *
19 01 TPINFDEF-REC VALUE LOW-VALUES.
20 COPY TPINFDEF.
21 *****************************************************
22 * Log messages definitions
23 *****************************************************
24 01 LOGMSG.
25 05 FILLER PIC X(8) VALUE "CSIMPCL:".
26 05 LOGMSG-TEXT PIC X(50).
27 01 LOGMSG-LEN PIC S9(9) COMP-5.
28 *
29 01 USER-DATA-REC PIC X(75).
30 01 SEND-STRING PIC X(100) VALUE SPACES.
31 01 RECV-STRING PIC X(100) VALUE SPACES.
32 *****************************************************
33 * Command line arguments
34 *****************************************************
35 * Start program with command line args
36 ******************************************************
37
38 PROCEDURE
39 START-CSIMPCL.
40 MOVE LENGTH OF LOGMSG TO LOGMSG-LEN.
41 ACCEPT SEND-STRING FROM COMMAND-LINE.
42 DISPLAY “SEND-STRING:” SEND-STRING.
43
44 MOVE “Started” TO LOGMSG-TEXT.
45 PERFORM DO-TPINIT.
46 PERFORM DO-TPCALL.
47 DISPLAY “RECV-STRING:” RECV-STRING.
48 PERFORM DO-TPTERM.
49 PERFORM EXIT-PROGRAM.
50 *****************************************************
51 * Now register the client with the system.
52 *****************************************************
53 DO-TPINIT.
54 MOVE SPACES TO USRNAME.
55 MOVE SPACES TO CLTNAME.
56 MOVE SPACES TO PASSWD.
57 MOVE SPACES TO GRPNAME.
58 MOVE ZERO TO DATALEN.
59 SET TPU-DIP TO TRUE.
60
61 CALL "TPINITIALIZE" USING TPINFDEF-REC
62 USER-DATA-REC
63 TPSTATUS-REC.
64
65 IF NOT TPOK
66 MOVE "TPINITIALIZE Failed" TO LOGMSG-TEXT
67 PERFORM DO-USERLOG
68 PERFORM EXIT-PROGRAM
69 END-IF.
70
71 *****************************************************
72 * Issue a TPCALL
73 *****************************************************
74 DO-TPCALL.
75 MOVE 100 to LEN.
76 MOVE "STRING" TO REC-TYPE.
77 MOVE "CSIMPSRV" TO SERVICE-NAME.
78 SET TPBLOCK TO TRUE.
79 SET TPNOTRAN TO TRUE.
80 SET TPNOTIME TO TRUE.
81 SET TPSIGRSTRT TO TRUE.
82 SET TPCHANGE TO TRUE.
83
84 CALL "TPCALL" USING TPSVCDEF-REC
85 TPTYPE-REC
86 SEND-STRING
87 TPTYPE-REC
88 RECV-STRING
89 TPSTATUS-REC.
90
91 IF NOT TPOK
92 MOVE "TPCALL Failed" TO LOGMSG-TEXT
93 PERFORM DO-USERLOG
94 END-IF.
95
96 *****************************************************
97 * Leave Tuxedo
98 *****************************************************
99 DO-TPTERM.
100 CALL "TPTERM" USING TPSTATUS-REC.
101 IF NOT TPOK
102 MOVE "TPTERM Failed" TO LOGMSG-TEXT
103 PERFORM DO-USERLOG
104 END-IF.
105
106 *****************************************************
107 * Log messages to the userlog
108 *****************************************************
109 DO-USERLOG.
110 CALL "USERLOG" USING LOGMSG
111 LOGMSG-LEN
112 TPSTATUS-REC.
113
114 *****************************************************
115 *Leave Application
116 *****************************************************
117 EXIT-PROGRAM.
118 MOVE "Ended" TO LOGMSG-TEXT.
119 PERFORM DO-USERLOG.
120 STOP RUN.

Table 4-1 Significant Lines in the CSIMPCL.cbl Source Code 
Line(s)
File/Function
Purpose
11, 14, 17, 20
COPY
Command used to replicate files needed whenever Oracle Tuxedo ATMI functions are used.
61
TPINITIALIZE
The ATMI function used by a client program to join an application.
84
TPCALL
The ATMI function used to send the message record to the service specified in SERVICE-NAME. TPCALL waits for a return message. STRING is one of the three basic Oracle Tuxedo record types. An argument, LEN IN TPTYPE-REC, specifies the length of the record in USER-DATA-REC.
100
TPTERM
The ATMI function used to leave an application. A call to TPTERM is used to exit an application before performing a STOP RUN.
110
USERLOG
The function that displays the message returned from the server, the successful conclusion of tpcall.

How to Compile the Client

  1. Run buildclient to compile the ATMI client program:
  2. buildclient -C -o CSIMPCL -f CSIMPCL.cbl

    The output file is CSIMPCL and the input source file is CSIMPCL.cbl.

  3. Check the results:
  4. $ ls CSIMPCL*
    CSIMPCL CSIMPCL.cbl CSIMPCL.idy CSIMPCL.int CSIMPCL.o

    You now have an executable module called CSIMPCL.

See Also

 


Step 3: Examining and Compiling the Server

How to Examine the Server

  1. Review the source code from the CSIMPSRV ATMI server program:
  2. $ more CSIMPSRV.cbl
    Listing 4-2 Source Code for CSIMPSRV.cbl
    1      IDENTIFICATION DIVISION.
    2 PROGRAM-ID. CSIMPSRV.
    3 AUTHOR. BEA Tuxedo DEVELOPMENT.
    4 ENVIRONMENT DIVISION.
    5 CONFIGURATION SECTION.
    6 WORKING-STORAGE SECTION.
    7 ******************************************************
    8 * Tuxedo definitions
    9 ******************************************************
    10 01 TPSVCRET-REC.
    11 COPY TPSVCRET.
    12 *
    13 01 TPTYPE-REC.
    14 COPY TPTYPE.
    15 *
    16 01 TPSTATUS-REC.
    17 COPY TPSTATUS.
    18 *
    19 01 TPSVCDEF-REC.
    20 COPY TPSVCDEF.
    21 ******************************************************
    22 * Log message definitions
    23 ******************************************************
    24 01 LOGMSG.
    25 05 FILLER PIC X(10) VALUE
    26 "CSIMPSRV :".
    27 05 LOGMSG-TEXT PIC X(50).
    28 01 LOGMSG-LEN PIC S9(9) COMP-5.
    29 ******************************************************
    31 * User defined data records
    32 ******************************************************
    33 01 RECV-STRING PIC X(100).
    34 01 SEND-STRING PIC X(100).
    35 *
    36 LINKAGE SECTION.
    37 *
    38 PROCEDURE DIVISION.
    39 *
    40 START-FUNDUPSR.
    41 MOVE LENGTH OF LOGMSG TO LOGMSG-LEN.
    42 MOVE "Started" TO LOGMSG-TEXT.
    43 PERFORM DO-USERLOG.
    44
    45 ******************************************************
    46 * Get the data that was sent by the client
    47 ******************************************************
    48 MOVE LENGTH OF RECV-STRING TO LEN.
    49 CALL "TPSVCSTART" USING TPSVCDEF-REC
    50 TPTYPE-REC
    51 RECV-STRING
    52 TPSTATUS-REC.
    53
    54 IF NOT TPOK
    55 MOVE "TPSVCSTART Failed" TO LOGMSG-TEXT
    56 PERFORM DO-USERLOG
    57 PERFORM EXIT-PROGRAM
    58 END-IF.
    59
    60 IF TPTRUNCATE
    61 MOVE "Data was truncated" TO LOGMSG-TEXT
    62 PERFORM DO-USERLOG
    63 PERFORM EXIT-PROGRAM
    64 END-IF.
    65
    66 INSPECT RECV-STRING CONVERTING
    67 "abcdefghijklmnopqrstuvwxyz" TO
    68 "ABCDEFGHIJKLMNOPQRSTUVWXYZ".
    69 MOVE "Success" TO LOGMSG-TEXT.
    70 PERFORM DO-USERLOG.
    71 SET TPSUCCESS TO TRUE.
    72 COPY TPRETURN REPLACING
    73 DATA-REC BY RECV-STRING.
    74
    75 ******************************************************
    76 * Write out a log err messages
    77 ******************************************************
    78 DO-USERLOG.
    79 CALL "USERLOG" USING LOGMSG
    80 LOGMSG-LEN
    81 TPSTATUS-REC.
    82 ******************************************************
    83 * EXIT PROGRAM
    84 ******************************************************
    85 EXIT-PROGRAM.
    86 MOVE "Failed" TO LOGMSG-TEXT.
    87 PERFORM DO-USERLOG.
    88 SET TPFAIL TO TRUE.
    89 COPY TPRETURN REPLACING
    90 DATA-REC BY RECV-STRING.

    Table 4-2 Significant Lines in the CSIMPSRV.cbl Source Code 
    Line(s)
    Routine
    Purpose
    49
    TPSVCSTART
    Routine used to start this service and to receive the service’s parameters and data. After a successful call, the RECV-STRING contains the data sent by the client.
    66-68
    INSPECT statement
    Statement that converts the input to uppercase (Microfocus-specific).
    72
    COPY TPRETURN
    Command line that returns the converted string to the client with TPSUCCESS set.
    79
    USERLOG
    Routine that logs messages used by the Oracle Tuxedo system and applications.

  3. During server initialization (that is, before the server starts processing service requests), the Oracle Tuxedo system calls the TPSVRINIT subroutine. To familiarize yourself with TPSVRINIT, page through the source code for it.
  4. $ more TPSVRINIT.cbl
    Listing 4-3 Source Code for TPSVRINIT.cbl
    1   IDENTIFICATION DIVISION.
    2 PROGRAM-ID. TPSVRINIT.
    3 ENVIRONMENT DIVISION.
    4 CONFIGURATION SECTION.
    5 *
    6 DATA DIVISION.
    7 WORKING-STORAGE SECTION.
    8 *
    9 01 LOGMSG.
    10 05 FILLER PIC X(11) VALUE "TPSVRINIT :".
    11 05 LOGMSG-TEXT PIC X(50).
    12 01 LOGMSG-LEN PIC S9(9) COMP-5.
    13 *
    14 01 TPSTATUS-REC.
    15 COPY TPSTATUS.
    16 *********************************************************
    17 LINKAGE SECTION.
    18 01 CMD-LINE.
    19 05 ARGC PIC 9(4) COMP-5.
    20 05 ARG.
    21 10 ARGS PIC X OCCURS 0 TO 9999 DEPENDING ON ARGC.
    22 *
    23 01 SERVER-INIT-STATUS.
    24 COPY TPSTATUS.
    25 ***********************************************************
    26 PROCEDURE DIVISION USING CMD-LINE SERVER-INIT-STATUS.
    27 A-000.
    28 MOVE LENGTH OF LOGMSG TO LOGMSG-LEN.
    29 ***********************************************************
    30 * There are no command line parameters in this TPSVRINIT
    31 ***********************************************************
    32 IF ARG NOT EQUAL TO SPACES
    33 MOVE "TPSVRINIT failed" TO LOGMSG-TEXT
    34 CALL "USERLOG" USING LOGMSG
    35 LOGMSG-LEN
    36 TPSTATUS-REC
    37 ELSE
    38 MOVE "Welcome to the simple service" TO LOGMSG-TEXT
    39 CALL "USERLOG" USING LOGMSG
    40 LOGMSG-LEN
    41 TPSTATUS-REC
    42 END-IF.
    43 *
    44 SET TPOK IN SERVER-INIT-STATUS TO TRUE.
    45 *
    46 EXIT PROGRAM.

A default is provided by the Oracle Tuxedo system that writes a message to USERLOG indicating that the server has been booted.

How to Compile the Server

  1. Run buildserver as follows to compile the ATMI server program.
  2. buildserver -C -o CSIMPSRV -f CSIMPSRV.cbl -f TPSVRINIT.cbl -s CSIMPSRV

    The executable file to be created is named CSIMPSRV and CSIMPSRV.cbl and TPSVRINIT.cbl are the input source files. The service being offered by the server CSIMPSRV is indicated by -s CSIMPSRV.

  3. Check the results by displaying a list of the files in your current directory.
  4. $ ls
    CSIMPCL CSIMPCL.int CSIMPSRV.cbl CSIMPSRV.o TPSVRINIT.int
    CSIMPCL.cbl CSIMPCL.o CSIMPSRV.idy TPSVRINIT.cbl TPSVRINIT.o
    CSIMPCL.idy CSIMPSRV CSIMPSRV.int TPSVRINIT.idy UBBCSIMPLE

    You now have an executable module called CSIMPSRV.

See Also

 


Step 4: Editing and Loading the Configuration File

How to Edit the Configuration File

  1. In a text editor, familiarize yourself with the configuration file for CSIMPAPP.
  2. Listing 4-4 CSIMPAPP Configuration File
    #Skeleton UBBCONFIG file for the BEA Tuxedo COBOL Simple Application.
    #Replace the <bracketed> items with the appropriate values.
    *RESOURCES
    IPCKEY <Replace with a valid IPC Key>
    #Example:
    #IPCKEY 123456

    DOMAINID UBBCSIMPLE
    MASTER simple
    MAXACCESSERS 5
    MAXSERVERS 5
    MAXSERVICES 10
    MODEL SHM
    LDBAL N
    *MACHINES
    DEFAULT:
    APPDIR="<Replace with the current pathname>"
    TUXCONFIG="<Replace with TUXCONFIG Pathname>"
    TUXDIR="<Root directory of BEA Tuxedo (not /)>"
    ENVFILE="<pathname of file of environment vars>"
    #Example:
    # APPDIR="/home/me/simpapp"
    # TUXCONFIG="/home/me/simpapp/TUXCONFIG"
    # TUXDIR="/usr/tuxedo"
    # ENVFILE=”/home/me/simpapp/envfile”
    <Machine-name> LMID=simple
    #Example:
    #usltux LMID=simple
    *GROUPS
    GROUP1
    LMID=simple GRPNO=1 OPENINFO=NONE
    *SERVERS
    DEFAULT:
    CLOPT="-A"
    CSIMPSRV           SRVGRP=GROUP1   SRVID=1
    *SERVICES
    CSIMPSRV
  3. For each string (that is, for each string shown in italic between angle brackets), substitute an appropriate value:
    • IPCKEY—use a value that will not conflict with any other users.
    • TUXCONFIG—provide the full pathname of the binary TUXCONFIG file.
    • TUXDIR—the full pathname of your Oracle Tuxedo system root directory.
    • APPDIR—the full pathname of the directory in which you intend to boot the application; in this case, the current directory.
    • ENVFILE—the full pathname for the environment file to be used by mc, viewc, tmloadcf, and so on.
    • machine-name—the machine name as returned by the uname -n command on a UNIX platform.
Note: The pathnames for TUXCONFIG and TUXDIR must be identical to those you set and exported earlier. You must specify actual pathnames; references to pathnames through environment variables (such as TUXCONFIG) are not acceptable. Do not forget to remove the angle brackets.

How to Load the Configuration File

  1. Run tmloadcf to load the configuration file:
  2. $ tmloadcf UBBCSIMPLE
    Initialize TUXCONFIG file: /usr/me/CSIMPDIR/TUXCONFIG [y, q] ? y
    $
  3. Check the results by displaying a list of the files in your current directory:
  4. $ ls
    CSIMPCL CSIMPCL.o CSIMPSRV.int TPSVRINIT.int
    CSIMPCL.cbl CSIMPSRV CSIMPSRV.o TPSVRINIT.o
    CSIMPCL.idy CSIMPSRV.cbl TPSVRINIT.cbl TUXCONFIG
    CSIMPCL.int CSIMPSRV.idy TPSVRINIT.idy UBBCSIMPLE

    We now have a file called TUXCONFIG (a new file system under the control of the Oracle Tuxedo system).

See Also

 


Step 5: How to Boot the Application

Execute tmboot to bring up the application:

$ tmboot
Boot all admin and server processes? (y/n): y
Booting all admin and server processes in /usr/me/CSIMPDIR/TUXCONFIG
Booting all admin processes ...
exec BBL -A:
process id=24223 ... Started.
Booting server processes ...
exec CSIMPSRV -A :
process id=24257 ... Started.
2 processes started.
$

The Bulletin Board Liaison (BBL) is the administrative process that monitors the shared memory structures in the application. CSIMPSRV is the CSIMPAPP server that runs continuously, awaiting requests.

See Also

 


Step 6: How to Test the Run-time Application

To test CSIMPAPP, have the client submit a request:

$ CSIMPCL “hello world”
HELLO WORLD

 


Step 7: How to Monitor the Run-time Application

As the administrator, you can use the tmadmin command interpreter to check an application and make dynamic changes. To run tmadmin, you must set the TUXCONFIG variable

tmadmin can interpret and run over 50 commands. For a complete list, see tmadmin(1) in the Oracle Tuxedo Command Reference. The following demonstrates two of the many tmadmin commands:

  1. Enter the following command:
  2. tmadmin

    The following lines are displayed:

    tmadmin - Copyright (c) 1999 BEA Systems Inc.; 1991 USL. All rights reserved.
    >
Note: The greater-than sign (>) is the tmadmin prompt.
  1. Enter the printserver(psr) command to display information about servers:
  2. > psr
    a.out Name Queue Name Grp Name ID RqDone Load Done Current Service
    ---------- ---------- -------- -- ------ --------- ---------------
    BBL 531993 simple 0 0 0 (IDLE)
    CSIMPSRV 00001.00001 GROUP1 1 0 0 (IDLE)
    >
  3. Enter the printservice(psc) command to display information about services:
  4. > psc
    Service Name Routine Name a.out Name Grp Name ID Machine # Done Status
    ------------ ------------ ---------- -------- -- ------- ---- -------
    CSIMPSRV CSIMPSRV CSIMPSRV GROUP1 1 simple - AVAIL
    >
  5. Leave tmadmin by entering a q at the prompt. (You can boot and shut down the application from within tmadmin.)

See Also

 


Step 8: How to Shut Down the Application

  1. Run tmshutdown to bring down the application:
  2. $ tmshutdown
    Shutdown all admin and server processes? (y/n): y
    Shutting down all admin and server processes in /usr/me/CSIMPDIR/TUXCONFIG
    Shutting down server processes ...
    Server Id = 1 Group Id = GROUP1 Machine = simple:  shutdown succeeded.
    Shutting down admin processes ...
    Server Id = 0 Group Id = simple Machine = simple:  shutdown succeeded.
    2 processes stopped.
    $
  3. Check the ULOG:
  4. $ cat ULOG*
    $
    140533.usltux!BBL.22964: LIBTUX_CAT:262: std main starting
    140540.usltux!CSIMPSRV.22965: COBAPI_CAT:1067: INFO: std main starting
    140542.usltux!CSIMPSRV.22965: TPSVRINIT :Welcome to the simple service
    140610.usltux!?proc.22966: CSIMPCL:Started
    140614.usltux!CSIMPSRV.22965: CSIMPSRV :Started
    140614.usltux!CSIMPSRV.22965: CSIMPSRV :Success
    140614.usltux!?proc.22966: switch to new log file
    /home/usr_nm/CSIMPDIR/ULOG.112592
    140614.usltux!?proc.22966: CSIMPCL:Ended

    Each line of the ULOG for this session is significant. First look at the format of a ULOG line:

    time (hhmmss).machine_uname!process_name.process_id: log message

    Now look at an actual line.

    140542. Message from TPSVRINIT in CSIMPSRV

See Also


  Back to Top       Previous  Next