Chapter 3 . Installing and Getting Ready to Configure BEA Connect TPS

One of the major benefits of using Connect TPS to connect dissimilar systems is the degree to which different programming environments can be isolated. BEA TUXEDO programmers rarely need to know that services are handled by dissimilar systems or by systems in remote regions. Application programs do not need to be developed in any special way.

The key to this high degree of transparency is the Connect TPS configuration. It is through this mechanism that environmental differences, such as naming conventions and data formats, are concealed from programmers and programs.

There are three kinds of environmental differences that are isolated in the Connect TPS configuration file (TPSINIT):

Service names	Different systems have different rules for naming services. Service names can differ in length, allowable characters, and even conventions as to how they are constructed or chosen.
Input and output data formats	Different systems have different conventions for formatting input and output data (such as structure, character set, and so forth).
Error handling	Different systems report application errors in different ways.

The technique that is used to hide these differences is called mapping. Generally speaking, when you map things, you associate local values or entities with values or entities that are meaningful to programs on remote systems.

The procedure for mapping service names is self-explanatory; you create a configuration file record in which a local name for a service is paired with a remote name for that service. On the other hand, procedures for mapping input data, output data, and application errors are more complex. Conceptual information and other background information is required.

In addition to providing installation instructions, this chapter explains how Connect TPS performs the following tasks:

• Converts input and output data into formats that are acceptable to target systems

• Translates data

• Processes application errors

This chapter also introduces configuration file parameters that you must set. These configuration file parameters will:

• Map input data and output data that flows between the local region and remote systems and thereby facilitate the Connect TPS conversion process

• Specify how data is translated

• Specify how application errors are processed

In addition, this chapter provides information about creating VIEW definitions. VIEW definitions are descriptions of data structures that are used for input and output in the BEA TUXEDO environment. Connect TPS uses VIEW definitions to determine how to convert input data and output data into formats that are acceptable to target systems.

For detailed information about updating the Connect TPS configuration file (TPSINIT), see Chapter 4, "Configuring BEA Connect TPS".

Note: All Connect TPS configuration parameters are described in Chapter 4, "Configuring BEA Connect TPS". This chapter focuses on complex parameters that require a separate introduction. The task of configuring data mappings could be considered a programming activity because it requires knowledge of the BEA TUXEDO programming environment. However, because configuration parameters affect many application programs, configuration is usually an administrator's responsibility.

How to Install BEA Connect TPS

The installation procedure for BEA Connect TPS is slightly different for each platform on which the software can be installed. Please follow the directions for the appropriate platform.

Installing BEA Connect TPS on UNIX

To install BEA Connect TPS on any UNIX platform use the "install.sh" script on the CD ROM. To run the script, complete the following steps:

1. Mount the CD ROM.

2. Change directories to the top-level directory on the CD ROM.

3. Enter "sh install.sh" and the installation program will guide you through the installation process. Be sure to install BEA Connect TPS in the TUXEDO directory.

To install BEA Connect TCP for IMS, please refer to the installation instructions in the BEA Connect TCP for IMS User Guide. To install BEA Connect TCP for CICS, please refer to the installation instructions in the BEA Connect TCP for CICS User Guide.

Installing BEA Connect TPS on Windows NT

To install BEA Connect TPS on Windows NT, complete the following steps.

1. Mount the BEA Connect TCP CD ROM.

2. Change directory to the appropriate Windows NT directory.

3. Execute the SETUP.EXE program in this directory.

This subsection introduces procedures that Connect TPS follows to process and convert input and output data.

Buffers and Records

In this guide, the following terms are used to describe input and output data:

Buffer

Input or output data as it exists inside the local BEA TUXEDO region. This includes all the buffer types that BEA TUXEDO software supports-both BEA TUXEDO ATMI buffer types and X/Open XATMI buffer types.

Record

Input or output data as it exists outside the local BEA TUXEDO region-on different kinds of systems.

These terms make it easier to understand how Connect TPS handles input and output data.

Buffers Received from Local Programs

When Connect TPS receives a buffer from a local program, it automatically determines the buffer's type.

• Connect TPS Requesters automatically "type" input buffers that local client programs send to remote services.

• Connect TPS Handlers automatically "type" output buffers that local services return to remote client programs.

After Connect TPS determines a buffer's type, it consults the configuration (TPSINIT) to determine whether or not the buffer needs to be converted to a different format.

• Input buffers that will be sent to remote services may need to be converted to record formats that are meaningful to those services.

• Output buffers that will be returned to remote client programs may need to be converted to record formats that are meaningful to those programs.

