.HE ^^^^^^^^^^^^^^^^^^^^^^^^^^RAG^SOFTWARE^TI^99/4A^LINKER^^^^^^^^^^^^^^^%
.PA 1;BP
@INTRODUCTION
.SP
The TI 99/4A LINKER is a tool for
building assembler language memory
image programs from tagged object.
It makes this process simple and
straight forward.  LINKER's main
features are:
.SP;LM +5;IN -3
1.^tagged object modules may be
compressed and/or uncompressed,
2.^tagged object modules may be
absolute or relocatable,
3.^a library search can be done to
resolve REFs,
4.^a listing can be produced containing
object information, memory maps and
REF/DEF cross-references,
5.^the memory image program can be
built to load anywhere in the TI
99/4A's 64K address space.
.SP;LM -5;IN +0
The LINKER has three modes of
operation depending upon the type of
input in its control file.
.SP;LM+5;IN-3
1.^Automatic.  A single tagged object
file is processed, a single library
file is searched if necessary and a
memory image program is produced.  The
memory image program will load as if
the tagged object had been loaded by
the E/A loader, excluding the E/A
routines in low memory.  That is, the
object is loaded first in the 24K high
memory block, then into the 8K low
memory block.
.SP
2.^Semi-automatic.  A control file is
processed which names one or more
tagged object files to be processed and
names one or more libraries to be
searched.  The resulting memory image
program will load as if the tagged
object had been loaded by the E/A
loader, excluding the E/A routines in
low memory.  That is, the object is
loaded first in the 24K high memory
block, then into the 8K low memory
block.
.SP
3.^Complete Programmer Control.  A
control file is processed which names
one or more tagged object files to be
processed, names one or more libraries
to be searched and which designates the
memory layout for the resulting memory
image program.
.LM-5;IN+0
.BP
@DISK^CONTENTS
.SP
The distribution disk is a single sided
single density disk containing the
following files.
.SP;LM +10;IN -10
LINKER^^^^The linker program in memory
image form.
LINKES^^^^The second segment of LINKER.
LNKDOC^^^^The documentation for LINKER
to be printed by the TI WRITER
formatter.
LNKDOC1^^^Continuation of the
documentation.
LNKDOC2^^^Continuation of the
documentation.
LNKDOC3^^^Continuation of the
documentation.
LNKINST^^^Installation program for
LINKER
LOAD^^^^^^Extended BASIC loader for
LINKER
LOADINST^^Extended BASIC loader for
LNKINST.
RAGLIB^^^^A library of routines
similiar to those provided by the E/A,
MM or XB.
.SP2;LM-10;IN+0
@FAIRWARE
.SP
This package is being made available
via the Fairware concept.  If you like
the package and are using it, send a
donation to:
.SP;IN +15
R. A. Green
1032 Chantenay Drive
Gloucester, Ont. Canada
K1C 2K9
.IN+0;SP
And, at the same time, distribute
complete copies of the package to your
friends.  If you have any suggestions
for improvements or have found any bugs
please forward them to the above
address.
.SP2
@TAILORING^THE^LINKER

The LINKER is designed to work with
various loaders, memory configurations
and printers, and to produce a compact
listing to reduce print time and paper
usage.  In order to do this you must
"install" the LINKER with options
suitable to your environment.  The
LNKINST (E/A Option 5) program or the
LOADINST (XBASIC) program on the
distribution disk will prompt you for
the values for your environmemt and
then modify the LINKER on disk so that
it will use your values.

In order to produce a compact listing
and still have the listing contain full
information, the printer should be set
up to print in elite mode at 8 lines
per inch.  Most printers can do this
although it is not required.  To
accomplish this printing, the LINKER
will send a "setup sequence" of control
characters to the printer before
printing the first line of the listing,
and will send a "reset sequence" of
control characters to the printer after
printing the last line of the listing.
The LINKER will truncate any lines that
are too long for the printer and will
count the number of lines per page.
The length of a line and the number of
lines per page must be coordinated with
the way your printer is set up.  The
LINKER as distributed is set up for
a GEMINI 10X printer.

During entry of your default values,
press ENTER to proceed to the next
prompt or press BACK (FCTN 8) to begin
again at the beginning.  Typing an
asterisk (*) as the first character of
the line indicates that the
corresponding default value is not to
be changed.  A response of all blanks
or of just pressing ENTER indicates
that there is to be &no default value.
Each of the prompts is described below.

&Installation^Drive^Number

