HOME | SEARCH | CONTACT | PDF FILES | WHAT'S NEW
TABLE OF CONTENTS | PREVIOUS TOPIC | NEXT TOPIC
|
|
|
BEA eLink for Mainframe SNA 3.1 Information Center |
|
HOME | SEARCH | CONTACT | PDF FILES | WHAT'S NEW |
||
|
TABLE OF CONTENTS | PREVIOUS TOPIC | NEXT TOPIC |
||
The topics in this section cover activities an administrator performs to maintain BEA eLink for Mainframe SNA applications. More details about these activities can be found in BEA TUXEDO documentation. Before attempting the activities, it is essential that you become familiar with BEA TUXEDO configuration procedures.
This section covers the following administration topics:
The administrative interface for eLink SNA software has two components:
Administration Facilities
dmadmin, other shell-level commands, and by screens of the BEA TUXEDO Graphical Administrative Interface.
This subsection covers the following topics:
The
Note:
The following four The dmadmin Command Interpreter
dmadmin interactive command interpreter is used for the administration of domain gateway groups defined for a BEA TUXEDO System/T application. It can operate in two modes, administration mode and configuration mode. Configuration mode allows you to change a configuration while the application is running. The dmadmin description in Appendix A, "Reference Pages," of this guide has been edited to include material and new subcommands that apply specifically to the eLink SNA gateway.
dmadmin commands are not applicable to eLink SNA because transactions, in the BEA TUXEDO System sense, are not supported:
dsdmlog
The reference pages for these subcommands and other /Domain commands have been modified for the eLink SNA product. Use Appendix A, "Reference Pages," in preference to similar pages in the BEA TUXEDO Reference Manual.
The SNA Communications Resource Manager ( Please refer to You can manually start the When you start Please refer to Please refer to You should specify the SNACRM as a BEA TUXEDO server. This is recommended for all platforms because it ensures that start-up and shut-down of the SNACRM is controlled by the BEA TUXEDO commands
Note:
This is required if eLink SNA software is installed on a Windows NT platform or if it is used with the BEA TAP for IBM CICS system.
To specify the SNACRM as a BEA TUXEDO server, provide the equivalent UBBCONFIG parameters shown in the example in Figure 5-1.
The executable script You can use the
Note:
The SNACRM monitor does not show trace data. This data is captured in a file under the The BEA eLink for Mainframe SNA product software includes two utilities which launch and execute the The following discussion relates to the Windows NT-based The BEA eLink for Mainframe SNA software CDROM contains the following files related to the The SNACRM and PU 2.1 Servers
SNACRM) is a server that communicates directly with the PU 2.1 server to provide SNA connectivity. These servers can be started manually or via the DMINIT server. In either case, the PU 2.1 server must always be started before the SNACRM. Both servers must be started before starting the associated SNA Domain gateway.
Starting the PU2.1 Server
SNACRM in Appendix A, "Reference Pages," of this guide for information about starting the PU2.1 server.
Starting the SNACRM
SNACRM from the command line or during tmboot with the DMINIT server. Before starting the SNACRM, you should specify it as a BEA TUXEDO server (refer to "Specifying the SNACRM as a BEA TUXEDO Server"). You can either start all SNACRM processes with a single DMINIT process or individually start each one with a DMINIT server that is defined to each gateway server group.
SNACRM from the UNIX command line, the SNACRM Command Line Console puts its prompt in this window, and if exited, shuts down all of the active links. When started from DMINIT, the console is redirected to the null device. In this case, you can use the xsnacrm command to monitor the console and enable/disable tracing of SNACRM and the SNA stack.
SNACRM in Appendix A, "Reference Pages," of this guide for more detailed information.
Using DMINIT
SNACRM in Appendix A, "Reference Pages," of this guide for information about using DMINIT.
Specifying the SNACRM as a BEA TUXEDO Server
tmboot and tmshutdown. To do this, you must enter parameters defining the SNACRM as a server in the UBBCONFIG file, then provide a script to perform the startup and shutdown of the specific group that contains the server.
Enter the UBBCONFIG Parameters
Figure 5-1 Example UBBCONFIG File Entries Specifying SNACRM as BEA TUXEDO Server
Write the Script
rstsnagrp should reside in the APPDIR and contain the following lines:
# Filename = rstsnagrp
tmshutdown -g SNAGRP
tmboot -g SNAGRP The SNACRM Monitor
SNACRM monitor to set trace levels for a selected SNACRM and the associated APPC stacks. You also can observe link activity and display trace status, link status, and link statistics.
/APPDIR directory. Please contact BEA Customer Support for help in locating the trace file(s) and interpreting them.
SNACRM monitor. The xsnacrm utility is designed for UNIX platforms and requires Motif libraries. The jsnacrm utility is designed for Windows NT platforms and supplies both a Java-based application and an applet.
SNACRM monitor only. Refer to xsnacrm in Appendix A, "Reference Pages," for detailed information about the UNIX-based SNACRM monitor.
jsnacrm utility:
bealogo.gif
The In order to run both the application and the applet, you must first have the Java Development Kit (JDK) 1.1 installed on your system. You can download this kit from the following internet location:
The following paragraphs describe how to set up and run the Java applet version of the JSNACRM utility.
You must have either Netscape Communicator 4.0x or Internet Explorer 4.0x installed on your NT Windows system. You also must have the Java plug-in installed on your system. You can download this plug-in from the following internet location:
Note:
If the Java plug-in is not already installed on your system, when you attempt to open the Next, you must set up your system to accept code signed by the identity "moncrm." To do this, perform the following steps:
Prerequisite for Running the JSNACRM Utility on an NT Platform
jsnacrm utility is written in Java as both an application and an applet. The application launches and executes like any other Java application and can be set up so it is accessible from the Windows desktop. The applet launches and executes from a network browser, either Netscape Communicator 4.0x or Internet Explorer 4.0x.
http://java.sun.com/products/jdk/1.1 Running the Java Applet Version
PREREQUISITES for RUNNING the JAVA APPLET VERSION
http://java.sun.com/products/plugin
jsnacrm.html file, the program prompts you for an automatic download of the plug-in by the browser.
moncrm in your JDK 1.1 identity database. By entering the
parameter true, you establish moncrm to be a trusted identity.
javakey -c moncrm true
moncrm certificate into your identity database. To associate the
certificate with the identity, use the nickname moncrm as the first argument to the
javakey command.
To start the Java applet in an existing browser, open the file:
<tuxedo-path>\bin\jsnacrm.html
To build a shortcut to start the Java applet using a separate instance of your network browser, enter the following command:
<browser-pathname> %TUXDIR%\bin\jsnacrm.html
Set up your applet version to monitor either a local or a remote SNACRM. To do this, you make selections on the Java(TM) Plug-in Properties control panel. This control panel is automatically downloaded with the plug-in and is initiated from the Windows Start Programs pop-up menu. Refer to on-line documentation about the control panel at the following internet location:
http://java.sun.com/products/plugin/1.1.1/docs
Once the Monitor screen displays (Figure 5-2), you enter in the field at the top of the screen the address of the SNACRM you want to monitor.
To monitor a local SNACRM, select Applet Host from the Network access drop-down menu. Type the following in the Enter SNACRM Address panel:
//localhost:port
where:
localhost
port
To monitor a remote SNACRM, select Unrestricted from the Network access drop down menu. Type the following in the Enter SNACRM Address panel:
//remotehostname:addresswhere:
remotehostname
address
The GUI contains two screen areas that require user entry and four screen areas that display information about the SNACRM being monitored. Status messages are displayed at the bottom of the screen. The GUI screen functions are listed in Table 5-1 and shown in Figure 5-2.
The Java application version displays and operates identically to the applet version. Refer to screen definitions and functions discussed under "Running the Java Applet Version."
To build a shortcut to start the Java application version, perform the following steps:
Figure 5-2 The SNACRM Monitor Running as an Applet on a Network Browser
Running the Java Application Version
jrew -classpath %ClassPath%;jsnacrm.jar jsnacrm
To run from a command window, perform the following steps:
The eLink SNA gateway software provides a command line tool you can use to activate and de-activate links that have been defined in the DM_SNALINKS section of the DMCONFIG file. This tool consists of two commands and their associated parameters: crmlkon and crmlkoff.
Note:
If a link to a remote host is de-activated and re-activated by the host, the eLink SNA software normally re-establishes the link automatically. If this does not occur, you can use the crmlkon command to re-establish the link.
You can start one or more SNA links with this command. Use the following syntax:
crmlkon {-n} {hostname:port} {-v} {-i} {h} {linkname}...where:
Note:
There is no notification that the link(s) started with the crmlkon command are activated. Use the SNACRM monitor to verify a link is active. Refer to "The SNACRM Monitor."
You can stop one or more SNA links with this command. Use the following syntax:
crmlkoff {-n} {hostname:port} {-v} {-I} {-h} {linkname}...where:
Note:
There is no notification that the link(s) stopped with the crmlkoff command are de-activated. Use the SNACRM monitor to verify a link is not active. Refer to "The SNACRM Monitor."
This subsection covers the following topics:
In order for any security checking to occur, the BEA TUXEDO Local Domain and the Host System must have security mechanisms in place. For the Local Domain, this is the Authorization Server. For the Host System, this is the External Security Manager. Figure 5-3 shows these elements.
There are four sections in two BEA TUXEDO configuration files in which you specify parameters bearing on Local Domain security. The two configuration files are DMCONFIG and UBBCONFIG.
Userid and password mapping between the Local Domain and the Host System also bears on security. There are five
Caution:
Mixed environment security is more complex than depicted in Figure 5-3. A domain without an operational security mechanism in place accepts all transaction requests by treating userids as "trusted users." Refer to BEA TUXEDO documentation for more detailed information about domain security.
The configuration sections where security is specified are:
Security Overview
DMADMIN subcommands which you use to enter userids and passwords, set up mappings, remove mappings, remove userids and passwords, and modify passwords.
Figure 5-3 BEA eLink for Mainframe SNA Security Elements
Where You Specify Security Parameters
RESOURCES section of the UBBCONFIG file
DM_LOCAL_DOMAINS section of the DMCONFIG file
The where UBBCONFIG File Security Parameters
RESOURCES section in this file contains a SECURITY parameter which works in conjunction with the SECURITY parameter in the DMCONFIG file to establish how eLink SNA controls access to the BEA TUXEDO local domain. This parameter takes the form:
SECURITY = {value}value is:
NONE
APP_PW
USER_AUTH
APP_PW, but additional authorization is required on a per-user basis.
ACL
USER_AUTH, but additional access-control checks are done on service names, queue names, and event names. If no Access Control Lists (ACL) exists for a given name, access is granted.
MANDATORY_ACL
ACL, but if no ACL exists for a given name, access is denied.
In most cases, the UBBCONFIG file has already been configured and you don't need to establish the SECURITY parameter settings, but examining this file enables you to ascertain how eLink SNA enforces security.
If this parameter is set to NONE, no security is enforced. If set to APP_PW, the local BEA TUXEDO domain's Authorization Server prompts for the application password. If set to USER_AUTH, ACL, or MANDATORY_ACL, the qualified security is enforced as specified.
Three sections in the DMCONFIG file contain parameters affecting eLink SNA control of access to the BEA TUXEDO local domain:
DM_LOCAL_DOMAINS section contains a SECURITY parameter which specifies the type of security enforced for the BEA TUXEDO local domain.
The where DM_LOCAL_DOMAINS section
SECURITY parameter settings in this section work in conjunction with the SECURITY parameter in the RESOURCES section of the BEA TUXEDO local domain's UBBCONFIG file to establish how eLink SNA controls access to the BEA TUXEDO local domain. The parameter takes the form:
SECURITY = {value}value is:
NONE
APP_PW
DM_USER_PW
If this parameter is set to NONE or APP_PW, the local domain takes no action with regard to security. If this parameter is set to DM_USR_PW, the local domain enforces security according to the setting in the UBBCONFIG file (refer to "UBBCONFIG File Security Parameters").
This section of the DMCONFIG file is dedicated to eLink SNA parameters. It records the security in effect for the host system. It correlates to the values set for the ATTACHSEC parameter in the connection resource definition. In the following parameter definition, remote refers to the TUXEDO domain and local refers to the host system. The parameter takes the form:
SECURITY_TYPE = {value}where value is:
LOCAL
LOCAL is the default value.
IDENTIFY
VERIFY
PERSISTENT
MIXIDPE
The values LOCAL and IDENTIFY are roughly equivalent to NONE and APP_PW for the SECURITY parameter in the DMCONFIG file.
This section contains local Access Control Lists (ACL) used by the BEA TUXEDO local domain to restrict access by remote regions to local resources. (Refer to "Security Administration" in the BEA TUXEDO Administrator's Guide.) Each entry consists of an ACL_NAME resource identifier along with a list of required parameters designating remote domains permitted to access the resource. If no entry exists for a local service, the service is accessible to all remote domains.
The domain administrator can add or delete users from the domain security table in two ways: first, through data entry panels in the TUXEDO System administration Graphical Administrative Interface; second, by using the dmadmin command.
The combined settings of the SECURITY parameters in the UBBCONFIG and the DMCONFIG files have the following effects:
DM_LOCAL_DOMAINS Security parameter is set to NONE or APP_PW, no action is taken by the eLink SNA gateway with regard to security.
UBBCONFIG file SECURITY parameter must be set to one of USER_AUTH, ACL, or MANDATORY_ACL;
DMCONFIG file DM_LOCAL_DOMAINS section SECURITY parameter must be set to DM_USER_PW
DM_SNALINKS SECURITY parameter must be set to IDENTIFY or VERIFY.
(Refer to Table 5-2 for a summary of the file settings required to achieve different security combinations for inbound requests from the host system.)
If security is to be enforced by both the local domain and the host system for each request outbound from the local domain, the following settings must be made:
UBBCONFIG file SECURITY parameter must be set to one of USER_AUTH, ACL, or MANDATORY_ACL
DM_LOCAL_DOMAINS section SECURITY parameter must be set to DM_USER_PW
DM_SNALINKS SECURITY parameter must be set to IDENTIFY or VERIFY
(Refer to Table 5-3 for a summary of the file settings required to achieve different security combinations for outbound requests from the local domain.)
For a request sent to the host system, the local principal userid is located in the domain security table and the associated remote userid, or userid and password, are put into the conversation start-up request before being sent over the LU6.2 conversation. (This occurs if For requests sent from the host system, the local domain extracts the remote userid, or userid and password, from the conversation start-up request and checks the domain security table. That table contains pairs of local principal userids and remote userids, maintained on a service-by-service basis. The remote userid is mapped to the local principal userid. The local principal userid and password are used for further Access Control List (ACL) When a request is received from the host system, the local domain checks the Therefore, if the Table 5-2 shows settings for the
Note:
Security setting combinations other than those shown in the tables will have unpredictable results.
SECURITY is set to IDENTIFY or VERIFY in the DM_SNALINKS section of the DMCONFIG file.)
checking, as specified in the UBBCONFIG file.
DMCONFIG file ACL for the local service to see if requests from the remote domain are permitted. If the DMCONFIG file does not contain an ACL for the local service, the service is accessible to all requests.
ATTACHSEC level for the connection definition in the host system is Identify or Verify, the DMCONFIG SECURITY parameter must be set to DM_USER_PW so that a userid and a password are sent on the conversation start-up requests.
Security Setting Summary Tables
SECURITY parameters in the UBBCONFIG and DMCONFIG files required to achieve local domain and host system security combinations for inbound requests.
Table 5-3 shows settings for the
Note:
Security setting combinations other than those shown in the tables will have unpredictable results.
SECURITY parameters in the UBBCONFIG and DMCONFIG files required to achieve local domain and host system security combinations for outbound requests.
After setting up and/or checking the security settings for the BEA TUXEDO domain and the host system, you must relate the security information in both domains to each other. To do this, use the Once the user security information in both domains is mapped, you can perform administration on the affected security files in each domain. To do this, use the The following paragraphs discuss how you enter these commands. Refer to Appendix A, "Reference Pages," for detailed information about each subcommand.
Use the where:
How To Administer Security
addusr and addumap subcommands provided with the dmadmin command interpreter.
delumap, modusr, and delusr subcommands.
Adding a Userid and Password
addusr subcommand to add a BEA TUXEDO local domain's userid and password to the remote CICS/ESA domain's user and password file. Enter the following command:
addusr {-d} local_domain_id {-R} remote_domain_id {-u} remote_userid
-d
-R
-u
Use the addumap subcommand to map a local domain principal userid number to a remote domain user name. The userid must be added before it can be mapped (refer to "Adding a Userid and Password"). Enter the following command:
addumap {-d} local_domain_id {-R} remote_domain_id
{-p} local_principal_userid {-u} remote_useridwhere:
-d
-R
-p
-u
Use the delumap subcommand to remove the mapping for a local domain principal userid to a remote domain user name. Enter the following command:
delumap {-d} local_domain_id {-R} remote_domain_id
{-p} local_principal_userid {-u} remote_useridwhere:
-d
-R
-p
-u
Use the delusr subcommand to remove a local BEA TUXEDO domain's user ID and password from the CICS/ESA remote domain's user and password file. The mapping for a userid must be removed before the userid can be removed (refer to "Removing a Userid's Mapping"). Enter the following command:
delusr {-d} local_domain_id {-R} remote_domain_id {-u} remote_useridwhere:
-d
-R
-u
Use the modusr subcommand to modify a local BEA TUXEDO domain user's password recorded in a CICS/ESA remote domain's user and password file. Enter the following command:
modusr {-d} local_domain_id {-R} remote_domain_id {-u} remote_useridwhere:
-d
-R
-u
This section discusses the following aspects of data translation:
The following subsections provide suggestions to help you develop VIEW definitions for input and output buffers and records. It also explains how string data and numeric data are treated by default in the eLink SNA environment.
If you do not specify string transformation (please refer to "Programming Language String Transformation"), the rules in Table 5-4 apply.
Default Data Translation Rules
Table 5-4 Default Data Translation Rules
Note:
BEA TUXEDO provides a field type named The translation rules between C and IBM/310 data types are listed in the following table.
dec_t that supports decimal values within VIEWs. The gateway 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 5-5 Data Translation Rules between C and IBM/370 Data Types
When you create VIEW definitions for input and output records that are used by CICS/ESA applications, do not specify an extra position for the terminating NULL characters that are used in string fields.
For example, when a CICS/ESA application program expects 10 characters in an input record, specify 10 for that field, not 10 plus 1.
Note:
Although eLink SNA software does not require strings to be null-terminated, it respects null termination. When the gateway software 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 eLink SNA are fully localizable, in accordance with the X/Open XPG Portability Guides. ASCII and EBCDIC translations are loaded from message files. Refer to "Programming Language String Transformation" for more information.
The eLink SNA software contains default behaviors which should meet the requirements of most English-language applications. However, you may find it necessary to customize tables. Refer to "Code Page Translation Tables" for more information.
You can convert numeric data into different data types easily, as long as you specify enough range in the intermediate and destination types to handle the maximum value needed.
For example, you can convert an FML field of double into a packed decimal field on the remote target system by specifying an appropriate In addition, you can convert numeric values into strings, vice versa. For example, while FML buffers do not directly support the Like other domain gateways, the eLink SNA gateway uses the BEA TUXEDO Typed Buffer to transmit and receive data. When communication is between an eLink SNA application and a remote host region, there are some special considerations.
Since the remote host application does not understand the typed buffer, the BEA TUXEDO application must communicate with the host application by using an aggregate data type known as a record. A record is a flat data area defined by a template that describes the data type and length of each field in the record.
The typed buffer must be represented to the host application as a record and the record must be represented to the BEA TUXEDO application as a typed buffer. In addition, string data must be in EBCDIC format for the host region and in ASCII format for the BEA TUXEDO application.
The data may be manipulated into the correct format by the BEA TUXEDO application or remote host application, or it may be formatted prior to transmission by the eLink SNA gateway. The service definitions in the DM_LOCAL_SERVICES and the DM_REMOTE_SERVICES section of the DMCONFIG file provide parameters to describe the typed buffer/record combination required for successful communications between the applications. These parameters are The parameter definitions are made from the perspective of the receiver of the buffer, the BEA TUXEDO application which receives a typed buffer, or the remote host application which receives record data. That is, The BEA TUXEDO application buffer is a typed buffer that must be communicated to the remote host as a record containing aggregate data fields. The eLink SNA gateway looks at the service definition to determine what, if any, conversion must be applied to the data buffer. The service definition uses the In this parameter definition, The Only one The null terminated string is converted to EBCDIC. The null character is part of the converted record.
No data conversion is performed on these typed buffers. The BEA TUXEDO application or remote host application performs all conversion of data fields in the record. This includes all numeric and EBCDIC conversions.
These typed buffers are used when a data record cannot be described or converted using one of the other strong typed buffers. Strong means that eLink SNA can understand all data fields and perform the required data conversions.
These typed buffers are also options when the remote service expects many styles of data aggregation (multiple record types). The A subtype is required for these typed buffers. The subtype is the name of the view that describes the remote host record. The BEA TUXEDO buffer is converted from a C structure to the record, including EBCDIC conversion, using the compiled VIEW file. By default, the record is a COBOL structure, mapped by the remote host application using a COBOL copybook.
A subtype is required for these typed buffers. The subtype is the name of the view that describes the remote host record. The data in the typed buffer is Field Manipulation Language (FML) data. The eLink SNA converts the buffer to a record described by the view; this includes EBCDIC conversion.
The BEA TUXEDO buffer is converted from an FML typed buffer to a C structure using the subtype compiled VIEW file. The C structure is then converted to the record using the same subtype compiled VIEW file. By default, the record is a COBOL structure that is mapped by the remote host application using a COBOL copybook
An aggregate data type known as a record is received from the remote host application. The record must be converted to a BEA TUXEDO typed buffer by eLink SNA before it is passed to the BEA TUXEDO application. eLink SNA looks at the service definition to determine what, if any, conversion must be applied to the host data buffer. The service definition uses the In this parameter definition, The Only one The null terminated string is converted to ASCII. The converted string is moved to a BEA TUXEDO STRING typed buffer.
No data conversion is performed on these typed buffers. The remote host application or the BEA TUXEDO application converts the data fields in the record. This includes all numeric and ASCII conversions.
These typed buffers are used when the data record cannot be described or converted using one of the other strong type buffers. Strong means eLink SNA can understand all data fields and perform the required data conversion.
These typed buffers are also options when the remote service expects many styles of data aggregation (multiple record types). The A subtype is required for these typed buffers. The subtype is the name of the view that describes the remote host record. The remote host record is converted to a BEA TUXEDO typed buffer. The compiled VIEW file is used to perform the data and ASCII conversion on the host record. By default, the host record is a COBOL data aggregate and the converted typed buffer is mapped by the BEA TUXEDO application using a C structure.
A subtype is required for these typed buffers. The subtype is the name of the view that describes the remote host record. The host record is converted to an FML buffer that is passed to the BEA TUXEDO application.
By default, the host record is a COBOL record aggregate data type. The data is converted to a C structure, including ASCII conversion, using the compiled VIEW file. This data is then converted to an FML buffer using the field definitions associated with the VIEW.
The eLink SNA system supports remote CICS services as Distributed Program Link (DPL) programs, as described in "Introducing the BEA eLink SNA System." The DPL support is performed as if the BEA TUXEDO service is a peer CICS/ESA service.
In a DPL program, the application is protected from all Distributed Transaction Processing (DTP). The DPL application is a request/response service, with all data communication performed by the passing of a A basic DPL request API looks like this:
In the preceding example, the requester sends the The difference between a DPL program and a BEA TUXEDO service is that a receiving BEA TUXEDO service can resize a reply buffer, while the DPL program expects a reply buffer of a designated size. Also, a BEA TUXEDO requester can receive a resized buffer in a buffer different from the original reply buffer.
eLink SNA performs the manipulation described in the following subsections to smoothly adjust to the requirements of both types of applications.
The eLink SNA software must determine what size To determine the The remote DPL application receives a buffer of Strings and Numeric Data
Converting Numeric Data
dec_t type VIEW element.
dec_t type, you can place decimal values in string fields and map these to dec_t fields within VIEW definitions.
Application-to-Host Communications
INBUFTYPE and OUTBUFTYPE.
INBUFTYPE is used to format a typed buffer into a record for the remote host application; OUTBUFTYPE is used to format a host record into a typed buffer for the BEA TUXEDO application.
Buffers Going To The Remote Host Application
INBUFTYPE in both the DM_LOCAL_SERVICES and DM_REMOTE_SERVICES section of the DMCONFIG file to describe the type of buffer manipulation.
INBUFTYPE Parameter Definition
INBUFTYPE = type:subtype
type must be one of the designated BEA TUXEDO typed buffers described in the following subsections.
subtype value names a view and is required for certain BEA TUXEDO typed buffers.
type:subtype may be entered for the INBUFTYPE parameter.
Data Conversion for STRING Typed Buffer
Data Conversion for X_OCTET/CARRAY Typed Buffers
INBUFTYPE parameter is limited to one type:subtype.
Data Conversion for VIEW/VIEW32/X_C_TYPE/X_COMMON Typed Buffers
Data Conversion for FML/FML32 Typed Buffers
Buffers Coming From The Remote Host Application
OUTBUFTYPE in both the DM_LOCAL_SERVICES and DM_REMOTE_SERVICES section of the DMCONFIG file to describe the host record, and how to convert the record to the BEA TUXEDO typed buffer.
OUTBUFTYPE Parameter Definition
OUTBUFTYPE=type:subtype
type must be one of the designated BEA TUXEDO typed buffers described in the following subsections. The type not only determines the typed buffer, but also describes the host record.
subtype value names a view and is required for certain BEA TUXEDO typed buffers.
type:subtype may be entered for the OUTBUFTYPE parameter.
Data Conversion for STRING Typed Buffer
Data Conversion for X_OCTET/CARRAY Typed Buffers
OUTBUFTYPE parameter is limited to one type:subtype.
Data Conversion for VIEW/VIEW32/X_C_TYPE/X_COMMON Typed Buffers
Data Conversion for FML/FML32 Typed Buffers
Data Conversion For DPL Services
COMMAREA.
EXEC CICS LINK
PROGRAM()
DATALENGTH()
LENGTH()
COMMAREA()COMMAREA of DATALENGTH size and the receiving application receives the COMMAREA data contents in a buffer the size of LENGTH. The DATALENGTH size might be smaller then the LENGTH size, but the requester expects and receives the response in the original COMMAREA buffer the size of LENGTH.
DPL Requests Originating From A TUXEDO Application
COMMAREA the remote DPL service is expecting because there is no corresponding LENGTH parameter on a BEA TUXEDO request.
LENGTH value for a DPL request, the software uses the larger potential size of the INBUFTYPE or the OUTBUFTYPE parameter definitions, as described in Table 5-6.
LENGTH size and returns a buffer of LENGTH size.
If no The eLink SNA software receives a When considering the interaction between TUXEDO and host applications, you must attend to the programming languages in which the applications are written. A character string is represented differently in the COBOL language than in the C language and associated TUXEDO VIEW buffer. This is shown in Listing 5-1, which demonstrates the three ways that the same two strings are coded (LENGTH can be determined, then the largest value allowed by the CICS application is allocated. Refer to the "General Usage Notes" section.
DPL Requests Originating From a CICS DPL
LENGTH value and COMMAREA data of DATALENGTH size from the requesting CICS DPL. The software allocates a buffer of LENGTH size and moves the COMMAREA data into this buffer before performing the conversions.
Programming Language String Transformation
string1 and string2).
Listing 5-1
Three Representations of Strings
C Structure:struct text
{
char rbufsize[5];
char testnum[2];
char sendnum;
char sysid[4];
char textfld[10];
char string1[10];
char string2[16];
};VIEW text#type cname fbname count flag size null
char rbufsize - 5 - - -
char testnum - 2 - - -
char sendnum - 1 - - -
char sysid - 4 - - -
char textfld - 10 - - -
string string1 - 1 - 10 -
string string2 - 1 - 16 -
ENDCOBOL Record 01 TEXT.
05 RBUFSIZE PIC X(5).
05 TEXTNUM PIC X(2).
05 SENDNUM PIC X.
05 SYSID PIC X(4).
05 STRING1 PIC X(9).
05 STRING2 PIC X(15).
The listing shows that, in the C structure and VIEW buffer, the sizes of string1 and string2 are represented as 10 and 16 characters, respectively. However, in the COBOL record, the sizes are 9 and 15 characters, respectively. This incompatibility can cause code misalignment between C and COBOL programs if not anticipated in the source code.
To avoid such incompatibilities, the eLink SNA gateway provides a software switch to control the mapping of string data between C and COBOL applications. This switch enables you to automatically compensate for the differences in null termination and padding characteristics of the two languages.
Note: The switch operates on string fields in TUXEDO VIEW buffers only. STRING buffers are not affected by this switch.
To set the switch, use the CLOPT parameter when you configure the gateway server definition in the UBBCONFIG file. If you set the -t option of the CLOPT parameter to one of the values listed in Table 5-7, the gateway performs the corresponding string transformation. Use the following syntax format:
CLOPT="-- -t {number}"
where:
CLOPT
--
-t option, to the server.
-t
number
Note:
If you do not set the -t option of the CLOPT parameter in your server definition, by default the eLink SNA gateway performs no string transformation.
Table 5-7 C to COBOL String Transformation
| CLOPT -t Parameter Value | TUXEDO Application Language | Host Application Language |
|---|---|---|
|
Not Set |
No string transformation established | |
|
1 |
C |
COBOL |
|
2 |
COBOL |
C |
|
3 |
C |
C |
|
4 |
COBOL |
COBOL |
The following is an example of a server definition using the switch to establish string transformations between a TUXEDO application written in C and a host application written in COBOL.
*SERVERS
GWSNAX SRVGRP=GROUP1 SRVID=5 CLOPT="-A -- -t 1"
The eLink SNA software includes translation tables which enable conversions between ASCII character sets and EBCDIC character sets. This gives you 12 standardized tables to facilitate operations between TUXEDO applications using the Latin-1 ASCII code set (CP-00819) and host applications using a national language code set.
Note: Code Page Translation Tables are not supported for WebLogic Enterprise 4.0.
Each translation table consists of two mapping tables, one for outbound conversions (TUXEDO to host) and one for inbound conversions (host to TUXEDO). You do not have to specify the direction of a translation. All you have to determine is the national language in which the host application is written. Figure 5-4 illustrates code page translation.
Figure 5-4 eLink SNA Code Page Translation
The figure demonstrates how a TUXEDO application using the Latin-1 ASCII code page CP-00819 character set operates with a host application using German EBCDIC code page CP-00273. The eLink SNA translation table 00819x00273 provides both the inbound and outbound conversions.
To designate the translation table for your applications, make an entry in the TUXEDO DMCONFIG file definition for each remote domain. Use the CODEPAGE parameter with the following format:
*DM_LOCAL_DOMAINS
{ldom} TYPE={type}*DM_REMOTE_DOMAINS
{rdom} TYPE={type} CODEPAGE={cpname}where:
ldom
ldom must be unique across both local and remote domains.
type
TYPE can be set to one of the following values: TDOMAIN, OSITP or SNAX.
rdom
rdom must be unique across both local and remote domains.
cpname
Note:
The DMCONFIG file entries in the previous format description are intended for example only. All required entries are not shown. Refer to dmconfig in Appendix A for complete syntax requirements.
Table 5-8 lists the translation tables provided with eLink SNA software.
Table 5-8
1. The default TUXEDO ASCII and EBCDIC code pages are slightly different than CP-00819 and CP-00037.
2. CP-00819 is exactly equivalent to ISO-8859-1 (also called Latin-1 ASCII), and is used as the ASCII code page in all of the countries listed in this table.
The eLink SNA translation tables are based on IBM-defined code sets. At start up, the eLink SNA gateway loads a translation table for each remote domain.
You can modify any of the tables to suit your application translation needs, except the default TUXEDO tables, which are hard-coded. Refer to Appendix F, "Code Page Translation Tables" for detailed table contents. You must restart the gateway to change any translation table definitions.
Note:
Replicas of the default TUXEDO translation tables are included with your product software. These are provided for you to modify, if desired. They are not the actual default tables. You cannot modify the default TUXEDO tables.
The eLink SNA translation tables are located in the following sub-directory:
If no Listing 5-2 depicts entries defining one local domain (CIXA) and two remote domains (CISA and IMSA). In all cases, it is assumed that the local domain uses ASCII code page CP-00819. In the example, the two remote domains use the German and French EBCDIC code pages CP-00273 and CP-00297, respectively.
How the Translation Tables Work
$TUXDIR/udataobj/codepage
CODEPAGE specification is made for a remote domain, the eLink SNA software uses the TUXEDO default translation tables. If the software cannot find the translation table file, it generates a message 2241:ERROR Unable to access codepage table with a reason code and the gateway fails to start. (Refer to this message in Appendix D, "Error Messages" for explanations of the reason codes.) If the software cannot read the translation table file, it generates an Invalid or Corrupt message and the gateway fails to start. If the software cannot read a translation table file because of access permission, it generates a Permission Denied message and the gateway fails to start.
Example
Listing 5-2
Code Page Definition Example
# DMCONFIG
*DM_LOCAL_DOMAINS
CIXA TYPE=SNAX
*DM_REMOTE_DOMAINS
CISA TYPE=SNAX CODEPAGE=00819X00273
IMSA TYPE=SNAX CODEPAGE=00819X00297
The current size limit of remote host messages is limited to approximately 32K bytes. Any conversions resulting in records larger than 32756 bytes are not supported.
