LOAD (Load a Phase) Macro

The LOAD macro loads the phase that is specified in the first operand (if this phase is not in the SVA) and returns control to the calling program.

After execution of the macro, the entry-point address of the called phase is returned to you in register 1. LOAD sets the high-order bit in register 1 to indicate the phase 's AMODE (0 for 24, 1 for 31). If the phase 's AMODE is ANY, LOAD sets the high-order bit in register 1 corresponding to the caller 's AMODE.
Note:
  1. RMODE ANY is allowed for the following LOAD specification: LOAD phasename | (S,address) | (1), loadpoint | (S,loadpoint),(0). All other specifications require RMODE 24.
  2. The addresses are not validated by the macro expansion. Depending on the macro call, only 3 bytes of a passed 4-byte address might be passed to the SVC service. This might cause unpredictable results, since the address cannot be validated properly.
  3. If any of the parameters LIST, SYS, DE, TXT, MFG, or RET are specified RMODE=24 is required. RMODE=ANY is not supported for the parameter list format.

For a non-relocatable phase, the address of the called phase is the entry-point determined at link-edit time. For a relocatable phase, the entry point is adjusted by the relocation factor.

If the phase is in the SVA, it is not loaded. Instead, the system returns, in register 1, the entry-point address of the phase in the SVA. If, however, the SDL operand is specified in the LIBDEF statement, the phase is loaded if it is found in one of the sublibraries that are specified before the SDL operand.

Format

Read syntax diagramSkip visual syntax diagramnameLOADphasename(S, address)(1), loadpoint,(S, loadpoint),(0),LIST=listname(S, listname)( r1),SYS=YES,DE=NO,DE=YESVSEVSEFORM,TXT=NO,MFG=area(S, area)( r2),RET=NO,RET=YES

Requirements for the caller

AMODE:
24 or 31
RMODE:
24 or ANY
ASC Mode:
Primary

Parameters

phasename | (S,address) | (1)
For phasename specify the name of the required phase. The address is regarded as either a 24-bit or 31-bit address, depending on the AMODE of the caller.

If the DE operand is omitted or if DE=NO is specified, the address as specified in (S, address) or as loaded into a register points to an 8-byte field that contains the phase name.

If DE=YES or DE=VSE | VSEFORM, the operand has a different meaning; refer to the discussion of the DE operand.

loadpoint | (S,loadpoint) | (0)
If loadpoint is provided, the phase is loaded at the specified address. If no loadpoint is given, the (relocated) loadpoint specified at link-edit time is used. The loadpoint is interpreted as either a 24-bit or 31-bit address, depending on the AMODE of the caller.

The address that is used must be outside the supervisor area. When an overriding address is given, the entry-point address is relocated and returned in register 1. An overriding load-point address must not be specified for a phase that is linked as a member of an overlay structure.

If the phase is non-relocatable, none of the other addresses in the phase are relocated; if the phase is relocatable, however, the entry point and address constants are updated with the relocation factor.

If loadpoint is given in register notation, the register that is used must not be register 1. Preload the register with the load-point address.

With (S,...) notation, the load-point address is derived from base register and displacement as assembled for loadpoint in the (S,loadpoint) specification.

LIST=listname | (S,listname) | (r1)
For listname specify the name of your local directory list that is generated in the partition by the GENL macro. When this operand is included, the system scans the local directory list for the name of the required phase before it initiates a search for this phase name in the directories of accessible sublibraries.

If the phase isfound in the local directory list, general register 0 points to the related directory entry; otherwise, register 0 is set to zero.

The local directory list must be located below 16 MB (only 3 bytes are used in the macro expansion).

If LIST is specified, DE=YES or DE=VSE | VSEFORM is invalid.

SYS=YES
If SYS=YES is specified, the system scans the system directory list (SDL) in the SVA and the system sublibrary before any private sublibraries. If the operand is omitted, the SDL and the private sublibraries are searched first.
DE=NO | YES | VSE | VSEFORM
By specifying DE=YES or DE=VSE | VSEFORM you can generate your own local directory entry for a frequently used phase to save a time-consuming library directory search for that phase. A specification of YES or VSE|VSEFORM is invalid if LIST is specified.
DE=NO
Indicates that no local directory entry is to be generated.
DE=YES
Indicates a conventional 38-byte directory entry in the old (VSE/Advanced Functions Version 1) librarian format is to be generated.
DE=VSE | VSEFORM
Indicates that a 40-byte directory entry in the new (VSE/Advanced Functions Version 2) librarian format is to be generated. VSE is a short form of VSEFORM.

