GENMOD

Authorization

General User

Purpose

Use the GENMOD command to create both relocatable and nonrelocatable MODULE files on a disk or directory.

The GENMOD command will save the AMODE and RMODE attributes in the file. If the module has architectural dependencies, you can give the module an architectural attribute to restrict its execution to that particular type of architecture.

The GENMOD command is the final step in the CMS link edit process, which also includes the LOAD and INCLUDE commands.

To execute a module that has been loaded with the LOADMOD command, issue the START command.

To load and execute a MODULE file in a single step, invoke the file as a command by using its file name as the command name.

Operands

fn

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

fm

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

Options

FROM entry1

specifies an entry point or a control section name that represents the starting virtual storage location from which a MODULE is generated. For more information, see Usage Note 12.

TO entry2

specifies an entry point or a control section name that represents the ending virtual storage location from which a MODULE is generated. For more information, see Usage Note 12.

MAP

copies system loader table entries for the generated module. The record can contain up to 2730 map entries. You can issue the MODMAP command to display the module map. The default is MAP.

Using this option with the NOPRES option on the LOADMOD command deletes previously loaded non-OS programs and causes the loader tables to be rewritten with the map information which was saved when the module was generated.

NOMAP

specifies a module map is not to be contained in the MODULE file.

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

NOSTR

does not cause anything to be deleted when used with the NOPRES option on the LOADMOD command. The default is NOSTR.

STR

deletes previously loaded non-OS programs when used with the NOPRES option on the LOADMOD command.

OS

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

DOS

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

ALL

indicates the program:

• Contains CMS macros and must be capable of running regardless of whether CMS/DOS is active
• Contains no VSE or OS macros
• Preserves and resets the DOS flag in the CMS nucleus
• 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.

CLEAN

indicates the module is to be cleaned from storage at the end of its execution. The default is CLEAN, for the relocatable modules.

NOCLEAN

indicates the module is to remain in storage until end-of-command (Ready;). NOCLEAN can be specified for either relocatable or nonrelocatable modules. The default is NOCLEAN, for nonrelocatable modules.

SYSTEM

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

AMODE

specifies the addressing mode in which the program will be entered.

This option overrides the AMODE determined by the LOAD process. If you specify RMODE, but do not specify AMODE, the AMODE for the MODULE is determined from the following default criteria:

• If you specify RMODE ANY, the AMODE specification defaults to AMODE 31.
• If you specify RMODE 24, the AMODE defaults to the AMODE of the entry point determined by the LOAD process.

If you specify neither AMODE nor RMODE, the AMODE for the module is determined by the LOAD process. If RMODE was specified as ANY in the LOAD process, however, the AMODE will be given a value of 31. This is done to prevent a situation where a module is called from an exec and is given AMODE 24, because REXX and its interpreter can run AMODE 24. With RMODE specified as ANY, however, the program can be loaded outside the 24-bit addressing scheme specified by AMODE 24. The valid AMODE values and their meanings are:

24

This entry point is to receive control in 24-bit addressing mode.

31

This entry point is to receive control in 31-bit addressing mode.

ANY

This entry point is capable of operating in either 24-bit or 31-bit addressing mode. It will receive control in the addressing mode of its caller. If the module is executed by name from the command line or from an exec, it will receive control in 31-bit addressing mode.

RMODE

specifies the location in virtual storage where the loaded MODULE is to reside.

The RMODE defined by this option overrides the RMODE determined by the LOAD process if the module being generated is relocatable. This means you specified the RLDSAVE option on:

• The LOAD command
• Any INCLUDE command you used to prepare the TEXT needed for the MODULE file

The RMODE option will not provide override capability as stated if the module being generated is nonrelocatable. This means you did not specify the RLDSAVE option on the LOAD or INCLUDE command used for the MODULE file.

When you load a nonrelocatable MODULE file using one of the CMS loading methods (except NUCXLOAD), the module will be loaded according to its generated origin.

Note: An AMODE value specified without an RMODE option defaults to RMODE 24 for the module.

If you specify neither AMODE nor RMODE, the RMODE for the module is determined by the LOAD process. The valid RMODE values and their meanings are:

24

The load must reside below the 16 MB line, overriding the RMODE determined by the LOAD process.