Enter the number of the disk containing
a copy of the original LINKER modules.
During installation the LINKER module,
LINKER, is loaded from this drive and
then saved back to the drive.  The
default installation drive is 1 (i.e.
DSK1).

&Printer^Name

Enter the device/filename for your
printer.  If no printer name is
entered, then the LINKER will prompt
for the printer name each time it is
run.  The distributed printer name is
"PIO".

&Printer^Setup^Sequence

Enter the printer control codes
required for making your printer print
the LINKER listing in the mode you
want. For example: in elite mode at 8
lines/inch, or in compressed mode at 8
lines/inch.  Enter the data in
hexadecimal (2 digits per byte).  You
will have to refer to your printer
manual to determine the proper codes
for your printer.  The distributed
setup seguence is "1B42021B30", which
makes the GEMINI 10X print in elite
mode at 8 lines per inch.

&Printer^Reset^Sequence

Enter the printer control codes
required to make your printer revert to
its normal printing mode.  This
sequence should contain a form feed to
position the printer at the top of the
page.  Most printers have a single
"reset" code.  Enter the data in
hexadecimal.  You will have to refer to
your printer manual to determine the
proper codes for your printer.

The distributed reset seguence is
"122764", which is form feed and reset
for the GEMINI 10X.

&Lines^Per^Page

Enter, in decimal, the number of lines
to print before a form feed is issued.
The number of lines per page depends
upon your paper size and the printer
setup.  For example, enter 75 for 11"
paper at 8 lines/inch, or 55 for 11"
paper at 6 lines/inch.  You must allow
for the top and bottom margin on the
page.  The distributed value is 75
lines per page.

&Maximum^Line^Length

Enter, in decimal, the maximum number
of characters to be printed per line.
The LINKER can print up to 116
characters on a line.  All lines will
be truncated to the length you specify.
The value specified depends upon the
capability of your printer and on the
way your printer is set up.  Most
printers can print an 80 character line
in standard mode and a 96 character
line in elite mode.  The distributed
value is 96 characters per line.

&Default^Options

Enter up to 6 one letter option codes
that are to be used as the defaults
when no options are entered during a
LINKER run.  The distributed default
options are "MLX".

&Type^of^Return^(RT^or^BLWP)

