spdos.gml

开放源码的编译器open watcom 1.6.0版的源代码

.*
.*
.helppref DOS:
:set symbol="unique_lbl" value="dos".
:set symbol="opsys" value="DOS".
:set symbol="sysprompt" value="".
:set symbol="exeformat" value="dos".
:set symbol="exefmtup" value="DOS".
:set symbol="form_drctv" value="form dos".
:set symbol="syst_drctv" value="system dos".
:set symbol="exeextn" value="exe".
:set symbol="libvarname" value="lib".
:set symbol="tmpvarname" value="tmp".
.*
.im dosfiles
.*
.chap *refid=doschap The DOS Executable File Format
.*
.im wlintro
.im wlsyntax
.np
where
.bi directive
is any of the following:
.begnote $compact
.note ALIAS alias_name=symbol_name{,alias_name=symbol_name}
.if '&overlay' eq 'yes' .do begin
.note AUTOSECTION
.note BEGIN {section_type [INTO ovl_file] {directive}} END
.do end
.note DEBUG dbtype [dblist] | DEBUG [dblist]
.note DISABLE msg_num{,msg_num}
.note ENDLINK
.note FILE obj_spec{,obj_spec}
.if '&overlay' eq 'yes' .do begin
.note FIXEDLIB library_file{,library_file}
.note FORCEVECTOR symbol_name{,symbol_name}
.do end
.note FORMAT DOS [COM]
.note LANGUAGE lang
.note LIBFILE obj_file{,obj_file}
.cw !
.note LIBPATH path_name{&ps.path_name}
.cw ;
.note LIBRARY library_file{,library_file}
:cmt. .note MODFILE obj_file{,obj_file}
.note MODTRACE obj_module{,obj_module}
.note NAME exe_file
.note NEWSEGMENT
.if '&overlay' eq 'yes' .do begin
.note NOVECTOR symbol_name{,symbol_name}
.do end
.note OPTION option{,option}
:cmt. where option is one of
.begnote $compact
.if '&overlay' eq 'yes' .do begin
.note AREA=n
.do end
.note ARTIFICIAL
.note [NO]CACHE
.note [NO]CASEEXACT
.note CVPACK
.if '&overlay' eq 'yes' .do begin
.note DISTRIBUTE
.do end
.note DOSSEG
.if '&overlay' eq 'yes' .do begin
.note DYNAMIC
.do end
.note ELIMINATE
.note [NO]FARCALLS
:cmt. crashes linker .note INCREMENTAL
.note MANGLEDNAMES
.note MAP[=map_file]
.note MAXERRORS=n
.note NAMELEN=n
.note NODEFAULTLIBS
.note NOEXTENSION
.if '&overlay' eq 'yes' .do begin
.note NOINDIRECT
.do end
.note OSNAME='string'
.note PACKCODE=n
.note PACKDATA=n
.note QUIET
.note REDEFSOK
.note SHOWDEAD
.if '&overlay' eq 'yes' .do begin
.note SMALL
.do end
.note STACK=n
.if '&overlay' eq 'yes' .do begin
.note STANDARD
.do end
.note START=symbol_name
.note STATICS
.note SYMFILE[=symbol_file]
.note [NO]UNDEFSOK
.note VERBOSE
.note VFREMOVAL
.endnote
.note OPTLIB library_file{,library_file}
.if '&overlay' eq 'yes' .do begin
.note OVERLAY class{,class}
.do end
.cw !
.note PATH path_name{&ps.path_name}
.cw ;
.note REFERENCE symbol_name{,symbol_name}
.if '&overlay' eq 'yes' .do begin
.note SECTION
.do end
.note SORT [GLOBAL] [ALPHABETICAL]
.note STARTLINK
.note SYMTRACE symbol_name{,symbol_name}
.note SYSTEM BEGIN system_name {directive} END
.note SYSTEM system_name
.if '&overlay' eq 'yes' .do begin
.note VECTOR symbol_name{,symbol_name}
.do end
.note # comment
.note @ directive_file
.endnote
:CMT. .synote
:CMT. .im objfile
:CMT. .im libfile
:CMT. .im objmod
:CMT. .mnote exe_file
:CMT. is a file specification for the name of the executable file.
:CMT. If no file extension is specified, a file extension of "exe" is assumed
:CMT. unless a "COM" executable file is being generated in which case a file
:CMT. extension of "com" is assumed.
:CMT. .mnote ovl_file
:CMT. is a file specification for the name of an overlay file.
:CMT. If no file extension is specified, a file extension of "ovl" is assumed.
:CMT. .mnote path_name
:CMT. is a path name.
:CMT. .mnote msg_num
:CMT. is a message number.
:CMT. .mnote directive_file
:CMT. is a file specification for the name of a linker directive file.
:CMT. If no file extension is specified, a file extension of "lnk" is assumed.
:CMT. .mnote map_file
:CMT. is a file specification for the name of the map file.
:CMT. If no file extension is specified, a file extension of "map" is assumed.
:CMT. .mnote symbol_file
:CMT. is a file specification for the name of the symbol file.
:CMT. If no file extension is specified, a file extension of "sym" is assumed.
:CMT. .mnote symbol_name
:CMT. is the name of a symbol.
:CMT. .mnote alias_name
:CMT. is the name of an alias symbol.
:CMT. .mnote system_name
:CMT. is the name of a system.
:CMT. .mnote comment
:CMT. is any sequence of characters.
:CMT. .mnote class
:CMT. is a segment class name.
:CMT. .im lnkvalue
:CMT. .esynote
.*
.im wlprompt
.*
.im wlmemlay
.im wlmem
.*
.section *refid=useover Using Overlays
.*
.np
.if '&overlay' eq 'no' .do begin
The creation of overlaid executables is not supported by this version
of the &lnkname..
.do end
.el .do begin
.ix 'overlays'
Overlays are used primarily for large programs where memory
requirements do not permit all portions of the program to reside in
memory at the same time.
.ix 'root'
.ix 'overlay area'
An overlayed program consists of a
.us root
and a number of
.us overlay areas.
.np
The root always resides in memory.
The root usually contains routines that are frequently used.
For example, a floating-point library might be placed in the root.
Also, any modules extracted from a library file during the linking
process are placed in the root unless the "DISTRIBUTE" option is
specified.
This option tells the &lnkname to distribute modules extracted from
libraries throughout the overlay structure.
See the section entitled :HDREF refid='xdistri'. for information on
how these object modules are distributed.
Libraries can also be placed in the overlay structure by using the
"FIXEDLIB" directive.
See the section entitled :HDREF refid='xfixedl'. for information on how
to use this directive.
.np
An
.us overlay area
is a piece of memory shared by various parts of a program.
Each overlay area has a structure associated with it.
This structure defines where in the overlay area sections of a program
are loaded.
.ix 'overlays'
Sections of a program that are loaded into an overlay area are
called
.us overlays.
.np
The &lnkname supports two overlay managers: the standard overlay manager and
the dynamic overlay manager.
The standard overlay manager requires the user to create an overlay structure
that defines the "call" relationship between the object modules that comprise
an application.
It is the responsibility of the user to define an optimal overlay structure
so as to minimize the number of calls that cause overlays to be loaded.
The "SMALL" and "STANDARD" options select the standard overlay manager.
The "SMALL" option is required if you are linking an application compiled
for a small code memory model.
The "STANDARD" option is required if you are linking an application compiled
for a big code memory model.
By default, the &lnkname assumes your application has been compiled using
a memory model with a big code model.
Option "STANDARD" is the default.
.np
The "DYNAMIC" option,
described in the section entitled :HDREF refid='xdynami'.,
selects the dynamic overlay manager.
The dynamic overlay manager is more sophisticated than the standard overlay
manager.
The user need not be concerned about the "call" relationship between the
object modules that comprise an application.
Basically, each module is placed in its own overlay.
The dynamic overlay manager swaps each module (overlay) into a single overlay
area.
This overlay area is used as a pool of memory from which memory for overlays
is allocated.
The larger the memory pool, the greater the number of modules that can
simultaneously reside in memory.
The size of the overlay area can be controlled by the "AREA" option.
See the section entitled :HDREF refid='xarea'. for information on
using this option.
.np
Note that the dynamic overlay manager can only be used with
applications that have been compiled using the "of" option and a big
code memory model.
.*
.beglevel
.*
.section Defining Overlay Structures
.*
.np
Consider the following directive file.
.millust begin
#
# Define files that belong in the root.
#
file file0, file1
#
# Define an overlay area.
#
begin
  section file file2
  section file file3, file4
  section file file5
