.bp odd
.cs 5
.he
.mt 5
.mb 6
.pl 66
.ll 65
.po 10
.hm 2
.fm 2
.ft All Information Presented Here is Proprietary to Digital Research
.he
.ce 2
.tc 3  Command File Format 
.sh
Section 3
.qs
.sp
.sh
Command File Format
.qs
.he CP/M-8000 Programmer's Guide              3.1  Command File Format
.sp 2
.pp 5
This section describes the format of a command file.  
The linker processes one or more compiled or assembled files to
produce an executable machine-readable file called a command
file.  By default, a command file has a filetype of 8000. 
.ix command file
.ix symbol table
.pp
A command file always contains a header, two program segments
(a text segment and an initialized data segment), and optionally
contains a symbol table and relocation information.  These components are 
described in the following sections. 

============ THE ENTIRE REMAINDER OF THIS SECTION MUST BE ==========
============ RE-WRITTEN BASED ON INFORMATION IN X.OUT.H   ==========
.sp 2
.tc    3.1  The Header and Program Segments
.sh
3.1  The Header and Program Segments
.ix header
.ix program segments
.qs
.pp
The header, the first component in the file, specifies
the size and starting address of the other components in the command 
file, which are listed below.
.sp 2
.in 5
.ti -2
o Program segments:
.sp
text:  contains the program instructions.
.sp
.in 12
.ti -7
data:  contains data initialized within the command file.
.sp
.ti -7
block storage segment (bss): 
.sp 0 
specifies space for uninitialized data generated by the program during
execution.  Although space for the bss is specified in the source command
file, the space is not allocated until the command file is loaded in memory.
Therefore, the source command file on the disk contains no uninitialized data. 
.sp
.in 5
.ti -2
o Symbol table: defines referenced symbols.
.sp
.ti -2
o Relocation information:
.sp 0
.in 12
specifies the relative relocation of 
each word within each program segment, if required. 
.in 0
.sp
.ix command file format
.pp
The command file format supports two types of headers.  The size
and content of each type differs.  The contiguity of the  program
segments determines which type of header a command file contains.
When the program segments must be contiguous, the file contains a
14-word header in the format shown in Figure 3-1.  When the
program segments can be noncontiguous, the file contains an
18-word header in the format shown in Figure 3-2.  The first word
of each header contains a hexadecimal integer that defines which
type of header the file contains. 
.sp 3
.po 5
.nf
Byte      Sample Values          Size            Contents 
Offset 
                                    
                               1 Word       Integer 601AH denotes text,
  0H      601AH                             data, and bss are contiguous
       
  2H         2376H             1 Longword   Number of bytes in text segment 
       
  6H          422H             1 Longword   Number of bytes in data segment
       
 0AH         1806H             1 Longword   Number of bytes in bss      
       
 0EH          142H             1 Longword   Number of bytes in symbol table  

 12H         0000H             1 Longword   Reserved; always zero      
       
 16H          500H             1 Longword   Beginning of text segment and  
                                            of program execution
 1AH       00H           
                               1 Word       Integer flag for relocation
                                            bits;  if 0, relocation bits
                                            exist;  if not 0, no relocation
                                            bits exist. 

 
.fi
.po 10
.ce
.sh
Figure 3-1.  Header for Contiguous Program Segments
.qs
.sp 2
.pp
To create a file that can contain noncontiguous program segments,
specify the -T, -D, and -B linker options described in
Section 6 when you link the files.  The header, identified by
601BH denotes the size and location of each program
segment.  Note that this header indicates the program segments 
can be noncontiguous and does not imply the segments must be 
noncontiguous.  See Figure 3-2.
.sp 2
.ne 32
.nf
.po 5
Byte    Sample Values        Size            Contents
Offset
                                    
                            1 Word       Integer 601BH denotes text, data,
 0H      601BH                           and bss can be noncontiguous
      
 2H        57864H           1 Longword   Number of bytes in text segment
      
 6H          446H           1 Longword   Number of bytes in data segment
      
0AH         2568H           1 Longword   Number of bytes in bss
      
