Retro1.org codex

GENMOD                                                      CMS Nucleus command

Use the GENMOD command to generate a (MODULE) file on a CMS disk.

The format of the GENMOD command is:
+----------+------------------------------------------------------------------+
| GENMOD   | [fn [MODULE [A1|fm]]] [(options... [)]]                          |
|          | options:                                                         |
|          | FROM entry1         TO entry2           MAP|NOMAP                |
|          | STR|NOSTR           OS|DOS|ALL          SYSTEM                   |
+----------+------------------------------------------------------------------+
where:

fn       is the filename of the MODULE file being created.  If fn is not
         specified, the file created has a filename equal to that of the first
         entry point in the LOAD MAP.

fm       is the filemode of the MODULE file being created.  If fm is not
         specified, A1 is assumed.

Options:

If conflicting options are specified, the last one entered is used.

FROM entry1
         specifies an entry point or a control section name that represents the
         starting virtual storage location from which the nonrelocatable copy
         is generated.

TO entry2
         specifies an entry point or a control section name that represents the
         ending virtual storage location from which the nonrelocatable copy is
         generated.

MAP      includes a load map in the MODULE file, which is an 80-byte record
         placed in front of the load module.  MAP is the default.

NOMAP    specifies that a load map is not to be contained in the MODULE file.

         Note:  If a module is generated with the NOMAP option, that module
         cannot later be loaded and started with the CMS LOADMOD and START
         commands.  When NOMAP is specified, the information produced is not
         sufficient for the START command to execute properly.  However, a
         module generated with the NOMAP option can later be invoked as a
         command; that is, it can be invoked if its filename is entered.

STR      invokes the CMS storage initialization routine when the MODULE file is
         subsequently loaded (using the LOADMOD command).  This routine frees
         any storage remaining from a previous program.  STR is the default
         setting if the MODULE is to be loaded at the beginning of available
         user storage.

         If you have issued CMS SET RELPAGE ON, STR causes CMS storage
         initialization to release the remaining pages of storage.

         Note:  If a program running in the user area calls a transient
         routine that was generated with the STR option, the user area storage
         pointers will be reset.  This reset condition could cause errors upon
         return to the original program (for example, when OS GETMAIN/FREEMAIN
         macros are issued in the user program).

NOSTR    indicates that, when the MODULE is loaded, free storage pointers are
         not reset for any storage currently in use.  NOSTR is the default
         setting if the MODULE file is to be loaded at a location other than
         the default load address.

SYSTEM   indicates that when the MODULE file is subsequently loaded, it is to
         have a storage protect key of zero.

OS       indicates that the program may contain OS macros and, therefore,
         should be executed only when CMS/DOS is not active.

DOS      indicates that the program contains VSE macros; CMS/DOS must be active
         (that is, SET DOS ON must have been previously invoked) in order for
         this program to execute.  (See Usage Note 2).

ALL      indicates that the program:
         o   Contains CMS macros and must be capable of running regardless of
             whether or not CMS/DOS is active.
         o   Contains no VSE or OS macros.
         o   Preserves and resets the DOS flag in the CMS nucleus.
         o   Does its own setting of the DOS flags.

         Note:  The ALL option is primarily for use by CMS system programmers.
         CMS system routines are aware of which environment is active and will
         preserve and reset the DOS flag in the CMS nucleus.


Usage Notes:

1.  The GENMOD command is usually invoked following the LOAD command, and
    possibly the INCLUDE command.  For example, the sequence:
       load myprog
       genmod testprog
    loads the file MYPROG TEXT into virtual storage and creates a
    nonrelocatable load module named TESTPROG MODULE.  TESTPROG may now be
    invoked as a user-written command from the CMS environment.

2.  The execution of MODULE files created from DOS programs is not supported
    and may give unpredictable results.  GENMOD is intended for use with the
    LOAD command, not the FETCH command.  Storage initialization for FETCH is
    different from that for LOAD.

3.  Before the file is written, undefined symbols are set to location zero and
    the common reference control section is initialized.  The undefined symbols
    are not retained as unresolved symbols in the MODULE file.  Therefore, once
    the MODULE file is generated, those references cannot be resolved and may
    cause unpredictable results during execution.

4.  If you load a program into the transient area you should issue the GENMOD
    command with the STR option.  Be careful if the program uses OS GETMAIN or
    FREEMAIN macros because your program, plus the amount of storage obtained
    via GETMAIN, cannot exceed two pages (8192 bytes). It is recommended that
    you do not use GETMAIN macros in programs that execute in the transient
    area.

5.  A transient module (loaded with the ORIGIN TRANS option) that was generated
    with the SYSTEM option is written on disk as a fixed-length record with a
    maximum length of 8192 bytes.  The relocation and history information for
    these files cannot be saved.

6.  If you are using FORTRAN under CMS, compiling with the RENT option, and
    have named the main program the same as fn, then you must use the FROM
    option specifying entry1 the same as fn, preceded by an "at" sign (@).
    For example, you would enter:
       genmod mnprog (from @mnprog

7.  If FROM is not specified on the GENMOD command, the starting virtual
    storage location (entry point) of the module is either the address of fn
    (if it is an external name) or the entry point determined according to the
    hierarchy discussed in Usage Note 4 of the LOAD command.  This is not
    necessarily the lowest address loaded.  If you have any external references
    before your START or CSECT instructions, you must specify the 'FROM entry1'
    operand on the GENMOD command to load your program properly.  External
    references include the following:  EXTRN, WXTRM, DXD, CXD, and COM are
    considered EXTERNAL references.  The Assembler Language Reference and
    Programmers Guide should be consulted for additional information on
    external references.

8.  If you are using PL/I under CMS, use FROM PLISTART as an option to avoid
    unpredictable results.

9.  The GENMOD command can be used to create a relocatable CMS MODULE file.
    Relocation is performed only when using the NUCXLOAD command.  When the
    GENMOD command generates a MODULE file, one record of this MODULE file can
    contain relocation information.  This depends on the previous LOAD or
    INCLUDE command that was issued.  If the RLDSAVE option was specified on
    the LOAD or INCLUDE command, the MODULE file may contain the relocation
    information.  If the RLDSAVE option was not specified on the LOAD or
    INCLUDE command, the relocation information for the file cannot be saved
    See the LOAD or INCLUDE commands for more information.

10. The FROM or TO options should not be specified when module relocation
    information is being saved (using RLDSAVE option of the LOAD and INCLUDE
    commands).  If specified, the results will be unpredictable. The FROM or TO
    options must not be specified if module is loaded into the Transient area
    since the start address must be X'E000'.

11. If the HIST option was specified on the LOAD or INCLUDE command, the module
    file may contain history information.  See the LOAD or INCLUDE commands for
    more information.