Chapter 4 . Configuring BEA Connect TPS

To configure Connect TPS, you must

• Update the TUXEDO configuration (the UBBCONFIG file) by establishing a server group for Connect TPS and by adding entries for Connect TPS Requesters (TPSR) and Liaisons (TPSL)

• Specify various parameters in the TPSINIT configuration file

Updating the TUXEDO UBBCONFIG File

As with any TUXEDO servers, Connect TPS Requesters and Liaisons must be specified in the UBBCONFIG file for the local region.

More specifically, you must add records to

• The *GROUPS section

• The *SERVERS section

See the TUXEDO Transaction Manager Administration Guide for more information about the UBBCONFIG file.

Updating the *GROUPS Section

This subsection explains how to establish a server group for Connect TPS.

Overview

To establish a server group for Connect TPS, you must add the following items to the *GROUPS section of the TUXEDO UBBCONFIG file:

• A name for the Connect TPS server group

• The logical machine name for the system on which Connect TPS is installed

• A group number for the Connect TPS server group

Syntax

The syntax of the configuration file entry is as follows:

groupname LMID=logical_machine_identifier
          GROUPNO=group_number

The variables are defined as follows:

Example

Here is an example of a UBBCONFIG entry that establishes a server group:

NODE2GATE   LMID=NODE2
            GROUPNO=1

This subsection explains how to specify Connect TPS servers in the TUXEDO configuration.

Overview

Connect TPS provides the two kinds of servers you need to list in the *SERVERS section of the TUXEDO UBBCONFIG configuration file:

Server	Description
Liaisons (TPSL)	Servers that monitor the Connect TPS server group. Also, Liaisons process administrative commands from tmadmin.
Requesters (TPSR)	Servers that process requests for remote services (services that reside outside the local TUXEDO region).

For each Connect TPS server group, you can specify

• One Liaison

• Zero or more Requesters

If you want a local system to function only as a "server" (a node that processes requests from remote systems), you must configure and invoke a Liaison. Requesters are unnecessary in this situation.

On the other hand, if you want a local system to function only as a "client" (a node that sends service requests to remote systems), you must configure and invoke a Liaison and one or more Requesters.

Finally, if you want the local system to perform both roles, you must configure and invoke a Liaison and one or more Requesters.

Syntax

The syntax of each configuration file entry is as follows:

{ TPSL | TPSR }  SVGRP=groupname  SRVID=integer
           CLOPT="-A -- -k GWIPCKEY -i {-M | -Ixxxx} TPSINIT"

The following table describes the parts of the syntax.

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.

For more information about TUXEDO servers and related configuration parameters, see the TUXEDO Transaction Manager Administration Guide.

Other Options for Configuring Servers

As with other TUXEDO servers, you can use the full range of TUXEDO system server boot options with Connect TPS servers.

The "-r" option may be particularly useful. Using this timestamp recording option, together with the txrpt report command, you can analyze remote service response times. Of course, the process of gathering statistics creates overhead. Consequently, you should use this option selectively.

The RQADDR parameter is also helpful. It enables you to simplify system administration tasks by assigning intuitive names to Connect TPS server queues. To do so, specify the nodename, LMID or SRVGRP value as part of the queue name (as shown in the following example). Each server entry must have a unique RQADDR value. Also, you cannot use the RQADDR parameter if the TUXEDO MIN or MAX parameters are set to values that are greater than 1.

Here are two final points about boot options:

• Boot options must be specified with the CLOPT parameter (before the CLOPT double-dash separator).

• Because Connect TPS dynamically advertises services that are listed in its initialization file, you should not advertise services by using the "-s" option.

For more information about these and other boot options, see servopts(5) in the TUXEDO Transaction Manager Administration and Programming Reference Manual.

Example

Here is an example of a UBBCONFIG entry that configures three Connect TPS servers (a Liaison (TPSL), an IMS Requester (TPSR), and a CICS Requester (TPSR)):

* SERVERS
TPSL  SRVGRP=LIAISON  SRVID=1
      CLOPT="-A -- _M   -iTPSLIAS"  RQADDR=TPSL
TPSR  SRVGRP=REQIMS   SRVID=2
      CLOPT="-A -- -M   -iTPSRQ1I"  RQADDR=TPSRIMS
