ibm:vm370-lib:cmshelp:load.helpcmd
LOAD
CMS Commands
- load.helpcmd.txt
LOAD CMS Nucleus command Use the LOAD 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. The format of the LOAD command is: +----------+------------------------------------------------------------------+ | LOAD | fn... [(options...[)]] | | | | | | options: | | | NOCLEAR|CLEAR RESET entry|* ORIGIN hexloc|TRANS | | | MAP|NOMAP NOTYPE|TYPE INV|NOINV | | | REP|NOREP AUTO|NOAUTO LIBE|NOLIB | | | START DUP|NODUP | +----------+------------------------------------------------------------------+ where: fn... specifies the names of the files to be loaded into storage. The files must have a filetype of TEXT and consist of relocatable object code such as that produced by the OS language processors. If a GLOBAL TXTLIB command has been issued, fn may indicate the name of a TXTLIB member. Options: If conflicting options are specified, the last one entered is in effect. Options may be overridden or added when you use the INCLUDE command to load additional TEXT files. 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 sets the starting location for the programs currently loaded. The operand, entry, must be an external name (for example, CSECT or ENTRY) in the loaded programs. If RESET is not specified, the default entry point is used. (See Usage Note 4.) If * is entered the results are the same as if the RESET option were omitted. 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 TRANS is specified, the file is loaded into the CMS nucleus transient area. If ORIGIN is not specified, loading begins at the next available storage location in the user program area. Note: Any program loaded into the transient area must have a starting address of x'E000'. See the GENMOD command for information on loading programs in the transient area. MAP | NOMAP writes a load map on your A-disk, named LOAD MAP A5. This is the default. NOMAP does write the LOAD MAP file. NOTYPE | 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 in effect. NOTYPE does not display the load map at the terminal. This is the default. INV | NOINV 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 | NOREP writes Replace (REP) statement images in the LOAD MAP file. This is the default. NOREP suppresses this. AUTO | NOAUTO searches your disks for TEXT files to resolve undefined references. This is the default. NOAUTO suppresses this. LIBE | NOLIBE searches the text libraries defined by the GLOBAL command for missing subroutines. This is the default. NOLIBE prevets the search. START begins execution after loading is completed. LOAD does not normally begin execution of the loaded files. To begin execution immediately upon successful completion of loading, specify START. Execution begins at the default entry point. (See Usage Note 4.) DUP | NODUP 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 suppresses warning messages. Usage notes: 1. You must have a read/write CMS A-disk accessed when you issue the LOAD command; the loader creates a temporary workfile named DMSLDR SYSUT1 and writes it to the A-disk. 2. Each time LOAD is issued, any previously existing LOAD MAP on the A-disk is erased. If NOMAP is specified no new map is created. If invalid card images exist in the file or files that are being loaded, they are listed with the message INVALID CARD in the LOAD MAP file. To suppress this listing in the load map, use the NOINV option. If Replace (REP) statements exist in the file being loaded, they are included in the LOAD MAP file. To suppress this listing of REP statements, specify the NOREP option. If the ENTRY or LIBRARY control cards are encountered in the file, the load map contains an entry: CONTROL CARD- ... listing the card that was read. 3. Duplicate CSECTs (control sections) are bypassed by the loader. Only the first CSECT encountered is physically loaded. The duplicates are not loaded. A warning message is displayed at your terminal if you specified the DUP option. 4. The loader selects the entry point for the loaded program according to the following hierarchy: o From the parameter list on the START command. o From the last RESET operand in a LOAD or INCLUDE command. o From the last ENTRY statement in the input. o From the last LDT statement in the input. o From the first assembler- or compiler-produced END statement that specifies an entry point if no ENTRY statement is in the input. o From the first byte of the first control section of the loaded program if there is no ENTRY statement and no assembler- or compiler-produced END statement specifying an entry point. 5. The LOAD command should not be used to execute programs containing DOS macros. To link-edit and execute programs in the CMS/DOS environment, use the DOSLKED and FETCH commands. 6. The CMS loader also loads routines called dynamically by OS LINK, LOAD, and XCTL macros. Under certain circumstances, an incorrect entry point may be returned to the calling program. See the VM/370 CMS User's Guide for more information. 7. LOAD does not clear user storage unless the CLEAR option is specified. 8. The following figure illustrates the loader search order. The loader uses this search order to locate the filename on the LOAD and INCLUDE command lines, as well as in the handling of unresolved references. +-----------------------------------------------+ | Use standard order of search to locate the | | TEXT files specified by fn ... | +-----------------------------------------------+ . * . . * Any * . +----------+ . * unresolved * . NO | Search | * . references . *----->| complete | * . ? . * +----------+ * . . * * |YES . * . . * Is * . . * NOAUTO * . YES * . specified . *-----------------+ * . ? . * | * . . * | * | |NO | +-----------------------------------------------+ | | Use standard order of search to locate files | | | with a filetype of TEXT and a filename | | | corresponding to the unresolved reference | | +-----------------------------------------------+ | |<----------------------------+ . * . . * Any * . +----------+ . * unresolved * . NO | Search | * . references . *----->| complete | * . ? . * +----------+ * . . * * |YES . * . . * Is * . +----------+ . * NOLIBE * . YES Search * . specified . *-----> complete * . ? . * +----------+ * . . * * |NO +-----------------------------------------------+ | Search active text libraries (those that were | | previously specified by a GLOBAL command). | | Files are searched in the order they are | | entered in the command. | +-----------------------------------------------+ | +-----------------+ | Search complete | +-----------------+ Loader Control Statements You can add loader control statements to TEXT files either by editing them or by punching real cards and adding them to a punched text deck before reading it into your virtual machine. The five control cards recognized by the CMS loader are discussed below. The ENTRY and LIBRARY cards, which are discussed first, are similar to the OS linkage editor control statements ENTRY and LIBRARY. The CMS ENTRY and LIBRARY statements must be entered beginning in column 1. ENTRY The ENTRY statement specifies the first instruction to be executed. It can be placed before, between, or after object modules or other control statements. The external name is the name of a control section or an entry name in the input deck. It must be the name of an instruction, not of data. +----------+---------------------------------------------------------+ | ENTRY | external name | +----------+---------------------------------------------------------+ LIBRARY The LIBRARY statement can be used to specify the never-call function. The never-call function (indicated by an asterisk (*) as the first operand) specifies those external references that are not to be resolved by the automatic library call during any loader step. It is negated when a deck containing the external name referred to is included as part of the input to the loader. The external reference refers to an external reference that may be unresolved after input processing. It is not to be resolved. Multiple external references within the parentheses must be separated by commas. The LIBRARY statement can be placed before, between, or after object decks or other control statements. +----------+---------------------------------------------------------+ | LIBRARY | * (external reference) | +----------+---------------------------------------------------------+ LDT The Loader Terminate (LDT) statement is used in a text library as the last record of a member. It indicates to the loader that all records for that member were processed. The LDT statement can contain a name to be used as the entry point for the loaded member. +----------+---------------------------------------------------------+ | Column | Contents | | 1 | X'02' (12-2-9 punch). Identifies this as a loader | | | control statement. | | 2-4 | LDT -- identifies type of statement. | | 5-16 | Not used. | | 17-24 | Blank or entry name (left-justified and padded with | | | blanks to eight characters). | | 25 | Blank. | | 26-33 | May contain information specified on a SETSSI card | | | processed by the TXTLIB command. | | 34-72 | May be used for comments or left blank. | | 73-80 | Not used by the loader. You may leave these columns | | | blank or insert program identification for your own | | | convenience. | +----------+---------------------------------------------------------+ ICS The Include Control Section (ICS) statement changes the length of a specified control section or defines a new control section. It should be used only when REP statements cause a control section to be increased in length. The format of an ICS statement is shown in the following figure. An ICS statement must be placed at the front of the file or TEXT file. +----------+---------------------------------------------------------+ | Column | Contents | | 1 | X'02' (12-2-9 punch). Identifies this as a loader | | | control statement. | | 2-4 | ICS -- identifies type of statement. | | 5-15 | Blank. | | 16 | , (comma). | | 17-24 | Control section name, left-justified in these columns. | | 25-28 | Hexadecimal length in bytes of the control section. | | | This must not be less than the actual length of the | | | previously specified control section. It must be | | | right-justified in columns with unused leading columns | | | filled with zeros. | | 29-72 | May be used for comments or left blank. | | 73-80 | Not used by the loader. You may leave these columns | | | blank or insert program identification for your own | | | convenience. | +----------+---------------------------------------------------------+ SLC The Set Location Counter statement sets the location counter used with the loader. The file loaded after the SLC statement is placed in virtual storage beginning at the address set by this SLC statement. The SLC statement has the format shown in the following figure. It sets the location counter in one of three ways: 1. With the absolute virtual address specified as a hexadecimal number in columns 7-12. 2. With the symbolic address already defined as a program name or entry point. This is specified by a symbolic name punched in columns 17-24. 3. If both a hexadecimal address and a symbolic name are specified, the absolute virtual address is converted to binary and added to the address assigned to the symbolic name; the resulting sum is the address to which the loader's location counter is set. For example, if 0000F8 was specified in columns 7-12 of the SLC card image and GAMMA was specified in columns 17-22, where GAMMA has an assigned address of 006100 (hexadecimal), the absolute address in columns 7-12 is added to the address assigned to GAMMA giving a total of 0061F8. Thus, the location counter would be set to 0061F8. +----------+---------------------------------------------------------+ | Column | Contents | | 1 | X'02' (12-2-9 punch). Identifies this as a loader | | | control statement. | | 2-4 | SLC -- identifies type of statement. | | 5-6 | Blank. | | 7-12 | Hexadecimal address to be added to the value of the | | | symbol, if any, in columns 17-24. It must be right- | | | justified in these columns, with unused leading columns | | | filled with zeros. | | 17-24 | Symbolic name whose assigned location is used by the | | | loader. Must be left-justified in these columns. If | | | blank, the address in the absolute field is used. | | 25-72 | May be used for comments or left blank. | | 73-80 | Not used by the loader. You may leave these columns | | | blank or insert program identification for your own | | | convenience. | +----------+---------------------------------------------------------+ REP The Replace (REP) statement allows instructions and constants to be changed and additions made. The REP statement must be punched in hexadecimal code. The format of a REP statement is shown in the following figure. The data in columns 17-70 (excluding the commas) replaces what has already been loaded into virtual storage, beginning at the address specified in columns 7-12. REP statements are placed in the file either (1) immediately preceding the last statement (END statement) if the text deck does not contain relocatable data such as address constants, or (2) immediately preceding the first RLD (relocatable dictionary) statement if there is relocatable data in the text deck. If additions made by REP statements increase the length of a control section, an ICS statement, which defines the total length of the control section, must be placed at the front of the deck. +----------+---------------------------------------------------------+ | Column | Contents | | 1 | X'02' (12-2-9 punch). Identifies this as a loader | | | control statement. | | 2-4 | REP -- identifies type of statement. | | 5-6 | Blank. | | 7-12 | Hexadecimal starting address of the area to be replaced | | | as assigned by the assembler. It must be right- | | | justified in these columns with unused leading columns | | | filled with zeros. | | 13-14 | Blank. | | 15-16 | ESID (External Symbol Identification) -- the | | | hexadecimal number assigned to the control section in | | | which replacement is to be made. The LISTING file | | | produced by the compiler or assembler indicates this | | | number. | | 17-70 | A maximum of 11 four-digit hexadecimal fields, | | | separated by commas, each replacing one previously | | | loaded halfword (two bytes). The last field must not | | | be followed by a comma. | | 71-72 | Blank. | | 73-80 | Not used by the loader. You may leave these columns | | | blank or insert program identification for your own | | | convenience. | +----------+---------------------------------------------------------+ Responses: DMSLIO740I Execution begins ... START was specified with LOAD and the loaded program starts execution. Any further responses are from the program. INVALID CARD - xxx...xxx INV was specified with LOAD and an invalid statement was found. The message and the contents of the invalid statement (xxx...xxx) are listed in the file LOAD MAP. The invalid statement is ignored and loading continues.
ibm/vm370-lib/cmshelp/load.helpcmd.txt · Last modified: 2023/08/06 13:36 by Site Administrator