Chapter 2 . Understanding How BEA Connect TPS Works

To understand how Connect TPS works, you need to understand how it performs the following functions:

• Initializes during the BEA TUXEDO booting procedure

• Handles service requests

• Shuts down

Each of these operations is described in the following subsections.

Initializing Connect TPS

When you boot BEA TUXEDO software using the tmboot command, Connect TPS initializes in the following manner.

1. Connect TPS parses the TPSINIT configuration file and initializes all parameters. If syntax errors are encountered during parsing, Connect TPS writes a message to the ULOG file and initialization fails.

2. After reading the TPSINIT file, Connect TPS advertises remote services that are named in the file dynamically. This includes services for all remote gateways. The standard BEA TUXEDO administration service for gateways, GATE_ADMIN, is also advertised.

   Note: Because of its monitoring responsibilities, the Liaison (TPSL) must be configured so that it boots before Requesters (TPSR) boot. The simple way to accomplish this is to list the Liaison above Requesters in the UBBCONFIG file. Alternatively, you can use the SEQUENCE parameter.

When Connect TPS receives a BEA TUXEDO service request from a local client program, it processes the request in the following manner.

Step 1: Receiving a Service Request from BEA TUXEDO Software

When a client program sends a request for a remote service that is accessible through Connect TPS, BEA TUXEDO invokes the server that offers the requested service.

In this case, the server it invokes is TPSR-the Connect TPS Requester. The Requester is responsible for sending requests to remote systems and returning replies to callers.

Step 2: Connecting to a Remote System

If no connection to the target remote system exists or an existing connection has been broken, the Connect TPS Requester opens a new connection at this time.

If the remote system returns a connection failure indication, the BEA TUXEDO service request fails and an error is returned to the caller. The actual error value returned depends on the timing of the connection failure. Information about failures is logged to the ULOG file.

Step 3: Converting Input Buffer Types

In some circumstances, typed buffers associated with service requests must be converted before service requests can be sent to remote systems. Type conversion involves changing the layout of a buffer to a format that is acceptable to a remote service.

For example, if a local client program places user input in an FML buffer that a remote service cannot process, the buffer must be converted into the structure the remote service expects.

In situations where input type conversion is required, programmers or administrators must perform the following tasks:

• Determine the format of the input data the remote service expects.

• If necessary, create a VIEW definition that describes the format of the input data. VIEW definitions are descriptions of data structures that are used for input and output in the BEA TUXEDO environment.

• Specify this information in the Connect TPS configuration file (TPSINIT).

Once these tasks have been completed, Connect TPS performs all necessary type conversions automatically.

For information about creating VIEW definitions to facilitate type conversion, see Chapter 3, "Installing and Getting Ready to Configure BEA Connect TPS". For information about the Connect TPS configuration file, see Chapter 4, "Configuring BEA Connect TPS".

Step 4: Translating Input Data

BEA Connect TPS automatically translates data as required. Translation refers to a change in how intrinsic data types are represented with respect to word length, byte ordering, and character encoding.

To facilitate data translation, administrators must specify certain parameters in the TPSINIT configuration file. See Chapter 3, "Installing and Getting Ready to Configure BEA Connect TPS," for more detailed information about how BEA Connect TPS translates data.

Step 5: Transmitting the Service Request

Connect TPS constructs a request message. This message includes the following items and is sent to the remote system:

• The remote service name

• The input data record that Connect TPS has converted and translated, as required

• An indication of whether or not the remote service should return a reply to the caller

Step 6: Receiving a Reply

After sending a request message, Connect TPS performs a receive operation. If the Connect TPS receive timeout expires before a message arrives from the remote system, a TPETIME error is returned to the caller.

Step 7: Translating the Reply

After Connect TPS receives a reply, data representations are translated as needed, in the reverse of the input translation. See "Step 4: Translating Input Data," in this chapter, for details.

Step 8: Converting Output Data

If the format of the reply is not suitable for the local client program, Connect TPS converts the reply into an appropriate buffer format.

In situations where output conversion is required, programmers or administrators must do the following:

• Determine the type and the format of the output buffer the local client program expects

• If necessary, create a VIEW definition that describes the format of the output buffer

• Specify this information in the Connect TPS configuration file (TPSINIT)

Once these tasks have been completed, Connect TPS performs all necessary conversions automatically.

For information about creating VIEW definitions to facilitate type conversion, see Chapter 3, "Installing and Getting Ready to Configure BEA Connect TPS". For information about the BEA Connect TPS configuration file, see Chapter 4, "Configuring BEA Connect TPS".

Step 9: Sending the Reply to the Caller

