LINK is a utility used to combine relocatable object modules into an absolute file ready for execution under CP/M or MP/M. The relocatable object modules may be of two types. The first has a filetype of REL, and is produced by PL/I-80, RMAC, or any other language translator that produces relocatable object modules in the Microsoft format. The second has a filetype of IRL, and is generated by the CP/M librarian LIB. An IRL file contains the same information as a REL file, but includes an index which allows faster linking of large libraries.
Upon completion, LINK lists the symbol table, any unresolved symbols,
a memory map and the use factor at the console. The memory map shows the
size and locations of the different segments, and the use factor indicates
the amount of available memory used by LINK as a hexadecimal percentage.
LINK writes the symbol table to a SYM file suitable for use with the CP/M
Symbolic Instruction Debugger (SID), and creates a COM or PRL file for
direct execution under CP/M or MP/M.
LINK is invoked by typing
LINK filename1{,filename2,...,filenameN}
where filename1,...,filenameN are the names of the object
modules to be linked. If no filetype is specified, REL is assumed. LINK
will produce two files: filename1.COM and filename1.SYM. If some other
filename is desired for the COM and SYM files, it may be specified in the
command line as follows:
LINK newfilename=filename1{,filename2,...,filenameN}
When linking PL/I programs, LINK will automatically search the run-time
library file PLILIB.IRL on the default disk and include any subroutines
used by the PL/I programs.
XXABS.$$$ XXPROG.$$$ XXDATA.$$$ XXCOMM.$$$
YYABS.$$$ YYPROG.$$$ YYDATA.$$$ YYCOMM.$$$
These files are deleted if LINK terminates normally, but may remain
on the disk if LINK aborts due to an error condition.
LINK switches are used to control the execution parameters of LINK. They are enclosed in square brackets immediately following one or more of the filenames in the command line, and are separated by commas.
Example:
LINK TEST[L4000],IOMOD,TESTLIB[S,NL,GSTART]
All switches except the S switch may appear after any filename in
the command line. The S switch must follow the filename to which it refers.
1.2.1. The Additional Memory (A) Switch
The A switch is used to provide LINK with additional space for symbol
table storage by decreasing the size of LINK's internal buffers. This switch
should be used only when necessary, as indicated by a MEMORY OVERFLOW error,
since using it causes the internal buffers to be stored on the disk, thus
slowing down the linking process considerably.
1.2.2. The Data origin (D) Switch
The D switch is used to specify the origin of the data and common segments.
If not used, LINK will put the data and common segments immediately after
the program segment. The form of the D switch is Dnnnn, where nnnn is the
desired data origin in hex.
The G switch is used to specify the label where program execution is
to begin, if it does not begin with the first byte of the program segment.
LINK will put a jump to the label at the load address. The form of the
G switch is G<label>.
1.2.4. The Load Address (L) Switch
The load address defines the base address of the COM file generated by LINK. Normally, the load address is 100H, which is the base of the Transient Program Area in a standard CP/M system. The form of the L switch is Lnnnn, where nnnn is the desired load address in hex. The L switch also sets the program origin to nnnn, unless otherwise defined by the P switch.
Note that COM files created with a load address other than 100H will
not execute properly under a standard CP/M system.
1.2.5. The Memory Size (M) Switch
The M switch may be used when creating PRL files for execution under
MP/M to indicate that additional data space is required by the PRL program
for proper execution. The form of the M switch is Mnnnn, where nnnn is
the amount of additional data space needed in hex.
1.2.6. The No List (NL) Switch
The NL switch is used to suppress the listing of the symbol table at
the console.
1.2.7. The No Recording of Symbols (NR) Switch
The NR switch is used to suppress the recording of the symbol table
file.
1.2.8. The Output COM File (OC) Switch
The OC switch directs LINK to produce a COM file. This is the default
condition for LINK.
1.2.9. The Output PRL File (OP) Switch
The OP switch directs LINK to produce a page relocatable PRL file for
execution under MP/M, rather than a COM file. See section
1.3 for more information on creating PRL files.
1.2.10. The Program Origin (P) Switch
The P switch is used to specify the origin of the program segment. If
not used, LINK will put the program segment at the load address, which
is 100H unless otherwise specified by the L switch. The form of the P switch
is Pnnnn, where nnnn is the desired program origin in hex.
1.2.11. The '?' Symbol (Q) Switch
Symbols in the PL/I run-time library begin with a question mark to avoid
conflict with user symbols. Normally LINK suppresses listing and recording
of these symbols. The Q switch causes these symbols to be included in the
symbol table listed at the console and recorded on the disk.
The S switch is used to indicate that the preceding file should be treated
as a library. LINK will search the file and include only those modules
containing symbols which are referenced but not defined in the modules
already linked.
Assembly language programs often contain references to symbols in the
base page such as BOOT, BDOS, DFCB, and DBUFF. To run properly under CP/M
(or as a COM file under MP/M) these symbols are simply defined in equates
as follows:
BOOT EQU 0 ;JUMP TO WARM BOOT
BDOS EQU 5 ;JUMP TO BDOS ENTRY POINT
DFCB EQU 5CH ;DEFAULT FILE CONTROL BLOCK
DBUFF EQU 80H ;DEFAULT 1/0 BUFFER
With PRL files, however, the base page itself may be relocated at
load time, so LINK must know that these symbols, while at fixed locations
within the base page, are relocatable. To do this, simply declare these
symbols as externals in the modules in which they are referenced:
EXTRN BOOT,BDOS,DFCB,DBUFF
and link in another module in which they are declared as publics
and defined in equates:
PUBLIC BOOT,BDOS,DFCB,DBUFF
BOOT EQU 0 ;JUMP TO WARM BOOT
BDOS EQU 5 ;JUMP TO BDOS ENTRY POINT
DFCB EQU 5CH ;DEFAULT FILE CONTROL BLOCK
DBUFF EQU 80H ;DEFAULT I/O BUFFER
END
A sample link is shown on the following pages. First the sample program
GRADE.PLI
is compiled, and then a COM file is created by LINK. LINK automatically
searches the PL/I run-time library PLILIB.IRL for the subroutines used
by GRADE. The Q switch causes the symbols taken from PLILIB.IRL to be included
in the symbol table listing (and the SYM file). The memory map following
the symbol table indicates the length and location assigned to each of
the segments. A use factor of 49 indicates that 49H%, or a little more
than a quarter of the memory available to LINK was used.
PL/I-80 V1.0, COMPILATION OF: GRADE
D: Disk Print
L: List Source Program
NO ERROR(S) IN PASS 1
NO ERROR(S) IN PASS 2
PL/I-80 V1.0, COMPILATION OF: GRADE
1 a 0000 average:
2 a 0006 proc options (main);
3 a 0006 /* grade averaging
program */
4 a 0006
5 c 0006 dcl
6 c 000D
sysin file,
7 c 000D
(grade,total,n) fixed;
8 c 000D
9 c 000D on error (1)
10 c 0014
/* conversion */
11 d 0014
begin;
12 e 0017
put skip list('Bad Value, Try Again.');
13 e 0033
get skip;
14 e 0044
go to retry;
15 d 0047
end;
16 d 0047
17 c 0047 on endfile (sysin)
18 d 004F
begin;
19 e 0052
if n ^= 0 then
20 e 005B
put skip list
21 e 008A
('Average is',total/n);
22 e 008A
stop;
23 d 008D
end;
24 d 008D
25 c 008D put skip list
26 c 00A9
('Type a List of Grades, End with Ctl-Z');
27 c 00A9 total = 0;
28 c 00AF n = 0;
29 c 00B9
30 c 00B9 retry:
31 c 00B9 put skip;
32 c 00CA
do while('1'b);
33 c 00CA
get list (grade);
34 c 00E2
total = total + grade;
35 c 00ED
n = n + 1;
36 c 00F7
end;
37 a 00F7 end average;
CODE SIZE = 00F7
DATA AREA = 004C
B>link grade[q]
LINK 1.0
AVERAG 0100 /?FPBNX/ 1B73 /SYSIN/
1B82 ?START 19FB
?ONCOP 18A1 ?SYSPR 02C5
?SKPOP 0430 ?SLCTS 135A
?PNCOP 01FD ?QIOOP 197A
?SYSIN 02C1 ?ID22N 13A6
?QICOP 1271 ?PNVOP 0221
?STOPX 1B13 ?RECOV 145B
?GNVOP 07C8 ?QCIOP 11EE
/?FILAT/ 1BA7 /?FPB/ 1BB0
?PNBOP 01F7 ?PNCPR 04CF
?IS22N 13EC ?SIOOP 02CA
?SIOPR 02E8 /?FPBST/ 1BDE /SYSPRI/
1BF1 ?OIOOP 05A7
?FPBIO 0758 ?OIOPR 05C6
?BSL16 130F ?SIGNA 1619
?SKPPR 0439 ?GNCPR 0942
?WRBYT 0E29 ?PAGOP 07BA
?NSTOP 1315 ?SMVCM 1383
?SJSVM 1320 ?SSCFS 136D
?QB08I 11DA ?OPNFI 0D06
/?FMTS/ 1C19 ?FPBOU 19CE
?FPBIN 1986 ?GNVPR 0805
?RDBYT 0E16 ?RDBUF 0E4F
?WRBUF 0E72 ?CLOSE 0F5B
?GETKY 0F8C ?SETKY 0FB2
?PATH 0F3F ?BDOS
0005 ?DFCB0 005C ?DFCB1
006C
?DBUFF 0080 ?ALLOP 14C5
?FREOP 155B ?ADDIO 1A5E
?SUBIO 1A75 ?WRCHR 19E4
?RFSIZ 10B7 ?RRFCB 1129
?RWFCB 112E ?QB16I 11DD
?IN20 13E4 ?CNVER 13F3
?BSL08 1309 ?SJSCM 1322
?SJSTS 1334 ?SLVTS 1358
?SMCCM 1387 ?ID22 13BE
?IN20N 13E4 ?ZEROD 1413
?IS22 13EC /?CONSP/ 1C21
?OFCOP 14A5 ?RSBLK 142A
?RECLS 1E60 ?ERMSG 1B2E
?BEGIN 1E5E /?ONCOD/ 1C42
?SIGOP 1609 ?STACK 1E58
?ONCPC 193E ?REVOP 18F6
/?CNCOL/ 1C45 ?BOOT 0000
?CMEM 1B73 ?DMEM 1E62
ABSOLUTE 0000
CODE SIZE 1A73 (0100-1B72)
DATA SIZE 021B (1C47-1E61)
COMMON SIZE 00D4 (1B73-1C46)
USE FACTOR 4F
A>b:grade
Type a List of Grades, End with Ctl-Z
50, 75, 25
^Z
Average is 50
End of Execution
A>b:grade
Type a List of Grades, End with Ctl-Z
50
75
zot,66
Bad Value, Try Again.
25
^Z
Average is 50
End of Execution
A>b:grade
Type a List of Grades, End with Ctl-Z
^Z
End of Execution
CANNOT CLOSE: An output file cannot be closed. The diskette may be write protected.
COMMON ERROR: An undefined common block has been selected.
DIRECTORY FULL: There is no directory space for the output files or intermediate files.
DISK READ ERROR: A file cannot be read properly.
DISK WRITE ERROR: A file cannot be written properly, probably due to a full diskette.
FILE NAME ERROR: The form of a source file name is invalid.
FIRST COMMON NOT LARGEST: A subsequent COMMON declaration is larger than the first COMMON declaration for the indicated block. Check that the files being linked are in the proper order, or that the modules in a library are in the proper order.
INDEX ERROR: The index of an IRL file contains invalid information.
INSUFFICIENT MEMORY: There is not enough memory for LINK to allocate its buffers. Try using the A switch.
INVALID REL FILE: The file indicated contains an invalid bit pattern. Make sure that a REL or IRL file has been specified.
INVALID SYNTAX: The command line used to invoke LINK was not properly formed.
MAIN MODULE ERROR: A second main module was encountered.
MEMORY OVERFLOW: There is not enough memory to complete the link operation. Try using the A switch.
MULTIPLE DEFINITION: The specified symbol is defined in more than one of the modules being linked.
NO FILE: The indicated file cannot be found.
OVERLAPPING SEGMENTS: LINK attempted to write a segment into memory already used by another segment. Probably caused by incorrect use of P and/or D switches.
UNDEFINED START SYMBOL: The symbol specified with the G switch is not defined in any of the modules being linked.
UNDEFINED SYMBOLS: The symbols following this message are referenced but not defined in any of the modules being linked.
UNRECOGNIZED ITEM: An unfamiliar bit pattern has been scanned (and ignored)
by LINK.
The information in a REL file is encoded in a bit stream, which is interpreted as follows:
1) If the first bit is a 0, then the next 8 bits are loaded according to the value of the location counter.
2) If the first bit is a 1, then the next 2 bits are interpreted as follows:
00 - special link item (see 3)3) A special item consists of:
01 - program relative. The next 16 bits are loaded after being offset by the program segment origin.
10 - data relative. The next 16 bits are loaded after being offset by the data segment origin.
11 - common relative. The next 16 bits are loaded after being offset by the origin of the currently selected common block.
- A 4 bit control field which selects one of 16 special link items described below.The following items are followed by a name field only.
- An optional value field which consists of a 2 bit address type field and a 16 bit address field. The address
type field is interpreted as follows:00 - absolute- An optional name field which consists of a 3 bit name count followed by the name in 8 bit ASCII characters.
01 - program relative
10 - data relative
11 - common relative
0000 - entry symbol. The symbol indicated in the name field is defined in this module, so the module should be linked if the current file is being searched (as indicated by the S switch).The following items are followed by a value field and a name field.0001 - select common block. Instructs LINK to use the location counter associated with the common block indicated in the name field for subsequent common relative items.
0010 - program name. The name of the relocatable module. LINK checks that the first item in each module is a program name, and issues an error if it is not.
0011 - unused.
0100 - unused.
0101 - define common size. The value field determines the amount of memory to be reserved for the common block described in the name field. The first size allocated to a given block must be larger than or equal to any subsequent definitions for that block in other modules being linked.The following items are followed by a value field only.0110 - chain external. The value field contains the head of a chain which ends with an absolute 0. Each element of the chain is to be replaced with the value of the external symbol described in the name field.
0111 - define entry point. The value of the symbol in the name field is defined by the value field.
1000 - unused.
1001 - external plus offset. The following two bytes in the current segment must be offset by the value of the value field after all chains have been processed.The following item has no value field or name field.1010 - define data size. The value field contains number of bytes in the data segment of the current module.
1011 - set location counter. Set the location counter to the value determined by the value field.
1100 - chain address. The value field contains the head of a chain which ends with an absolute 0. Each element of the chain is to be replaced with the current value of the location counter.
1101 - define program size. The value field contains the number of bytes in the program segment of the current module.
1110 - end module. Defines the end of the current module. if the value field contains a value other than absolute 0, it is to be used as the start address for the program being linked. The next item in the file will start at the next byte boundary.
1111 - end file. Follows the end module item of the last module in the file.
An IRL file consists of three parts: a header, an index and a REL section.
The header contains 128 bytes defined as follows:
byte 0 - extent number of first record of REL section.The index consists of a number of entries corresponding to the entry symbol items in the REL section. The entries are of the form:byte 1 - record number of first record of REL section.
bytes 2-127 - currently unused.
+-----+-----+-----+-----+-----+---------+-----+-----+
| | | | | | | | |
| e | r | b | c1 | c2 | . . . | cn | d |
| | | | | | | | |
+-----+-----+-----+-----+-----+---------+-----+-----+
where:
e = extent offset from start of REL section to start of moduleThe index is terminated by an entry in which c1 = 0FFH. The remainder of the record containing the terminating entry is unused.
r = record offset from start of extent to start of module
b = byte offset from start of record to start of module
c1-cn = name of symbol
d = end of symbol delimiter (0FEH)
The REL section contains the relocatable object code as described in the previous section.