If the configuration indicates that conversion is required, Connect TPS transforms the buffer into the record format that is specified in the configuration.

Records Received from Remote Programs

When Connect TPS receives a record from a remote system, it consults the configuration (TPSINIT) to determine the record's type.

After Connect TPS determines a record's type, it consults the configuration (TPSINIT) to determine whether or not the record needs to be converted to a different format.

• Input records from remote client programs may need to be converted to buffer formats that are acceptable to local service routines.

• Output records returned from remote services may need to be converted to buffer formats that are acceptable to local client programs.

If the configuration indicates that conversion is required, Connect TPS transforms the record into the buffer format that is specified in the configuration.

Configuration Parameters for Managing Conversion

Connect TPS provides four configuration parameters you can use to map buffers and records. See subsection "Buffers and Records" on page 3-4 for a discussion of buffers and records. These include:

• INBUFTYPE - Identifies the type, and in some cases the format, of an input buffer

• INRECTYPE - Identifies the type, and in some cases the format, of an input record

• OUTRECTYPE - Identifies the type, and in some cases the format, of an output record

• OUTBUFTYPE - Identifies the type, and in some cases the format, of an output buffer

Each of these four parameters has two possible meanings or interpretations-one for service requests that originate locally, and one for service requests that originate on remote systems.

The next two subsections ("Parameters for Locally Originated Calls" and "Parameters for Remotely Originated Calls") explore these different meanings in detail.

Parameters for Locally Originated Calls

This subsection takes a closer look at how Connect TPS handles service calls that originate locally, within the immediate BEA TUXEDO region. Also, it explains how the INBUFTYPE, INRECTYPE, OUTRECTYPE, and OUTBUFTYPE parameters can be used to manage the conversion of buffers and records that flow between local client programs and remote services.

In Figure 3-1, a local BEA TUXEDO client program issues a service call that a local Connect TPS Requester (TPSR) routes to a remote server through Connect TPS.

Figure 3-1 How Parameters are Mapped during Locally Originated Calls

In this situation, the four configuration parameters that are shown in the figure have the following meanings:

• The INBUFTYPE parameter describes the BEA TUXEDO input buffer that the local client program provides to the Connect TPS Requester through BEA TUXEDO software.

• The INRECTYPE parameter describes the input record that is sent to the service on the remote system.

• The OUTRECTYPE parameter describes the output record that is received from the service on the remote system.

• The OUTBUFTYPE parameter describes the BEA TUXEDO output buffer that is returned to the local client program.

Guidelines for Mapping Input Buffers to Input Records

Here is some detailed information that will help you understand how to use the INBUFTYPE and INRECTYPE parameters for service calls that originate locally (where local client programs call remote services).

The INBUFTYPE Parameter

The INBUFTYPE parameter is used to specify the buffer type that is provided to a local Connect TPS Requester (TPSR) when a local client program issues a service request.

Because the Requester determines the type of incoming buffers automatically at run time, this parameter is described here for conceptual completeness only. In the Connect TPS configuration, it is used only by the Handlers (TPSH).

The INRECTYPE Parameter

The INRECTYPE parameter is used to specify the type, and in some cases the format, of the input record that a particular remote service requires. Connect TPS uses this information to convert BEA TUXEDO input buffers into records that remote services can process.

You must specify the INRECTYPE parameter when one of the circumstances described in Table 3-1 is true:

The INRECTYPE parameter may be omitted if the input buffer is identical, in type and structure, to the record the remote service expects.

Guidelines for Mapping Output Records to Output Buffers

Here is some detailed information that will help you understand how to use the OUTRECTYPE and OUTBUFTYPE parameters for service calls that originate locally (where local client programs call remote services and receive output from those services).

The OUTRECTYPE Parameter

The OUTRECTYPE parameter is used to specify the type, and in some cases the format, of the output record that a particular remote service returns to the local Connect TPS Requester (TPSR).

The OUTBUFTYPE Parameter

The OUTBUFTYPE parameter is used to specify the type, and in some cases the structure, of the output buffer that a local client program expects. Connect TPS uses this information to map output records from remote services to the appropriate kinds of output buffers.

You must specify the OUTBUFTYPE parameter when one of the circumstances described in Table 3-2 is true:

The OUTBUFTYPE parameter may be omitted if the remote service returns an output record that is identical, in type and structure, to the output buffer the local client program expects.

Parameters for Remotely Originated Calls