0EH           69H           1 Longword   Number of bytes in symbol table
      
12H         0000H           1 Longword   Reserved; always zero
      
16H          500H           1 Longword   Beginning of text segment 
      
1AH       00H        
                            1 Word       Integer flag for relocation bits;
                                         if 0, relocation bits exist; if 
                                         not 0, no relocation bits exist.
                         
      
 1CH       57D64H           1 Longword   Starting address of data segment
      
 20H       581AAH           1 Longword   Starting address of bss
      
.fi
.po 10
.sp 2
.ce
.sh
Figure 3-2.  Header for Noncontiguous Program Segments
.sp
.qs
.he CP/M-8000 Programmer's Guide                 3.2  The Symbol Table
.sp
.pp
The linker computes the size of the segments in bytes.  The result is always
rounded up to an even number.  For example, the linker adds a byte to a program
segment that contains an odd number of bytes.  The linker does not include the 
size of the header when it computes the size of the segments. 
.pp
After a program is linked and loaded in memory, it contains three 
program segments:
text, initialized data, and uninitialized data (bss).  
The BDOS Program Load Function (59) zeroes the
bss when a program is loaded.  A program begins
execution at the beginning of the text segment.  See Figures 3-1 and 3-2 
above. 
.sp 2
.tc    3.2  The Symbol Table
.he CP/M-8000 Programmer's Guide                 3.2  The Symbol Table
.sh
3.2  The Symbol Table 
.qs
.pp
The symbol table lists all the symbols specified in a program.  
Each symbol in the table consists of a 7-word entry that describes the symbol 
name, type, and value.  See Figure 3-3.
.bp
.ix symbol table
.in 3
.nf
          Field     BYTE
   
                          N               A         WORD
               
                          M               E        
          Name    
                        Null            Null       
 
                        Null            Null       
                  
          Type                A400H                
                  
                
          Value               A6F0H 
                
                
.sp
.fi
.in 0
.ce
.sh
Figure 3-3.  Entry in Symbol Table
.sp 2
.pp
The name
field, the first four words, contains the ASCII name of the
symbol.  This field is padded with null characters when the ASCII
name is less than eight characters.  The fifth word contains the
symbol type.  Valid values are listed in Table 3-1. 
.sp 2
.ce
.sh
Table 3-1.  Values For Symbol Types
.sp 
                        Type                   Value
.sp 
.qs
                defined                        8000H
.sp
                equated                        4000H
.sp
                global                         2000H
.sp
                equated register               1000H
.sp
                external reference              800H
.sp
                data based relocatable          400H
.sp
                text based relocatable          200H
.sp
                bss based relocatable           100H