The BEA TUXEDO buffer resulting from output type conversion and output data translation is returned to the caller with a TPSUCCESS indication.

How Connect TPS Processes Remote Service Requests

Connect TPS processes remote service requests (those which originate on remote systems) in much the same way that it processes local requests. Here is a brief summary:

1. If no connection with the remote system exists or an existing connection has been broken, the Connect TPS Liaison (TPSL) selects, or if necessary starts, a Handler (TPSH) that will complete the connection.

2. The Handler receives the service request and, if necessary, the input record associated with the request is translated and converted into the specified input buffer format.

3. Acting as a client program, the Handler passes the service request to BEA TUXEDO software.

4. When the service routine terminates, the output buffer is converted into the specified output record format and/or translated (when required).

5. Finally, the output is sent to the Requester on the remote system.

See "How Connect TPS Processes Local Service Requests" on page 2-2 for more detailed information about record and buffer conversion, and data translation.

How Connect TPS Shuts Down

When you send a shutdown request to Connect TPS by using the tmshutdown command, Connect TPS performs the following tasks:

• Completes outstanding requests

• Drops all open connections

• Terminates

Programming Considerations

The following subsections identify various issues that programmers should be aware of when they develop application programs that interoperate with other application programs through Connect TPS.

Introduction

In general, BEA TUXEDO application programs that send requests through Connect TPS are developed just like other BEA TUXEDO application programs.

Connect TPS supports all request/reply communications functions that are included in the ATMI and XATMI interfaces. In addition, all supported functions can be used in the standard manner. In particular,

• All XATMI and ATMI buffer types are supported.

• All system errors are reported in the standard manner.

Input and Output Issues

This subsection explores several input and output issues that programmers need to consider when developing application programs that will use Connect TPS.

Preparing Input and Output Data with Connect TPS

As described in "How Connect TPS Processes Local Service Requests" on page 2-2, there are many circumstances in which it is necessary to convert input and output parameters into formats that are acceptable to remote systems or regions and the local system.

Connect TPS provides powerful configuration capabilities that make it possible for you to convert or map parameters easily rather than requiring you to program in a different way.

The Connect TPS configuration file (TPSINIT) is a centralized mechanism that you can use to define and maintain relationships between the local system and remote systems or regions. In addition to input and output parameter mappings, these relationships include service name mappings (where remote service names are mapped to local service names) and error record mappings.

For more information about the TPSINIT configuration file, see Chapter 3, "Installing and Getting Ready to Configure BEA Connect TPS," and Chapter 4, "Configuring BEA Connect TPS".

Service Request Parameters

BEA TUXEDO application programs must provide input parameters that are acceptable and understandable to remote services. The following are two categories of remote services that BEA TUXEDO application programs can request through BEA Connect TPS:

• Existing application programs that were originally developed for traditional OLTP environments and have been adapted for use with BEA TUXEDO

• Services that were developed specifically for the XATMI or ATMI (BEA TUXEDO) environments. Included in this category are services that reside in remote BEA TUXEDO regions.

If a remote service was developed specifically for the BEA TUXEDO environment, the input it requires is shaped by three factors:

• Application-specific requirements

• Normal ATMI or XATMI requirements for defining and sending input

• Machine-specific requirements for how input is formatted (such as those described in "How Connect TPS Processes Local Service Requests" on page 2-2)

On the other hand, if a remote service is an existing OLTP application program, there are often additional requirements for input. For example, many systems require input that includes terminal data.

Often, by creative use of the Connect TPS configuration capabilities previously introduced, you can eliminate the need to include control information, such as terminal data, in the BEA TUXEDO application source code that you develop. For instance, you can include terminal control codes in VIEW definitions that are associated with the Connect TPS configuration.

For information about the normal input requirements of BEA TUXEDO services, see the BEA TUXEDO Transaction Manager Programming Guide.

Output Data Considerations

To maintain the location transparency of the BEA TUXEDO environment, Connect TPS does not preserve data from BEA TUXEDO input buffers in the associated output buffers. Hence, the consequences of using the same buffer for input and output must be understood to avoid problems.

In particular, some existing BEA TUXEDO applications may use FML buffers to accumulate results or to maintain application context across service requests. Developers adding Connect TPS to such an application must do one of the following:

• Maintain a copy of the necessary data in the client program (or service routine) that makes requests.

• Ensure that the remote service returns input data with the output record.

This requirement is no different from the requirement that existed before the use of Connect TPS. That is, application programs that accumulate output data in FML buffers must ensure that services return replies in original FML input buffers (with output data added)-not in new or re-initialized buffers.

Error Handling

