1. LINK LINKAGE EDITOR


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.
 

1.1. LINK Operation

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.

 

A number of optional switches, provided for additional control of the link operation, are described in the following section.
 

During the link process, LINK may create up to eight temporary files on the default disk. The files are named:
 
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.
 

1.2. LINK Switches

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.
 

1.2.3. The Go (G) Switch

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.
 

1.2.12. The Search (S) Switch

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.
 

1.3. Creating MP/M PRL Files

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


1.4. Sample Link

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
 

1.5. Error Messages

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.
 

1.6. Format of REL Files

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)
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.
3) A special item consists of:
- A 4 bit control field which selects one of 16 special link items described below.
- 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
01 - program relative
10 - data relative
11 - common relative
- An optional name field which consists of a 3 bit name count followed by the name in 8 bit ASCII characters.
The following items are followed by a name field only.
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).

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.

The following items are followed by a value field and a name field.
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.

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.

The following items are followed by a value field only.
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.

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.

The following item has no value field or name field.
1111 - end file. Follows the end module item of the last module in the file.


1.7. Format of IRL Files

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.

byte 1 - record number of first record of REL section.

bytes 2-127 - currently unused.

The index consists of a number of entries corresponding to the entry symbol items in the REL section. The entries are of the form:
 
+-----+-----+-----+-----+-----+---------+-----+-----+
|     |     |     |     |     |         |     |     |
|  e  |  r  |  b  |  c1 |  c2 |  . . .  |  cn |  d  |
|     |     |     |     |     |         |     |     |
+-----+-----+-----+-----+-----+---------+-----+-----+


where:

e = extent offset from start of REL section to start of module
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 index is terminated by an entry in which c1 = 0FFH. The remainder of the record containing the terminating entry is unused.

The REL section contains the relocatable object code as described in the previous section.


Next     Contents     Previous     Back to Home Page