.sp
.pp
When specifying a symbol type with multiple characteristics, the
linker uses an OR instruction to combine several of the above
values.  For example, to specify a defined, global, data based,
relocatable symbol, the linker combines the values of each
characteristic for a value of A400H. 
.ix symbol type
.pp
The last field in an entry is the value field.  It consists of a
longword that contains the value of the symbol.  The value can be
an address, a register number, the value of an expression, or
some other value.  When the value field is nonzero and the type 
field contains an external symbol, the linker
interprets the symbol to be a common region in which the size of
the region equals the value of the symbol. 
.sp 2
============= ALL PRINTING OF OBJECT FILE INFO DONE WITH XDUMP =========
.ix symbol table, printing
.tc         3.2.1  Printing The Symbol Table
.sh
3.2.1  Printing The Symbol Table
.qs
.pp
Use the NM68 Utility to print the symbol table of an object or 
command file.  To invoke this utility, specify
the NM68 command and filename as shown below.
.sp
.ti 8
NM68 filename.O [>filespec]
.pp
You must enter the filename of an object file or a command 
file.  You can optionally redirect the NM68 output from your console to a 
file.  To redirect the NM68 output to a file, specify a
greater than sign (>) followed by a file specification after
the filename and filetype of the file from which NM68 prints the
symbol table.
.pp
The NM68 utility does not sort the symbols; it prints them in the order in 
which they appear in the file.  Each symbol name is printed, followed by its 
value and one or more of the type descriptors listed below:
.sp 2
.nf
.in 3
o equ (equated)
o global
o equreg (equated register)
o external
o data
o text
o bss
o abs (absolute)
.fi
.in 0
.sp 2
.he CP/M-8000 Programmer's Guide           3.3  Relocation Information
.tc    3.3  Relocation Information
.sh
3.3  Relocation Information
.qs
.ix relocation information
.pp
Relocation information is optional.  The header relocation word,
the last word in the header, indicates whether relocation
information exists.  When its value is zero, relocation
information exists.  None exists when the its value is nonzero. 
.pp
Relocation information specifies the relocation of words in program
segments.  One word of relocation information, called a relocation word,
exists for each word in each of the program segments.  The assembler and
compiler generate relocation words for external symbols and address
constants referenced in the text and data program segments.  The linker and
sometimes the BDOS Program Load Function (59) use these relocation words as
described below. 
.pp
The linker resolves external symbols when
linking files by modifying bits 0 through 2 of each relocation
word that references an external symbol.
After being modified, the relocation word indicates the program
segment that the symbol references.  Therefore, instead
of referencing an external symbol, the relocation word references
a word located in one of the program segments.  Because the 
linker only modifies relocation words that refer to external
symbols, relocation words that do not reference this type of
symbol have the same value in the source file input to the linker 
and the 
executable file output by the linker.
.ix relocation words
.pp
================= RELOCATION ON LOADING IS NOT SUPPORTED =============

The BDOS Program Load Function uses relocation words when it
loads a program in a location other than the one at which it was
linked.  The Program Load Parameter Block (LPB) used by the
Program Load Function specifies where the program is loaded.  When
the LPB specifies a location other than the linked location, the
BDOS computes a bias (the difference between where a program
segment is linked and where it will be loaded in memory).  When
loading the program, the BDOS adds the bias as indicated by the
relocation words to the address of the relocatable words in the
text and/or data segments.  However, when the BDOS loads the
program in the memory locations at which it was linked, the BDOS
does not use the relocation words. 
.ix Program Load Parameter Block (LPB)
.sp 2
.tc         3.3.1  The Format of A Relocation Word
.sh
3.3.1  The Format Of A Relocation Word
.qs
.pp 
A relocation word is a 16-bit quantity.  Bits 0 through 2 in each
relocation word indicate the type of address referenced and, if
applicable, designate the segment to which the relocation word
refers.  Values for these bits are described in Table 3-2. 
.sp 2
.sh
.ce
Table 3-2.  Relocation Word Values (bits 0 through 2)
.sp
.in 5
.ll 60
Value                     Description
.in 12
.ti -5
.sp 
00   no relocation information required; the reference is absolute
.sp
.ti -5
01   reference relative to the base address of the data segment
.sp
.ti -5
02   reference relative to the base address of the text segment
.sp 
.ti -5
03   reference relative to the base address of the bss 
.sp
.ti -5
04   references an undefined symbol
.sp
.ti -5
05   references the upper word of a longword; the next relocation word 
contains the value determining whether the reference is absolute or 
dependent on the base address of the text or data segments, or the bss.
.bp
.in 0
.ll 65
.sh
.ce
Table 3-2.  (continued)
.sp
.in 5
.ll 60
Value                     Description
.in 12
.sp
.ti -5
06   16-bit PC-relative reference
.sp
.ti -5
07   indicates the first word of an instruction, which does not 
require relocation information.
.in 0
.ll 65
.mb 6
.fm 2
.pp
The remaining bits, 3 through 15, are not used unless the program
references an external symbol.  In that case, these bits contain
an index to the symbol table.  The index specifies the entry
number of the symbol listed in the symbol table.  Entry numbers in the
symbol table are numbered sequentially starting with zero. 
.he CP/M-8000 Programmer's Guide            3.3  Relocation Words
.sp 2
.ce
End of Section 3
.bp
.he CP/M-8000 Programmer's Guide               End of Section 3
.sp 50
.nx four


