Micro Focus External Call Interface

Programming for Micro Focus External Call Interface

You can use ECI calls in your client program to communicate directly with a CICS application running under Enterprise Server, and bypass the need for any third-party software at all.

Client-side support

ECI entry points such as CICSEXTERNALCALL are exposed by the casbnccl module which is supplied as a dynamic load library on Windows and a callable shared object on UNIX and Linux platforms.

Client programs should call this module either by coding a CALL statement, or by using an INITCALL(casbnccl) compilation directive. Currently, there is no facility to link the casbnccl module into a client application.

Java client support

Micro Focus also provides an ECI API for Java clients. Using this API, you can invoke CICS programs running on Enterprise Server, and do it without the help of CTG. You can invoke CICS programs using either extended mode (transactional) or non-extended mode (non-transactional).

Note: The Java client ECI API supports only synchronous calls to Enterprise Server.

To use the API, you typically set up the connection with host, port, connection type and trace flags. After populating the CommArea object and the CCLParams object with an appropriate CICS program name, user ID, and password, the API sends the request to the enterprise server and gets a ECIResponse object back from the server. In case of an exception, the enterprise server returns either a CICSException or an AbendException.

An explanation of how you change your Java code to work with Micro Focus ECI calls is in Micro Focus ECI Java API.

Configuration

To configure an Enterprise Server region to use the ECI, set the ES_LEGACY_ECI environment variable to Y. For example, ES_LEGACY_ECI=Y.

If the amount of data to be returned from the CICS programs that you will be running will be approximately more than twice the size of the input data, set the ES_ECI_MAX_RESP environment variable to the maximum expected response size (in bytes). For example, ES_ECI_MAX_RESP=70000.

Locating a Server

The simplest method of communicating with a server in a COBOL program is via a Micro Focus ECI extension. This feature is enabled with these environment variables:

ES_REGION	An eight character region/server ID. Example: ES_REGION=myserver Implies use of shared memory to a local server.
ES_ECI_SOCKET	An eight character region/server ID and web services listener port separated by a colon (<server>:<port>). Example: ES_ECI_SOCKET=myserver:9001 Implies use of TCP/IP to a local or remote server.

The two environment variables are mutually exclusive. However, if you do use both, ES_ECI_SOCKET takes precedence over ES_REGION.

If you omit to use either of these environment variables, then the mode of operation is the same as that for IBM CTG. In this instance, the server to which the request is directed is identified through the ECI-SYSTEM-NAME variable in the ECI parameter block, and takes a null- or space-padded value, which must match a server definition in the MFDS repository.

The location of this repository can be specified either by editing the mf-client.dat file, or by setting the environment variable ES_ECI_CCITCP2 which takes the value: <host>:<mfds-port>, for example:

ES_ECI_CCITCP2=localhost:86

The mf-client.dat file can be found in the \bin and \bin64 directory of your Micro Focus COBOL product installation on Windows, and in /etc on UNIX and Linux.

Long password/pass phrase support

Micro Focus ECI support allows for user IDs and passwords greater than 8 characters in length. This is achieved by appending the IBM ECI v2 fields to the v1 structure. For example, in C:

#pragma pack(1)
#define ECI_VERSION_2A 6

	struct
	{
		ECI_PARMS	eci_base_parms;
		short		eci_v2_ext_filler1;
		short		eci_v2_ext_filler2;
		void*		eci_v2_ext_filler3;
		char*		eci_userid_ptr;
		char*		eci_password_ptr;
	} eci_ext_parms;

#pragma pack()

Before invoking CICS_ExternalCall() execute the following:

eci_ext_parms.eci_base_parms.eci_version = ECI_VERSION_2A;
eci_ext_parms.eci_userid_ptr = uid;
eci_ext_parms.eci_password_ptr = pwd;

Where uid and pwd are null terminated strings.

To accomplish the same in COBOL, add the following ECI-PARMS definition in the IBM cicseci.cbl file inserted just after the ECI-TPN declaration:

           03                          pic x(2)    comp-5.
           03                          pic x(2)    comp-5.
           03                          pointer.
           03  ws-eci-user-id-ptr      pointer.
           03  ws-eci-passwd-ptr       pointer.

Note: If it is not possible to modify the cicseci.cbl file, add the following code to your program as an alternative:

Data definition:

       78  78-eci-parm-length              value length of ECI-PARMS.
       01  ws-eci-extended-parms.
           03  ws-eci-base-parms       pic x(78-eci-parm-length).
           03                          pic x(2)    comp-5.
           03                          pic x(2)    comp-5.
           03                          pointer.
           03  ws-eci-user-id-ptr      pointer.
           03  ws-eci-passwd-ptr       pointer.

Procedural code:

           move 6                      to eci-version
           move eci-parms              to ws-eci-base-parms

           call eci-entry-pptr using
             by reference              ws-eci-extended-parms
           returning eci-error-id
           end-call
           move ws-eci-base-parms      to eci-parms