		BEA eLink TCP for TUXEDO 3.0 Information Center
		HOME \| SEARCH \| CONTACT \| PDF FILES \| WHAT'S NEW
		TABLE OF CONTENTS \| PREVIOUS TOPIC \| NEXT TOPIC \| INDEX

Getting Ready to Configure BEA eLink TCP for TUXEDO

One of the major benefits of using eLink for Mainframe TCP for TUXEDO (hereafter referenced as eLink TCP for TUXEDO) 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 eLink TCP for TUXEDO configuration. It is through this mechanism that environmental differences, such as naming conventions and data formats, are concealed from programmers and programs.

This document provides information about the following topics:

There are three kinds of environmental differences that are isolated in the eLink TCP for TUXEDO configuration files (GWICONFIG and DMCONFIG).


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.

This document explains how eLink TCP for TUXEDO performs the following tasks:

Converts input and output data into formats that are acceptable to target systems
Translates data
Processes application errors

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

Map input data and output data that flows between the local region and remote systems and thereby facilitate the eLink TCP for TUXEDO conversion process
Specify how data is translated
Specify how to set up security
Specify how application errors are processed

In addition, this document 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. eLink TCP for TUXEDO 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 eLink TCP for TUXEDO configuration files (GWICONFIG and DMCONFIG), see "Configuring BEA eLink TCP for TUXEDO."

Note: All eLink TCP for TUXEDO configuration parameters are described in "Configuring BEA eLink TCP for TUXEDO." This document 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.

Converting Input and Output Data

This section introduces procedures that eLink TCP for TUXEDO 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 eLink TCP for TUXEDO handles input and output data.

Buffers Received from Local Programs

When eLink TCP for TUXEDO receives a buffer from a local program, it automatically determines the buffer's type.

BEA eLink TCP for TUXEDO automatically "types" input buffers that local client programs send to remote services.
BEA eLink TCP for TUXEDO automatically "types" output buffers that local services return to remote client programs.

After eLink TCP for TUXEDO determines a buffer's type, it consults the configuration file (GWICONFIG) to determine whether the buffer needs to be converted to a different format.

Input buffers sent to remote services may need to be converted to record formats that are meaningful to those services.
Output buffers 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, eLink TCP for TUXEDO transforms the buffer into the record format that is specified in the configuration.

Records Received from Remote Programs

When eLink TCP for TUXEDO receives a record from a remote system, it consults the configuration file (GWICONFIG) to determine the record's type.

After eLink TCP for TUXEDO determines a record's type, it consults the domain configuration (DMCONFIG) to determine whether 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, eLink TCP for TUXEDO transforms the record into the buffer format that is specified in the configuration.

Managing Parameters for Buffer and Record Conversion

BEA eLink TCP for TUXEDO provides four configuration parameters you can use to map buffers and records. For more information about buffers and records, see section "Buffers and Records."

Specify the following buffer configuration parameters in the domain configuration file (DMCONFIG).

INBUFTYPE - Identifies the type, and in some cases the format, of a buffer received from a TUXEDO client or server
OUTBUFTYPE - Identifies the type, and in some cases the format, of a buffer to be sent to a TUXEDO client or server

Specify the following record configuration parameters in the gateway configuration file (GWICONFIG).

