GWTUX2TE, GWTE2TUX(5)


	BEA Home \| Events \| Solutions \| Partners \| Products \| Services \| Download \| Developer Center \| WebSUPPORT
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary

Tuxedo Documentation \| File Formats and Data Descriptions Reference \| Local Topics \| Previous Topic \| Next Topic \| Contents

Name

GWTUX2TE, GWTE2TUX—BEA Tuxedo / BEA TOP END gateway servers

Synopsis

GWTUX2TE SRVGRP = "identifier" SRVID = "number"
	CLOPT = "-- -f service_definition_file 
	[-c TOPEND_remote_configuration_file] 
	[-R sec] [-w wait_time] [[-u username] [-p password_file]]"

GWTE2TUX SRVGRP = "identifier" SRVID = "number" 
	CLOPT = "-- -f service_definition_file 
	[-c TOPEND_remote_configuration_file] 
	[-R sec] [[-u username] [-g groupname]]"

Description

GWTUX2TE and GWTE2TUX are gateway servers. GWTUX2TE provides connectivity between BEA Tuxedo clients and BEA TOP END servers. GWTE2TUX provides connectivity between BEA TOP END clients and BEA Tuxedo servers. One or both of these gateway servers may be configured for a domain.

GWTUX2TE and GWTE2TUX are defined in the SERVERS section of the UBBCONFIG file as servers running within a particular server group. Therefore, SRVGRP must be set to the value of the corresponding GRPNAME parameter (as specified in the GROUPS section). The SVRID parameter is also required. GWTUX2TE and GWTE2TUX allow for MIN and MAX values of gateway instances to be specified. Although the gateway servers are synchronous, you may use multiple instances to provide better throughput.

CLOPT is an "umbrella parameter" that passes a set of command-line options to the gateway servers when the servers are booted. To specify options with CLOPT, use the following format.

CLOPT="-- gateway_group_runtime_parameters"

The following CLOPT options are recognized:

-f service_definition_file

This file lists the services and functions to be advertised by the gateway server. (The file format is described in "Configuration" later in this reference page.) If -f is not specified or if the specified file has an invalid syntax, the gateway server logs an error and exits.

-c TOP_END_remote_configuration_file

This file defines the connectivity between the gateway servers and the BEA TOP END system. If this option is not specified, $APPDIR/TOPENDRC.cfg is used, by default, as the configuration file. If there is no configuration file or if the file specified has an invalid syntax, the gateway server logs an error and exits.

-u username -p password_file

If security is enabled on the BEA TOP END system, then the -u and -p options should be specified for the GWTUX2TE gateway.

After the -p option, specify the file that contains the password associated with the user specified by -u. The password file must be in ASCII format; the password must be provided on a single line. To ensure security, the file should be read and write protected; only the BEA Tuxedo administrator should be granted access.

See "Security" for additional information.

-R Retry_interval

If the gateway server is unable to establish a connection with the BEA TOP END system, or if an existing connection is broken, the server will, by default, retry to establish a connection every 60 seconds. This time interval (in seconds) may be set to a different value using -R. Setting -R to 0 turns off retry. If you do so and specify RESTART=Y then, when a connection cannot be established or is broken, the gateway server exits and restarts.

If a connection to the BEA TOP END system is not available, the services on that system are not offered by the gateway server.

-w wait_time

When the GWTUX2TE gateway server sends a request to the BEA TOP END system, it waits for a response, by default, for 30 seconds. The -w parameter allows the waiting time to be specified. Specifying a waiting time of 0 indicates infinite waiting time.

The GWTE2TUX gateway server does not provide a configurable waiting time, so normal timeout parameters may be configured in TUXCONFIG.

-u username -g groupname

If access control lists are being used for BEA Tuxedo services, then both the -u and -g options should be specified for a GWTE2TUX gateway server. By default, the gateway uses guest privileges.

See "Security" for additional information.

Programming Paradigms

The GWTUX2TE and GWTE2TUX gateway servers support request/response messages only. The following BEA Tuxedo client API calls for sending and receiving are allowed:

