The purpose of this chapter is to describe the environment in which you will be writing code for a BEA TUXEDO system application.
In addition to the COBOL code that expresses the logic of your application, you will be using the Application-Transaction Monitor Interface (ATMI), which refers to the interface between the BEA TUXEDO system and your application. The ATMI calls are COBOL calls that have the specific purpose of implementing the communication among application modules running under the control of BEA TUXEDO, including all the associated resources you need.
As you might remember from the BEA TUXEDO Product Overview, the BEA TUXEDO system uses an enhanced client-server architecture. The remaining chapters of this book describe how the ATMI calls are used in writing and debugging clients and services. This chapter provides some of the context within which you will be doing that work.
A client process takes user input and sends it as a service request to a server process that offers the requested service.
A client process uses one ATMI call to join an application, another to send the data structure to a server and still others to receive the reply.
The operation of a basic client process can be summarized by the pseudo-code shown in Listing 10-1.
Introduction
Client Processes
Basic Client Operation
Listing 10-1
Pseudo-code for a Client
START PROGRAM
enroll as a client of the BEA TUXEDO application
place initial client identification in data structure
perform until end
get user input
place user input in DATA-REC
send service request
receive reply
pass reply to the user
end perform
leave application
END PROGRAM
Most of the statements in Listing 10-1 are implemented with ATMI calls. Placing user input in a DATA-REC and passing the reply to the user are implemented with COBOL calls.
When client programs are ready to test, you use the buildclient -C command to compile and link edit them.
A client may send and receive any number of service requests before leaving the application. These can be sent as a series of request/response calls or, if it is important to carry state information from one call to the next, a connection to a conversational server can be set up. The logic within the client program is about the same, but different ATMI calls are used.
Servers are processes that provide one or more services. They continually check their message queue for service requests and dispatch them to the appropriate service subroutines.
Applications combine their service subroutines with the controlling program that the BEA TUXEDO system provides in order to build server processes. This system supplied controlling program is a set of predefined routines. It performs server initialization and termination and places user input in data structures to receive and dispatch incoming requests to service routines. All of this processing is transparent to the application.
Server and a service subroutine interaction can be summarized by the pseudo-code shown in Figure 10-1.
Figure 10-1 Pseudo-code for a Request/Response Server and a Service Subroutine
After some initialization a server waits until a request message is put on its message queue, dequeues the request and dispatches it to a service subroutine for processing. If a reply is needed, the reply is considered part of request processing.
The conversational paradigm is somewhat different. Pseudo-code is shown in Figure 10-2.
Figure 10-2 Pseudo-code for a Conversational Service Subroutine
The BEA TUXEDO system-supplied controlling program contains the code needed to enroll as a server, advertise services and dequeue request messages. The ATMI calls are used in service subroutines that process requests. When they are ready to compile and test, service subroutines are link edited with the server by means of the buildserver -C command to form an executable server.
The serially reusable architecture of servers is particularly significant if the operation requested by the user is logically divisible into several services, or several iterations of the same service. Such operations can be overlapped by having a server assume the role of a client and hand off part of the task to another server as part of fulfilling the original client's request. In such a capacity the server becomes a requester. Both clients and servers can be requesters. In fact, a client can only be a requester. The coding model for such a system is easily accomplished with the routines that are provided by ATMI.
A request/response server can also forward a request to another server. This is different from becoming a requester. In this case, the server does not assume the role of client since no reply is expected by the server that forwards a request. The reply is expected by the original client.
The Application-Transaction Monitor Interface is a reasonably compact set of calls used to open and close resources, begin and end transactions, and provide the communication between clients and servers. Table 10-1 summarizes them. Each routine is documented on its own page in the BEA TUXEDO Reference Manual.
In addition to ATMI's transaction management verbs, BEA TUXEDO also supports X/Open's TX Interface for defining and managing transactions. Because X/Open used ATMI's transaction demarcation verbs as the base for the TX Interface, the syntax and semantics of the TX Interface are quite similar to ATMI.
Table 10-2 introduces the routines in the TX Interface and highlights the main differences with their corresponding ATMI routines. For maximum portability, the TX routines can be used in place of the ATMI routines shown in Table 10-1.
An Overview of X/Open's TX Interface
There are two points to keep in mind when using the TX Interface. First, the TX interface requires that The second rule concerns the default Listing 10-2 is an example of how the TX Interface can be used to support chained transactions. Note that TXOPEN be called before using any other TX verbs. Thus, even if a client or a server is not accessing an XA-compliant resource manager, it must call TXOPEN before it can use TXBEGIN, TXCOMMIT, and TXROLLBACK to define transactions.
TPSVRINIT and TPSVRDONE routines provided with BEA TUXEDO. If an application writer wants to use the TX Interface in service routines, then the default BEA TUXEDO system TPSVRINIT and TPSVRDONE routines should not be used. This is because these routines call TPOPEN and TPCLOSE which would preclude the use of TX verbs in service routines. Thus, application writers should supply their own TPSVRINIT and TPSVRDONE routines that call TXOPEN and TXCLOSE.
TXBEGIN must be used to start the first of a series of chained transactions. Also, note that before calling TXCLOSE, the application must switch to unchained transactions so that the last TXCOMMIT or TXROLLBACK does not start a new transaction.
Listing 10-2
Chained Transaction Example
CALL "TXOPEN" USING TX-RETURN-STATUS.
SET TXCHAINED TO TRUE.
CALL "TXSETTRANCTL" USING TX-INFO-AREA
TX-RETURN-STATUS.
MOVE 120 TRANSACTION-TIMEOUT.
CALL "TXSETTIMEOUT" USING TX-INFO-AREA
TX-RETURN-STATUS.
do forever
do work as part of transaction.
if no more work exists
SET TXCHAINED TO FALSE.
CALL "TXSETTRANCTL" USING TX-INFO-AREA
TX-RETURN-STATUS.
if work done was successful
CALL "TXCOMMIT" USING TX-RETURN-STATUS.
else
CALL "TXROLLBACK" USING TX-RETURN-STATUS.
if no more work exists
leave
end do
CALL "TXCLOSE" USING TX-RETURN-STATUS.
Messages are passed to servers in typed records, actually pairs of records. Why "typed?" Well, different types of data require different software to initialize the record, send and receive the data and perhaps encode and decode it, if the record is passed between heterogeneous machines. Records are designated as being of a specific type so the routines appropriate to the record and its contents can be invoked. These issues are typically not of concern to application developers, but more details can be found in buffer(3c), tuxtypes(5), and typesw(5) in the BEA TUXEDO Reference Manual.
BEA TUXEDO provides eight record types for messages: STRING, CARRAY, VIEW, VIEW32, X_OCTET, X_COMMON, FML, and FML32. Applications can define additional types as needed. Consult the manual pages referred to above and Administering the BEA TUXEDO System.
The STRING record type allows an arbitrary number of characters which may not contain LOW-VALUE characters anywhere within the record but could be at the end of the record. When sending data, LEN IN TPTYPE-REC must contain the number of bytes to be transferred.
The data in a CARRAY record type allows an arbitrary number of characters which may contain LOW-VALUE characters. When sending data, LEN IN TPTYPE-REC must contain the number of bytes to be transferred. The X_OCTET record type is equivalent to CARRAY.
The VIEW type is a COBOL data structure that the application defines and for which there has to be a view description file. Records of the VIEW type must have subtypes, that designate individual data structures. The X_COMMON record type is similar to VIEW but is used for both COBOL and C programs so field types should be limited to PIC S9(4) COMP-5, PIC S9(9) COMP-5, and PIC X(any-length). The VIEW32 record type is similar to VIEW but allows for larger character fields, more fields, and larger overall records.
An FML record is a proprietary BEA TUXEDO system type of self-defining buffer where each data field carries its own identifier, an implied occurrence number and possibly a length indicator. This type provides great flexibility at the expense of some processing overhead in that all data manipulation is done via FML function calls. The FML function calls are not available from COBOL. COBOL procedures are provided with procedures to initialize an FML record, and convert FML records to/from VIEW records. This is used primarily for applications that have COBOL programs communicating with C programs that use FML records.
If you are using the VIEW or FML buffer types, some preliminary work is required to create view description files or field table files. In the case of VIEWs, a description file must exist and must be available to client and server processes that use a data structure described in the VIEW. The BEA TUXEDO system view compiler program, viewc, is used with the -C option to produce one or more COBOL COPY files (one per view) from a source viewfile. These COPY files contain Data Description Records, which may be used in the LINKAGE SECTION or the WORKING STORAGE section of the DATA DIVISION according to the demands of the program.
For FML buffers, a field table file containing descriptions of all fields that may be in the buffer must be available.
There are two kinds of VIEW buffers. One is based on an FML buffer. The other VIEW buffer is independent; it is simply a C structure. Both types are described in view description files and compiled with viewc(1), the BEA TUXEDO system view compiler. We're going to talk first about the FML variety.
BEA TUXEDO system FML is a family of functions some of which convert an FML buffer into a COBOL record or vice versa. The COBOL record that is derived from the fielded buffer is referred to as an FML VIEW. FML buffers must be converted to COBOL records for manipulation since the FML are functions not available to COBOL programs. The VIEW is then converted back into an FML buffer for message transmission to a C program that expects an FML buffer.
There are slight differences between a view description of an FML-based view and one that is independent of FML. Listing 10-3 shows a view description file with all of the available data types. Note that the CARRAY1 field has a count of two occurrences and has the "C" count flag to indicate that an additional count element should be created in the record so the application can indicate how many of the occurrences are actually being used. It also has the "L" length flag such that there is a length element (which occurs twice, once for each occurrence of the field) indicating how many of the characters the application has populated.
Listing 10-3 View Description File for FML View
VIEW MYVIEW
$/* View structure */
#type cname fbname count flag size null
float float1 FLOAT1 1 - - 0.0
double double1 DOUBLE1 1 - - 0.0
long long1 LONG1 1 - - 0
short short1 SHORT1 1 - - 0
int int1 INT1 1 - - 0
dec_t dec1 DEC1 1 - 9,16 0
char char1 CHAR1 1 - - '\0'
string string1 STRING1 1 - 20 '\0'
carray carray1 CARRAY1 2 CL 20 '\0'
END
Field table files are always required when using FML records, including the use of FML-dependent VIEWS. A field table file maps the logical name of a field in an FML buffer to a field identifier that uniquely identifies the field.
An example that could be used with the view shown in Listing 10-3 is shown in Listing 10-4.
Listing 10-4 The myview.flds Field Table File
# name number type flags comments
FLOAT1 110 float - -
DOUBLE1 111 double - -
LONG1 112 long - -
SHORT1 113 short - -
INT1 114 long - -
DEC1 115 string - -
CHAR1 116 char - -
STRING1 117 string - -
CARRAY1 118 carray - -
Listing 10-5 shows the view description file, similar to the example in Listing 10-3, but for a VIEW independent from FML.
Listing 10-5 View Description File for Independent Views
$/* View data structure */
VIEW MYVIEW
#type cname fbname count flag size null
float float1 - 1 - - -
double double1 - 1 - - -
long long1 - 1 - - -
short short1 - 1 - - -
int int1 - 1 - - -
dec_t dec1 - 1 - 9,16 -
char char1 - 1 - - -
string string1 - 1 - 20 -
carray carray1 - 2 CL 20 -
END
Note that in this view description, the format is similar to the FML-dependent view, except that the columns fbname and null in the file are ignored by the view compiler. These columns are not relevant when an FML buffer does not stand behind the view, but it is necessary to place some value (a dash, for example) in these columns to serve as a placeholder.
The COBOL application programmer should define float and double fields in the application as COMP-1 and COMP-2, respectively.
The UNIX field types long and short correspond to S9(9) COMP-5 and S9(4) COMP-5 respectively in COBOL (the use of COMP-5 is for use with MicroFocus COBOL so that the COBOL integer fields match the data format of the corresponding C fields; the data type for VS COBOL II would simply be COMP).
The dec_t type maps to a COBOL COMP-3 packed decimal field. Packed decimals exist in the COBOL environment as two decimal digits packed into each byte with the low-order half byte used to store the sign. The length of a packed decimal may be 1 to 9 bytes with storage available for 1 to 17 digits and a sign. The dec_t field type is supported within the VIEW definition for the conversion of packed decimals between the C and the COBOL environments. The dec_t field is defined in a VIEW with a size of two numbers separated by a comma. The number to the left of the comma is the total number of bytes that the decimal occupies in COBOL. The number to the right is the number of digits to the right of the decimal point in COBOL. The formula for conversion to the COBOL declaration is:
dec_t(m, n) => S9(2*m-(n+1),n)COMP-3
For example, say a size of 6,4 is specified in the VIEW. There are 4 digits to the right of the decimal point, 7 digits to the left and the last half byte stores the sign. The COBOL application programmer would represent this as 9(7)V9(4), with the V representing the decimal point between the number of digits to each side. Note that there is no dec_t type supported in FML; if FML-dependent VIEWs are used, then the field must be mapped to a C type in the VIEW file (for instance, the packed decimal can be mapped to an FML string field and the mapping functions do the conversion between the formats).
View description files are source files. To use the VIEW in a program, you need a COBOL COPY file that defines the data structures in the view. You can create a COBOL COPY file from the myview.v view description file by invoking the view compiler, viewc.
viewc -C -n myview.v
Note that the -n option is specified only if the VIEW is independent of any FML definition. viewc -C creates three files. One is the COBOL COPY file, MYVIEW.cbl, another is the header file, myview.h, for C routines that share the same view, and the other is the binary version of the source description file, myview.V. This binary file must be in the environment when a VIEW record is defined.
The COBOL COPY file created from myview.v is shown in Listing 10-6.
Listing 10-6 Resulting MYVIEW COBOL Copy File
* VIEWFILE: "myview.v"
* VIEWNAME: "MYVIEW"
05 FLOAT1 USAGE IS COMP-1.
05 DOUBLE1 USAGE IS COMP-2.
05 LONG1 PIC S9(9) USAGE IS COMP-5.
05 SHORT1 PIC S9(4) USAGE IS COMP-5.
05 FILLER PIC X(02).
05 INT1 PIC S9(9) USAGE IS COMP-5.
05 DEC1.
07 DEC-EXP PIC S9(4) USAGE IS COMP-5.
07 DEC-POS PIC S9(4) USAGE IS COMP-5.
07 DEC-NDGTS PIC S9(4) USAGE IS COMP-5.
* DEC-DGTS is the actual packed decimal value
07 DEC-DGTS PIC S9(1)V9(16) COMP-3.
07 FILLER PIC X(07).
05 CHAR1 PIC X(01).
05 STRING1 PIC X(20).
05 FILLER PIC X(01).
05 L-CARRAY1 OCCURS 2 TIMES PIC 9(4) USAGE IS COMP-5.
* LENGTH OF CARRAY1
05 C-CARRAY1 PIC S9(4) USAGE IS COMP-5.
* COUNT OF CARRAY1
05 CARRAY1 OCCURS 2 TIMES PIC X(20).
05 FILLER PIC X(02).
COBOL COPY files for views must be brought into client programs and service subroutines with COPY statements. In Listing 10-6 note that there are some FILLER fields. These are created by the view compiler so that the alignment of fields in COBOL matches the alignment in C. Also, note the format of the packed decimal value, DEC1. It is composed of 5 fields; the DEC-EXP, DEC-POS, DEC-NDGTS and FILLER fields are used only in C (they are defined in the dec_t type) but are included in the COBOL record for filler; they should not be used by the COBOL application programmer. The actual packed decimal value is stored in the DEC-DGTS value; this is the value that should be set and/or accessed by the COBOL programmer. All of the ATMI primitives take care of correctly populating the DEC-DGTS in packed decimal format before the record is passed to the COBOL program from a C program, and convert back to the dec_t type when passed from the COBOL program to a C program. The only restriction is that a COBOL program cannot directly pass the record to a C function without going through the ATMI interface (the decimal formats won't match).
Also note that there is an L-CARRAY1 length field that occurs twice, once for each occurrence of CARRAY1 and there is also the C-CARRAY1 count field.
viewc also creates a C version of the header file which can be used if an application desires to mix C and COBOL service and/or client programs.
The FML function interface consists of about eighty 16-bit primitives and the same number for FML32. This interface was designed for use with the C language. Instead of providing a COBOL version of this interface, COBOL procedures are provided to convert a received FML buffer to a COBOL record for processing, and then convert the record back to FML.
If a COBOL client or server is the originator of an FML message, the record must be initialized using the FINIT procedure. FINIT takes the FML record (suitably aligned on a full-word boundary) and FML-LENGTH in an FMLINFO record which is set to length of the FML record. The initialization is shown in Listing 10-7. If an FML record is received in a program, it is automatically initialized (unless TPNOCHANGE is set). That means that if a program first receives an FML record instead of being the originator of the message, it is unnecessary to call FINIT.
Listing 10-7 FML/VIEW Conversion
WORKING-STORAGE SECTION.
*RECORD TYPE AND LENGTH
01 TPTYPE-REC.
COPY TPTYPE.
*STATUS OF CALL
01 TPSTATUS-REC.
COPY TPSTATUS.
* SERVICE CALL FLAGS/RECORD
01 TPSVCDEF-REC.
COPY TPSVCDEF.
* TPINIT FLAGS/RECORD
01 TPINFDEF-REC.
COPY TPINFDEF.
* FML CALL FLAGS/RECORD
01 FML-REC.
COPY FMLINFO.
*
*
* APPLICATION FML RECORD - ALIGNED
01 MYFML.
05 FBFR-DTA OCCURS 100 TIMES PIC S9(9) USAGE IS COMP-5.
* APPLICATION VIEW RECORD
01 MYVIEW.
COPY MYVIEW.
.....
* MOVE DATA INTO MYVIEW
.....
* INITIALIZE FML RECORD
MOVE LENGTH OF MYFML TO FML-LENGTH.
CALL "FINIT" USING MYFML FML-REC.
IF NOT FOK
MOVE "FINIT Failed" TO LOGMSG-TEXT
PERFORM DO-USERLOG
PERFORM EXIT-PROGRAM
END-IF.
* Convert VIEW to FML Record
SET FUPDATE TO TRUE.
MOVE "MYVIEW" TO VIEWNAME.
CALL "FVSTOF" USING MYFML MYVIEW FML-REC.
IF NOT FOK
MOVE "FVSTOF Failed" TO LOGMSG-TEXT
PERFORM DO-USERLOG
PERFORM EXIT-PROGRAM
END-IF.
* CALL THE SERVICE USING THE FML RECORD
MOVE "FML" TO REC-TYPE IN TPTYPE-REC.
MOVE SPACES TO SUB-TYPE IN TPTYPE-REC.
MOVE LENGTH OF MYFML TO LEN.
CALL "TPCALL" USING TPSVCDEF-REC
TPTYPE-REC
MYFML
TPTYPE-REC
MYFML
TPSTATUS-REC.
IF NOT TPOK
MOVE "TPCALL MYFML Failed" TO LOGMSG-TEXT
PERFORM DO-USERLOG
PERFORM EXIT-PROGRAM
END-IF.
* CONVERT THE FML RECORD BACK TO MYVIEW
CALL "FVFTOS" USING MYFML MYVIEW FML-REC.
IF NOT FOK
MOVE "FVFTOS Failed" TO LOGMSG-TEXT
PERFORM DO-USERLOG
PERFORM EXIT-PROGRAM
END-IF.
The FVSTOF procedure is used to convert an FML record to a VIEW record. The view is defined by including the copy file generated by the view compiler. The FML-REC record provides the VIEWNAME and the FML-MODE transfer mode which can be set to FUPDATE, FOJOIN FJOIN or FCONCAT. The actions of these modes are the same as those described in Fupdate(3fml), Fojoin(3fml), Fjoin(3fml), and Fconcat(3fml).
The FVFTOS procedure is used to convert a VIEW record into an FML record. The parameters are the same as for FVSTOF procedure but the FML-MODE need not be set. Fields are copied from the fielded buffer into the structure based on the element descriptions in the view. If a field in the fielded buffer has no corresponding element in the COBOL record, it is ignored. If an element specified in the COBOL record has no corresponding field in the fielded buffer, a null value is copied into the element. The null value used is definable for each element in the view description. To store multiple occurrences in the COBOL record, the record element should be defined with OCCURS. If the buffer has fewer occurrences of the field than there are occurrences of the element, the extra element slots are assigned null values. On the other hand, if the buffer has more occurrences of the field than there are occurrences of the element, the surplus occurrences are ignored.
For FML32 and VIEW32, the FINIT32, FVSTOF32, and FVFTOS32 procedures should be used.
Upon successful completion, FML-STATUS is set to FOK. On error, FML-STATUS is set to a non-zero value (see the reference manual pages).
Environment variables needed either for clients or service routines associated with a server can be set in ENVFILEs that are specified in the configuration file. The environment variables, for example, that need to be set for view descriptions are summarized in Table 10-3.
For the The Set The location of the BEA TUXEDO system binary files must be known to your application. It is the convention to install the BEA TUXEDO system software under a root directory whose location is specified in the The configuration file specifies the configuration of an application to the BEA TUXEDO system. For a BEA TUXEDO system application in production, it is the responsibility of the BEA TUXEDO administrator to set up a configuration file that defines the application. In the development environment, the responsibility may be delegated to application programmers to create their own.
If you are faced with the task of creating a configuration file, here are some suggestions:
FML32 and VIEW32 record types, the environment variables are suffixed with "32," that is, FLDTBLDIR32, FIELDTBLS32, VIEWFILES32, and VIEWDIR32.
ALTCC and ALTCFLAGS environment variables are used by the buildclient and buildserver commands when run with the -C option for COBOL. You may want to set them in your environment to make compilation of clients and servers more convenient. Set ALTCC to the command that invokes the COBOL compiler. It defaults to cobcc. Set ALTCFLAGS to the link edit flags you may want to use on the compile command line. Setting these variables are optional.
COBOPT to the arguments you may want to use on the compile command line. This variable is also optional. Set COBCPY to the directories that contain a set of the COBOL COPY files to be used by the compiler. Set COBDIR to the directory that contains the COBOL compiler software.
TUXDIR environment variable. $TUXDIR/bin must be included in your PATH in order for your application to locate the executables for BEA TUXEDO system commands.
Configuration File
ubbshm that comes with the sample application is a good starting point.
UID and GID parameters so that you are the owner of the configuration.
The configuration file is an ASCII file. To make it usable, you have to run The bulletin board is the BEA TUXEDO system name for a group of data structures in a segment of shared memory that is allocated from information stored in All processes that are part of a BEA TUXEDO application share this UNIX shared memory.
Execute the When it is time to bring the application down, execute the Making the Configuration Usable
tmloadcf(1) to convert it to a binary file. The TUXCONFIG environment variable must be set to the pathname for the binary file, and exported.
The Bulletin Board
TUXCONFIG when the application is booted. Both client and server processes attach to the bulletin board. Part of the bulletin board associates service names with the queue address of servers that advertise that service. Clients send their requests to the name of the service they want to invoke, rather than to a specific address.
Starting and Stopping an Application
tmboot(1) command to bring up an application. The command gets the IPC resources needed by the application, starts administrative processes and the application servers.
tmshutdown(1) command. tmshutdown stops the servers and releases the IPC resources used by the application, except any that might be used by the database resource manager.