Retro1.org codex

INCLUDE                                                     CMS Nucleus command

Use the INCLUDE command to read one or more TEXT files (containing relocatable
object code) from disk and to load them into virtual storage, establishing the
proper linkages between the files.  A LOAD command must have been previously
issued for the INCLUDE command to produce desirable results.  For information
on the CMS loader and the handling of unresolved references, see the
description of the LOAD command.  The format of the INCLUDE command is:
+----------+------------------------------------------------------------------+
| INclude  | fn... [(options...[)]]                                           |
|          | options:                                                         |
|          |    NOCLEAR|CLEAR          RESET *|entry      MAP|NOMAP           |
|          |    ORIGIN hexloc|TRANS    NOTYPE|TYPE        INV|NOINV           |
|          |    REP|NOREP              AUTO|NOAUTO        LIBE|NOLIBE         |
|          |    START                  SAME               DUP|NODUP           |
+----------+------------------------------------------------------------------+
where:

fn...    are the names of the files to be loaded into storage.  Files must have
         a filetype of TEXT and consist of relocatable object code such as that
         produced by the OS language processor.  If a GLOBAL TXTLIB command has
         identified one or more TXTLIBs, fn may indicate the name of a TXTLIB
         member.

Options:

If options were specified with a previous LOAD or INCLUDE command, these
options (with the exception of CLEAR, NODUP, and ORIGIN) remain set if SAME is
specified when INCLUDE is issued.  Otherwise, the options assume their default
settings.  If conflicting options are specified, the last one entered is in
effect.

CLEAR    clears the load area in storage to binary zeros before the files are
         loaded.

NOCLEAR  does not clear the load area before loading.  NOCLEAR is the default.

RESET entry
         resets the execution starting point previously set by a LOAD or
         INCLUDE command.  If entry is specified, the starting execution
         address is reset to the specified location.  If an asterisk (*) is
         specified, the starting address is reset to the default entry point.

ORIGIN hexloc | TRANS
         begins loading the program at the location specified by hexloc; this
         location must be in the CMS transient area or in the user area below
         the start of the CMS nucleus.  The variable, hexloc, is a hexadecimal
         number of up to 6 characters.  If this option is not specified,
         loading begins at the next available storage location.  INCLUDE does
         not overlay any previously loaded files unless this option is
         specified and the address given indicates a location within a
         previously loaded object module.  TRANS indicates that the file is
         loaded into the transient area.

MAP      adds information to the load map.  This is the default.

NOMAP    does not add any information to the load map.

TYPE     displays the load map of the files at the terminal, as well as writing
         it on the A-disk.  This option is valid only if MAP is specified or
         implied.

NOTYPE   does not display the load map at the terminal.  This is the default.

INV      writes invalid card images in the LOAD MAP file.  This is the default.

NOINV    does not write invalid card images in the LOAD MAP file.

REP      writes Replace (REP) statement images in the LOAD MAP file.  See the
         explanation of the CMS LOAD command for a description of the Replace
         (REP) statement.  This is the default.

NOREP    suppresses the writing of Replace (REP) statements in the LOAD MAP
         file.

AUTO     searches your disks for TEXT files to resolve undefined references.
         This is the default.

NOAUTO   suppresses automatic searching for TEXT files.

LIBE     searches the text libraries defined by the GLOBAL command for missing
         subroutines.  This is the default.

NOLIBE   does not search any text libraries for unresolved references.

START    begins execution after loading is completed.

SAME     retains the same options (except ORIGIN, NODUP, and CLEAR) that were
         used by a previous INCLUDE or LOAD command.  Otherwise, the default
         setting of unspecified options is assumed.  If other options are
         specified with SAME, they override previously specified options.
         (See Usage Note 1.)

DUP      displays warning messages at your virtual console when a duplicate
         CSECT is encountered during processing.  The duplicate CSECT is not
         loaded.  This is the default.

NODUP    does not display warning messages at your virtual console when
         duplicate CSECTs are encountered during processing.  The duplicate
         CSECT is not loaded.


Usage note:

1.  If you specify several non-default options on the LOAD command and you want
    those options to remain in effect, use the SAME option when you issue the
    INCLUDE command; for example:
       include main subi data (reset main map start)
    brings the files named MAIN TEXT, SUBI TEXT, and DATA TEXT into virtual
    storage and appends them to previously loaded files.  Information about
    these loaded files is added to the LOAD MAP file.  Execution begins at
    entry point MAIN.
       load myprog (nomap nolibe norep)
       include mysub (map same)
    During execution of the LOAD command, the file named MYPROG TEXT is brought
    into real storage.  The following options are in effect: NOMAP, NOLIBE,
    NOREP, NOTYPE, INV, and AUTO.  During execution of the INCLUDE command, the
    file named MYSUB TEXT is appended to MYPROG TEXT.  The following options
    are in effect:
       MAP, NOLIBE, NOREP, NOTYPE, INV, AUTO

Responses:

DMSLIO740I    Execution begins ...
    START was specified with INCLUDE and the loaded program has begun
    execution. Any further responses are from the program.

INVALID CARD - xxx...xxx
    INV was specified with LOAD and an invalid card has been found.  The
    message and the contents of the invalid card (xxx...xxx) are listed in the
    LOAD MAP file.  The invalid card is ignored and loading continues.