tpcall()
tpacall() (with or without TPNOREPLY flag)
tpgetrply()
tpforward()

BEA TOP END servers cannot set the APPL_CONTEXT flag. If this flag is set, the gateway server dissolves the BEA TOP END dialog and returns an error (TPESVCFAIL) to the BEA Tuxedo client.

The following BEA TOP END client API calls are allowed:

tp_client_send
tp_client_receive

Buffer Types

The GWTUX2TE and GWTE2TUX gateway servers support BEA Tuxedo CARRAY (X_OCTET) buffers only. Attempts to send other types of buffers from a BEA Tuxedo application generate an error, which is logged by the gateway server.

Configuration

The GWTUX2TE and GWTE2TUX gateway servers use the BEA TOP END remote client and remote server services. GWTUX2TE assumes the role of a BEA TOP END client and makes use of the remote client services. GWTE2TUX assumes the role of a BEA TOP END server and makes use of the remote server services. Therefore, you must provide a BEA TOP END remote client/server configuration file on any BEA Tuxedo node running these gateway processes.

BEA TOP END Remote Client/Server Configuration File

The BEA TOP END remote client/server configuration file is described in the BEA TOP END Remote Client Services Guide; this section provides a brief description of the file.

Entries in this configuration file are formatted as follows:

[top end configuration file]
[component type] remote server
[system] sysname
[primary node] machine_name        portnum

The component type entry should be set to remote server. The system entry should match the name of the BEA TOP END system. The primary node entry should be set to the machine name and port number of the BEA TOP END Network Agent (NA).

A secondary node may also be specified. This node can be used when a connection to the primary node cannot be established. If multiple secondary nodes are specified, the BEA TOP END system uses a "round robin" technique to load balance the connections. This feature enables multiple instances of a gateway server to connect to different nodes on the BEA TOP END system, as follows:

[secondary node] machine    28001
[secondary node] machine2   28001

The optional target parameter is also supported by the GWTUX2TE and GWTE2TUX gateway servers.

The following parameters are not supported by the GWTUX2TE and GWTE2TUX gateway servers; do not include them in the configuration file.

shutdown
codeset
maxconctx

Each gateway process may connect to only one BEA TOP END system, as specified by [system] in the TOPENDRC.cfg file. A second gateway process may be configured to connect to a different BEA TOP END system. Use the CLOPT -c parameter to point to a second configuration file.

Service Definition File

The service definition file has the following syntax:

*TE_LOCAL_SERVICES # For BEA TUXEDO services accessible by TOP END clients
Servicename PRODUCT=product_name FUNCTION=function_name
    QUALIFIER=function_qualifier

*TE_REMOTE_SERVICES # For TOP END services accessible by BEA TUXEDO clients
Servicename PRODUCT=product_name FUNCTION=function_name
    QUALIFIER=function_qualifier TARGET=target_name

Servicename indicates the BEA Tuxedo service to be imported (TE_REMOTE_SERVICE) or exported (TE_LOCAL_SERVICE).

While the PRODUCT parameter must be specified, the FUNCTION, QUALIFIER, and TARGET parameters are optional. In addition, the TARGET parameter is valid for TE_REMOTE_SERVICES only.

You can define any service definition file parameter as a default by using the following syntax:

DEFAULT: PRODUCT=product_name

All services in the TE_LOCAL_SERVICES section must have the same PRODUCT name.

If the FUNCTION parameter is not specified, the function name is assumed to be the service name. If the QUALIFIER and TARGET parameters are not specified for a service entry, no function qualifier or target name is used for that service.

Refer to Setting Up a BEA Tuxedo Application for information on valid values for BEA Tuxedo service names. Refer to the BEA TOP END Administrator's Guide for information on valid values for the PRODUCT, FUNCTION, QUALIFIER, and TARGET parameters.

Limitations

The gateways do not support the following:

Transactions
Conversations
Events
Unsolicited notifications
Queues (/Q, RTQ)
Encryption
Compression
Message size above 30K
Migration
Formats
MCC and LMA

Security

