PDP-10.its/doc/_info_/stink.doc

This file is a product of Computational Archaeology. Do not believe
everything you read...

STINK is a relocating linking loader. The basic input to STINK is
one or more files in RELOCATABLE format (produced by MIDAS or other
translators). The output is a runnable program image. After the
program image is created you may start it, return to DDT with the
image loaded into a job, or dump the image to a file for later use.

Upon starting, STINK identifies itself and prompts for a command.
STINK commands are one-character sequences, optionally preceeded by a
numeric argument and followed by a text argument, usually a file name.
Many commands may appear on the same line. If the command expects
a text argument, the argument is terminated by an ESCAPE ($)
character. Two such characters in a row signify the end of the
command line, and cause STINK to start processing the entered
commands. 

The general command format is thus

<arg>C <name>$...$$

<arg> is usually a number typed by the user, but may be a value returned
by a command. <name> may include device, directory, and file name fields.

STINK may be invoked with JCL. In this case the first word on the command
line is assumed to be the FN1 of an indirect command file, which is
used to provide further commands. The FN2 defaults to LOADER. Typing

:STINK FOO

is identical to typing

:STINK
*M FOO LOADER$@$$

(see description of M and @ commands below).

Commands:

@ - Use current file as command file

  The file specified as the current file is opened, and lines from the
  file are read as commands to STINK. When EOF is reached control returns
  to the TTY or previous command file. If unspecified the default FN2 for
  this command is LOADER.

A - Set High Segment Origin to <arg>

  The high segment origin will be set to the value given as an argument
  to the command. Code specified as being in the high segment will appear
  starting at this address in the linked image. You must give this command
  before any high segment code is seen. The high segment origin defaults
  to 400000.

B - Return current relocation factor

  This command sets the numeric argument to the current relocation factor
  (of the low segment, if a two segment program). You can read the returned
  value with the = command. This tells you where the next loaded code is
  going to go. [There should be a way to read other parameters such as the
  high segment relocation, segment origin, etc. Not yet.]


C - Set COMMON address to <arg>

  Programs can specify the use of an area of shared COMMON storage (like
  FORTRAN). This command sets the address of that storage in the linked
  image to <arg>.

D - Back to DDT w/linked image loaded in job

  Executing this command leaves you at DDT with an inferior job containing
  the loaded program. DDT will have the program's symbols available. The
  name of the job will be the program name of the first file loaded unless
  it has been specified with the J command.

G - Start loaded program

  Loads the program into a job under DDT as in the D command, then starts
  it. If a numeric arg is given, starts program at that address. If no
  arg is given, starts program at the address specified in the REL file.

H - Set symbol table hash size

  Sets the hash size of STINK's global symbol table to the value given by
  the numeric arg, which must be present. The initial value is 151. You
  should set this bigger if you are loading a program with lots of global
  symbols.

J - Read and set Job Name

  J <name> sets the job name to <name>. This is used by the D and G
  commands to figure out what to call the loaded image.

K - Seems to be a NOP today. Was called KILL

L - Load current file

  Load the current file into the linked image, preserving all symbols.

M - Read and set "current file"

  M DEV:SNAME;FN1 FN2$ sets the current file to the given name. This
  filename is used for all upcoming operations that require a file
  name. In cases where it makes sense, the FN2, if not given, defaults
  to REL. (Actually this command can take a numeric arg, which is used
  to set the device. 0 is DSK, and 1-8 are UT1-UT8. What fun.)

N - Load current file w/o local syms

  Loads the current file into the linked core image, but does not make
  the local symbols of that file available to DDT or the Y command.

O - Set Global Offset. 

  Sets the Global Offset to the value of the numeric arg, which must
  be given. I assume the global offset is an offset as in the FAIL
  PHASE/DEPHASE commands, and is used for code that is to be loaded
  at one address but run at another. But I'm not sure.

P - Set current file to be Paper Tape!

  See M.

Q - Get COMMON address to current arg

  Makes the address of the COMMON storage available as the numeric arg 
  to a following command. Probably useful for setting relocation factors
  and suchlike.

R - Set relocation factor

  Set the current relocation factor to the value of the numeric arg, which
  must be specified. Values over 400000 set the highseg relocation factor,
  values under 400000 set the loseg relocation factor.

S - List modules loaded (searched?)

  Print a list of all program modules which have been loaded into the image
  under construction.

W - Set flag to make high segment pure

  If you do this the high segment of the loaded program will be marked
  pure (read-only).

X - Set start address to <arg>

  The start address of the program is set to the numeric arg.

Y - Dump linked image to current file

  The current image and symbol table is dumped to an SBLK format file.
  If the immediately preceeding command was M, that filename is used.
  Otherwise, the program is dumped to _STNK_ DUMP. Currently this command
  is useless for programs with pure high segments because it doesn't
  know how to PDUMP. To do that you will have to get to DDT with the D
  command and :PDUMP.

Z - Zero core 

  I don't know exactly -which- core. Probably the linked image.

[ - Examine address <arg> in linked image

  Prints out what is currently contained in address <arg> of the linked 
  image.


= - Print numeric argument.

  Prints its numeric argument in octal. This is useful with commands
  that return an argument, such as B and Q. B=$$ prints the current
  relocation factor.


? - List currently undefined symbols

  Prints out a listing of all currently requested but undefined global
  symbols, and the modules that asked for them.


< - ???

  This command has something to do with defining global symbols from
  the TTY, but I haven't figured out the syntax yet.


Memory layout:

  The program is loaded into memory starting at location 100. If a high
  segment is present, it is loaded at the high segment origin, which is
  400000 unless reset by the A command. When the load is complete, the
  RH of location 20 is initialized to the last legal address of the
  low segment. If a separate high segment was loaded, location 21 is
  initialized to FIRST_HISEG_SDDRESS,,LAST_HISEG_ADDRESS.

  There are various limitations on what can be loaded due to the fact
  that STINK builds the linked image in its own address space and has
  to work around itself.

High segment loading:

  This is fuzzy as I haven't figured out enough stuff yet. But it may be
  that unlike the DEC system, you don't have to explicitly request high
  segment loading in the REL file. Rather, STINK may automatically
  create a high segment and load things into it when it sees a program
  address over 400000. This seems bogus, but if you don't want a two
  segment program, either figure this out and fix this doc, or keep
  your addresses below 400000.