INRECTYPE - Identifies the type, and in some cases the format, of a buffer to be sent to a remote gateway
OUTRECTYPE - Identifies the type, and in some cases the format, of a buffer received from a remote gateway

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 sections ("Parameters for Locally Originated Calls" and "Parameters for Remotely Originated Calls" explore these different meanings in detail.

Parameters for Locally Originated Calls

This section takes a closer look at how eLink TCP for TUXEDO 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 eLink TCP for TUXEDO gateway routes to a remote server through eLink TCP for TUXEDO.

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 eLink TCP for TUXEDO gateway 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.


Circumstance	Explanation
The remote service uses an input record that is structured differently than the client program's input buffer.	In this circumstance, the remote service uses a record that is structured differently than the client program's VIEW, X_C_TYPE, or X_COMMON buffer. For example, the remote service may expect structure members to be sequenced differently.
The remote service uses an input record that differs from the client program's input buffer in both type and structure.	In this case, the client program uses a BEA TUXEDO FML buffer and the remote service expects a corresponding record with an appropriate structure.

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

The following sections provide detailed information explaining 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 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. eLink TCP for TUXEDO uses this information to map output records from remote services to the appropriate kinds of output buffers.

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 eLink TCP for TUXEDO gateway.

You must specify the OUTRECTYPE parameter when one of the circumstances described in the following table is true.


Circumstance	Explanation
The remote service returns an output record that is structured differently than the output buffer the local client program expects.	In this circumstance, the remote service returns a record that is structured differently than the client program's VIEW, X_C_TYPE, or X_COMMON buffer. For example, the structure members of the output record may be sequenced differently than the structure members of the output buffer.
The remote service returns an output record that differs in both type and structure from the output buffer the client program expects.	In this case, the remote service returns a particular record and the local client program expects a corresponding BEA TUXEDO FML buffer.

The OUTRECTYPE 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 section takes a closer look at how eLink TCP for TUXEDO 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 Figure 3-2, a remote client program issues a service request that a remote eLink TCP gateway routes to the local eLink TCP for TUXEDO gateway. The gateway 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 OUTRECTYPE parameter describes the output record that the remote client sends to the eLink TCP for TUXEDO gateway.
The OUTBUFTYPE parameter describes the BEA TUXEDO output buffer that is provided to the local server.
The INBUFTYPE parameter describes the BEA TUXEDO input buffer that the local server returns to the eLink TCP for TUXEDO gateway.
The INRECTYPE parameter describes the input record that the local eLink TCP for TUXEDO gateway returns to the remote client program.

Guidelines for Mapping Input Records to Input Buffers

The following sections provide detailed information explaining how to use the INRECTYPE and INBUFTYPE parameters for service calls that originate on remote systems (where remote client programs call local services).

The INBUFTYPE Parameter

The INBUFTYPE parameter is used to specify the type, and in some cases the structure, of the input buffer that the eLink TCP for TUXEDO gateway expects from a local server. eLink TCP for TUXEDO uses this information to map input buffers from local server programs to the appropriate kind of input records.

Because the gateway determines the type of incoming buffers automatically at runtime, this parameter is described here for conceptual completeness only.

The INRECTYPE Parameter

The INRECTYPE parameter is used to specify the type, and in some cases the format, of the input record that the local eLink TCP for TUXEDO gateway sends to the remote client.

You must specify the INRECTYPE parameter when one of the circumstances described in the following table is true.


Circumstance	Explanation
The remote client program requires an input record that is structured differently than the input buffer the local service provides.	In this circumstance, the remote client program sends a record that is structured differently than the local service's VIEW, X_C_TYPE, or X_COMMON buffer. For example, the structure members of the input record may be sequenced differently than the structure members of the input buffer.
The remote client program requires an input record that differs in both type and structure from the input buffer the local service provides.	In this case, the remote client program requires a particular record and the local service provides a corresponding BEA TUXEDO FML buffer.

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

Guidelines for Mapping Output Buffers to Output Records

The following sections provide detailed information explaining 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 the local eLink TCP for TUXEDO gateway provides to the local server.

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 sends to the eLink TCP for TUXEDO gateway. eLink TCP for TUXEDO uses this information to convert output records from remote clients into buffers that local client programs can process.

You must specify the OUTRECTYPE parameter when one of the circumstances described in the following table is true:


Circumstance	Explanation
The remote client program provides an output record that is structured differently than the local service's output buffer.	In this circumstance, the remote client program provides a record that is structured differently than the local service's VIEW, X_C_TYPE, or X_COMMON buffer. For example, the local server program may expect structure members to be sequenced differently.
The remote client program provides an output record that differs from the local service's output buffer in both type and structure.	In this case, the remote client outputs a record and the local client program expects a corresponding BEA TUXEDO FML buffer.

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 provides.

Mapping Buffers to Records

Figure 3-3 shows all the possibilities for mapping buffers to records. The eLink TCP for TUXEDO gateway is responsible for mapping buffers to records, based on information it finds in the eLink TCP for TUXEDO configuration. This mapping occurs for TUXEDO client requests and TUXEDO server responses.

Figure 3-3 Buffer to Record Mappings

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 parameter to CARRAY, and omit the INRECTYPE parameter. 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 affects 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 parameter to STRING, and omit the INRECTYPE parameter.
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 parameter, and omit the INRECTYPE parameter.
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. Note: In the DMCONFIG file, if FML or FML32 are specified as INBUFTYPE or OUTBUFTYPE, the type must be followed by a colon (:). (Example: INBUFTYPE="FML32:")

Mapping Records to Buffers

Figure 3-4 shows all the possibilities for mapping records to buffers. The eLink TCP for TUXEDO gateway is responsible for mapping records to buffers, based on information it finds in the eLink TCP for TUXEDO configuration. This mapping occurs for remote client requests and remote server responses.

Figure 3-4 Record to Buffer Mappings

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).


