Home     Previous Topic     Next Topic

 

5. Administering the Application Domain

The topics in this section cover activities an administrator performs to maintain 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.

Administration Facilities

The administrative interface for BEA eLink for Mainframe SNA software has two components:

The dmadmin Command Interpreter

The 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 eLink SNA.

Note: The following four dmadmin commands are not applicable to eLink SNA because transactions, in the BEA TUXEDO System sense, are not supported:

New subcommands have been added to dmadmin to support entering of userids and passwords in the domain security table. These new commands can be entered only as subcommands of dmadmin:

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 SNACRM and PU 2.1 Servers

The SNA Communications Resource Manager (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

Please refer to SNACRM in Appendix A, "Reference Pages," of this guide for information about starting the PU2.1 server.

Starting the SNACRM

You can manually start the 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.

When you start 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.

Please refer to SNACRM in Appendix A, "Reference Pages," of this guide for more detailed information.

Using DMINIT

Please refer to SNACRM in Appendix A, "Reference Pages," of this guide for information about using DMINIT.

Specifying the SNACRM as a BEA TUXEDO Server

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

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.

Enter the UBBCONFIG Parameters

To specify the SNACRM as a BEA TUXEDO server, provide the equivalent UBBCONFIG parameters shown in the example in Figure 5-1.

Figure 5-1 Example UBBCONFIG File Entries Specifying SNACRM as BEA TUXEDO Server

Write the Script

The executable script rstsnagrp should reside in the APPDIR and contain the following lines: 

# Filename = rstsnagrp
tmshutdown -g SNAGRP
tmboot -g SNAGRP

The SNACRM Monitor

You can use the 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.

Note: The SNACRM monitor does not show trace data. This data is captured in a file under the /APPDIR directory. Please contact BEA Customer Support for help in locating the trace file(s) and interpreting them.

The BEA eLink for Mainframe SNA product software includes two utilities which launch and execute the 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.

The following discussion relates to the Windows NT-based SNACRM monitor only. Refer to xsnacrm in Appendix A, "Reference Pages," for detailed information about the UNIX-based SNACRM monitor.

The BEA eLink for Mainframe SNA software CDROM contains the following files related to the jsnacrm utility:

Prerequisite for Running the JSNACRM Utility on an NT Platform

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

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: 

http://java.sun.com/products/jdk/1.1

Running the Java Applet Version

The following paragraphs describe how to set up and run the Java applet version of the JSNACRM utility.

PREREQUISITES for RUNNING the JAVA APPLET VERSION

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: 

http://java.sun.com/products/plugin

Note: If the Java plug-in is not already installed on your system, when you attempt to open the jsnacrm.html file, the program prompts you for an automatic download of the plug-in by the browser.

Next, you must set up your system to accept code signed by the identity "moncrm." To do this, perform the following steps:

  1. Create the identity 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

  2. Import the moncrm certificate into you identity database. To associate the certificate with the identity, use the nickname moncrm as the first argument to the javakey command. 

    javakey -ic moncrm %TUXDIR%\bin\moncrm.x509
STARTING the JAVA APPLET

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
RUNNING the JAVA APPLET VERSION

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
Explicitly specifies the local host.

port
Specifies the port number of the SNACRM on the local host.

To monitor a remote SNACRM, select Unrestricted from the Network access drop down menu. Type the following in the Enter SNACRM Address panel: 

//remotehostname:address

where:

remotehostname
Specifies the remote host.

address
Specifies the network address of the SNACRM on the remote host.

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.

Table 5-1 SNACRM Monitor Screen Functions
Display Section Function

SNACRM Address

This is where you enter the address of the SNACRM to be monitored.

Selected SNACRM

Displays the name of the SNACRM at the address entered in the address field.

Trace Status

Displays the currently selected trace options.

Trace Options

Link Status

Displays the current status of all remote links for the selected SNACRM. (Text may be scrolled.)

Link Statistics

Displays the current statistics for all remote links for the selected SNACRM. (Text may be scrolled.)

Message Line

Displays messages showing the either the results of automatic connection attempts or commands issued to change the trace options.

Figure 5-2 The SNACRM Monitor Running as an Applet on a Network Browser

Running the Java Application Version

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:

  1. Enter the command: 

    jrew -classpath %ClassPath%;jsnacrm.jar jsnacrm

  2. Start the application in the directory %TUXDIR%\bin so it can find its files.

To run from a command window, perform the following steps:

  1. Change directory to %TUXDIR%\bin.

  2. Enter the command: 

    jrew -classpath %ClassPath%;jsnacrm.jar jsnacrm

Security

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 DMADMIN subcommands which you use to enter userids and passwords, set up mappings, remove mappings, remove userids and passwords, and modify passwords.

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.

Figure 5-3 BEA eLink for Mainframe SNA Security Elements

Where You Specify Security Parameters

The configuration sections where security is specified are:

UBBCONFIG File Security Parameters

The 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

where value is:

NONE
No security is enforced (default)

APP_PW
Requires password authorization for BEA TUXEDO clients and administrative tools to connect to the local application.

USER_AUTH
Same as APP_PW, but additional authorization is required on a per-user basis.

ACL
Same as 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
Same as 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.

DMCONFIG File Security Parameters

Three sections in the DMCONFIG file contain parameters affecting eLink SNA control of access to the BEA TUXEDO local domain:

DM_LOCAL_DOMAINS section

The 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

where value is:

NONE
No security is enforced.

APP_PW
No security is enforced.

DM_USER_PW
User and password security is enforced.

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

DM_SNALINKS section

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
Specifies that a user identifier is not to be supplied by the remote system. LOCAL is the default value.

IDENTIFY
Specifies that a user identifier is expected on every attach request. All remote users of a system must be identified to the remote external security manager.

VERIFY
Attaches a userid and valid password to the remote region. The userid and password are controlled by the region's external security manager.

PERSISTENT
Not fully supported. Functions the same as VERIFY.

MIXIDPE
Not fully supported. Functions the same as VERIFY.

The values LOCAL and IDENTIFY are roughly equivalent to NONE and APP_PW for the SECURITY parameter in the DMCONFIG file.

DM_ACCESS_CONTROL section

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.

Security Setting Summary

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:

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:

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

If security is to be enforced by both the local domain and the host system for each request inbound from the host system to the local domain, the following settings must be made:

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

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 SECURITY is set to IDENTIFY or VERIFY in the DM_SNALINKS section of the DMCONFIG file.)

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) checking, as specified in the UBBCONFIG file.