ANY

The load may reside above or below the 16 MB line, overriding the RMODE determined by the LOAD process.

XA

specifies this module can execute in ESA, XA, and XC virtual machines.

XC

when specified as the only architecture attribute, specifies this module can execute only in XC virtual machines.

Note: If you specify neither XA nor XC, no architecture attribute is added to the module, and the module can execute in any kind of virtual machine. If you specify both XA and XC, both architecture attributes are added to the module, and the module can execute in any kind of virtual machine. This is the default.

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 or loaded into storage and executed with the LOADMOD and START commands.
2. The execution of MODULE files created from VSE 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 be careful not to exceed two pages (8192 bytes).
5. A transient module (loaded with the ORIGIN TRANS option) that was generated with the SYSTEM option is written on a disk or directory as a fixed-length record with a maximum length of 8192 bytes. The relocation and history information for these files cannot be saved. The AMODE/RMODE for the module are set to 24.
6. If you are using FORTRAN under CMS, compiling with the RENT option, and have named the main program the same as fn, you must use the FROM option specifying entry1 the same as fn, preceded by the “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 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 the Usage Notes of, LOAD. 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.
8. If you are using PL/I under CMS, use FROM PLISTART as an option to avoid unpredictable results.
9. You can use the GENMOD command to create a relocatable CMS MODULE file. Relocation is performed when using the LOADMOD or NUCXLOAD command. A MODULE file generated by GENMOD can contain relocation information if the RLDSAVE option was specified on any of the LOAD or INCLUDE commands used to create this MODULE file. The file is thus considered to be relocatable. If the RLDSAVE option was not specified on any of the LOAD or INCLUDE commands, the relocation information for the file cannot be saved.
10. If the HIST option was specified on the LOAD or INCLUDE command, the MODULE file may contain history information. For more information, see INCLUDE and LOAD.
11. Do not XEDIT and then FILE a variable format MODULE file. This deletes any trailing blanks in records, which causes unpredictable results at module execution time. If this occurs, you must regenerate the MODULE.
12. The FROM option is still required when a partial module would otherwise be written as a consequence of Usage Note 7. When module relocation information is being saved (using the RLDSAVE option of the LOAD and INCLUDE commands), the FROM option must specify the first byte of the program; it is not optional when Usage Note 7 applies. TO should not be specified. If TO or FROM is specified in other ways in conjunction with RLDSAVE, the results will be unpredictable.
13. The SET GEN370 command can be used to allow modules generated with the GENMOD 370 option (no longer supported) to execute in ESA, XA, or XC virtual machines. It is likely the CP SET 370ACCOM ON command will also be necessary for the module to execute.

Messages and Return Codes

• DMS003E Invalid option: option [RC=24]
• DMS005E No option specified [RC=24]
• DMS018E No load map available [RC=40]
• DMS021E Entry point name not found [RC=40]
• DMS032E Invalid filetype ft [RC=24]
• DMS037E Filemode mode[(vdev)] is accessed as read/only [RC=36]
• DMS040E No files loaded [RC=40]
• DMS069E Filemode mode not accessed [RC=36]
• DMS070E Invalid parameter parameter [RC=24]
• DMS084E The length of the module to be generated is non-positive. GENMOD terminated. [RC=24]
• DMS105S Error nn writing file fn ft fm on disk [RC=31│55│70│76│99│100]
• DMS257T Internal system error at address addr (offset offset)
• DMS810E 370 cannot be specified as an architecture when AMODE is 31. [RC=68]
• DMS811E [AMODE 24|RMODE 24] cannot be specified when module size exceeds 16Mb. file not generated. [RC=68]
• DMS943E Invalid AMODE mode specified. file not generated. [RC=24]
• DMS944E Invalid RMODE mode specified. file not generated. [RC=24]
• DMS945E AMODE/RMODE values conflict. file not generated|loaded. [RC=68]
• DMS988E Module file cannot execute in XC architecture [RC=64]
• DMS1144E Implicit rollback occurred for work unit workunitid [RC=31]
• DMS1252T Rollback unsuccessful for file pool filepoolid

Additional system messages may be issued by this command. The reasons for these messages and their location are: