7 ECI Client Support

This chapter contains the following topics:

• Overview
  
• Introduction
  
• Platform
  
• Installation and Setup
  
• Encoding and Decoding
  
• Security
  
• Failover
  
• Diagnostic
  
• Limitation and Compatibility
  

7.1 Overview

The external interfaces allow non-CICS applications to access and update CICS resources by calling CICS programs. When communicating with CICS, the external interfaces enable non-CICS programs to access and update resources on any CICS system. This method of using the external interfaces supports such activities as the development of graphical user interface (GUI) front ends for CICS applications and allows the integration of CICS systems and non-CICS systems.

Oracle Tuxedo Application Runtime for CICS and Batch provides the target environment for migrating mainframe applications from IBM z/OS to an open systems application grid running Oracle Tuxedo.

When customers choose to use Oracle Tuxedo Application Runtime for CICS, ECI emulator enables customers to keep using their existed program without code change.

7.2 Introduction

CICS Transaction Gateway and CICS Universal Client provide ECI programming interface for C, C++, COBOL, COM, .NET, and JAVA. Regarding that the implementation of programming interface is done in dynamic load library (DLL), the basic idea of ECI emulator is to replace the library and so users can keep using their application as if nothing changed; in DLL, ECI request is routed to Tuxedo and leverages all the benefits provided by Tuxedo.

This figure demonstrates how ECI Emulator works. In this document, we focus on ECI C API.

Figure 7-1 ECI Emulator

Note:

For ECI C API, only ECI v1 API CICS_ExternalCall (ECI_Parms) is supported.

For more information, refer to Supported ECI API Parameters in CICS Commands and Parameters Coverage.

7.3 Platform

The supported platforms are listed in the Supported Platforms.

7.4 Installation and Setup

This section contains the following topics:

• Installation
  
• ECI Connection to ART CICS
  
• Configuration on ART CICS
  

7.4.1 Installation

The delivery of ECI Emulator is a ZIP package, including one cclapi32.dll file and other Tuxedo dependency files. To use ECI Emulator, users need to install CICS Transaction Gateway or CICS Universal Client and unzip the package under the directory, where the original cclapi32.dll is located in, to replace the original DLL with the delivery.

7.4.2 ECI Connection to ART CICS

In typical case, user application runs on Windows while ART CICS runs on Linux. To build connection between ECI client and ART CICS, Tuxedo /WS is used.

Users need to set environment variables before calling ECI client application. For example:

set TUXDIR=<where the delivered package will be unzip to>

set WSNADDR=//<machine>:<port>

7.4.3 Configuration on ART CICS

CICS programs that are invoked by an ECI request must be configured as DPL programs on ART CICS Runtime as the following:

• Configure the program in programs.desc, and specify the system name in REMOTESYSTEM field.
• Configure ARTDPL server in ubbconfig, and specify the system name using ARTDPL -s option.

  In ECI call CICS_ExternalCall (ECI_Parms), specify the program name using eci_program_name parameter, and the system name using eci_system_name parameter.

  Note:

  For more information about ART CICS DPL configuration, please refer to Implementing Distributed Program Link (DPL).

7.5 Encoding and Decoding

If the code page of the user application is different from that of the server, data conversion in a COMMAREA must be performed, and then two cases, legacy user application and new created user application, are required to handle.

For legacy application, the data in COMMAREA could be converted to EBCDIC before such legacy application connects server; however, regarding that the data flow on ART CICS is in ASCII format, ECI emulator needs to both convert COMMAREA from EBCDIC to ASCII before ECI request is routed to ART CICS and convert returned information back to EBCDIC.

For new created application, users could use ASCII directly without any conversion operation needed. To do this, we introduce an environment variable CTG_CLIENT_CHARSET. If its value is set to “EBCDIC”, ECI Emulator is to perform data conversion for COMMAREA between EBCDIC and ASCII; by contrast, if this environment is not set or its value is not “EBCDIC”, no conversion will be done.

7.6 Security

In ECI parameter block fields, the supplied user ID and password are used in subsequent security checking in the server. Usually, eci_userid and eci_password are used, but they are 8 character fields. Therefore, if a user ID or password more than 8 characters is required, users should set eci_userid and eci_password to nulls, and use fields eci_userid2 and eci_password2 instead.

Regarding that the security mechanism of ART CICS is different from the security mechanism in ECI request, a problem occurs if security is enabled on ART CICS requiring user ID, password, and application password while there is no application password defined in ECI parameter. To solve this problem, ECI Emulator offers two alternatives for users.

1. Set application password as empty when enabling security in ART CICS side. ECI Emulator can read user ID and password from ECI parameter and then feed application password with an empty string when doing tpinit()
2. Specify application password in an environment variable CTG_APP_PWD. If it is defined, the content in this variable will be used as application password.

If security is not enabled in ART CICS, security checking will not be performed even user ID and password are supplied in ECI parameter.

7.7 Failover

Tuxedo / WS allows to configure alternative network address connecting to /WS remote clients. This feature is used in ECI Emulator to implement failover. More precisely, the feature enables users to configure multiple WSL servers in UBBCONFIG and set environment variable WSNADDR with all alternative network address on client side.

For example, users can set environment variables as “set WSNADDR=//bjlinux16:46249, //bjlinux16:46246” when first address is not available; then the next address will be picked up automatically.

7.8 Diagnostic

This emulator provides a mechanism for users to diagnose the problems they met. To enable emulator log, users can set environment variables CTG_CLIENT_TRACE_FILE to specify log file name and CTG_CLIENT_TRACE_LEVEL to set log level.

The log level is ranged from 0 to 4 inclusive: 0 (no log), 1 (error), 2 (warning), 3 (info), and 4 (debug).

If environment variable CTG_CLIENT_TRACE_FILE is not set, userlog will be used.

If environment variable CTG_CLIENT_TRACE_LEVEL is not set, default log level will be set to error, meaning only error log will be printed. If CTG_CLIENT_TRACE_LEVEL is set with invalid log level, such as a negative number, debug level will be used.

7.9 Limitation and Compatibility

This section contains the following topics:

• Limitation
  
• Compatibility
  

7.9.1 Limitation

Only supports encoding/decoding on the whole eci_commarea between ASCII and EBCDIC; MBCS is not supported.

7.9.2 Compatibility

1. Most ECI return code does not have matched error code in Tuxedo. If ECI call is failed and there is no matched Tuxedo error code, this emulator will only return a general error code ECI_ERR_SYSTEM_ERROR and users can view detailed error information and diagnose problem by enabling log output. Supported ECI defined return codes are listed below:
   • ECI_NO_ERROR
   • ECI_ERR_SYSTEM_ERROR
   • ECI_ERR_INVALID_EXTEND_MODE
   • ECI_ERR_INVALID_CALL_TYPE
2. ECI emulator supports both customer legacy ECI program and new created ECI client.