When a request is received from the host system, the local domain checks the 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.

Therefore, if the 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

Table 5-2 shows settings for the SECURITY parameters in the UBBCONFIG and DMCONFIG files required to achieve local domain and host system security combinations for inbound requests.

Note: Security setting combinations other than those shown in the tables will have unpredictable results.

Table 5-2 Security Setting Summary (Inbound Requests from Host System)
(Col. A)
SECURITY COMBINATION 		(Col. B)
SETTINGS IN
UBBCONFIG
FILE 		(Col.C)
SETTINGS IN DM_LOCAL_DOMAINS SECTION of
DMCONFIG
FILE 		(Col. D)
SETTINGS IN DM_SNALINKS SECTION of
DMCONFIG FILE 		(Col.E)
OUTBOUND USERID and PASSWORD
ACTIVITY
(UID/PW)
LOCAL DOMAIN HOST SYSTEM

NO

NO

SECURITY = NONE or APP_PW

SECURITY =
NONE or APP_W

SECURITY= LOCAL

Not Applicable

YES

NO

SECURITY = USER_AUTH, ACL, or
MANDATORY_ACL

SECURITY =
NONE or APP_PW

SECURITY =
LOCAL

Not Applicable

NO

YES

SECURITY = NONE or APP_PW

SECURITY =
DM_USER_PW

SECURITY =
IDENTIFY or VERIFY

INVALID

YES

YES

SECURITY = USER_AUTH, ACL, or
MANDATORY_ACL

SECURITY =
DM_USER_PW

SECURITY =
IDENTIFY or VERIFY

UID or UID+PW checked by Host System

Table 5-3 shows settings for the SECURITY parameters in the UBBCONFIG and DMCONFIG files required to achieve local domain and host system security combinations for outbound requests.

Note: Security setting combinations other than those shown in the tables will have unpredictable results.

Table 5-3 Security Setting Summary (Outbound Requests from Local Domain)
(Col. A)
SECURITY COMBINATION 		(Col. B)
SETTINGS
IN
UBBCONFIG
FILE 		(Col.C)
SETTINGS
IN DM_LOCAL_DOMAINS SECTION of
DMCONFIG
FILE 		(Col. D)
SETTINGS
IN DM_SNALINKS SECTION of
DMCONFIG FILE 		(Col.E)
INBOUND USERID and PASSWORD
ACTIVITY
(UID/PW)
LOCAL DOMAIN HOST SYSTEM

NO

NO

SECURITY = NONE or APP_PW

SECURITY =
NONE or APP_W

SECURITY= LOCAL

Not Applicable

YES

NO

SECURITY = USER_AUTH, ACL, or
MANDATORY_ACL

SECURITY =
NONE or APP_PW

SECURITY =
LOCAL

INVALID

NO

YES

SECURITY = NONE or APP_PW

SECURITY =
DM_USER_PW

SECURITY =
IDENTIFY or VERIFY

UID or UID+PW from Host System ignored

YES

YES

SECURITY = USER_AUTH, ACL, or
MANDATORY_ACL

SECURITY =
DM_USER_PW

SECURITY =
IDENTIFY or VERIFY

UID or UID+PW checked by Local Domain