There are three kinds of errors that local application programs can encounter when they send requests through Connect TPS gateways:

• Gateway errors

• Problems on remote systems

• Errors from remote application programs

The following subsections explain how Connect TPS handles these different kinds of errors.

Gateway Errors

When local or remote gateway errors occur, they are logged in the BEA TUXEDO ULOG file and associated service requests fail. Also, appropriate error codes are returned to callers.

Remote System Failures

When remote systems encounter problems, service requests may fail or time out. The exact outcome depends on whether or not the remote system provides a means for Connect TPS to detect failure.

If the remote target system does not make it possible for Connect TPS to detect particular types of failure, the Connect TPS blocking timeout parameter can be tuned to provide timely detection of the problem.

See Chapter 4, "Configuring BEA Connect TPS," for more information about the blocking timeout parameter

Application Errors

Application errors are similar to remote system failures. That is, remote systems may or may not use error indicators to pass information back to the local Connect TPS gateway resulting in the generation of error messages. If no such error indicators exist, service routines typically use their own mechanisms to report failures to callers.

When application errors occur, some service routines may not return their usual output records at all. Instead, they may return some other data indicating that there has been an error, such as a string that contains a failure message.

When Connect TPS receives a service failure message from a remote system, it will:

• Convert the output buffer as required based on instructions it finds in the TPSINIT file

• Write an error record in the ULOG file if the configuration directs it to do so

• Return the appropriate type of BEA TUXEDO buffer to the caller

  Note: When BEA TUXEDO applications detect service failures, they should not assume that returned buffers are the expected type. In practice this may not be an issue, since BEA TUXEDO application programs may ignore return buffers when failures occur. If you need to check a buffer's type, you can use the BEA TUXEDO tptypes() function. Once the type is known, the buffer can be handled accordingly (for example, by displaying a window containing an error string).

Limitations on the Use of Certain ATMI Functions

The ATMI interface includes several features and functions-related primarily to conversations, transactions and client identities-that application programs cannot propagate to other application programs through Connect TPS.

In this guide, permanent limitations of this sort are referred to as operational considerations. Specific operational considerations are described in the following subsections.

Note: In this discussion, a "local" application program is one that resides within the immediate BEA TUXEDO region. A "remote" application program is one that resides outside the immediate BEA TUXEDO region.

Conversational Communication Functions

Conversational communication functions are subject to the following operational considerations.

• Local client and server programs cannot use the tpconnect() function to establish conversations with remote services.

• Remote client and server programs cannot use the tpconnect() function to establish conversations with local services.

• Similarly, the tpsend(), tprecv() and tpdiscon() functions may not be used for communication through Connect TPS.

Non-Transactional Communications

Connect TPS supports only non-transactional communications. Therefore, all communications via Connect TPS are subject to the following operational considerations:

• Remote services called by local client or server programs will always be invoked outside the boundaries of any local transaction.

• Local services called by remote client or server programs will always be invoked outside the boundaries of any local transaction.

• Local client or server programs calling remote services should invoke the tpcall() function, or the tpacall() and tpgetrply() functions, outside the boundaries of any local transaction (i.e., outside of any tx_begin()/tx_commit() or tpbegin()/tpcommit() pair).

• If local client or server programs must call remote services within the boundaries of a local transaction, TPNOTRAN must be specified as one of the flags to the tpcall() or tpacall() function.

Client Authentication Keys and Client Identifiers

Client authentication keys and client identifiers are subject to the following operational considerations:

• Local client programs cannot send authentication keys and identifiers to remote services.

• Remote client programs cannot send authentication keys and identifiers to local services. A local service that examines input for an authentication key and an identifier will find the authentication key and identifier of the local Connect TPS Handler (TPSH) that processed the request.

The tpsprio() and tpgprio() Functions

The tpsprio() and tpgprio() functions are subject to the following operational considerations:

• Local client and server programs cannot use the tpsprio() function to set the priority at which remote services are processed. Instead, a call to the tpsprio() function causes the priority of a local Connect TPS Requester (TPSR) to be set.

• Remote client and server programs cannot use the tpsprio() function to set the priority at which local services are processed.

• When local client or server programs use the tpgprio() function to determine the priority of a remote service, the priority of a local Connect TPS Requester (TPSR) is returned.

The tpbroadcast() and tpnotify() Functions

The tpbroadcast() and tpnotify() functions are subject to the following operational considerations:

• Local client programs cannot use the tpbroadcast() function to send unsolicited messages to remote client programs (and the reverse).

• Local services cannot use the tpbroadcast() or tpnotify() functions to send messages to remote client programs (and the reverse).