Static linkage using TSOSLNK

The static linkage editor TSOSLNK processes one or more object modules or prelinked modules to generate either

• an executable program, which it outputs to a separate catalog file or to a PLAM library as a type C library element, or

• a prelinked module, which it stores in the temporary EAM file of the current task, or in a PLAM library as a type R library element.

The TSOSLNK utility routine is called with the START-PROGRAM command. It subsequently expects control statements from SYSDTA that specify

• for output:

  • whether the result of the linkage run is to be an executable program or a prelinked object module, and

  • where the result is to be output

• for input:

  • which object modules it should link in, and

  • which libraries should be used for the resolution of unresolved external address references.

Control statements for TSOSLNK

The TSOSLNK control statements and their operands are described in detail in the “TSOSLNK” manual [9]; the following table merely provides an overview of the most important aspects.

Statement	Short description
PROGRAM PROG	instructs the linkage editor to generate a program from the read object modules, and specifies its characteristics and output location (PLAM library or cataloged file). Among the operands which can be specified are the following: SYMTEST=MAP or SYMTEST=ALL allows the user to use symbolic names from the compilation unit when debugging with the AID debugger. This is provided that an appropriate control statement was issued to COBOL2000 during compilation in order to have LSD information generated. SYMTEST=ALL instructs the linkage editor to pass this information on to the program, whereas SYMTEST=MAP allows LSD information from the object module to be loaded dynamically during debugging (see “AID” manual [8] for further information). LOADPT= * XS defines the load address of the program in the address space above 16 Mbytes. This specification is not possible unless only the XS runtime system and object modules that can be loaded into the upper address space are being linked. ENTRY/START=entry-point specifies the starting point of the program run. This specification becomes necessary when the COBOL main program is not the first program to be linked into an executable program. entry-point is then the PROGRAM-ID name (abbreviated to 7 positions, if necessary) followed by the suffix “$”. The PROGRAM and MODULE statements (see below) are mutually exclusive.
MODULE MOD	causes the linkage editor to link the read object modules into a prelinked object module and defines its output location. The MODULE and PROGRAM statements (see above) are mutually exclusive.
INCLUDE	specifies individual object modules from which the linkage editor is to create the program or prelinked module.
RESOLVE	assigns PLAM libraries to TSOSLNK for the autolink procedure (which is described on the next page).
EXCLUDE	excludes the specified PLAM libraries from the autolink procedure (described below).
ENTRY	see ENTRY or START operand of the PROGRAM statement.
END	signals the end of the input of linkage editor statements.

Table 9: Control statements for TSOSLNK

TSOSLNK autolink procedure

On finding external address references (in a generated module) that cannot be resolved by modules specified in INCLUDE statements, TSOSLNK proceeds according to the following autolink procedure:

1. TSOSLNK first checks whether a library containing a corresponding module was explicitly assigned to the external reference by means of a RESOLVE statement.

2. If TSOSLNK cannot resolve the external reference in the first step, it searches all libraries specified in RESOLVE statements. Libraries can be excluded from this search by means of EXCLUDE statements.

3. If TSOSLNK does not succeed in resolving the external reference in the second step, it searches the library TASKLIB, provided that this has not been prevented by the NCAL statement or a corresponding EXCLUDE statement.
   If there is no file named TASKLIB listed under the user ID of the current task, TSOSLNK uses the system library $.TASKLIB.

If unresolved external references are present even after the autolink procedure, TSOSLNK outputs a list of their names to SYSOUT and SYSLST.

Example 6-1

Static link-editing into an executable program

/START-PROGRAM FROM-FILE = $TSOSLNK —————————————————————————————— (1)
 % BLS0500 PROGRAM 'TSOSLNK', VERSION 'V21.0E02' OF '1999-03-15' LOADED
 % BLS0552 ...
*PROG COBOLPROG,LIB=PLAM.LIB,ELEM=COBOLLAD ——————————————————————— (2)
*INCLUDE COBOLMOD,PLAM.LIB ——————————————————————————————————————— (3)
*RESOLVE ,$.SYSLNK.CRTE —————————————————————————————————————————— (4)
*END ————————————————————————————————————————————————————————————— (5)
 % LNK0500 PROG BOUND
 % LNK0506 PROGRAM LIBRARY : PLAM.LIB
 % LNK0507 PHASE WRITTEN TO ELEMENT 'COBOLLAD'

(1) (2)	The utility routine TSOSLNK is called. The PROG statement specifies that TSOSLNK is to generate an executable program whose program name is COBOLPROG, and store it as library element COBOLLAD in the PLAM library PLAM.LIB.
(3)	The INCLUDE statement informs the linkage editor that it is to link object module COBOLMOD from the PLAM library PLAM.LIB.
(4)	TSOSLNK is to initially resolve external references with modules from the runtime system, which is cataloged on this system under the name $.SYSLNK.CRTE.
(5)	END terminates the input of control statements and starts the linkage process; after its completion, TSOSLNK provides information on the program that has been generated.

Linking segmented programs with overlay structure

By using appropriate COBOL language elements (see the “COBOL2000 Reference Manual” [1]), the compiler can be made to output the machine code for a compilation unit in parts, i.e. in the form of a number of object modules rather than just one. This procedure is known as segmentation. The program sections created in the process are called segments.

An overlay structure can be defined during link-editing of a segmented program (see “TSOSLNK” manual [9]):

With the exception of the root segment, which remains in main memory for the entire program run, it is possible to have the individual segments overlay-loaded under program control whenever they are necessary for execution. Segments can overlay one another under these circumstances, i.e. the segments can occupy a common memory area one after the other. Which segments can overlay one another is determined by means of control statements during linkage-editing of the program.
However, since the Executive of BS2000 automatically subdivides the object program into pages (i.e. 4096-byte sections) and only loads pages into main memory as and when required during execution of the program, segmentation to relieve the load on main memory is not necessary in BS2000. It only becomes essential if virtual storage is not large enough to accept the entire program, including data. For this reason, it is neither practical nor possible to define a true overlay structure for programs that are intended to run in the upper address space.

Overlay structures for segmented programs can be defined with the following TSOSLNK statements.

Statement	Short description
OVERLAY	determines the overlay structure for the program: The OVERLAY statements of a linkage-editor run define which segments can overlay one another and at which locations in the object program they are to mutually overlap. OVERLAY statements are only permitted during linkage editing of a load module (PROGRAM statement); in the case of a prelinked object module (MODULE statement), they are rejected with an error message. In the address space above 16 Mbytes, (LOADPT=*XS entry in the PROGRAM or OVERLAY statement) no true overlay structures are possible; although the linkage editor will accept the OVERLAY statement, it will arrange the segments sequentially on the basis of their addresses.
TRAITS	defines for a program segment that it should be aligned on page boundaries during loading, can only be read during the program run. (READONLY=Y specified)