The LINKER can exit in two ways.
First, it can return to the loader (or
cartridge) that loaded it.  This is
what is done if "RT" is specified.
This is the normal return for the
Editor/Assembler Cartridge Option 5 and
the TI Writer Cartridge Option 3.
Second, it can execute a "BLWP @@0"
which causes the 4A to reset.  This is
done if "BLWP" is specified.  Some
loaders are not prepared for programs
to return (i.e. a popular RAM DISK
LOADER), the BLWP return will suit
these loaders.  The distributed value
is RT.
.SP2
@RUNNING @THE @LINKER
.SP
The RAG Software LINKER is independent
of the module used to run it.  It has
been run using Option 3 of TI Writer,
Option 5 of Editor/Assembler, Extended
BASIC and GRAM KRACKER.
.SP
Using Extended BASIC, the LOAD program
on the disk automatically loads the
LINKER.  Using the other modules,
the file name of the LINKER is LINKER.
.SP
The LINKER is designed to make use of
any RAM that you might have in the
"module slot".  The LINKER work areas,
called "frames" are each 1K bytes in
size.  These frames are used for two
purposes, first, for the REF/DEF table
and, second, to build 1K sections of
the memory image program.  With only
the memory expansion unit there are 24
1K frames.  If you have a cartridge
with RAM such as TI's Mini Memory,
DataBioTics' Super Space, Millar's
Graphics' Gram Kracker or a home built
super E/A you can add 4 or 8 additional
frames to the LINKER's work area to
allow processing of a larger memory
image program.
.SP
The LINKER will prompt you for the
control file name, the print file name
(if no default installed), the library
file name, the memory image file name
and the options for this run.
.SP;LM+9;IN-9
CONTROL:^Enter the device and file name
of your control file or of the single
object file that you want processed.
.SP
PRINTER:^Enter the device and file name
for the printer file.  This prompt is
issued only if no printer was specified
during installation of the LINKER.  If
no listing options are selected, no
printer file is required.
.SP
LIBRARY:^Enter the device and file name
of the final library to be searched for
unresolved REFs.  A null entry (i.e.
pressing ENTER only) means no library
is to be searched.
.SP
OUTPUT:^^Enter the device and file name
into which your memory image program is
to be written.  If required, more than
one file may be written.  The names for
the second and following files are
generated by incrementing the last byte
of the given name.
.SP
OPTIONS:^Enter the one letter option
codes.  The codes may be entered in any
order.  The option codes are:
.LM +6;IN -4
L^-^produce a listing of control
statements and other optional data,
F^-^show full information in the
listing about each tagged object module
processed,
M^-^include in the listing a memory map
of the memory image program,
X^-^include in the listing a
cross-reference listing of all REFs and
DEFs,
P^-^Pause with a message to await
changing of disks for the library file
and for the memory image program file,
4^-^Use the 4K of RAM at address >7000
for work area frames,
8^-^Use the 8K of RAM at address >6000
for work area frames.
.LM -15;IN +0;SP
If during prompting you wish to restart
simply press BACK.
.SP 2
@NOTE
.SP
If you have trouble understanding the
following sections, do not despair.
The LINKER is a powerful tool so that
describing its functions sometimes gets
complicated.  At the same time, LINKER
is easy to use if not all of its
function is required for the job.  If
you do get bogged down in the following
sections skip them and go directly to
the examples at the end.  The first
three or four examples will show you
how to do the easy things easily.
.BP
@RESTRICTIONS
.SP
The LINKER has the following
restrictions.
.SP;LM +3;IN -3
1.^The size of the memory image program
is limited by the number of frames
available for work areas and the number
of DEFs in the program. The number of
frames available is 24 to 32 depending
upon the options specified.  At least
one frame is always allocated to the
REF/DEF table and for every 102 DEFs,
after the first 102, another frame is
allocated.  The resulting memory image
program can have code or data loaded in
up to 31 of the 1K blocks of memory in
the 64K address space of the TI 99/4A.
Note that this does not mean that the
maximum size of the program is
necessarily limited to the size of the
work area.  For example, if a program
has a work area (ie. BSS) that spans a
whole 1K block, then that 1K block has
no data or code loaded into it and is
not counted.
2.^Only the following tags in a tagged
object can be processed:
.IN +11
>01^^compressed object begin
^^0^^uncompressed object begin
^^1^^absolute program entry point
^^2^^relocatable program entry point
^^3^^REF in relocatable code
^^4^^REF in absolute code
^^5^^DEF relocatable
^^6^^DEF absolute
^^7^^checksum
^^8^^checksum ignore
^^9^^load address absolute
^^A^^load address relocatable
^^B^^absolute data
^^C^^relocatable data
^^F^^end of record
.IN+0
Note that the checksum, tag 7, is
always ignored.  The TI Assembler can
produce other tags due to DORG, PSEG,
DSEG and CSEG statements, but since
these are not documented they cannot be
processed.
.SP2;LM-3;IN+0
@LINKER^INPUT
.SP
The LINKER has three types of input
file.  First, a control file which is
the only required input.  The control
file contains LINKER control statements
and/or tagged object modules.  The
control file may be either VARIABLE or
FIXED with a record length of 80.
Tagged object modules in the control
file begin with the tag "0" or tag >01
record and end with the colon record as
is usual for object modules.
.SP
Second, tagged object files.  A tagged
object file is the normal output from
an assembly.  It ends with a record
with a colon in column 1.  Two or more
tagged object modules can be combined
into one file provided that all but the
last colon record are deleted.  Tagged
object files must be FIXED 80.
.SP
Third, library files.  Library files
are searched to resolve REFs.  Only the
modules required are processed.  Each
tagged object module in the library
begins with one or more special header
records and is terminated via the usual
colon record.  The header records are
identified by a period in colunm 1.
Beginning in column 2 of the header
record is a list of the names that can
be resolved by the module.  The list
contains 1 to 6 character names
separated by commas with no intervening
blanks (the first blank stops the scan
of the header record).  A name can not
be started on one header record and
continued onto the next.  Library files
are always FIXED 80.
.SP 2
@Building^a^Library
.SP
If the library is going to contain
&only uncompressed object then either
the E/A or TI Writer editors can be
used to put header and object records
together in the library form.  Remember
to save the library as FIXED 80.
(HINT: In TI Writer editor use PF then
"F^DSK1.LIBNAME".)
.SP 2
@NOTATION
.SP
Throughout the remainder of this
document, we will talk as though the
LINKER were actually loading the object
programs.  The LINKER does not acutally
load the programs, it builds a memory
image file that must be loaded by some
other means (ie. Option 5 of E/A,
Option 3 of TI WRITER).  Speaking of
the LINKER is this way makes it easier
to describe and to understand the
functions of the various control
statements.
€†€­†‹•Ÿееееееееее分