Programming a Tuxedo Application Using COBOL

Introduction to BEA Tuxedo Programming

This topic includes the following sections:

BEA Tuxedo Distributed Application Programming

A distributed application consists of a set of software modules that reside on multiple hardware systems, and that communicate with one another to accomplish the tasks required of the application. For example, as shown in the following figure, a distributed application for a remote online banking system includes software modules that run on a bank customer's home computer, and a computer system at the bank on which all bank account records are maintained.

Figure 1-1 Distributed Application Example - Online Banking System

Distributed Application Example - Online Banking System

The task of checking an account balance, for example, can be performed simply by logging on and selecting an option from a menu. Behind the scenes, the local software module communicates with the remote software module using special application programming interface (API) routines.

The BEA Tuxedo distributed application programming environment provides the API routines necessary to enable secure, reliable communication between the distributed software modules. This API is referred to as the Application-to-Transaction Monitor Interface (ATMI).

The ATMI enables you to:

Send and receive messages between clients and servers, possibly across a network of heterogeneous machines
Establish and use client naming and security features
Define and manage transactions in which data may be stored in several locations
Generically open and close a resource manager such as a Database Management System (DBMS)
Manage the flow of service requests and the availability of servers to process them

Communication Paradigms

The following table describes the BEA Tuxedo ATMI communication paradigms available to application developers.

Table 1-1 Communication Paradigms

Paradigm	Description
Request/response communication	Request/response communication enables one software module to send a request to a second software module and wait for a response. Can be synchronous (processing waits until the requester receives the response) or asynchronous (processing continues while the requester waits for the response). This mode is also referred to as client/server interaction. The first software module assumes the role of the client; the second, of the server. Refer to Writing Request/Response Clients and Servers for more information on this paradigm.
Conversational communication	Conversational communication is similar to request/response communication, except that multiple requests and/or responses need to take place before the "conversation" is terminated. With conversational communication, both the client and the server maintain state information until the conversation is disconnected. The application protocol that you are using governs how messages are communicated between the client and server. Conversational communication is commonly used to buffer portions of a lengthy response from a server to a client. Refer to Writing Conversational Clients and Servers for more information on this paradigm.
Application queue-based communication	Application queue-based communication supports deferred or time-independent communication, enabling a client and server to communicate using an application queue. The BEA Tuxedo/Q facility allows messages to be queued to persistent storage (disk) or to non-persistent storage (memory) for later processing or retrieval. For example, application queue-based communication is useful for enqueuing requests when a system goes offline for maintenance, or for buffering communications if the client and server systems are operating at different speeds. Refer to Using the ATMI /Q Component for more information on the /Q facility.
Event-based communication	Event-based communication allows a client or server to notify a client when a specific situation (event) occurs. Events are reported in one of two ways: Unsolicited events are unexpected situations that are reported by clients and/or servers directly to clients. Brokered events are unexpected situations or predictable occurrences with unpredictable timeframes that are reported by servers to clients indirectly, through an "anonymous broker" program that receives and distributes messages. Event-based communication is based on the BEA Tuxedo EventBroker facility. Refer to Writing Event-based Clients and Servers for more information on this paradigm.

BEA Tuxedo Clients

A BEA Tuxedo ATMI client is a software module that collects a user request and forwards it to a server that offers the requested service. Almost any software module can become a BEA Tuxedo client by calling the ATMI client initialization routine and "joining" the BEA Tuxedo application. The client can then exchange information with the server.

The client calls the ATMI termination routine to "leave" the application and notify the BEA Tuxedo system that it (the client) no longer needs to be tracked. Consequently, BEA Tuxedo application resources are made available for other operations.

The operation of a basic client process can be summarized by the pseudo-code shown in the following listing.

Listing 1-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 actions described in the above listing are implemented with ATMI calls. Others—placing the user input in DATA-REC and passing the reply to the user—are implemented with COBOL routines.

An ATMI client may send and receive any number of service requests before leaving the application. The client may send these requests as a series of request/response calls or, if it is important to carry state information from one call to the next, by establishing a connection to a conversational server. In both cases, the logic in the client program is similar, but different ATMI calls are required for these two approaches.

Before you can execute an ATMI client, you must run the buildclient -C command to compile it and link it with the BEA Tuxedo ATMI and required libraries. Refer to Writing Clients for information on the buildclient(1) command.

BEA Tuxedo Servers

A BEA Tuxedo ATMI server is a process that provides one or more services to a client. A service is a specific business task that a client may need to perform. Servers receive requests from clients and dispatch them to the appropriate service subroutines.

Basic Server Operation

To build server processes, applications combine their service subroutines with a controlling program provided by the BEA Tuxedo system. This system-supplied controlling program is a set of predefined routines. It performs server initialization and termination and places user input in data structures that can be used to receive and dispatch incoming requests to service routines. All of this processing is transparent to the application.

The following figure summarizes, in pseudo-code, the interaction between a server and a service subroutine.

Figure 1-2 Pseudo-code for a Request/Response Server and a Service Subroutine

Pseudo-code for a Request/Response Server and a Service Subroutine

After initialization, an ATMI waits until a request message is delivered to its message queue, dequeues the request, and dispatches it to a service subroutine for processing. If a reply is required, the reply is considered part of request processing.