For DE=YES or DE=VSE, the MAPDNTRY macro can be used to interpret the information that is returned by the LOAD (or FETCH) macro. Among other information, the local directory entry shows the AMODE/RMODE assigned to the phase. The directory entry must be located below 16 MB (see explanation for phasename).

The local directory entry is activated by the first LOAD request; all further LOAD requests are executed without any directory search.

If the first operand is written as phasename (instead of S-type or register notation), a directory entry is generated within the macro expansion. The generated directory entry contains the name of the phase in the first eight bytes.

If you use S-type or register notation for the first operand, you must set aside the 38-byte (or 40-byte) field for the directory entry yourself and point to it with this operand. The directory entry must contain the phase name in the first 8 bytes (left-justified and padded with blanks); its format is:

For DE=YES: 
      Bytes    Contents
        0      CL8'PHASENAM'
        8      XL3'0'
       11      XL1'0D'      NO. OF HALFWORDS FOLLOWING
       12      XL26'0'
For DE=VSE | VSEFORM: 
      Bytes    Contents
        0      CL8'PHASENAM'
        8      XL3'FFFFFF'      ID FOR NEW FORMAT
       11      XL1'0E'          NO. OF HALFWORDS FOLLOWING
       12      XL28'0'
TXT=NO
Together with LIST=listname or DE=YES, TXT=NO is useful if a phase is to be loaded more than once while your program executes. TXT=NO causes a search for the directory entry without transfer of the contents (or text) of the phase itself. It indicates, in the directory entry, if and where the phase was found. This can be used to accomplish either of the following:
  • The directory entry can be filled in from the sublibrary for later FETCH/LOAD calls without the overhead of text transfer.
  • You can establish whether a given phase is present in a user sublibrary, or the SYSLIB sublibrary, or the SVA since register 0 contains the address of the directory entry and byte 16 of the directory entry is:
    X'06'
    If the phase is not found
    X'12'
    If the phase is in the SVA
    X'0A'
    If the phase is in a user sublibrary
Note: Test these conditions with a Test Under Mask (TM) instruction, not a Compare instruction. If the phase is not found and both DE=YES and TXT=NO are specified, register 1 is returned with X'00'. See Table 1.
MFG=area | (S,area) | (r2)
The operand is required if the program that issues the LOAD macro is to be reenterable. It specifies the address of a 64-byte dynamic storage area, that is, storage which your program obtained through a GETVIS macro. This area is required for system use during execution of the macro.

The MFG area must be located below 16 MB.

RET=NO | YES
By specifying RET=YES you can cause control to be returned to your program in any case (both in normal and error situations). Register 15 contains one of the following return codes:
0
LOAD completed successfully.
4
Phase not found. This return code is issued also if a user directory entry is found and the corresponding phase has already been deleted or re-cataloged.
8
Irrecoverable I/O error during LOAD processing.
12
Invalid library or sublibrary structure that is detected during LOAD processing.
16
Either of the following was found during LOAD processing:
  • Local directory entry outside the partition.
  • Phase does not fit into the partition.
  • Loadpoint outside partition.
20
Security violation.
24
Inconsistent user directory state ─ LOAD found an inconsistency between your program 's local directory entry and the corresponding entry in the directory of the related sublibrary. The local directory entry is overwritten by the entry that is read from the directory of the sublibrary. LOAD checks the following:
  • Length of phase.
  • Relocation state.
  • Difference between the load point and the partition start address.
  • Difference between the load point and the entry point.

Return code 24 is also issued if an incorrect length is specified in byte 11 of the directory entry.

28
Partition is too small (or phase does not fit into the logical transient area).
36
A loadpoint is provided that causes a mismatch with the RMODE specification in the phase 's local directory (that is, loadpoint and end of phase, or both, is above 16 MB and RMODE=24). The phase is not loaded. If RET=NO is specified, the user is canceled with 'RMODE violation'.