RUNL - link/overlay support for Fortran in TSS.

(Note: This command is only recognized in the FORT subsystem.)

Syntax:

RUNL <object-files> = <hstar> (<opts>) <libraries> ; <link-sets>

Possible <opts>:

ULIB,CORE=nn,NAME=name,MAP,GO

Examples:

fort
runl /main.o = myprog (core=60,map) ;
                    link(a)   /ovly1.o ;
                    link(c,a) /ovly2.o ;
                    link(b)   /ovly3.o ;
                    link(d,b) /ovly4a.o ; /ovly4b.o
ftn myprog 06>/output 05</input

Description:

RUNL permits the construction of link/overlay H* files, to permit the running or programs which would otherwise be too large to run in TSS. The user is responsible for making sure that overlays are brought into memory before they are used.

Definitions:

<link-sets>    ::= <link-phrase> [;<link-phrase>]*
<link-phrase>  ::= LINK(name1,name2,entry) <object-files>
                 | LINK(name1,name2)       <object-files>
                 | LINK(name1)             <object-files>
                 | LINK(name1,,entry)      <object-files>
<object-files> ::= <file> [; <file>]*

Options:

<object-files>
is a pathname or a set of pathnames separated by semicolons pointing to a file or files containing object decks. The file of object decks between the RUNL command name and the first "=" sign is taken to consititute the main link of the H* file. The main link gets a default name of "//////". The link named "//////" is brought into memory for execution by most TSS commands which execute files (e.g. GO, FTN). You have to bring in other overlays yourself (see below).
<hstar>
is the pathname of a random file into which the system-loadable H* file generated by the loader is placed if the load is successful. You will probably want to run this file using the FTN command.
<opts>
may be one option or a set separated by commas. Remember the parentheses around the option list! The options may be chosen from the following.
ULIB
This tells RUNL that a user library file will be specified immediately after this option list.
CORE=nn
This sets the batch loader core allocation to nn+6K or 23K, whichever is larger. The default value of "nn" is 16K. Depending on your program, FORTRAN may need lots more (try core=60 or bigger if you get a "memory address fault").
NAME=<name>
This supplies a name for the main link of the saved H* file. The default name is "//////". (The main link is created from the object decks in the file(s) between the RUNL command name and the first "=" sign.) This name will be truncated to 6 BCD characters. If you do change the name to something other than "//////", then the regular ways of running the resulting H* file won't work. Don't change the name.
MAP
a load map is written to file PSTR. This map shows the addresses where the various link overlays will be loaded when they are called in.
GO
This option executes the H* file when the loading is complete. If your program reads or writes files, you must use the FTN command to run the program and specify the files. See "expl ftn". Default is NOGO.
<libraries>
is a pathname or a set of pathnames separated by semicolons; these refer to one or more random subroutine libraries.
<link-sets>
is a link phrase or a set of link phrases, where a link-phrase is of the form:
LINK(name1,name2,entry) <object-files>

Only <name1> has to be specified, the other two fields are optional. <name1> is the name to be given to the link overlay containing the following <object-files> object decks. <name2> is optional. If <name2> is given, it specifies the name of a (previously defined) link which <name1> will overlay. <entry> is also optional. If <entry> is given, it specifies the desired primary or secondary entry point (symdef) which will be used to enter the link when it is called.

Note that the <name>s and <entry> points must be less than or equal to six (6) characters in length. You will be using the <name>s in FORTRAN system subroutine calls when you bring overlays into memory (see below).

Programming considerations:

When your program is loaded (by GO, FTN, etc.), the link named "//////" is brought into memory and execution starts there. Normally, the "//////" link contains your FORTRAN main line program. Before you can use any subroutines in your overlays, you must bring the overlays into memory. One of the two following FORTRAN system subroutine calls will do this for you. Each call takes one argument which is the name of the overlay to bring into memory. This argument must be a FORTRAN character constant, and it must be exactly SIX (6) characters long. For example,

CALL LLINK( 'sixcha' )
- or -
CALL LLINK( 'a     ' )

Note that you have to left-justify and pad the name with blanks! The name is exactly the same name that you used as your first argument to the RUNL LINK statement for that overlay.

(1) CALL LINK(<link-name>)
This subroutine brings the named overlay into memory and transfers control to either the beginning of the overlay or else to the entry point you specified as the third name in your RUNL LINK directive. Don't try to bring in FORTRAN subroutine overlays this way!
(2) CALL LLINK(<link-name>)
This only brings the named overlay into memory; it does not transfer control to it. Control returns immediately to the statement following the call, as usual. This is used for overlays full of subroutines. Once the link is in memory, you may call the subroutines in it normally.

Warning: FORTRAN random I/O users:

If using Fortran random I/O, the CALL RANSIZ must be placed in the main link, in order to ensure proper file wrapup by forcing the random I/O subroutine FRRD to reside in core with the main link at all times.

Examples:

(1) creating the object files:
     FTN -go /main.f           object=/main
     FTN -go /suba /subb /subc object=/obj1
     FTN -go /subd /sube       object=/obj2
     FTN -go /subf             object=/obj3
     FTN -go /subg /subh /subi object=/obj4
(2) creating the link overlay H* using RUNL:
     FORT
     RUNL main = .h (ulib,map) /mylibrary ;
                 link(ovly1)        /obj1 ;
                 link(ovly2,ovly1)  /obj2 ;
                 link(ovly3,ovly2)  /obj3 ;
                 link(ovly4,ovly3)  /obj4
(3) running it:
     FTN .h 06>/output 05</input

Overlay Linking Example:

One main program with three overlays, all loaded at the same place in memory. Note that each subroutine must be compiled into its own separate object file, since each subroutine is a separate overlay. (Subroutines which go into the same overlay can be compiled together into the same object file.) The main program must also be compiled separately.

C FTN main.f -go object=/main
      print, 'Starting MAIN.'
      call llink('axxxxa')
      call one
      call llink('bxxxxb')
      call two
      call llink('cxxxxc')
      call three
      stop
      end
C FTN one.f -go object=/one
      subroutine one
      print, 'Subroutine one called.'
      return
      end
C FTN two.f -go object=/two
      subroutine two
      print, 'Subroutine two called.'
      return
      end
C FTN three.f -go object=/three
      subroutine three
      print, 'Subroutine three called.'
      return
      end

Here are the commands to link the object decks all together correctly and then run the .h file. Note that FORTRAN needs a lot of extra memory! The first name in each RUNL LINK statement is exactly the name used in the CALL LLINK() subroutine call in FORTRAN. It must be six characters or less.

*FORT
*RUNL /main = .h (map,core=60) ;
              link(axxxxa)        /one ;
              link(bxxxxb,axxxxa) /two ;
              link(cxxxxc,bxxxxb) /three
*GO

Also note that

..... link(cxxxxc,axxxxa) /three

does not work, even though one thinks it should.

Copyright © 1996, Thinkage Ltd.