This chapter contains a tutorial that describes a simple one-client, one-server application called If you follow the ten steps of the tutorial you will:
About This Chapter
CSIMPAPP. An interactive form of this chapter is distributed with the BEA TUXEDO system software.
Before you can run this tutorial the BEA TUXEDO system software must be installed so that the files and commands referred to in this chapter are available.
If you are personally responsible for installing the BEA TUXEDO system software, consult the BEA TUXEDO Installation Guide for information about how to install the BEA TUXEDO system.
If the installation has already been done by someone else, you need to know the pathname of the root directory of the installed software. You also need to have read and execute permissions on the directories and files in the BEA TUXEDO system directory structure so you can copy The tutorial consists of ten steps (plus an eleventh step for shutdown) designed to introduce you to the BEA TUXEDO system by showing how an application is developed and by encouraging you to bring the application up and run it. Each of the steps includes one or more smaller steps.
Some Preliminaries
CSIMPAPP files and execute BEA TUXEDO commands.
The CSIMPAPP Tutorial
CSIMPAPP is a very basic BEA TUXEDO system application. It has one client and one server. The server performs only one service; it accepts a string from the client and returns the same string in upper case.
Step 1: Copy the CSIMPAPP Files
CSIMPAPP and cd to it:
This is suggested so you will be able to see clearly the mkdir CSIMPDIR
cd CSIMPDIRCSIMPAPP 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; not csh.
You need 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=$PATH:$TUXDIR/bin
LD_LIBRARY_PATH=$COBDIR/coblib:${LD_LIBRARY_PATH}
export TUXDIR APPDIR TUXCONFIG UBBCONFIG COBDIR COBCPY
export COBOPT CFLAGS PATH LD_LIBRARY_PATHTUXDIR and PATH to be able to access files in the BEA TUXEDO system directory structure and to execute BEA TUXEDO system commands. On SunOS, /usr/5bin must be the first directory in your PATH. On AIX, LIBPATH must be set instead of LD_LIBRARY_PATH. On HPUX, SHLIB_PATH must be set instead of LD_LIBRARY_PATH. You need to set TUXCONFIG to be able to load the configuration file as shown in Step 7.
CSIMPAPP files.
Later on you will be editing some of the files and making them executable, so it is best to begin with a copy of the files rather than the originals delivered with the software.
cp $TUXDIR/apps/CSIMPAPP/* .
The files that make up the application are:
$ ls
CSIMPCL.cbl
CSIMPSRV.cbl
README
TPSVRINIT.cbl
UBBCSIMPLE
WUBBCSIMPLE
envfile
ws
$
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 ASCII form of the configuration file for the application
WUBBCSIMPLE-the config file for the Workstation example
ws-a directory with .MAK files for client programs for three workstation platforms
Page through the client program source code:
$ more CSIMPCL.cbl
The output is shown in Listing 1-1.
Listing 1-1 Source code of 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).
31 01 RECV-STRING PIC X(100).
32 *****************************************************
33 * Command line arguments
34 *****************************************************
35 LINKAGE SECTION.
36 01 CMD-LINE.
37 05 ARG-LENGTH PIC 9(4) COMP.
38 05 ARG.
39 10 ARGS PIC X OCCURS 0 TO 100 DEPENDING
40 ON ARG-LENGTH.
41 ******************************************************
42 * Start program with command line args
43 ******************************************************
44
45 PROCEDURE DIVISION USING CMD-LINE.
46 START-CSIMPCL.
47 MOVE LENGTH OF LOGMSG TO LOGMSG-LEN.
48 PERFORM CHECK-ARGS.
49 PERFORM DO-TPINIT.
50 MOVE ARG TO SEND-STRING.
51 PERFORM DO-TPCALL.
52 DISPLAY RECV-STRING.
53 PERFORM DO-TPTERM.
54 PERFORM EXIT-PROGRAM.
55
56 ******************************************************
57 * Check Arguments being passed
58 ******************************************************
59 CHECK-ARGS.
60 IF ARG-LENGTH = 0
61 DISPLAY "Usage: CSIMPCL string"
62 PERFORM EXIT-PROGRAM
63 END-IF.
64 IF ARG-LENGTH = 100
65 DISPLAY "Command Line Too Long"
66 PERFORM EXIT-PROGRAM
67 END-IF.
68
69 MOVE "Started" TO LOGMSG-TEXT.
70 PERFORM DO-USERLOG.
71
72 *****************************************************
73 * Now register the client with the system.
74 *****************************************************
75 DO-TPINIT.
76 MOVE SPACES TO USRNAME.
77 MOVE SPACES TO CLTNAME.
78 MOVE SPACES TO PASSWD.
79 MOVE SPACES TO GRPNAME.
80 MOVE ZERO TO DATALEN.
81 SET TPU-DIP TO TRUE.
82
83 CALL "TPINITIALIZE" USING TPINFDEF-REC
84 USER-DATA-REC
85 TPSTATUS-REC.
86
87 IF NOT TPOK
88 MOVE "TPINITIALIZE Failed" TO LOGMSG-TEXT
89 PERFORM DO-USERLOG
90 PERFORM EXIT-PROGRAM
91 END-IF.
92
93 *****************************************************
94 * Issue a TPCALL
95 *****************************************************
96 DO-TPCALL.
97 MOVE ARG-LENGTH TO LEN.
98 MOVE "STRING" TO REC-TYPE.
99 MOVE "CSIMPSRV" TO SERVICE-NAME.
100 SET TPBLOCK TO TRUE.
101 SET TPNOTRAN TO TRUE.
102 SET TPNOTIME TO TRUE.
103 SET TPSIGRSTRT TO TRUE.
104 SET TPCHANGE TO TRUE.
105
106 CALL "TPCALL" USING TPSVCDEF-REC
107 TPTYPE-REC
108 SEND-STRING
109 TPTYPE-REC
110 RECV-STRING
111 TPSTATUS-REC.
112
113 IF NOT TPOK
114 MOVE "TPCALL Failed" TO LOGMSG-TEXT
115
Here are the important things to see in this file:
The ATMI calls cited above are documented in the following pages in the BEA TUXEDO Reference Manual: References
TPINITIALIZE(3cbl), TPTERM(3cbl), TPCALL(3cbl), USERLOG(3cbl).
Step 3: Compile the Client
buildclient to compile the client program:
where the output file is buildclient -C -o CSIMPCL -f CSIMPCL.cbl
CSIMPCL, and the input source file is CSIMPCL.cbl.
As can be seen, we now have an executable module called $ ls CSIMPCL*
CSIMPCL CSIMPCL.cbl CSIMPCL.idy CSIMPCL.int CSIMPCL.oCSIMPCL.
buildclient is documented in buildclient(1) in the BEA TUXEDO Reference Manual.
$ pg CSIMPSRV.cbl
Listing 1-2
Source code of 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.
Here are the important things to see in this file:
$ pg TPSVRINIT.cbl
Listing 1-3
Source code of 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.
This subroutine is called during server initialization, before the server begins processing service requests. A default is provided by the BEA TUXEDO system that writes a message to USERLOG indicating that the server has been booted.
The ATMI calls and structure cited above are documented in the following pages in the BEA TUXEDO Reference Manual: TPSVCSTART(3cbl), TPSVRINIT(3cbl), TPRETURN(3cbl), USERLOG(3cbl).
buildserver to compile the server program:
where the executable file to be created is named buildserver -C -o CSIMPSRV -f CSIMPSRV.cbl -f TPSVRINIT.cbl -s CSIMPSRV
CSIMPSRV, and CSIMPSRV.cbl and TPSVRINIT.cbl are the input source files.
As can be seen, we now have an executable module called $ 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 UBBCSIMPLECSIMPSRV.
buildserver is documented in buildserver(1) in the BEA TUXEDO Reference Manual.
Listing 1-4
The 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 123456MASTER 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"<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
TUXCONFIG and TUXDIR must be identical to those you set and
exported in Step 1 in "Step 1: Copy the CSIMPAPP Files." The strings must be
the actual values; environment variables (such as $TUXCONFIG) are not
acceptable. Do not forget to remove the angle brackets.
The configuration file is documented in ubbconfig(5) in the BEA TUXEDO Reference Manual.
tmloadcf to load the configuration file:
$ tmloadcf UBBCSIMPLE
Initialize TUXCONFIG file: /usr/me/CSIMPDIR/TUXCONFIG [y, q] ? y
$
We see that we now have a file called $ 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 UBBCSIMPLETUXCONFIG. The TUXCONFIG file is a new file system under the control of the BEA TUXEDO system.
tmloadcf is documented in tmloadcf(1) in the BEA TUXEDO Reference Manual.
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.
$
BBL is the administrative process that monitors the application shared memory structures. CSIMPSRV is our server that runs continuously awaiting requests.
tmboot is documented in tmboot(1) in the BEA TUXEDO Reference Manual.
Run the client program to submit a request:
$ CSIMPCL "hello world"
HELLO WORLD
We are successful!!!
tmadmin is an interactive program that an administrator can use to check an application and make dynamic changes. It requires the TUXCONFIG variable to be set. We will show you just two of the many tmadmin commands.
You will see the following lines.
The greater-than sign (tmadmin
tmadmin - Copyright (c) 1987 ATT; 1991 USL. All rights reserved.
>
>) is the tmadmin prompt.
printserver(psr) command to display information about the
servers:
> 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)
> printservice(psc) command to display information about the
services:
> psc
Service Name Routine Name a.out Name Grp Name ID Machine # Done Status
------------ ------------ ---------- -------- -- ------- ---- -------
ADJUNCTBB ADJUNCTBB BBL simple 0 simple - AVAIL
ADJUNCTADMIN ADJUNCTADMIN BBL simple 0 simple - AVAIL
CSIMPSRV CSIMPSRV CSIMPSRV GROUP1 1 simple - AVAIL
> tmadmin by entering a q at the prompt. You can boot and shut down the
application from within tmadmin. We have done those functions with shell
commands in Steps 8 and 11, respectively.
tmadmin is documented in tmadmin(1) in the BEA TUXEDO Reference Manual.
tmshutdown to bring the application down:
$ tmshutdown
Shutdown all admin and server processes? (y/n): y
Shutting down all admin and server processes in /usr/me/CSIMPDIR/TUXCONFIGShutting 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.
$ ULOG:
Each line of the Now let's look at an individual line:
$ 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:EndedULOG for this session contains something of interest. First let's look at the format of a ULOG line:
time (hhmmss).machine_uname!process_name.process_id: log message
140542. Message from TPSVRINIT in CSIMPSRV
tmshutdown is documented in tmshutdown(1) in the BEA TUXEDO Reference Manual.
The USERLOG is documented in USERLOG(3cbl).
If you have reached this point, you have successfully brought up, run and brought down a BEA TUXEDO system application. You have seen what a client program and a server look like. You have edited a configuration file to refer to your own environment. You have invoked tmadmin to check on the activity of your application. In all the applications you may work on in the future the basic elements of client processes, server processes and a configuration file will be present, and you will have all of the BEA TUXEDO shell commands at your fingertips.
Good luck!