Programming an Oracle Tuxedo ATMI Application Using C

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Introduction to Oracle Tuxedo Programming

This topic includes the following sections:

 


Oracle 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 Figure 1-1, 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) functions.

The Oracle Tuxedo distributed application programming environment provides the API functions 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:

 


Communication Paradigms

Table 1-1 describes the Oracle Tuxedo ATMI communication paradigms available to application developers.

Table 1-1 Communication Paradigms
Paradigm
Description
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 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 Oracle 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 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 Oracle Tuxedo EventBroker facility.
Refer to Writing Event-based Clients and Servers for more information on this paradigm.

 


Oracle Tuxedo Clients

An Oracle 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 an Oracle Tuxedo client by calling the ATMI client initialization routine and “ joining” the Oracle Tuxedo application. The client can then allocate message buffers and exchange information with the server.

The client calls the ATMI termination routine to “ leave” the application and notify the Oracle Tuxedo system that it (the client) no longer needs to be tracked. Consequently, Oracle 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 Request/Response Client
main()
 {
       allocate a TPINIT buffer
       place initial client identification in buffer
       enroll as a client of the BEA Tuxedo application
       allocate buffer
       do while true {
             place user input in buffer
             send service request
             receive reply
             pass reply to the user }
       leave application
 }

Most of the actions described in the above listing are implemented with ATMI functions. Others—placing the user input in a buffer and passing the reply to the user—are implemented with C language functions.

During the “allocate buffer” phase, the client program allocates a memory area, called a typed buffer, from the Oracle Tuxedo run-time system. A typed buffer is simply a memory buffer with an associated format, for example, a C structure.

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 functions are required for these two approaches.

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

 


Oracle Tuxedo Servers

An Oracle 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 main() process provided by the Oracle Tuxedo system. This system-supplied main() is a set of predefined functions. It performs server initialization and termination and allocates buffers that can be used to receive and dispatch incoming requests to service routines. All of this processing is transparent to the application.

Figure 1-2 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 server allocates a buffer, 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 Figure 1-3.

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

Pseudo-code for a Conversational Service Subroutine

The Oracle Tuxedo system-supplied main() process contains the code needed to enroll a process as an ATMI server, advertise services, allocate buffers, and dequeue requests. ATMI functions 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 main() and generate an executable server. To do so, run the buildserver 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 Oracle Tuxedo ATMI functions.

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.

 


Oracle Tuxedo API: ATMI

In addition to the C 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 Oracle Tuxedo system. The ATMI functions are C language functions that resemble operating system calls. They implement communication among application modules running under the control of the Oracle Tuxedo system transaction monitor, including all the associated resources you need.

The ATMI is a reasonably compact set of functions used to open and close resources, begin and end transactions, allocate and free buffers, and support communication between clients and servers. Table 1-2 summarizes the ATMI functions. Each function is described in the Oracle Tuxedo ATMI C Function Reference.

Table 1-2 Using the ATMI Function
For a Task
Related to . . .
Use This C Function . . .
To . . .
For More Information,
Refer to . . .
Buffer management
Create a message buffer
Resize a message buffer
Get a message type and subtype
Free a message buffer
Client membership
Check whether authentication is required
Join an application
Leave an application
Multiple application context management
Retrieve an identifier for the current thread’s context
Set the current thread’s context in a multicontexted process
Service entry and return
Initialize a server
Terminate a server
Initialize an individual server thread
Termination code for an individual server thread
End a service function
Forward a request
Dynamic advertisement
Advertise a service name
Unadvertise a service name
Message priority
Get the priority of the last request
Set the priority of the next request
Request/response communications
Initiate a synchronous request/response to a service
Initiate an asynchronous request
Receive an asynchronous response
Cancel an asynchronous request
Conversational communication
Begin a conversation with a service
Abnormally terminate a conversation
Send a message in a conversation
Receive a message in a conversation
Reliable queuing
Enqueue a message to a message queue
Using the ATMI /Q Component
Dequeue a message from a message queue
Event-based communications
Send an unsolicited message to a client
Send messages to several clients
Set unsolicited message call-back
Check the arrival of unsolicited messages
Post an event message
Subscribe to event messages
Unsubscribe to event messages
Transaction management
Begin a transaction
Commit the current transaction
Roll back the current transaction
Check whether in transaction mode
Suspend the current transaction
Resume a transaction
Resource management
Open a resource manager
Setting Up an Oracle Tuxedo Application
Close a resource manager
Blocking time management
Get blocktime value
Oracle Tuxedo ATMI C Function Reference
Set blocktime value in seconds
Security
Open a key handle for digital signature generation, message encryption, or message decryption
Using Security in CORBA Applications
Get information associated with a key handle
Set optional attributes associated with a key handle
Close a previously opened handle
Mark a typed message buffer for generation of a digital signature
Mark a typed message buffer for generation of an encryption envelope
Access the digital signature and recipient information associated with a typed message buffer
Convert a typed message buffer into an exportable, machine-independent (externalized) string representation
Convert an externalized string representation back into a typed message buffer


  Back to Top       Previous  Next