TPSR  SRVGRP=REQCICS  SRVID=3  
      CLOPT="-A -- -IBEAH -iTPSRQ2C"   RQADDR=TPSRCICS

The TPSINIT file is the mechanism that system administrators use to configure Connect TPS. The following subsections introduce the file.

Sections in the TPSINIT File

The TPSINIT file is divided into the following three sections:

• *GENERAL

  Describes certain general characteristics of all Connect TPS server groups that share one configuration, or of one Connect TPS server group that has its own configuration.

• *GATEWAYS

  Describes all gateways that are accessible through the local Connect TPS server group. Each gateway represents a unique network endpoint, such as an MVS system that supports Connect TPS. The local TUXEDO region is also considered a gateway and therefore must be described in this section.

• *SERVICES

  Describes services that are accessible on all gateways. This includes local services and services that are offered on remote systems or regions.

These sections and their respective parameters are described in detail in this section.

General Suggestions and Observations

Here are some general suggestions and observations to consider before you create and implement an TPSINIT file:

• The TPSINIT file is similar to the TUXEDO Transaction Manager UBBCONFIG file, both in structure and in composition. This makes it possible for experienced TUXEDO administrators to configure Connect TPS without extensive training.

• TPSINIT is a generic filename. You are free to choose other filenames (just as with the TUXEDO UBBCONFIG file).

Updating the *GENERAL Section of the TPSINIT File

The following subsections describe parameters that are associated with the *GENERAL section of the TPSINIT file.

Description

The *GENERAL section of the TPSINIT file contains parameters that describe certain characteristics of a Connect TPS server group.

Syntax

The format of the *GENERAL section of the TPSINIT file is as follows:

