are:
50 OS PL/I Optimizing Compiler: Prograrrmer's Guide
PLIXCL Compile and link edit
PLIXCLG Compile, link edit, and execute PLIXLG Link edit and execute
The following paragraphs descrite the essential JCL statements for link editing.
The IBM-supplied cataloged procedures are described in Chapter 11 and include
examples of these statements.
EXEC STATEMENT
The name of the linkage editor is of the form IEWLFxxx, where "xxx" indicates the amount of main storage required fer its execution, as shown in Figure 5-3.
r---, I
~I
Amount of
1
1 I main storage I
1---1
1 440 I 44K 1
1 880 I 88K I
I 128 1 128K I
L---J
Figure 5-3. Main storage requirements for linkage editor
IEWLFxxx
The aliases IEWL or,LINKEDIT are often used for the linkage editor and nermally refer to the version at your installation with the largest design level. Yeu should find out what versions are availatle at your installation.
The basic EXEC statement is:
//stepname EXEC PGM=IEWL
By using the PARM parameter of the EXEC statement, you can select one or more of the optional facilities provided by the linkage editor; these facilities are described in "Optional Facilities," later in this chapter.
DO STATEMENTS FOR THE STANDARD DA'IA SETS
The linkage editor always requires four standard data sets. You must define these data sets in CD statements with the ddnames SYSLIN, SYSLMOD, SYSUT1, and SYSPRINT.
A fifth data set, defined by a t t statement with the name SYSLIB, is necessary if you want te use auterratic library call. 'Ihe five data set names, together with other characteristics ef the data sets, are shown in Figur~ 5-4.
Primary Input <SYSLIN)
Primary input to the linkage editer rrust te a standard data set defined ty a tc
statement with the narre SYSLIN; this data set rrust have consecutl.ve organization.
The input must comprise ene cr rrere ebject modules and/or linkage editor control
statements; a load rrodule car.net be fart ef the prirrary input, although i t can be
introduced by the contrcl staterrent
INCLUDE. For a PL/I program, the primary input is usually a data set centaining an object rr,odule produced ty the compiler.
This data set may be en rragnetic ta~e or en a direct-access device, or you can include i t in the input job strearr. In all cases, the input must te in the form of 80-byte F-format records.
The IBM-supplied cataloged procedure PLIXLG includes the DO statement:
//SYSLIN DO DDNAME=SYSIN
This statement specifies that the primary input data set rray be defined in a DO statement with the name SYSIN. If you use this cataloged procedure, spe~ify this DO statement ty using the qualified ddname IKED.SYSIN. For exarrple, te link edit and execute an etject module placed in the input stream, you can use the follewing statements ,:
//IEGC //STEP1 //LKED.SYSIN
JOB
EXEC PLIXLG DO
*
(insert here the object rrodule to be link edited and executed)
/*
If object modules with identically named control sections appear in the primary input, the linkage editor precesses enly the first appearance of that control
section.
You can include load rrodu les or ctject modules from one or more litraries in the primary input by using a li~kage editor
INCLUDE statement as descrited in
"Additional Processing,· later in this chapter.
r---,
ddname ContentsI
Possible device classes1SYSLIN Primary input data, normally the compiler output
SYSLMOO Load module
SYSUT1 Temporary workspace
SYSPRINT Listing, including messages SYSLIB Automatic call litrary
(normally the PL/I resident library)
1SYSSQ Magnetic tape or direct-access device SYSDA Direct access device
UNIT=SYSSQ or input jeb stream (specified by DD *)
UNIT=SYSDA UNIT=SYSDA
UNIT=SYSSQ (or SYSOUT=) UNIT=SYSDA
L---__________________________________
JFigure 5-4. Linkage editor standard data sets Output (SYSLMOD)
Output (that is, one or more load modules) from the linkage editor is always stored in a data set defined
by
the DO statement with the name SYSLMOD, unless you specifyotherwise. This data set is usually called a library; libraries are fully dE~scribed in Chapter 10.
The IBM-supplied cataloged procedures include the following DO statement:
//SYSLMOD DO DSNAME=&&GOSET(GO), // UNIT=SYSDA,
// DISP=(MOD,PASS),
/ / SPACE=(1024,C50,20,1) ,RLSE»
This statement defines a temporary library named &&GCSET and assigns the member name GO to the load module produced by the linkage editor. To retain the lead module after execution of the job, replace this DD statement with one that defines a permanent library. For example, assume that you have a permanent library called USLIB on 2311 disk pack serial number 371;
to name the load module MCD1 and J;:lace i t in this library, code:
//LKED.SYSLMOD DD DSNAME=USLIB(MOD1), / / UNIT=2311,VCL=SER=371,DISP=CLD
The size of a load module must not exceed 512K bytes for programs executed under MFTi a much larger load module is allowed for MVT. The SPACE parameter in the DD statement with the name SYSLMOD used in the IBM-suJ;:plied cataloged procedures allows for an initial allocation of 50K
bytes and, if necessary, 15 further allocations of 20K tytes (a tetal cf 350K bytes): this should suffice for most applications.
Temporary Workspace (SYSUT1)
The linkage editor requires a data set for use as temporary workspace. It is defined by a DD statement with the nane SYSUT1~
This data set must te on a direct-access device. The following statenent ccntains the essential parameters:
//SYSUTl DD UNIT=SYSDA, / / SPACE=(1024,(200,20»
You should normally never need to alter the DD statement with the nane SYSUT1 in an IBM-supJ;:lied cataloged procedure, except to increase the SPACE allccaticn when
processing very large programs.
If your installation supports dedicated workfiles, these can be used te prcvide tenpcrary workspace for the link-edit job step, 'as described in Chapter 11.
Automatic Call library (SYSlIE)
Unless you specify otherwise, the linkage editor will always attempt to resolve external references by autonatic litrary call (see "Linkage Editor Processing,"
earlier in this chapter). Tc enatle i t to
52 OS PL/I Optimi zing Compi le.r: Prcgrann:er's Guide
do this, you must define the data set or data sets to be searched in a DD statement with the name SYSLIB. (TO define second and subsequent data sets, include
additional, unnamed, 00 statements
immediately after the DO statement SYSLIB;
the data sets so defined will be treated as SYS1.PLITASK (the multitasking library).
The base library contains all the resident library subroutines required by a non-multitasking program. The multitasking
library contains subroutines that are peculiar to multitasking, together with multitasking variants of some of the base library subroutines.
For link editing a non-multitasking program, specify only the base library in the SYSLIB 00 statement. The following DD statement will usually suffice:
//SYSLIB DO DSN=SYS1.PLIBASE,DISP=OLD
E'or link editing a multitasking program, specify both the multitasking library and the base library. When attempting to resolve an external reference, the linkage editor will first search the multitasking library; if i t cannot find the required
multitasking library first, base library second. The following DD statements will usually suffice:
//SYSLIB DO DSNAME=SYS1.PLITASK,DISP=OLD / / DO DSNAME=SYS1.PLIBASE,DISP=OLD
Listing (SYSPRINT)
The linkage editor generates a listing that includes reference tatles relating to the load modules that i t produces and also, when necessary, messages. The information that may appear is described under "Listing consecutive organization. Although the listing is usually printed, i t can be
stored on any magnetic-tape cr direct-access device. For printed output, the following staterrent will suffice:
//SYSPRINT DD SYSOUT=A
EXAMPLE OF LINKAGE EDITOR JCL A typical sequence of jot control
statements for link editing an object module is shown in Figure 5-5. The DO statement SYSLIN indicates that the cbject module ~ill follow inrrediately in the input parameter indicates to the c~erating systerr that this 00 statement specifies the ' creation of a library.
Optional Facilities
The linkage editor provides a number of optional facilities that are selected by including the appropriate keywords from the following list in the PARM pararreter of the options, separating the opticns with commas and enclosing the list within single
quotation marks, for exarrple:
//STEPA EXEC PGM=IEWL,PARM='LIS~,MAP'
If you are using a cataloged procedure, you must include the FARM pararreter in the EXEC statement that invokes the procedure and qualify the keyword FARM with the name of the procedure step that invokes the linkage editor, for exarrple:
//STEPA EXEC PLIXCLG,PARM.LKED='LIS~,XREF'
The linkage editor opticns are of two
JOB
EXEC PGM=IEWL //LINK
//STEPl //SYSLMOD / /
//SYSUTl //SYSPRINT //SYSLIB //SYSLIN
DD DSNAME=MODLIB(LKEX),UNIT=2311,VOL=SER=D186 SPACE=(CYL, (10,10,1»,DISP=(NEW,KEEP) DD UNIT=SYSDA,SPACE=(1024, (200,20»
DD SYSOUT=A
DD DSNAME=SYS1.PLIBASE,DISP=OLD DD
*
(insert here the object module to be link-edited)
/*
Figure 5-5. Typical job control statements for link editing a PL/I };:regran 2. Keywords that permit you to assign a
value to a function (for exarrple, 81 ZE=10K) •
The linkage editor options are described in the following sections, in alphabetic order.
LET Option
The LET option specifies that the linkage editor is to mark the load module as
"executable" even if slight errors or abnormal conditions have been found during Ii nk editing provided these do not: exceed severity 2.
LIST option
The LIST option specifies that all linkage editor control statements processed should be listed in the data set defined by the DD statement with the name <SYSPRINT.
MAP Option
The MAP option specifies that the linkage editor is to produce a map of the load module showing the relative locations and lengths of all control sections in the load module.
NeAL Option
The NeAL option specifies that no external references are to be resolved by automatic
library call. However, the lead ncdule is marked "executable" provided that there are no errors.
You can use the NCAL o};:tien te censerve auxiliary storage in private libraries, since, by preventing the reselutien ef external references during link editing, you can store load roedules witheut the relevant library subroutines; the DD statement with the naroe SYSlIE is net required. Before executing these lead modules, you must link edit them again to resolve the external references, but the load module created need exist only while i t is being executed. You can use this technique to combine separately compiled PL/I procedures into a single lead ncdule.
SIZE Option
The SIZE option specifies the anount of main storage, in bytes, to
be
allocated to the linkage editor. The fornat of the SIZE option is:S IZ E= (m [ , n] )
where "m" is the anount ef nain storage in bytes or K bytes (where K=1024) to be allocated to the linkage editor: i t Rust
include "n" and i t must be greater than "n."
and "n" which is o};:tional, is the amount of main storage (in bytes or K bytes) te be allocated to the load module buffer.
Figure 5-6 gives values fcr "n" and "n"
for the three versions of the F-Ievel linkage editor.
54 OS PL/I Optimizing Compiler: Programmer's Guide
r---,
IVersion ImCminimum)
1
~I
rr.-nI
1 I 1 (Min) (Max) I (Min) I
1---/
I I I "
I
44K , 44KI
6K lOOK / 38R, 1 88K / 88K ,6K lOOK , 44K 1I
l28K ,128K / 6K lOOK / 66K /L---J
Figure 5-6. Coding the SIZE option
If you specify SIZE incorrectly, or if you omit i t , default values set at system generation are used. If you specify SIZE greater than the region or partition size, the maximum amount of main storage will be used.
XCAL Option
The XCAL option specifies that the linkage editor will mark the load module as
"executable" even if slight errors or abnormal conditions, including improper branches between control sections, have been found during link editing. XCAL, which implies LET, applies only to an overlay structure.
XREF Option
The XREF option specifies that the linkage editor is to print a map of the load module and a cross-reference list of all the
external references in each control section. XREF implies MAP.