EXCI – Communicating with a CICS Program from Outside of CICS

I’ve seen this kind of thing come up several times … There are resources within CICS that some process running outside of CICS needs to access. How can you do it? One answer is EXCI … This will be a brief introduction to EXCI.

EXCI refers to the External CICS Interface. This interface has been around for a long time and it allows a non-CICS program to call a CICS program, and pass information back and forth via the programs’ commarea. The non-CICS program (often a batch program) is considered the “client”, and the CICS program is considered the “server.”

Programming Interface.

The applications programmer would need to choose the programming interface to be used by the client program. There are two types of programming interfaces – the EXCI CALL interface, and the EXEC CICS interface. The EXEC CICS interface is the simpler method, but would be less efficient if a large number of calls were to be performed. The EXCI CALL interface is more difficult to understand and code, but is much more efficient, especially if a large number of calls are to be made.

The EXCI CALL interface consists of six commands, which are detailed in the CICS External Interfaces Guide:

  • Initialize-User
  • Allocate-Pipe
  • Open-Pipe
  • DPL call
  • Close-Pipe
  • Deallocate-Pipe

The first three commands establish a connection from the non-CICS client program to the CICS server program, and the final two commands close the connection. Once a connection to the server program is established, as many DPL (Distributed Program Link) calls can be made as desired before closing the connection.

The EXEC CICS interface has only one command – EXEC CICS LINK PROGRAM – which performs all six commands of the EXCI CALL interface in one invocation. So a connection has to be established and closed for each call, where with the EXCI CALL interface, the connection is established and closed once.

There is really nothing special about the server program – it is just an ordinary commarea program, and is totally unaware that it is being called from outside of CICS.

There are sample client programs in the SDFHSAMP library from the CICS installation in Assembler (DFH$AXCC), COBOL (DFH0CXCC), PL/I (DFH$PXCC), and C (DFH$DXCC). The only sample server program in the SDFHSAMP library is in Assembler (DFH$AXCS), but remember that the server is nothing more than an ordinary commarea program.

Systems Interface.

To support a given EXCI application, the CICS Systems Programmer would have to define the system interface. The system interface is a connection/session pair, similar to those set up for MRO or LU6.2 communications. There are two different types of interfaces – generic and specific. There can be only one generic interface per CICS region, and multiple EXCI programs can use it. Multiple specific interfaces can be defined in a given CICS region, and only one specific client program can use each one.

There are sample connection/session definitions for generic and specific EXCI interfaces in the DFH$EXCI group. You may want to consider putting the SDFHEXCI library in the Link List, or else it will be required to be concatenated to the JOBLIB or STEPLIB in the client’s JCL.

Limitation.

Since the EXCI interface utilizes commarea, it is restricted to the same 32K limit that the commarea has. I look for IBM to update the EXCI interface, or to introduce a new interface, that can take advantage of channels and containers. Until then, it will be necessary to utilize a non-CICS facility, such as MQ, to pass more than 32K between a CICS program and a non-CICS program.

Summary.

EXCI is a convenient way to call a CICS program from a non-CICS program. The CICS External Interfaces Guide will have all the details necessary for implementing, but this post will hopefully give you a good idea of what it’s all about before you dig into that.

About these ads

