![]() ![]() ![]() ![]() ![]() ![]() |
This topic includes the following sections:
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.
This topic leads you through the procedures you must complete to develop CSIMPAPP
. The following flow chart summarizes this procedure.
Click on each task for instructions on completing that task.
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.
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.
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 . |
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:
/usr/5bin
must be the first directory in your PATH
.LIBPATH
instead of LD_LIBRARY_PATH
.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.CSIMPAPP
files: 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. |
$ 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.
Review the client program source code:
$ more CSIMPCL.cbl
The output is shown in the following list.
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.
CSIMPSRV
ATMI server program: $ more 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.
TPSVRINIT
subroutine. To familiarize yourself with TPSVRINIT
, page through the source code for it.$ more 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.
buildserver
as follows to compile the ATMI server program.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.
$ 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
CSIMPAPP
.#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
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. |
tmloadcf
to load the configuration file: $ tmloadcf UBBCSIMPLE
Initialize TUXCONFIG file: /usr/me/CSIMPDIR/TUXCONFIG [y, q] ? y
$
$ 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).
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.
To test CSIMPAPP
, have the client submit a request:
$ CSIMPCL “hello world”
HELLO WORLD
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:
Note: | The greater-than sign (> ) is the tmadmin prompt. |
printserver(psr)
command to display information about 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 services:> psc
Service Name Routine Name a.out Name Grp Name ID Machine # Done Status
------------ ------------ ---------- -------- -- ------- ---- -------
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
.)
tmshutdown
to bring down the application:$ 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.
$
ULOG
: $ 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
140542. Message from TPSVRINIT in CSIMPSRV
Oracle Tuxedo Command Reference
![]() ![]() ![]() |