This chapter contains the following topics:
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.
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.
|Note:||For ECI C API, only ECI v1 API
|Note:||For more information, please refer toin .|
The supported platforms are listed in the.
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.
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>
CICS programs that are invoked by an ECI request must be configured as DPL programs on ART CICS Runtime as the following.
In ECI call
ECI_Parms), specify the program name using
eci_program_name parameter, and the system name using
|Note:||For more information about ART CICS DPL configuration, please refer to Implementing Distributed Program Link (DPL).|
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.
In ECI parameter block fields, the supplied user ID and password are used in subsequent security checking in the server. Usually,
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_password to nulls, and use fields
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.
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.
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.
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.
Only supports encoding/decoding on the whole
eci_commarea between ASCII and EBCDIC; MBCS is not supported.
ECI_ERR_SYSTEM_ERRORand users can view detailed error information and diagnose problem by enabling log output. Supported ECI defined return codes are listed below.