Micro Focus Enterprise Developer 2.3 for Visual Studio 2015 > Programming > Mainframe Programming > Mainframe Subsystem Support Developer Introduction > About CICS applications > Invoking CICS Programs Externally > Micro Focus External Call Interface

Micro Focus External Call Interface

ECI client programs can run on the same machine as the Enterprise Server, or on different physical hardware. Requests are submitted to the target region through the communication layer. If you wish to access a remote server, your programs connect via the Web Services and J2EE listener. The following diagram shows the path of the request from the client to a remote server over TCP/IP:

Alternatively, you may wish to access a local server via shared memory. The following diagram shows the path of the request from the client to a local server:

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.