Link edit part examples

Link edit parts are used for the z/OS® environments. In general, EGL automatically generates the linkage editor control statements. However, in some situations, such as those where you have a static link, you must provide a link edit part.

It is best to define the program's link edit part in the same project as the program so that it is available whenever the program is available. The link edit part must contain linkage editor control statements for linking every load module that contains the program.

Syntax and format rules

The control statements in the link edit part must follow these linkage editor syntax and format rules:
  • Statements cannot start in column one.
  • No blank lines are allowed between statements.
For more information about writing linkage editor control statements, refer to the linkage editor document for your host system.

zSeries® program with static calls to other programs

A link edit part containing linkage editor control statements must be defined for each generated program that contains static COBOL calls. The linkage editor control statements consist of ENTRY and NAME statements for the load module and INCLUDE statements for each statically called program and the base program. Your COBOL runtime (IBM® Rational® COBOL Runtime Server for zSeries®) entry stub program (ELARMAIN) must also be included in the z/OS® batch and IMS™ BMP environments. Other COBOL runtime and database stubs are included along with the programs from the original link edit step produced during the generation process.

The following table shows sample control statements when program BASEPGM statically calls both a generated COBOL program EGLAPP1 and a PL/I program PLIAPP1. In the example, the object decks for PL/I programs have been written to data set NONEGLL.OBJ.LIBRARY, which is referenced by the DD statement NONEGLL. All the INCLUDE statements for the called programs precede the INCLUDE for the calling program.

Table 1. Sample control statements
Environment Base program type Control statements in BASEPG

CICS for z/OS
IMS/VS

 Main or called 
INCLUDE SYSLMOD(EGLAPP1)
INCLUDE NONEGLL(PLIAPP1) (See note 1.)
INCLUDE SYSLMOD(BASEPGM)
ENTRY BASEPGM
NAME BASEPGM(R)

IMS BMP
z/OS batch

 Main only 
CHANGE ELAAPPL(BASEPGM)
INCLUDE SELALMD(ELARMAIN)
INCLUDE SYSLMOD(EGLAPP1)
INCLUDE NONEGLL(PLIAPP1)
INCLUDE SYSLMOD(BASEPGM)
ENTRY ELARMAIN
NAME BASEPGM(R)

IMS BMP
z/OS batch

 Called only 
INCLUDE SYSLMOD(EGLAPP1)
INCLUDE NONEGLL(PLIAPP1)
INCLUDE SYSLMOD(BASEPGM)
ENTRY BASEPGM
NAME BASEPGM(R)

1. PL/I programs cannot be statically linked for CICS® for z/OS®. For CICS® for z/OS®, this link would be to a statically linked non-EGL COBOL program.

To make the NONEGLL library available for the relink step, you must to add a DD statement to the build scripts. For this example, find the following line in the code: 
//* Add your DD statements here if you supply your own link edit parts
Then add a new line similar to this below it:
//* Add your DD statements here if you supply your own link edit parts
//NONEGLL DD DSN=NONEGLL.OBJ.LIBRARY,DISP=SHR

zSeries® programs that are statically called by other programs

A link edit part that contains link edit statements must also be defined for each EGL program that is the target of a static COBOL call from another program. Include statements to link every load module that calls the EGL program in the link edit part so that each load module is automatically linked again whenever the called EGL program is generated.

For example, if the COBOL generated program EGLAPP1 is statically called by BASEPGM and by BASEPG2, define the link edit part for EGLAPP1 so that it contains the set of statements for the runtime environment from the previous table twice: once referencing BASEPGM and once referencing BASEPG2. This ensures that both BASEPGM and BASEPG2 are relinked whenever you generate EGLAPP1.

Modifying the EGL build scripts

If a program is both the target of a static COBOL call and also includes a static COBOL call to other programs, you must further tailor any EGL build scripts to use different load libraries as the include and output libraries for generated program load modules.

The following example shows a SYSLMOD DD statement before modifications.
//SYSLMOD DD DISP=SHR,DSN=&CGHLQ..&ENV..LOAD
The next example shows the replacement DD statements for the SYSLMOD DD statement.
//EGLINCL DD DISP=SHR,DSN=&CGHLQ..&ENV..LOAD
//SYSLMOD DD DISP=SHR,DSN=&CGHLQ..&ENV..RELINK.LOAD
Then define all link edit parts containing link edit statements to use the EGLINCL library as the include library for generated programs. Setting up the libraries this way has the following effects:
  • The initial link edit step in the preparation procedures links the generated program with COBOL runtime and database stub programs into the EGLINCL library.
  • Statically called programs are not linked together in the EGLINCL library to avoid the same program being included multiple times on the relink step.
  • The relink step combines all statically linked programs into the appropriate load modules and stores the load modules in the SYSLMOD library.

Specifying the control statements

The following table shows how to specify the control statements for linking the program BASEPGM if the statically called program EGLAPP1 in turn statically called program EGLAPP2. The control statements for linking program BASEPGM should also be added to the EGLAPP1 and EGLAPP2 link edit parts so that program BASEPGM is linked again when either program EGLAPP1 or EGLAPP2 is generated.

Table 2. Sample control statements
Environment Base program type Control statements in BASEPG

CICS for z/OS
IMS/VS

 Main or called 
INCLUDE EGLINCL(EGLAPP1)
INCLUDE EGLINCL(EGLAPP2)
INCLUDE NONEGLL(PLIAPP1) (See note 1.)
INCLUDE EGLINCL(BASEPGM)
ENTRY BASEPGM
NAME BASEPGM(R)

IMS BMP
z/OS batch

 Main only 
CHANGE ELAAPPL(BASEPGM)
INCLUDE SELALMD(ELARMAIN)
INCLUDE EGLINCL(EGLAPP1)
INCLUDE EGLINCL(EGLAPP2)
INCLUDE NONEGLL(PLIAPP1)
INCLUDE EGLINCL(BASEPGM)
ENTRY ELARMAIN
NAME BASEPGM(R)

IMS BMP
z/OS batch

 Called only 
INCLUDE EGLINCL(EGLAPP1)
INCLUDE EGLINCL(EGLAPP2)
INCLUDE NONEGLL(PLIAPP1)
INCLUDE EGLINCL(BASEPGM)
ENTRY BASEPGM
NAME BASEPGM(R)

1. PL/I programs cannot be statically linked for CICS® for z/OS®. For CICS® for z/OS®, this link would be to a statically linked non-EGL COBOL program.

The relink load library and the original load libraries are required when running programs. The relink library is required for statically linked modules. The original library is required for modules that did not have to be statically linked. The following example shows how to customize the run time JCL file and the IMS™ and CICS® region JCL file to include the load libraries in the correct order in the STEPLIB statement.
// DD DISP=SHR,DSN=chglq.system.RELINK.LOAD
// DD DISP=SHR,DSN=chglq.system.LOAD
The variables chglq and system represent the values that were substituted for the CGHLQ and ENV parameters in the build script.