The following table lists the appropriate security settings for various configurations.

Gateway Server Security

For this Server	If. . .	Then. . .
GWTUX2TE	The BEA TOP END system is configured with authentication.	Set the username using the -u option. Set the password using the -p option. Protect this file using operating system protection.
GWTE2TUX	The BEA Tuxedo system is configured with SECURITY=APP_PW, USER_AUTH	No action is required.
GWTE2TUX	The BEA Tuxedo system is configured with SECURITY=ACL, MANDATORY ACL.	Set the username using the -u option, and the group name, using the -g option.

The username and groupname or username and password specified with CLOPT must also be entered into the corresponding BEA Tuxedo or BEA TOP END security database. For the BEA Tuxedo security database, the username is typically created using tpusradd(). The group name is typically created using tpgrpadd().

Portability

The GWTUX2TE and GWTE2TUX gateway servers are supported on Windows, Sun Solaris, HP-UX, IBM AIX, and NCR MP-RAS.

Interoperability

The GWTUX2TE and GWTE2TUX gateway servers must run on BEA Tuxedo release 6.5 or later. These gateway servers inter-operate with BEA TOP END 2.05 or later.

Examples

The following example shows how gateway servers are defined in the BEA Tuxedo UBBCONFIG file and in the BEA TOP END service definition file.

In this example, a BEA Tuxedo client issues tpcall() to the RSERVICE service. The request is forwarded (via the GWTUX2TE gateway) to a BEA TOP END system (pluto) and invokes a BEA TOP END service (RPRODUCT:RFUNC).

Similarly, a BEA TOP END client issues tp_client_send, specifying LPRODUCT as the PRODUCT and LFUNC as the FUNCTION. The request is forwarded (via the GWTE2TUX gateway) to the BEA Tuxedo system and invokes a BEA Tuxedo service (LSERVICE).

BEA Tuxedo UBBCONFIG File

##############
#UBBCONFIG
*GROUPS
TOPENDGRP  GRPNO=1

#
*SERVERS
GWTE2TUX SRVGRP="TOPENDGRP" SRVID=1001 RESTART=Y MAXGEN=3 GRACE=10 
	CLOPT="-- -f servicedefs -R 30"
GWTUX2TE SRVGRP="TOPENDGRP" SRVID=1002 RESTART=Y MAXGEN=3 GRACE=10
	MIN=5 MAX=5
	CLOPT="-- -f servicedefs"

BEA TOP END Service Definition File

############
#service definition file
*TE_LOCAL_SERVICES
DEFAULT: PRODUCT=LPRODUCT
LSERVICE FUNCTION=LFUNC

*TE_REMOTE_SERVICES
RSERVICE PRODUCT=RPRODUCT FUNCTION=RFUNC

BEA TOP END Remote Configuration File

# TOP END remote configuration file
[top end configuration file]
[component type] remote server
[system] pluto
[primary node] topendmach       28001

Note: Remember that the value of port in the primary node entry (which is 28001 in the listing BEA TOP END Remote Configuration File) must match the port number of the BEA TOP END Network Agent.

Software Requirements

The following software components are required:

BEA Tuxedo release 6.5
BEA TOP END 2.05

Failures

A BEA Tuxedo client receives a TPESVCFAIL under any of the following conditions:

A BEA TOP END service is unreachable.
A TOP END service returns an error.
The network link to the BEA TOP END system is unavailable.
A buffer type other than CARRAY or X_OCTET is sent by the BEA Tuxedo client.

A BEA TOP END client receives an error of TP_RESET, with the TP_EXT_SERVER_APPL extended status, under any of the following conditions:

A BEA Tuxedo service is unreachable (for example, because it is suspended).
A BEA Tuxedo service times out.
A BEA Tuxedo service returns with TPFAIL or TPEXIT.

Note that if a gateway offers a service that is not available on the corresponding system, the client receives an error (TPESVCFAIL), as indicated above, that is different from the error returned after a local service invocation. In the latter case, the client receives TPENOENT for the BEA Tuxedo system or TP_SERVICE for the BEA TOP END system.