The conversational paradigm is somewhat different from request/response, as illustrated by the pseudo-code in the following figure.

Figure 1-3 Pseudo-code for a Conversational Service Subroutine

Pseudo-code for a Conversational Service Subroutine

The BEA Tuxedo system-supplied controlling program contains the code needed to enroll a process as an ATMI server, advertise services, and dequeue requests. ATMI calls are used in service subroutines that process requests. When you are ready to compile and test your service subroutines, you must link edit them with the server and generate an executable server. To do so, run the buildserver -C command.

Servers as Requesters

If a client requests several services, or several iterations of the same service, a subset of the services might be transferred to another server for execution. In this case, the server assumes the role of a client, or requester. Both clients and servers can be requesters; a client, however, can only be a requester. This coding model is easily accomplished using the BEA Tuxedo ATMI calls.

Note: A request/response server can also forward a request to another server. In this case, the server does not assume the role of client (requester) because the reply is expected by the original client, not by the server forwarding the request.

BEA Tuxedo API: ATMI

In addition to the COBOL code that expresses the logic of your application, you must use the Application-to-Transaction Monitor Interface (ATMI), the interface between your application and the BEA Tuxedo system.

The ATMI is a reasonably compact set of calls used to open and close resources, begin and end transactions, and support communication between clients and servers. The following table summarizes the ATMI calls. Each call is described in the BEA Tuxedo ATMI COBOL Function Reference.

Table 1-2 Using the ATMI Calls

For a Task Related to . . .	Use This COBOL Function . . .	To . . .	For More Information, Refer to . . .
Client membership	`TPINITIALIZE`	Have a client join an application	Writing Clients
Client membership	`TPTERM`	Have a client leave an application	Writing Clients
Multiple application context management	TPGETCTXT(3cbl)	Retrieve an identifier for the current threads context	Programming a Multithreaded and Multicontexted ATMI Application
Multiple application context management	TPSETCTXT(3cbl)	Set the current thread's context in a multicontexted process
Service entry and return	`TPSVCSTART`	Get service information	Writing Servers
	`TPSVRINIT`	Initialize a server
	`TPSVRDONE`	Terminate a server
	`TPRETURN`	End a service routine
	`TPFORWAR`	Forward a request
Dynamic advertisement	`TPADVERTISE`	Advertise a service name	Writing Servers
Dynamic advertisement	`TPUNADVERTISE`	Unadvertise a service name	Writing Servers
Message priority	`TPGPRIO`	Get the priority of the last request	Writing Servers
Message priority	`TPSPRIO`	Set the priority of the next request	Writing Servers
Request/Response communications	`TPCALL`	Initiate a synchronous request/response to a service	Writing Servers Writing Request/Response Clients and Servers
	`TPACALL`	Initiate an asynchronous request (fanout)
	`TPGETRPLY`	Receive an asynchronous response
	`TPCANCEL`	Cancel an asynchronous request
Conversational communications	`TPCONNECT`	Begin a conversation with a service	Writing Conversational Clients and Servers
	`TPDISCON`	Abnormally terminate a conversation
	`TPSEND`	Send a message in a conversation
	`TPRECV`	Receive a message in a conversation
Reliable queuing	TPENQUEUE(3cbl)	Enqueue a message to a message queue	Using the ATMI /Q Component
Reliable queuing	TPDEQUEUE(3cbl)	Dequeue a message from a message queue	Using the ATMI /Q Component
Event-based communications	`TPNOTIFY`	Send an unsolicited message to a client	Writing Event-based Clients and Servers
	`TPBROADCAST`	Send messages to several clients
	`TPSETUNSOL`	Set unsolicited message call-back
	`TPCHKUNSOL`	Check the arrival of unsolicited messages
	`TPGETUNSOL`	Get an unsolicited message
	`TPPOST`	Post an event message
	`TPSUBSCRIBE`	Subscribe to event messages
	`TPUNSUBSCRIBE`	Unsubscribe to event messages
Transaction management	`TPBEGIN`	Begin a transaction	Writing Global Transactions
	`TPCOMMIT`	Commit the current transaction
	`TPABORT`	Roll back the current transaction
	`TPGETLEV`	Check whether in transaction mode
Resource management	TPOPEN(3cbl)	Open a resource manager	Programming a Multithreaded and Multicontexted ATMI Application Getting Started with BEA Tuxedo CORBA Applications
Resource management	TPCLOSE(3cbl)	Close a resource manager
Nontransactional blocking time management	TPGBLKTIME(3cbl)	Get blocktime value	BEA Tuxedo ATMI COBOL Function Reference
Nontransactional blocking time management	TPSBLKTIME(3cbl)	Set blocktime value in seconds	BEA Tuxedo ATMI COBOL Function Reference
Security	TPKEYOPEN(3cbl)	Open a key handle for digital signature generation, message encryption, or message decryption	Using Security in CORBA Applications
	TPKEYGETINFO(3cbl)	Get information associated with a key handle
	TPKEYSETINFO(3cbl)	Set optional attributes associated with a key handle
	TPKEYCLOSE(3cbl)	Close a key handle previously opened using `TPKEYOPEN`