This subsection takes a closer look at how Connect TPS handles service calls that originate on remote computers, outside the local BEA TUXEDO region. Also, it explains how the INRECTYPE, INBUFTYPE, OUTBUFTYPE, and OUTRECTYPE parameters can be used to manage the conversion of buffers and records that flow between remote client programs and local services.

In subsection "Parameters for Locally Originated Calls," a remote client program issues a service request that a remote Connect TPS gateway (or equivalent software) routes to the local Connect TPS gateway. A Handler process (TPSH) that was previously started by the Connect TPS Liaison (TPSL) receives the request from the network and passes the request to a local BEA TUXEDO server.

Figure 3-2 How Parameters are Mapped during Remotely Originated Calls

In this situation, the four configuration parameters that are shown in the figure have the following meanings:

• The INRECTYPE parameter describes the input record that the local Connect TPS Handler receives from the remote client program.

• The INBUFTYPE parameter describes the BEA TUXEDO input buffer that is provided to the local server.

• The OUTBUFTYPE parameter describes the BEA TUXEDO output buffer that comes from the local server.

• The OUTRECTYPE parameter describes the output record that the local Handler sends to the remote system where the client program resides.

Guidelines for Mapping Input Records to Input Buffers

Here is some detailed information that will help you understand how to use the INRECTYPE and INBUFTYPE parameters for service calls that originate on remote systems (where remote client programs call local services).

The INRECTYPE Parameter

The INRECTYPE parameter is used to specify the type, and in some cases the format, of the input record that a particular remote client program sends to a local Connect TPS Handler.

The INBUFTYPE Parameter

The INBUFTYPE parameter is used to specify the type, and in some cases the structure, of the input buffer that a local service expects. Connect TPS uses this information to map input records from remote client programs to the appropriate kinds of input buffers.

You must specify the INBUFTYPE parameter when one of the circumstances described in Table 3-3 is true:

You can omit the INBUFTYPE parameter if the remote client program sends an input record that is identical in type and structure to the input buffer the local service expects.

Guidelines for Mapping Output Buffers to Output Records

Here is some detailed information that will help you understand how to use the OUTBUFTYPE and OUTRECTYPE parameters for service calls that originate on remote computers (where remote client programs call local services and receive output from those services).

The OUTBUFTYPE Parameter

The OUTBUFTYPE parameter specifies the buffer type that is provided to the local Connect TPS Handler (TPSH) after the local server completes its work.

Because the Handler determines the type of incoming buffers automatically at run time, this parameter is described here for conceptual completeness only. In the Connect TPS configuration, it is used only by Requesters (TPSR).

The OUTRECTYPE Parameter

The OUTRECTYPE parameter is used to specify the type, and in some cases the format, of the output record a particular remote client program requires. Connect TPS uses this information to convert output buffers from local services into records that remote client programs can process.

You must specify the OUTRECTYPE parameter when one of the circumstances described in Table 3-4 is true:

The OUTRECTYPE parameter may be omitted if the local service's output buffer is identical, in type and structure, to the record the remote client program expects.

Guidelines for Setting Parameters

This section provides guidelines for setting configuration parameters.

Mapping Input Buffers to Input Records

Figure 3-3 shows all the possibilities for mapping input buffers to input records:

Figure 3-3 Input Mappings

As Figure 3-3 shows, Connect TPS Requester is responsible for mapping input buffers to input records, based on information it finds in the Connect TPS configuration.

Setting the INBUFTYPE and INRECTYPE Parameters

Here are some comments about the mapping possibilities that are shown in Figure 3-3 and some suggestions for setting the INBUFTYPE and INRECTYPE parameters.