1	BEA TUXEDO CARRAY output records can be copied to CARRAY output buffers. A CARRAY buffer contains raw data that is not converted or translated. Set the OUTBUFTYPE parameter to CARRAY. The OUTRECTYPE parameters need not be set. BEA TUXEDO CARRAY output records can also be copied to STRING output buffers. 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 affects the buffer when later handled as a STRING. The OUTRECTYPE should be set to CARRAY and OUTBUFTYPE should be set to STRING.
2	BEA TUXEDO STRING output records can be mapped to CARRAY output buffers. There is no data conversion or translation performed. The STRING buffer is copied through the leftmost null characters only. Set OUTRECTYPE to STRING and OUTBUFTYPE to CARRAY.
3	BEA TUXEDO STRING output records can be mapped to STRING output buffers. The buffer goes through datatype translation (i.e., ASCII to EBCDIC). OUTBUFTYPE and OUTRECTYPE parameters are set to STRING.
4	BEA TUXEDO VIEW output records can be mapped to identical BEA TUXEDO VIEW output buffers. In this situation, the data structure that the remote service returns is identical to the data structure the local client program expects. There is no need to create a new VIEW definition. Instead, specify the VIEW buffer type and the name of the existing VIEW definition with the OUTBUFTYPE parameter. The OUTRECTYPE parameter can be set to `VIEW:``viewname`, but it is not mandatory.
5	BEA TUXEDO VIEW output records can be mapped to VIEW output buffers-in any combination. However, in this situation, the data structure that the remote service returns (designated as VIEW `B' in Figure 3-4) differs from the data structure the client program expects (designated as VIEW `A' in Figure 3-4). To facilitate the conversion process, perform the following tasks: Create a VIEW definition for the data structure that the remote service returns. If the name given to the VIEW definition is different than the name that the remote service returns (that is, ATMI buffer subtype), specify the output record type and the name of VIEW `B' with the OUTRECTYPE parameter. (By doing this, you override the value the eLink TCP for TUXEDO requester automatically detects.) Specify the output buffer type and the name of an existing view (VIEW `A' in the figure) specified in the OUTBUFTYPE parameter.
6	BEA TUXEDO VIEW output records can be mapped to FML output buffers. To facilitate the conversion process, you must perform the following tasks: Create a VIEW definition that describes the data structure that the remote service returns. If the name given to the VIEW definition is different than the name that the remote service returns (that is, the ATMI buffer subtype), specify the output record type and the name of your VIEW definition with the OUTRECTYPE parameter. (By doing this, you override the value the eLink TCP for TUXEDO requester automatically detects.) Set the OUTBUFTYPE parameter to FML. Note: In the DMCONFIG file, if FML or FML32 are specified as INBUFTYPE or OUTBUFTYPE, the type must be followed by a colon (:). (Example: INBUFTYPE="FML32:")

Creating VIEW Definitions to Facilitate Buffer Conversion

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, eLink TCP for TUXEDO translates field data types as required to maintain transparency between dissimilar systems.

You should create VIEW definitions before you configure eLink TCP for TUXEDO. For complete information about VIEW definitions and related topics, see the BEA TUXEDO Programmer's Guide.

BEA eLink TCP for TUXEDO 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 make it possible to specify composite data structures that can be used:

On different kinds of machines
With different programming languages

Preparing VIEW Definitions

After determining the input and output record layouts for the remote application programs you are working with, you need to:

Create standard BEA TUXEDO VIEW definitions in files.
Run the viewc or viewc32 VIEW compiler.
Set the VIEWFILES, VIEWDIR, FIELDTBLS, and FLDTBLDIR environment variables, using a BEA TUXEDO ENVFILE if necessary (so that eLink TCP for TUXEDO 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 GWICONFIG and DMCONFIG files (by associating names of VIEW definitions with the INRECTYPE, OUTRECTYPE, INBUFTYPE, and OUTBUFTYPE parameters, as required).

For detailed information about configuring eLink TCP for TUXEDO, see "Configuring BEA eLink TCP for TUXEDO."

Note: FML fields must be specified for all VIEWs that eLink TCP for TUXEDO 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). For the FML fields to match, you must compile these VIEWs without the -n option specified.

Translating Data

When a local client program sends data to (or receives data from) a service routine on a different kind of computer, eLink TCP for TUXEDO automatically translates data as required. Translation involves changing the representation of intrinsic data types by changing attributes such as word length and byte order.

BEA eLink TCP for TUXEDO automatically translates input and output data as required, following rules that are described in the following section. Read the information carefully before you create VIEW definitions (to facilitate buffer conversion) and configure eLink TCP for TUXEDO.

Basic rules for how eLink TCP for TUXEDO translates data are described in the following subsection. For detailed information about how eLink TCP for TUXEDO handles string and numeric data, refer to the "NULL Characters in String Length Calculations (C Programs)" section.

Data Translation Rules

Here are the data translation rules that eLink TCP for TUXEDO follows:

CARRAY fields are passed untranslated as sequences of bytes.
STRING and CHAR fields 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. eLink TCP for TUXEDO 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.

The following table summarizes the relationships.


Remote Data Type	Description	View Field Type/Length
PIC X(n)	Alphanumeric characters	string / n
PIC X	Single alphanumeric character	char
PIC X(n)	Raw bytes	carray / n
PIC X	Single numeric byte	carray / 1
PIC S9(4) COMP	16-bit integer	short
PIC S9(9) COMP	32-bit integer	long
COMP-1	Single-precision floating point	float
COMP-2	Double-precision floating point	double
PIC S9((m+(n+1))/2)V9(n) COMP-3	Packed decimal	dec_t / m,n

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 eLink TCP for TUXEDO does not require strings to be NULL-terminated, it respects NULL termination. Therefore, when eLink TCP for TUXEDO 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.

BEA eLink TCP for TUXEDO provides standard character translation from ASCII-to-EBCDIC and EBCDIC-to-ASCII. eLink TCP for TUXEDO automatically performs this translation on the string data type.

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.

Enabling eLink TCP Security

The eLink TCP product supports a security feature that allows a requester from TUXEDO to pass a USERID requirement through the OTMA or CICS server interfaces for verification through RACF.

Security Checking from UNIX to Mainframe

Figure 3-5 depicts the process flow for security verifications from eLink TCP for TUXEDO on UNIX to a mainframe.

Figure 3-5 Security Checking for UNIX to Mainframe Transactions

Verify the user is a valid TUXEDO user. For valid users, access is given; for invalid users, access is rejected.
Verify user name (reviewing the tpusr file), group (reviewing the tpgrp file), and ACL (reviewing the tpacl file). If all three pass, the transaction request processes. If any one of the three are rejected, the transaction request stops and a security violation occurs.

Note: The userids in these files must match in the BEA TUXEDO and the mainframe environments or a security violation occurs.
Accept the transaction request at the mainframe gateway based on the request coming from a trusted source. No password is passed.
Verify the user name against the security system (such as RACF). If the user name is valid, a proxy is spawned. If the user name is not valid, the request is rejected and a security violation occurs.
Complete the transaction request to the server if a proxy is spawned.

Security Checking from Mainframe to UNIX

Figure 3-6 depicts the process flow for security verifications from a mainframe to eLink TCP for TUXEDO on UNIX.

Figure 3-6 Security Checking for Mainframe to UNIX Transactions

Verify the user name against the security system (such as RACF). If the user name is valid, a proxy is spawned. If the user name is not valid, the request is rejected and a security violation occurs.
Pass the transaction request from the client to the mainframe gateway.
Accept the transaction request at the UNIX gateway based on the request coming from a trusted source. No password is passed.
Determine the appkey corresponding to the supplied user name. Decode the appkey to obtain the user and group numbers. Verify the user name against TUXEDO security. If the user name passes these checks, the transaction request is accepted. If the user name fails, the request is rejected and a security violation occurs.
The TUXEDO server will verify the user's access to the requested service by examining the access control list (ACL). If access is denied, an error is returned to the client. If access is granted, the server processes the request.

Setting Up Security

Complete the following tasks to enable the security feature.

Code SECURITY in the BEA TUXEDO UBBCONFIG file. Refer to the BEA TUXEDO Administration Guide for more information.
Set up user, group, and ACL files. Refer to the BEA TUXEDO Administrator's Guide for more information.

Note: The user information in these files must match in the BEA TUXEDO and the mainframe environments or a security violation occurs.
Code the security parameter in your eLink TCP for TUXEDO configuration file (GWICONFIG). For GWICONFIG syntax and parameter definitions, refer to "Configuring BEA eLink TCP for TUXEDO."

Sample Security Files

Part of the process for setting up security for eLink TCP requires you to have user, group, and ACL files. The following sections include these sample files.

User Files

The following sample is a user file that includes user names, encrypted passwords, a userid number, group number, and a client name.

Listing 3-1 Sample User (tpusr) File

#illen:w2ZMOKeJmiU0M:1:0:TPCLTNM,someguy::
#illen:0YzvQeqzcNz56:1:0:TPCLTNM,*::
#eke:x3vG37eOqh0XE:2:0:TPCLTNM,*::
#illen:0YzvQeqzcNz56:1:1:TPCLTNM,*::
#illen:0YzvQeqzcNz56:1:2:TPCLTNM,*::
john:x3vG37eOqh0XE:2:1:TPCLTNM,*::
jim:0YzvQeqzcNz56:1:1:TPCLTNM,*::
richard:IxqosKHu5Q3BA:3:1:TPCLTNM,*::
JDOE:zBMWVUBNNBVgo:4:0:TPCLTNM,*::
smith:ULfRJzAeyGAD2:5:0:TPCLTNM,*::

Lines that begin with the pound sign (#) are users that have been changed or deleted by tpusrmod or tpusrdel.

Group File

The following sample is a group file that specifies the names and indexes of groups.

Note: The tpgrp file is only necessary when specifying ACL or MANDATORY_ACL modes for security. If you specify USER_AUTH for security, you can assign users to groups, but they do not correlate to the groups used for security by the remote system.

Listing 3-2 Sample Group (tpgrp) File

good::1:
bad::2:

ACL File

The tpacl file correlates a group and the services to which that group has access. In the tpacl file, the first field specifies what is protected, the second field specifies the type of object being protected (specified in the first field), and the third field specifies the group that has access to the object.

In the following example, only users in group 1 (john, jim, richard) can access TOLOWER, and only users in group 2 can access TOUPPER.

Note: The tpacl file is only necessary when specifying ACL or MANDATORY_ACL modes for security.

Listing 3-3 Sample ACL (tpacl) File

TOLOWER:SERVICE:1:
TOUPPER:SERVICE:2:

Considerations for Error Handling

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 eLink TCP for TUXEDO gateway.
Service routines can include information about failures in output records that are returned to client programs.

TABLE OF CONTENTS | PREVIOUS TOPIC | NEXT TOPIC | INDEX