18 responses to “EXCI – Communicating with a CICS Program from Outside of CICS

  1. I just want to be able to issue
    CICS REFRESH,PROGRAM=&progname,CICSID=(&cicsid),PHASEIN

    What JCL needs to be wrapped around this to submit it in batch? I think this is the EXCI approach, right?

    Probably, to test the JCL I should just try to display something. suggestions?
    thanks,
    roy

  2. Roy,

    If all you want to do is perform a PHASEIN or NEWCOPY from batch, you might not need EXCI. You can issue a z/OS modify command to perform the CICS command by sending it to the internal reader. For example:

    //STEP1 EXEC PGM=IEBGENER
    //SYSPRINT DD SYSOUT=*
    //SYSUT1 DD *,DLM=’%%’
    /*$VS,’F MYCICS,CEMT SET PROG(MYPROG) PHASEIN’
    %%
    //SYSUT2 DD SYSOUT=(A,INTRDR)

    If you need to do more than just issue the command (i.e., log the results, etc.), then you will need to write client and server programs and use EXCI. Hopefully this blog post gives you an idea of how to get started if that’s the case.

    Steve

  3. Hi Steve,

    In the batch program I have an cursor opened. For the first record fetched in the batch program the CICS program through EXCI call processed it and gives back the result but when it goes for the next record it gives a -501 sql error. Does this EXCI call closes the cursor. If so what could be done to make the cursor open. I have tried the WITH HOLD option too.

    Note: the batch program uses a different DB2 system where as the online program uses another DB2 system.

    • Hi, Deepak.

      I’ll bet that you have your calls set up to where you are syncpointing between calls, which is losing your cursor position. I’m not a DB2 expert, so all I can do is advise where I would start – and I would be looking into the options to not syncpoint or checkpoint until you explicitly request it.

      Good luck with your project!

      Steve
      theCICSguy

  4. Consider using BatchCICS-Connect when accessing CICS from a batch cobol program.

    Sounds to me like your 501 sql error is a db2
    issue.

    You’ve lost cursor positioning because the
    task that issued the original read and returned a cursor within CICS has ended. You need to create the ability to keep the task alive if you want to readnext record.

    • Hi Earl,

      Thanks for the explanation and suggestion. If any function available which would keep the cursor open please let me know.

      Thanks
      Deepak

      • Deepak,
        There is a way to keep the cursor open,
        but would require some some additional
        online coding.

        contact me offline >> okearl@yahoo.com if
        this functionality is urgent need for your
        installation.

  5. Hi Earl! My company currently uses a commercial product to allow batch jobs to read, update, and add data to VSAM files that are owned by CICS. They will be moving the CICS work to another platform (whaaa!) within about 6 months and the annual renewal for the commercial product will come up within about 2 months. I have been looking at EXCI as a replacement for the interim. There are only a few batch programs that will need to be rewritten for this to work. My question is: “Is EXCI a good replacement for the short term under these circumstances?” Also, the sample EXCI server program closes the VSAM file at the end. Is there any reason that this should be done, as there are other CICS transactions that will be referencing the same file? (Possibly while the batch job is running.) – Thanks!

    • Hi, Jeff. Thanks for checking out the blog. EXCI should work fine. It’s been a while since I have reviewed the sample server program, but I’m sure you can modify it as would make sense for your use. Good luck with the EXCI program, and be sure to be a spokesman for what CICS is capable of – the folks at Hursley have added a lot of functionality previously only found in server environments in recent years!

      Steve

  6. Jeff,
    Depending upon the complexiting of the process you intend to replicate with your own code, using EXCI could create some issues for you, especially
    if you are processing a large number of records with multiple EXEC CICS LINKS from batch. You might be better off just paying the addtional license fee or investigate other commerical products that would be less expensive to run for the remaing life of the existing work on the CICS platform.
    I’m curious, is the commerical product SYSB-II ?

    Good luck,
    Earl

  7. Hi Earl,

    There is an already existing online API, Since EXEC CICS LINK is not working (Am getting compilation error) am using EXCI calls in my COBOL batch program to call the already existing Online API. Am getting Response codes and reason codes as Zero’ but the online API is not called and the COMMAREA contains no value. Can you help me out to figure out the problem

    Regards,
    Deepthi

  8. Deepthi,
    Your June2 response just now showed up in my email account. In answer to your question, if you are using the EXCI call interface , there could be many
    different reasons whey the Online API is not being invoked. I would need to
    learn more about your CICS region setup and determine if proper defintions
    have been defined, also in your batch program call interface are you performing the proper sequence of EXCI calls ?

    If this is an urgent need , contact me at okearl@yahoo.com

    Regards,
    Earl

  9. Hi CICSGuy!, thank for your blog.
    I Have LPAR1 with CICS1, Program1 in CICS1, Is posibled execute by EXCI Program1 from LPAR2 ? or EXCI is valid only in local LPAR?
    I have LPAR1 and LPAR2.

    • Hi, eoscarvf.

      I have not done EXCI across LPAR’s like that, but it is my understanding that it is possible. You will definitely need to talk to your VTAM people to make sure that the CICS ACB in LPAR1 is accessible from LPAR2. Good luck with your project!

      Steve
      theCICSguy.com

  10. Hi Earl,

    I hope you would be the right person to help me to understand EXCI.

    Background:

    I want to write a batch program which invoke already exsisting transaction e.g. ABCD transaction.

    So I am planning to use External cics interface

    EXEC CICS
    LINK PROGRAM(name)
    RETCODE(data-area)
    SYNCONRETURN
    [COMMAREA(data-area)]
    [LENGTH(data-value)]
    [[DATALENGTH(data-value)]]
    [APPLID(name)]
    [TRANSID(name)]
    END-EXEC

    New batch program will be on demand program.

    I want to read input file(with max 50 records) in batch program and for each record want to invoke transaction ABCD.

    INCOPY is my input file copybook of length 700 in batch program but I am passing only 2-3 fields of copybook to ABCD transaction.

    If ABCD transaction fails to do its task it shoud return error code and error description to batch proram.
    Error code and error description are moved in DFHCOMMAREA in ABCD transaction.

    Queries:
    1.Is it necessary to move entire INCOPY fields to COMMAREA of link command as I want pass only 2-3 required fields .
    2.How get back Error Code and Error Description in batch program from DFHCOMMAREA of ABCD transaction.

    • First of all, you can only link to a “program” from batch. You can not invoke ABCD transaction from batch. 2nd, The Transid option of the link command is the mirror transaction that the “program” runs under. You will need to contact your technical support to find out the mirror transid.
      If you really want to invoke a transaction id from batch and retrieve results
      back, you need a software product like BatchCICS-Connect (www.batchcics.com)

  11. Hi, I have CICS driver program which dynamically “CALL”s its application programs by reference (using COBOL pointers). Though all the programs are compiled with RENT option, if two users execute the same transaction concurrently, data is stepping on each other screens. Same is working fine, if the dynamic call is converted to call by value. Is it the issue with COBOL pointers?

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s