Developing applications

The programmers that want to use XECI native libraries to communicate with server programs must apply the following guidelines.

Each time the programmer wants to call the remote program, it must invoke one of the  XECI functions (CICSEXTERNALCALL or xeci_remote_link), providing the input parameters in the I/O data structure. Once the server program replyed, the XECI function will return the control to the caller, which have to analyze to output parameters in the I/O structure.

The programmer identifies the server system by an 8 bytes identifier which is dynamically mapped to the corresponding internet address (IP address + port) where the XECI server is listening. The mapping between the 8 bytes name and the full address is configured in the XECI configuration file.

Function names

XECI functions may be invoked by xeci_remote_link or by its alias CICSEXTERNALCALL. Both these functions have the same behaviour and the same call interface.

Parameters

The I/O data area is described in by the C structure xeci_parms defined in the header file "xeci.h", and by the COBOL area ECI-PARMS, defined in the copybook "XCICSECY.cpy". Both these files are located in $XFRAMEHOME/utils.

When invoking the remote program at least 2 information must be provided in the I/O area:

If a COMMAREA must be exchanged with the server program, you must also provide:

Sample calls

This is the sample of a client program written in COBOL that invokes a remote program:

move low-values to eci-parms
move "XECISRV"  to eci-program-name
move "XCICSSRV" to eci-system-name
move "TPNX"     to eci-tpn
move "hi! I'm the client"    to commarea
move length of commarea      to eci-commarea-length
set eci-commarea             to address of commarea
call "CICSEXTERNALCALL" using by reference eci-parms
                       returning eci-error-id.

or in C language:

memset(&parms, 0x00, sizeof(struct xeci_parms));
memcpy(parms.eci_program_name, "XECISRV ", 8);
memcpy(parms.eci_system_name,  "XCICSSRV", 8);
memcpy(parms.eci_tpn, "TPNX", 4);
strcpy(commarea, "HI! I'm the C client program");
parms.eci_commarea=commarea;
parms.eci_commarea_length=256;
rc=xeci_remote_link(&parms);

Complete XECI samples for UNIX/Linux may be found in the directory $XFRAMEHOME/samples/xcics/xeci. Samples for Windows may be found in the XECI package for Windows.

Building client applications

UNIX/Linux

Client applications that use XECI, must be compiled including the XECI structures definition: xeci.h for C/C++ and XCICSECI.cpy for COBOL. Both of them are in the directory $XFRAMEHOME/utils. C sources must also include the file "xport.h" (in $XFRAMEHOME/include).

Once compiled, they have to be linked with the XECI shared library (libxeci.so/sl/dll).

Programs running in the XFRAME environment may take advantage of the dynamic loading features of the XFRAME batch runtime: you simply have to set up the dynamic loading of the shared loading before to start the runtime. I.e.

export XRUN_LIBRARIES=$XFRAMEHOME/lib/libxeci.so
xrun MYCLIENT

If your program does not use XFRAME facilities, you have to specify the XECI library at link time.

I.e.

include $(XFRAMEHOME)/include/xport.make
 
COMPILE=$(CC) -I$(XFRAMEHOME)/include -I$(XFRAMEHOME)/utils
 
all: xeciclt
 
xeciclt: xeciclt.c
       $(COMPILE) -o xeciclt -L$(XFRAMEHOME)/lib -lxeci xeciclt.c

Windows

On Windows client XECI APIs are made available through these files:

C/C++ must include "xeciw32.h" and they must be linked with "xeciwin.lib" in order to acces the API contained in the DLL.