1	BEA TUXEDO CARRAY input buffers can be copied to CARRAY input records. A CARRAY buffer contains raw data that is not converted or translated. Set the INBUFTYPE and INRECTYPE parameters to CARRAY. CARRAY input buffers can also be copied to STRING input records. This creates a string that goes through no conversion and no translation. The resultant buffer is the length of the original CARRAY buffer. Since all characters are copied, if the CARRAY buffer contains null characters, it will affect the buffer when later handled as a STRING. The INBUFTYPE parameter should be set to CARRAY and the INRECTYPE parameter should be set to STRING.
2	BEA TUXEDO STRING input buffers can be mapped to CARRAY input records. No data conversion or translation is performed. The STRING buffer is copied through the leftmost null character only. Set the INBUFTYPE parameter to STRING and the INRECTYPE parameter to CARRAY.
3	BEA TUXEDO STRING input buffers can be mapped to STRING input records. The buffer goes through data type translation (i.e., ASCII to EBCDIC). Set the INBUFTYPE and INRECTYPE parameters to STRING.
4	BEA TUXEDO VIEW input buffers can be mapped to identical BEA TUXEDO VIEW input records. In this situation, the data structure that the remote service expects is identical to the data structure the client program uses. There is no need to create a new VIEW definition. Instead, specify the input record type (VIEW) and the name of the existing VIEW definition (the one the client program currently uses) for both the INBUFTYPE and INRECTYPE parameters.
5	BEA TUXEDO VIEW input buffers can be mapped to VIEW input records-in any combination. However, in this situation, the data structure that the remote service expects (designated as VIEW `B' mapping possibilities in Figure 3-3) differs from the data structure the client program uses (designated as VIEW `A' in Figure 3-3). Consequently, you must Create a VIEW definition for the data structure that the remote service expects. Specify the desired record type and the name of this VIEW definition with the INRECTYPE parameter. Set the INBUFTYPE parameter to VIEW:original-viewname.
6	Before a BEA TUXEDO FML input buffer can be sent to a remote service that does not support FML, it must be mapped to one of the following input record types: VIEW, X_C_TYPE, or X_COMMON. Also, you must create a VIEW definition for the input data structure that the remote service expects. Set INBUFTYPE to FML and INRECTYPE to VIEW:viewname.

Mapping Output Records to Output Buffers

Figure 3-4 shows all the possibilities for mapping output records to output buffers:

Figure 3-4 Output Mappings

As Figure 3-4 shows the Connect TPS Requester is responsible for mapping output records to output buffers, based on information it finds in the Connect TPS configuration.

Setting the OUTRECTYPE and OUTBUFTYPE Parameters

Here are some comments about the mapping possibilities that are shown in Figure 3-4 and some suggestions for setting the OUTRECTYPE and OUTBUFTYPE parameters (for service calls that originate locally).

How Connect TPS Translates Data

The following subsections

• Describe basic rules that Connect TPS follows when it translates data

• Provide detailed information about how Connect TPS handles string and numeric data

Read this information carefully before you create VIEW definitions (to facilitate buffer conversion) and configure Connect TPS.

Introduction

When a local client program sends data to (or receives data from) a service routine on a different kind of computer, Connect TPS automatically translates data as required.

Translation involves changing the representation of intrinsic data types by changing attributes such as

• Word length

• Byte order

Connect TPS automatically translates input and output data as required, following rules that are described in this subsection.

Data Translation Rules

Here are the data translation rules that Connect TPS follows:

• CARRAY fields are passed untranslated as sequences of bytes.

• STRING and CHAR fields will undergo ASCII to EBCDIC translation (if needed).

• SHORT and LONG fields are translated to S9(4) COMP and S9(9) COMP, respectively.

• FLOAT and DOUBLE fields translate to COMP-1 and COMP-2, respectively.

  Warning: dec_t cannot be used with VIEW translations.

  Note: BEA TUXEDO provides a field type named dec_t that supports decimal values within VIEWs. Connect TPS translates these fields into machine independent representations of packed decimals. For example, dec_t(m,n) becomes S9(2*m-(n+1))V9(n) COMP-3. Therefore, a decimal field with a size of 8,5 corresponds to S9(10)V9(5) COMP-3.

Table 3-5 summarizes the relationships.

Strings and Numeric Data: A Closer Look

This subsection

• Provides suggestions that will help you develop VIEW definitions for input and output buffers and records

• Explains how string data and numeric data are treated in the Connect TPS environment

NULL Characters in String Length Calculations (C Programs)

When you create VIEW definitions for input and output buffers that are used by C language applications, you must specify extra characters for terminating NULL characters that are used in string fields.

For example, when a local application program expects a 10-byte string in an output buffer, you would specify 11 for that field-10 for the string plus 1 for the terminating NULL character.

NULL Characters in String Length Calculations (COBOL Programs)

When you create VIEW definitions for input and output buffers that are used by COBOL language applications, do not specify extra characters for terminating NULL characters that are used in string fields.

For example, when a remote COBOL application program expects 10 characters in an input record, you would specify 10 for that field, not 10 plus 1 (for the terminating NULL character).

Note: Although Connect TPS does not require strings to be NULL-terminated, it respects NULL termination. Therefore, when Connect TPS detects a NULL (zero) character within a string, it does not process any subsequent characters. To pass full 8-bit data that contains embedded NULL values, use a CARRAY type field or buffer.

The character set translations performed by BEA Connect TPS are fully localizable, in accordance with the X/Open XPG Portability Guides. ASCII and EBCDIC translations are loadable from message files based on the locale subdirectory and the LANG environment variable. Connect TPS contains default behaviors for translation, one for ASCII and one for EBCDIC. There are two message catalogs, TPS-ASC_CAT for ASCII and TPS-EBC_CAT for EBCDIC respectively. The text for each is in TPS-ASC.text and TPS-EBC.text. These mapping table files should meet the requirements of most English-language applications. However, you may find it necessary to customize tables. See Appendix B, "Customizing Character Set Mapping Tables," for complete instructions.

Converting Numeric Data

Numeric data can easily be converted into different data types, provided that you have enough range in the intermediate and destination types to handle the maximum value you need to represent.

For example, you can convert numeric values into strings (and the reverse). For example, while FML buffers do not directly support the dec_t type, you can place decimal values in string fields and map these to dec_t fields within VIEW definitions.

How the Connect TPS Configuration Helps with Error Handling

This subsection will provide information about error handling. It will:

• Discuss the problem of error detection and reporting in the BEA TUXEDO environment.

• Introduce configuration parameters that Connect TPS provides to help application programs deal with errors.

• Provide a brief example showing how these configuration parameters can be used.

Read this information carefully before you configure Connect TPS.

Introduction

There are several ways that local client programs can learn about application errors that occur on remote systems. For example:

• Application failures can be communicated through error indicators that remote systems send to the local Connect TPS gateway.

• Service routines can include information about failures in output records that are returned to client programs.

To maintain the transparency of the BEA TUXEDO environment and to provide a flexible approach to error reporting, Connect TPS makes it possible for administrators to specify (in the TPSINIT file)

• How error records are returned

• Whether or not error records should be written to the ULOG file

This makes it possible to centralize error detection and reporting and frees client programs from the burden of knowing too much about remote application programs.

Configuration Parameters for Managing Application Errors

Connect TPS provides several configuration parameters that help you manage application errors. These are introduced in Table 3-6:

See Chapter 4, "Configuring BEA Connect TPS," for more detailed information about these parameters.

Example

By setting the Connect TPS configuration parameters (that were introduced in Table 3-6) to the following values, you can instruct the local gateway to look for error indications within records sent from the remote system. Connect TPS will examine the structure member "status_fld" and, if it contains a value of 256, log an error and convert it into a format that the client program finds acceptable.

OUTRECTYPE=VIEW:YOURSTRUCT
ERRORLOCATION=status_fld
ERRORMATCH=256
ERRBUFTYPE=VIEW:MYSTRUCT
ERRORLOG=Y

The following subsections explain how to create VIEW definitions. Connect TPS uses VIEW definitions to determine how to convert input data and output data into formats that are acceptable to target systems.

You should create VIEW definitions before you configure Connect TPS.

For complete information about VIEW definitions and related topics, see the BEA TUXEDO Transaction Manager Programming Guide.

Introduction

Connect TPS buffer and record conversion capabilities are extremely powerful and flexible. The key to maximizing these capabilities is to thoroughly understand the BEA TUXEDO VIEW definition mechanism.

VIEW definitions are used to describe input and output records that are sent to and received from remote systems. They describe data elements and indicate how data elements are typed and sequenced. Based on these descriptions, Connect TPS translates field data types as required to maintain transparency between dissimilar systems.

VIEW definitions make it possible to specify composite data structures that can be used

• On different kinds of machines

• With different programming languages

Preparing VIEW Definitions

Once you have determined the input and output record layouts for the remote application programs you will be working with, you need to

• Create standard BEA TUXEDO VIEW definitions in files.

• Run the viewc VIEW compiler.

• Set the VIEWFILES, VIEWDIR, FIELDTBLS, and FLDTBLDIR environment variables, using a BEA TUXEDO ENVFILE if necessary (so that Connect TPS servers can locate binary VIEW files and field table files at run time).

After these tasks are complete, you can specify VIEW definitions in the TPSINIT file (by associating names of VIEW definitions with the INRECTYPE, OUTRECTYPE, INBUFTYPE, and OUTBUFTYPE parameters, as required).

See Chapter 4, "Configuring BEA Connect TPS," for detailed information about configuring Connect TPS.

Note: FML fields must be specified for all VIEWs that Connect TPS converts. In other words, any VIEW that you specify as an INRECTYPE, OUTRECTYPE, INBUFTYPE or OUTBUFTYPE must be defined with appropriate FML fields (no dashes in the FNAME column of the VIEW definition).