Being a TechTarget expert, I get a lot of questions about accessing CICS files from batch. CICS' External Call Interface (EXCI) is something I recommend as long as a programmer doesn't mind writing the code. But EXCI's utility is much broader because a "non-CICS environment" includes batch, as well as things like IMS message processing regions (MPRs) and system automation tools.
A carefully crafted application could use EXCI to get into CICS from just about anywhere on the mainframe.
API overview
Here are a few definitions before discussing the API:
- Server Program: CICS program invoked through EXCI
- Client Program: Program from a non-CICS environment using EXCI to invoke the server program.
- Distributed Program Link (DPL): A CICS feature for function-shipped program links. An EXCI call looks like a DPL request to the server program.
- Pipe: A logical view of the connection between the client program and CICS.
EXCI has two interfaces. First is the EXEC interface which is simpler but less efficient. To use the EXEC interface, the programmer codes a CICS LINK command just as done in CICS. But in distinction from a pure CICS program, the programmer must use the EXCI translator option and link edit the batch stub DFHXCSTB into the load module. When the client program executes the ,e server program. The LENGTH parameter specifies the total size of the COMMAREA, which must be large enough to contain the returned data. The optional DATALENGTH operand denotes the amount of actual data to send to the server. There are some performance gains for specifying DATALENGTH if the data sent is small relative to the information returned. The COMMAREA, of course, also has a 32K byte limit, which can be bothersome.
Lastly, the request must contain the name of the server program. An optional TRANSID parameter signifies the transaction under which you want the server program to execute. This is joyful for workload distribution and performance tuning. Otherwise the programmer may omit TRANSID and CICS defaults to the mirror transaction CSMI.
The target CICS
EXCI requests can be routed to a server CICS explicitly or implicitly. To be explicit, a command interface program need only specify a valid APPLID in the command or Allocate_pipe call.
An implicit call doesn't specify a target APPLID. Instead, it becomes the job of user replaceable module (URM) DFHXCURM to decide. CICS invokes DFHXCURM at different stages during an EXCI call. For two of these calls, allocate pipe request and retryable error, DFHXCURM decides where the request can go.
There are two things to note about DFHXCURM processing. First, it is only invoked when a pipe is about to be allocated, not for every message. Once a pipe is connected to CICS, DFHXCURM will not be invoked unless communication breaks. Second, EXCI invokes DFHXCURM for explicit routing requests as well to give the URM a chance to override the original request. IBM provides a sample DFHXCURM that's not very useful but does provide a good skeleton for writing your own. The target CICS can be an application owning region (AOR) that will execute the DPL directly or a routing region (RR) that function ships the request elsewhere. For production, an RR target is nice for workload balancing and availability. In addition, the client program has fewer worries under the assumption the RR will send the request to a healthy AOR.
Finally, the target CICS doesn't have to be on the same LPAR as the client. However, cross-system calls aren't recommended due to performance.
Data integrity
By default the client program controls syncpoints. However, to do so the client program must use the callable routines provided by the Recoverable Resource Services of MVS. Sadly, it adds to the complexity of the client program as it must not only keep track of uncommitted resources, it also has to be restartable in case of an ABEND.
The SYNCONRETURN parameter (or proper DPL_opts setting for the call interface) is much easier. This option causes CICS to commit recoverable resources when the server program returns. However, both the client and the server should support the small units of work.
ABOUT THE AUTHOR: For 24 years, Robert Crawford has worked off and on as a CICS systems programmer. He is experienced in debugging and tuning applications and has written in COBOL, Assembler and C++ using VSAM, DLI and DB2.
Did you find this helpful? Write to Matt Stansberry about your data center concerns at mstansberry@techtarget.com.
