MainframeSupports
tip week 48/2005:

For many years it has been possible to call a CICS program running in CICS from a batch program or a program running in TSO, but this facility is only rarely used. The interface called EXCI is mainly known by the CICS systems programmers and they use it for install of CICS definitions and newcopy of programs, but EXCI can call any program running in CICS. Therefore I will let you know about EXCI as well.

Your first task is to find out if EXCI is ready to be used on your CICS region. Use CEMT I CONN for this task. One of the listed Con() must have the parameters Ins Irc Exci, but no Net() parameter. There might be some Con() entries with the Exci parameter and the Net() parameter, but they cannot be used for our porpose. If there isn't a suitable Con() entry, you must ask your CICS systems progammer to do a CEDA install of the sample CICS group called DFHEXCI. In the CICS group you really only need the definitions EXCG CONNECTION and EXCG SESSIONS. You or your systems programmer can copy those definitions to a new CICS group and then just CEDA install this new group.

Your next task is to create a batch program that issues a EXEC CICS LINK to the CICS program you want to execute. This EXEC CICS LINK should look like this:

EXEC CICS
  LINK PROGRAM('CICSPGM')
  COMMAREA(MYCOMMAREA)
  APPLID(CICSNAME)
  SYSCONRETURN
  RETCODE(RC-AREA)
END-EXEC

The parameters PROGRAM and COMMAREA are used in the same way as when running in CICS. The new parameters are APPLID, SYSCONRETURN and RETCODE. APPLID must contain the VTAM name of the CICS region where you want to execute CICSPGM and RETCODE must contain an area in your program with the following definition:

01 RC-AREA.
  02 RESP PIC S9(9) COMP.
  02 RESP2 PIC S9(9) COMP.
  02 ABENDCODE PIC X(4).
  02 MSGLEN PIC S9(9) COMP.
  02 MSGADDR POINTER.

In your linkage section (in PL/1 a variable BASED(MSGADDR) you should declare a variable 01 MSGAREA PIC X(250). If you want to, you can use a DEPENDING ON MSGLEN. The fields RESP, RESP2 and ABENDCODE need no further explanation, I hope. In the variable MSGLEN will be returned the number of bytes that CICS has returned in the message text at the location indicated by MSGADDR. To address this text in COBOL you must issue a SET ADDRESS OF MSGAREA TO MSGADDR.

When you compile the program you have to send it through the CICS precompiler using precompile option EXCI. In the linkage editor (the binder) you must link the program using module DFHXCSTB. This module is found in hlq.CICS.SDFHEXCI. You have to find out by asking your CICS systems progammer what you should substitute hlq with.

Now you are ready to run your program for the first time. The STEPLIB concatenation in your batch job must include dataset hlq.CICS.SDFHEXCI to make it work. In your test runs you should start by printing the complete RC-AREA and examine all the returned values in order to find out what went wrong. For this purpose the CICS External Interfaces Guide is indespensable. If it works the first time you have witnessed a miracle. The use of EXCI is protected by RACF and therefore you should also look for any RACF messages if it goes wrong. Show the RACF message to your nicest RACF administrator so that he or she can give you the correct authorizations. When you have been properly authorized the program usually works. Good luck.

Previous tip in english        Sidste danske tip        Tip list