[ # A comment (from "#" to end of line)]

*GENERAL
[ SCANUNIT=number_of_seconds ]
[ SANITYSCAN=number_of_SCANUNITs ]
[ BLOCKTIME=number_of_SCANUNITs ]

[ MAXDATALEN=remote_length_limit_in_bytes ]

As the syntax indicates, all parameters in the *GENERAL section are optional.

Parameters

This section describes the parameters that you set in the *GENERAL section.

The SCANUNIT and SANITYSCAN Parameters

The SCANUNIT and SANITYSCAN parameters, like their TUXEDO counterparts, are used to specify how often processes are monitored. In the case of Connect TPS, these parameters determine how often the Liaison process (TPSL) monitors Handlers (TPSH).

Here are brief definitions for each parameter:

• SCANUNIT determines the frequency (in seconds) of the Liaison's periodic monitoring efforts. This monitoring always includes timeout supervision and may involve the detection of dead processes as well (on any given monitoring scan).

• SANITYSCAN specifies the number of SCANUNITs that elapse between process monitoring efforts.

If you do not specify values for SCANUNIT and SANITYSCAN in the TPSINIT file, Connect TPS uses TUXEDO SCANUNIT or SANITYSCAN values-either defaults or other values that are set in the UBBCONFIG file.

Note: When the Liaison determines that a Handler has died, it cleans up after the Handler.

The BLOCKTIME Parameter

The BLOCKTIME parameter, like its TUXEDO counterpart, is used along with the SCANUNIT parameter to specify how long a process can block (wait) for a message-and to prevent an application from locking up when a remote system does not respond.

BLOCKTIME is used to specify how many SCANUNITs a Handler or a Requester can wait for a message. When BLOCKTIME is exceeded, the Liaison times out the associated service request.

If you do not specify a value for BLOCKTIME in the TPSINIT file, Connect TPS uses the TUXEDO BLOCKTIME value-either the default or the value that is set in the UBBCONFIG file.

The MAXDATALEN Parameter

The MAXDATALEN parameter establishes the maximum length of a Connect TPS record, including all encoding, that can be sent to or received from remote systems.

The parameter is used to

• Tailor the size of internal work buffers

• Guarantee that outbound messages do not exceed limits that may be imposed by transport mechanisms or by remote systems

The default value for MAXDATALEN is 32,000 bytes.

Updating the *GATEWAYS Section of the TPSINIT File

The following subsections describe parameters that are associated with the *GATEWAYS section of the TPSINIT file.

Description

Connect TPS provides mechanisms that enable various systems to communicate through gateways. A gateway can be thought of in two ways:

• From a communications perspective, every gateway represents a target that is the source of or the destination for service calls.

• From a processing perspective, gateways that use Connect TPS are also server groups, each of which consists of a Liaison, and possibly Requesters and Handlers.

Therefore, while all gateways represent communications targets, only gateways that use Connect TPS are also server groups.

The *GATEWAYS section supports parameters that describe all gateways for a given configuration. Each gateway represents a unique communications endpoint, such as a remote Connect TCP for CICS gateway. The local TUXEDO region is also considered a gateway and therefore must be defined in the *GATEWAYS section.

There are two kinds of parameters in the *GATEWAYS section:

• Communications parameters - Various names and identifiers that are used to distinguish individual gateways (or communications targets)

• Processing parameters - Various settings that are used to control processing that is performed by gateways that are also Connect TPS server groups

Communications parameters must be set for all gateways that are identified in the configuration. Processing parameters, on the other hand, apply only to those gateways that are also Connect TPS server groups. This approach helps support shared configurations.

The *GATEWAYS section is organized as a series of repetitive entries. Each entry consists of

• An initial tag that identifies the node on which the gateway resides.

• A parameter that names the gateway.

• Communications parameters that apply to the gateway.

• Processing parameters that apply to the gateway. These are used only for gateways that are Connect TPS server groups.

Syntax

The format of the *GATEWAYS section of the TPSINIT file is as follows:

[ # A comment (from "#" to end of line)]
*GATEWAYS
[ DEFAULT: default_gateway_parameters ]
nodename
GWID=alphanumeric_gateway_name
[ GWIPCKEY=valid_IPCKEY_value ]
[ MAXHANDLERS=positive_integer ]
[ MULTIPLEX=positive_integer ]
NWADDR=TUXEDO_format_network_address
[ NWDEVICE= network_device_path_spec ]
[ RMTACCT=remote_account_id ]
[ PASSWORD=remote_password ]
[ nodename ... ]

Lines beginning with the reserved word DEFAULT: contain parameter specifications that apply to any lines that follow them in the section in which they appear. Values associated with the reserved word DEFAULT: remain in effect until one of the following situations occurs:

• Another DEFAULT specification causes current values to be replaced by new values

• The end of the section is reached

You can override current values on non-DEFAULT lines by placing optional parameter settings on those lines. A parameter that is set on a non-DEFAULT line is valid for that entry only; entries that follow revert to the default setting.

If DEFAULT: appears on a line by itself, all current defaults are cleared and are replaced by system defaults.

The Nodename Tag

Each *GATEWAYS entry begins with a nodename tag. This identifies the node with which a particular gateway is associated. The value you specify is equivalent (on UNIX nodes) to the machine name that the UNIX uname -n command returns.

The nodename must be the first (non-comment) field in a *GATEWAYS entry. It is required for all gateways.

Parameters

The parameters described in this subsection may be set for each gateway that you specify in the *GATEWAYS section.

The GWID Parameter

The GWID parameter is used to assign a unique name to each gateway that is defined in the *GATEWAYS section. Any alphanumeric value is permitted. However, the value must be unique within the file.

This parameter is required for all gateways.

The GWIPCKEY Parameter

The GWIPCKEY parameter identifies interprocess communication (IPC) resources that are used by gateways that are also Connect TPS server groups.

GWIPCKEY is analogous to the IPCKEY parameter that you specify for the TUXEDO Transaction Manager (in the UBBCONFIG file). However, because the TUXEDO Transaction Manager and Connect TPS gateways require separate IPC resources, the TUXEDO IPCKEY and the GWIPCKEY must be different.

Here are a couple of observations to consider when you specify the GWIPCKEY parameter:

• Although one GWIPCKEY can be used on multiple computer systems (where Connect TPS gateways exist), each gateway on a single computer system must have its own GWIPCKEY.

• If you configure only one Connect TPS server group in the TPSINIT file, you can omit the GWIPCKEY parameter. However, as described in "Updating the *SERVERS Section", you must always specify the GWIPCKEY in the UBBCONFIG entry for the Connect TPS server group.

Except for the circumstance described above, the GWIPCKEY parameter is required for gateways that are Connect TPS server groups. It is not used for other gateways.

The MAXHANDLERS Parameter

The MAXHANDLERS parameter specifies how many Handlers (TPSH) the Connect TPS Liaison (TPSL) starts.

If you do not specify a value for MAXHANDLERS, or if you set MAXHANDLERS to zero, the maximum number of Handlers started is one.

The MULTIPLEX Parameter

The MULTIPLEX parameter is a qualifier of the MAXHANDLERS parameter.

The MULTIPLEX parameter specifies the maximum number of network connections a single Handler (TPSH) will support. The value of MULTIPLEX may range from 1 to 1000; the default value is 10. Set MULTIPLEX=1 to ensure a connection.

Note: To ensure that the Listener establishes a connection with a new Handler for each request, the Handler must be set to a multiplexing factor of 1.

The NWADDR Parameter

The NWADDR parameter identifies a TCP/IP communication endpoint for each gateway.

NWADDR is a network address and port in the format accepted by the TUXEDO System/T network library for the machine on which the Connect TPS gateway server group will be run. NWADDR is analogous to the NADDR parameter that you specify for the TUXEDO Transaction Manager (in the UBBCONFIG file). However, because the TUXEDO Transaction Manager and BEA Connect TPS gateways require separate TCP/IP addresses, the TUXEDO NADDR and the NWADDR must be different.

The NWADDR parameter is required for all gateways, whether or not they are BEA Connect TPS server groups.

Here are two valid ways of specifying the same TCP/IP address:

• NWADDR=0x000212347F000001

• NWADDR=//127.0.0.1:4660

The NWDEVICE Parameter

The NWDEVICE parameter identifies a network communication device for each gateway.

NWDEVICE is a network device name, as required by the TUXEDO System/T network library for the machine on which the BEA Connect TPS gateway server group will be run. This may be optional in sockets-based network library implementations. NWDEVICE is analogous to the BRIDGE parameter that you specify for the TUXEDO Transaction Manager (in the UBBCONFIG file). In fact, on a given machine, the TUXEDO BRIDGE and the NWDEVICE will probably be set to exactly the same path.

Except for the case of sockets-based implementations described above, the NWDEVICE parameter is required for gateways that are BEA Connect TPS server groups. It is not used for other gateways.

The RMTACCT and PASSWORD Parameters

The RMTACCT and PASSWORD parameters are used to specify security information to be passed in to a remote gateway.

While Connect TPS considers this information to be optional, it may be required by a remote BEA Connect TPS gateway.

Updating the *SERVICES Section of the TPSINIT File

The following subsections describe parameters associated with the *SERVICES section of the TPSINIT file.

Description

The *SERVICES section of the TPSINIT file contains parameters that collectively describe services that are accessible through all gateways that are defined in the Connect TPS configuration. This includes local services that are invoked by calls from remote client programs, and remote services that are requested by local client programs.

Each *SERVICES entry is a set of parameters that specify

• The name of a service

• The location of the service

• Instructions for converting

  • Input to the service

  • Output from the service

• Instructions for handling errors that occur during the service call

Syntax

The format of the *SERVICES section of the TPSINIT file is as follows:

[ # A comment (from "#" to end of line)]
*SERVICES
[ DEFAULT: default_service_parameters ]
svc_name 
GWID=gateway_name_defined_in_*GATEWAYS
[ RMTNAME=remote_svc_name ]
[ INBUFTYPE={ unstructured_buffer_type | 
	structured_buffer_type: viewname } ]
[ INRECTYPE={ unstructured_buffer_type | 	
	structured_buffer_type:viewname } ]
[ OUTRECTYPE={ unstructured_buffer_type | 
	structured_buffer_type:viewname } ]
[ OUTBUFTYPE={ unstructured_buffer_type | 
	structured_buffer_type:viewname } ]
[ ERRORLOCATION={ VIEW_fieldname | byte_offset }
	ERRORMATCH=data_to_match ]
[ ERRBUFTYPE={ unstructured_buffer_type |
	structured_buffer_type:viewname } ]
[ ERRORLOG={ Y | N } ]
[ BLOCKTIME=integer ]
[ svc_name ... ]

The term "unstructured_buffer_type" in the preceding syntax diagram refers to those types that do not use external structure definitions. Included in this group are X_OCTET, CARRAY, STRING, and FML.

The term "structured_buffer_type" refers to those XATMI and ATMI buffer types that directly represent C language structures or COBOL records. Included in this group are X_C_TYPE, X_COMMON, and VIEW buffers. The name of a VIEW definition (a viewname) must always be provided when you set a BEA Connect TPS parameter to any of these three types.

The Reserved Word DEFAULT:

Lines beginning with the reserved word DEFAULT: contain parameter specifications that apply to any lines that follow them in the section in which they appear. Values associated with the reserved word DEFAULT: remain in effect until one of the following situations occurs:

• Another DEFAULT: specification causes current values to be replaced by new values

• The end of the section is reached

Current values can also be overridden on non-DEFAULT lines by placing optional parameter settings on those lines. A parameter that is set on a non-DEFAULT line is valid for that entry only; entries that follow revert to the default setting.

If DEFAULT: appears on a line by itself, all current defaults are cleared and are replaced by system defaults.

The Svc_name Tag

Each *SERVICES entry must begin with a svc_name tag. The svc_name tag is the name by which a local or remote service is known within the local TUXEDO region. Any legal TUXEDO service name can be used.

The svc_name must be the first (non-comment) field in a *SERVICES entry.

Note: Because of differences in naming conventions, services that exist on remote systems may be known by different names in their native environments. Also, local TUXEDO services that are advertised in these remote environments may be advertised by different names. The RMTNAME parameter, which is described in the following subsection, makes it possible to map local names to remote names and the reverse.

Parameters

The parameters described in this subsection can be set for each service you configure. As the syntax indicates, with the exception of the required GWID parameter, all other parameters may or may not be required, depending on the needs of the service you are configuring.

The GWID Parameter

The GWID parameter identifies the region or system where a service actually exists. This can be any gateway target (Connect TPS endpoint) that is defined in the *GATEWAYS section of the TPSINIT file, including the local BEA Connect TPS server group.

You must set GWID to a gateway name that is defined in the *GATEWAYS section.

When BEA Connect TPS is booted, the Connect TPS Requester (TPSR) advertises all services that are defined in the TPSINIT file-except those that are associated with the local gateway. (These local services are invoked by Connect TPS Handlers (TPSH) when requests are received from the network.)

The GWID parameter is required for all services.

The RMTNAME Parameter

The RMTNAME parameter is used to specify the name by which a service is known on a remote system. Generally, RMTNAME is used in situations where remote systems have different naming conventions for services.

Connect TPS uses this information to map local names to remote names and the reverse. More specifically,

• When the Connect TPS Requester receives a request for svc_name from a local client program, it maps svc_name to RMTNAME before it sends the request to the remote system.

• When a Connect TPS Handler receives a request for RMTNAME from a remote system, it maps RMTNAME to svc_name before it passes the request to TUXEDO software.

The RMTNAME parameter is optional.

Note: If you omit RMTNAME, you are indicating that the value for svc_name is universally acceptable. In other words, the TUXEDO service name that is advertised by the local Connect TPS Requester will be acceptable to the remote target system. Or, the remote service name that BEA Connect TPS Handlers receive will be acceptable locally.

The INBUFTYPE Parameter

The INBUFTYPE parameter is used to describe data buffers that flow between local TUXEDO application programs and local Connect TPS Requesters and Handlers.

When local and remote application programs use different layouts for data, you may need to map these different layouts by setting the INBUFTYPE parameter to an appropriate value.

For a general introduction to input and output mapping, see Chapter 3, "Installing and Getting Ready to Configure BEA Connect TPS". For detailed information about possible settings for the INBUFTYPE parameter, see "Parameters for Locally Originated Calls" and "Parameters for Remotely Originated Calls" in Chapter 3, "Installing and Getting Ready to Configure BEA Connect TPS".

The INRECTYPE Parameter

The INRECTYPE parameter is used to describe data records that flow between different gateways.

When local and remote application programs use different layouts for data, you may need to map these different layouts by setting the INRECTYPE parameter to an appropriate value.

For a general introduction to input and output mapping, see Chapter 3, "Installing and Getting Ready to Configure BEA Connect TPS". For detailed information about possible settings for the INRECTYPE parameter, see "Guidelines for Setting Parameters" in Chapter 3, "Installing and Getting Ready to Configure BEA Connect TPS".

The OUTRECTYPE Parameter

The OUTRECTYPE parameter is used to describe data records that flow between different gateways.

When local and remote application programs use different layouts for data, you may need to map these different layouts by setting the OUTRECTYPE parameter to an appropriate value.

For a general introduction to input and output mapping, see Chapter 3, "Installing and Getting Ready to Configure BEA Connect TPS". For detailed information about possible settings for the OUTRECTYPE parameter, see "Guidelines for Setting Parameters" in Chapter 3, "Installing and Getting Ready to Configure BEA Connect TPS".

The OUTBUFTYPE Parameter

The OUTBUFTYPE parameter is used to describe data buffers that flow between local TUXEDO application programs and local Connect TPS Requesters and Handlers.

When local and remote application programs use different layouts for data, you may need to map these different layouts by setting the OUTBUFTYPE parameter to an appropriate value.

For a general introduction to input and output mapping, see Chapter 3, "Installing and Getting Ready to Configure BEA Connect TPS". For detailed information about possible settings for the OUTBUFTYPE parameter, see "Guidelines for Setting Parameters" in Chapter 3, "Installing and Getting Ready to Configure BEA Connect TPS".

The ERRORLOCATION and ERRORMATCH Parameters

The ERRORLOCATION and ERRORMATCH parameters go hand-in-hand, and both must be specified (ERRORLOCATION followed by ERRORMATCH) whenever used.

The ERRORLOCATION specifies the area in the OUTRECTYPE to examine for an error indication, while the ERRORMATCH parameter is used to provide the data which when matched (found) will indicate that an application error has occurred.

The ERRORLOCATION may be expressed as either a field name or a byte offset. To indicate that a particular field in the OUTRECTYPE VIEW should be examined, the field name used for that field in the VIEW description should be entered as the ERRORLOCATION. The field type will be used to determine the appropriate type of evaluation to perform. Numeric types are tested for equality, while STRING and CARRAY fields are matched (up to the length of the ERRORMATCH argument).

Specifying the ERRORLOCATION as a byte offset allows STRING, X_OCTET, and CARRAY OUTRECTYPEs to be evaluated. This can also be used in the event that the remote service would normally return a particular record (which you have specified as an OUTRECTYPE VIEW) but abandons that layout in the event of an error, returning an error string instead. It is not unusual for ERRORLOCATION to be set to 0 (zero), indicating that the record should be examined beginning at the very first byte (i.e., no offset).

Whenever ERRORLOCATION is given as an offset rather than a field, the OUTRECTYPE parameter controls the type of evaluation of the ERRORMATCH value. If the OUTRECTYPE is an X_OCTET (or CARRAY), ERRORMATCH is treated as an uninterpreted byte sequence. Otherwise, it will undergo string translation and comparison. This of course supports STRING OUTRECTYPEs, but also provides a way to handle remote services which return error strings instead of their usual record.

BEA Connect TPS considers these parameters to be optional but whenever used, both must be specified (ERRORLOCATION followed by ERRORMATCH).

The ERRBUFTYPE Parameter

The ERRBUFTYPE parameter specifies the type and format of the error buffer that Connect TPS will return to the service's caller (a local client program). If you do not specify ERRBUFTYPE, Connect TPS will return unconverted error records.

The ERRBUFTYPE parameter is optional.

The ERRORLOG Parameter

The ERRORLOG parameter controls whether or not error records from a remote service are sent to the TUXEDO ULOG. If you specify the value "Y" for this parameter (as shown in Syntax), error records are sent to the log.

The ERRORLOG parameter is optional.

The BLOCKTIME Parameter

The BLOCKTIME parameter specifies the number of SCANUNITs within which the service must complete and return results. If no BLOCKTIME value is specified for a particular service, the BLOCKTIME value specified in the *GATEWAYS section (or the default value) will be used to set the timeout.

The BLOCKTIME parameter is optional.