Calling programs in IMS and z/OS batch environments

In non-CICS environments, standard OS linkage conventions are used. Up to 30 parameters can be passed on a call statement. The called program runs and returns to the calling program when the program ends.

Use the linkage options part to specify the type of linkage generated for a call statement. For non-CICS environments, you can specify that the call statement be generated either as a DYNAMIC or a STATIC COBOL call with parameters passed using a standard COBOL parameter list (OSLINK), with all parameters passed by reference.

Calls from an EGL program to an EGL program

EGL call statements are generated as standard COBOL CALLs. The parameters on the EGL call statement are the parameters on the COBOL CALL. All parameters are passed by reference, not by content. Use the linkage options to specify whether the COBOL CALL is a dynamic or static call.

The compiled COBOL CALL passes parameters using standard linkage conventions. Register 1 points to a list of parameter addresses. The high order byte of the last parameter address is set to 1, as in the following illustration.

The list of parameter addresses that Register 1 points to

Special considerations apply if you pass dliLib.psbData or a PCBRecord as a parameter. For more information, see “Reference information for special parameters on call or transfer statements.”

Sharing called programs between environments

Programs generated for IMS/VS, BMP, and z/OS® CICS® can call subprograms generated for the z/OS batch environment. You must ensure that the z/OS batch program does not do any SQL I/O, file I/O, or batch-environment-specific calls, as these will not be allowed from the original environment. For example, as CICS owns all file I/O access, it will not allow batch-type file access to execute. Programs that are generated for z/OS batch but are called by logic running in other environments are typically limited to operations such as calculations and table lookups.

Calls from an EGL program to a non-EGL program

A call to a non-EGL program is generated in the same way as a call to an EGL program. Calls to programs written in PL/I must be made as static calls. If the non-EGL program is not written in COBOL, follow the rules for interfacing to other languages described in the application programming guide for your release of COBOL.

Calls from a non-EGL program to an EGL program

The non-EGL program uses a standard COBOL CALL statement to call the EGL program. All parameters are passed by reference, not by content. Calls from programs written in PL/I must be made as static calls. If the non-EGL program is not written in COBOL, follow the rules for interfacing to other languages described in the application programming guide for your release of COBOL.

Avoiding multiple calls to runtime services initialization

If the first program invoked in the run unit is a non-EGL program, and the program calls EGL programs repeatedly, then Rational® COBOL Runtime for zSeries performs initialization and termination functions on each call. The overhead for these calls can be significant if the number of calls is large. To avoid the overhead and perform initialization and termination once, EGL provides a wrapper program for each environment. You must link edit the appropriate wrapper program with your EGL program. To do this automatically, create a link edit part with the same name as your EGL program. If your EGL program does not need to be link edited with any programs other than the wrapper program, use the link edit commands as shown below, substituting your program name for the name YOURPROG. SELALMD represents the runtime services load library.

z/OS batch control statements:
CHANGE NONVGRTN(YOURPROG)
CHANGE ELAAPPL(ELAWBAT)
INCLUDE SELALMD(ELAWBAT)
ENTRY ELARMAIN
NAME YOURPROG(R)
IMS™ BMP control statements:
CHANGE NONVGRTN(YOURPROG)
CHANGE ELAAPPL(ELAWBMP)
INCLUDE SELALMD(ELAWBMP)
ENTRY ELARMAIN
NAME YOURPROG(R)
IMS/VS control statements:
CHANGE NONVGRTN(YOURPROG)
CHANGE ELAAPPL(ELAWIMS)
INCLUDE SELALMD(ELAWIMS)
ENTRY ELARMAIN
NAME YOURPROG(R) 
If you need to link your program with other modules (such as a PL/I program, for example), see “Link edit part examples.”
If your main program receives parameters passed from LE (typically from the PARM parameter in the JCL), you need to link the module with an LE main program so that the parameters will be properly received. In particular, you need to include the program ELARLEMN, which is an LE compliant module that is provided with EGL and is the entry point. ELARLEMN accepts the passed parameters and passes them to ELARMAIN, which in turn calls YOURPROG. Here are example statements:
CHANGE NONVGRTN(YOURPROG)
CHANGE ELAAPPL(ELAWBAT)
INCLUDE SELALMD(ELAWBAT)
INCLUDE SELALMD(ELARLEMN)
ENTRY ELARLEMN
NAME YOURPROG(R)

Calling a CICS program from an EGL z/OS batch program

A z/OS batch program can use the External CICS Interface (EXCI) to call programs in a CICS region. The called programs might be generated by EGL or created in another way.

Use the linkage options part to specify how you want EGL to generate the call statement:
  • The type must be remoteCall.
  • The remoteComType must be CICSEXCI.
  • To pass parameters to the called program, set the parmForm property of the callLink element to COMMDATA.

When processing the call statement, EGL generates the necessary COBOL code to call via EXCI. For more information on these linkage options, see "Calling programs in CICS environments.”

Calling a CICS program from the z/OS batch environment has the following limitations:
  • Client unit of work is not supported.
  • Channels and containers are not supported for the EXCI call from the z/OS batch environment.
  • You cannot pass EGL variable length parameters (such as STRING type variables) to the called program.
  • DL/I is not supported.

Example

In the following example, a program named calledExci is called from z/OS batch. The call uses the following linkage options:
  • remoteComType = CICSEXCI (required)
  • alias = CALLED
  • location = NQA17C03 (required)
  • luwControl = SERVER
  • parmForm = COMMDATA
  • pgmName = calledExci
  • remotePgmType = EGL | EXTERNALLYDEFINED (has no effect)
  • serverID = ABCD (default is CSMI)
  • type = REMOTE
  • conversionTable (has no effect)
The calling program includes the following EGL statement:
call "calledExci"(d, j);

Feedback