How To Administer Security

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 addusr and addumap subcommands provided with the dmadmin command interpreter.

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 delumap, modusr, and delusr subcommands.

The following paragraphs discuss how you enter these commands. Refer to Appendix A, "Reference Pages," for detailed information about each subcommand.

Adding a Userid and Password

Use the 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

where:

-d
Specifies the name of the local domain with which the userid and password are associated.

-R
Specifies the name of the remote domain to which the userid and password are to be added.

-u
Specifies the user name to be added. Enter the user's password when prompted.

Mapping a Userid

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_userid

where:

-d
Specifies the name of the local domain with which the userid is associated.

-R
Specifies the name of the remote domain to which the userid is mapped.

-p
Specifies the local principal userid number defined in the ACL.

-u
Specifies the remote user name as defined in the security application of the remote domain.

Removing a Userid's Mapping

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_userid

where:

-d
Specifies the name of the local domain with which the userid is associated.

-R
Specifies the name of the remote domain to which the userid is mapped.

-p
Specifies the local principal userid number defined in the ACL.

-u
Specifies the remote user name as defined in the security application of the remote domain.

Deleting a Userid and Password

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_userid

where:

-d
Specifies the name of the local domain with which the userid and password are associated.

-R
Specifies the name of the remote domain from which the userid and password are to be deleted.

-u
Specifies the user name to be deleted. Enter the user's password when prompted.

Modifying a Password

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_userid

where:

-d
Specifies the name of the local domain with which the userid and password are associated.

-R
Specifies the name of the remote domain in which the userid and password are to be modified.

-u
Specifies the user name to be modified. Enter the user's password when prompted.

Data Translations

Like other domain gateways, the eLink SNA gateway uses the BEA TUXEDO Typed Buffer to transmit and receive data. When communication is between a 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 INBUFTYPE and OUTBUFTYPE.

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, 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

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

In this parameter definition, type must be one of the designated BEA TUXEDO typed buffers described in the following subsections.

The subtype value names a view and is required for certain BEA TUXEDO typed buffers.

Only one type:subtype may be entered for the INBUFTYPE parameter.

Data Conversion for STRING Typed Buffer

The null terminated string is converted to EBCDIC. The null character is part of the converted record.

Data Conversion for X_OCTET/CARRAY Typed Buffers

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 INBUFTYPE parameter is limited to one type:subtype.

Data Conversion for VIEW/VIEW32/X_C_TYPE/X_COMMON Typed Buffers

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.

Data Conversion for FML/FML32 Typed Buffers

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

Buffers Coming From The Remote Host Application

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

In this parameter definition, 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.

The subtype value names a view and is required for certain BEA TUXEDO typed buffers.

Only one type:subtype may be entered for the OUTBUFTYPE parameter.

Data Conversion for STRING Typed Buffer

The null terminated string is converted to ASCII. The converted string is moved to a BEA TUXEDO STRING typed buffer.

Data Conversion for X_OCTET/CARRAY Typed Buffers

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 OUTBUFTYPE parameter is limited to one type:subtype.

Data Conversion for VIEW/VIEW32/X_C_TYPE/X_COMMON Typed Buffers

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.

Data Conversion for FML/FML32 Typed Buffers

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.

Data Conversion For DPL Services

eLink SNA supports remote CICS services as Distributed Program Link (DPL) programs, as described in Section 1, "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 COMMAREA.

A basic DPL request API looks like this: 

EXEC CICS LINK
       PROGRAM()
       DATALENGTH()
       LENGTH()
       COMMAREA()

In the preceding example, the requester sends the 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.

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.

DPL Requests Originating From A TUXEDO Application

eLink SNA must determine what size COMMAREA the remote DPL service is expecting because there is no corresponding LENGTH parameter on a BEA TUXEDO request.

To determine the LENGTH value for a DPL request, eLink SNA uses the larger potential size of the INBUFTYPE or the OUTBUFTYPE parameter definitions, as described in Table 5-4.

The remote DPL application receives a buffer of LENGTH size and returns a buffer of LENGTH size.

Table 5-4 DPL Request LENGTH Calculation
INBUFTYPE or OUTBUFTYPE LENGTH CALCULATION

STRING/X_OCTET/ CARRAY

For these typed buffers, only the INBUFTYPE parameter definition is used to determine the LENGTH.

VIEW/VIEW32/ X_COMMON/ X_C_TYPE

LENGTH is the maximum size of the VIEW file. This calculation takes in the potential size of both the C structure and the target record.

FML/FML32

The maximum size of the VIEW file. This calculation takes in the potential size of both the C structure, and the target record. The length of the FML buffer is not taken into account.

If no 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

eLink SNA receives a LENGTH value and COMMAREA data of DATALENGTH size from the requesting CICS DPL. eLink SNA allocates a buffer of LENGTH size and moves the COMMAREA data into this buffer before performing the conversions.

General Usage Notes

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.


Home     Previous Topic     Next Topic