end
.millust end
.autonote
.note
The root consists of
.id file0
and
.id file1.
.note
Three overlays are defined.
The first overlay (overlay #1) contains
.id file2,
the second overlay (overlay #2) contains
.id file3
and
.id file4,
and the third overlay (overlay #3) contains
.id file5.
.endnote
.np
The following diagram depicts the overlay structure.
:cmt. :set symbol='c0' value=&sysin+4
:cmt. :set symbol='c1' value=&c0+12
:cmt. :set symbol='c2' value=&c1+12
:cmt. :set symbol='c3' value=&c2+12
:cmt. .tb set `
:cmt. .tb &c0+1 &c0+4 &c1+1 &c1+4 &c2+1 &c2+4 &c3+2
:cmt. .bx &c0 &c3
:cmt. ```file0```\{ start of root
:cmt. ```file1
:cmt.
:cmt. .bx &c0 &c1 &c2 &c3
:cmt. #1``#2``#3``\{ start of overlay area
:cmt. `file2``file3``file5
:cmt. ```file4
:cmt.
:cmt. .bx end
.millust begin
+-----------------------------------+<- start of root
|                                   |
|               file0               |
|               file1               |
|                                   |
+-----------+-----------+-----------+<- start of overlay
| #1        | #2        | #3        |   area
|           |           |           |
|   file2   |   file3   |   file5   |
|           |   file4   |           |
|           |           |           |
+-----------+-----------+-----------+
.millust end
.autonote Notes:
.note
The 3 overlays are all loaded at the same memory location.
Such overlays are called
.ix 'parallel overlays'
.ix 'overlays parallel'
.us parallel.
.endnote
.np
In the previous example, only one overlay area was defined.
It is possible to define more than one overlay area as demonstrated
by the following example.
.millust begin
#
# Define files that belong in the root.
#
file file0, file1
#
# Define an overlay area.
#
begin
  section file file2
  section file file3, file4
  section file file5
end
#
# Define an overlay area.
#
begin
  section file file6
  section file file7
  section file file8
end
.millust end
.np
Two overlay areas are defined.
The first is identical to the overlay area defined in the previous
example.
The second overlay area contains three overlays; the first overlay
(overlay #4) contains
.id file6,
the second overlay (overlay #5) contains
.id file7,
and the third overlay (overlay #6) contains
.id file8.
.np
The following diagram depicts the overlay structure.
:cmt. :set symbol='c0' value=&sysin+4
:cmt. :set symbol='c1' value=&c0+12
:cmt. :set symbol='c2' value=&c1+12
:cmt. :set symbol='c3' value=&c2+12
:cmt. .tb set `
:cmt. .tb &c0+1 &c0+4 &c1+1 &c1+4 &c2+1 &c2+4 &c3+2
:cmt. .bx &c0 &c3
:cmt. ```file0```\{ start of root
:cmt. ```file1
:cmt.
:cmt. .bx &c0 &c1 &c2 &c3
:cmt. #1``#2``#3``\{ start of overlay area
:cmt. `file2``file3``file5
:cmt. ```file4
:cmt.
:cmt. .bx
:cmt. #4``#5``#6``\{ start of overlay area
:cmt. `file6``file7``file8
:cmt.
:cmt. .bx end
.millust begin
+-----------------------------------+<- start of root
|                                   |
|               file0               |
|               file1               |
|                                   |
+-----------+-----------+-----------+<- start of overlay
| #1        | #2        | #3        |   area
|           |           |           |
|   file2   |   file3   |   file5   |
|           |   file4   |           |
|           |           |           |
+-----------+-----------+-----------+<- start of overlay
| #4        | #5        | #6        |   area
|           |           |           |
|   file6   |   file7   |   file8   |
|           |           |           |
+-----------+-----------+-----------+
.millust end
.np
In the above example, the "AUTOSECTION" directive could have been used to
define the overlays for the second overlay area.
The following example illustrates the use of the "AUTOSECTION" directive.
.millust begin
#
# Define files that belong in the root.
#
file file0, file1
#
# Define an overlay area.
#
begin
  section file file2
  section file file3, file4
  section file file5
end
#
# Define an overlay area.
#
begin
  autosection
  file file6
  file file7
  file file8
end
.millust end
.np
In all of the above examples the overlays are placed in the
executable file.