Description

The requirements for the caller are:

If you code any of the parameters LSEARCH, ADDR, ADRNAPF, GLOBAL, EOM, or LOADPT, you will obtain a macro-generated parameter list. Therefore, except for the error routine address, all addresses must be specified as A-type addresses or registers (2) - (12).

• Any module loaded by a task will not be removed from virtual storage unless the task that loaded the module invokes the DELETE macro or terminates.
• The load module entry name must be listed as a member name or alias in a partitioned data set directory or it must have been specified previously in an IDENTIFY macro invocation. If the LOAD macro cannot find the specified entry name, the caller's task is ended abnormally unless the caller provides an ERRET exit.
• The caller cannot have an EUT FRR established.

After the caller issues the macro, the system might use some registers as work registers or might change the contents of some registers. When the system returns control to the caller, the contents of these registers are not the same as they were before the macro was issued. Therefore, if the caller depends on these registers containing the same value before and after issuing the macro, the caller must save these registers before issuing the macro and restore them after the system returns control.

When control returns to the caller or the ERRET exit receives control, the access registers (ARs) are unchanged.

None.

The LOAD macro is written as follows:

The parameters are explained below:

EP=entry name

EPLOC=entry name addr

DE=list entry addr

Specifies the entry name, the address of the name, or the address of the name field in a 62-byte list entry for the entry name that was constructed using the BLDL macro. If EPLOC is coded, the name must be padded to eight bytes, if necessary.

Note: When you use the DE parameter with the LOAD macro, DE specifies the address of a list that was created by a BLDL macro. The LOAD and the BLDL must be issued from the same task. Otherwise, the system might terminate the program with a system completion code of 106 and a return code of 15. Therefore, do not issue an ATTACH or DETACH between issuances of BLDL and LOAD.

,DCB=dcb addr

Specifies the address of the data control block for the partitioned data set containing the entry name described above. This parameter must indicate the same DCB used in the BLDL mentioned above.

If the DCB parameter is omitted or if DCB=0 is specified when the LOAD macro is issued by the job step task, the data sets referred to by either the STEPLIB or JOBLIB DD statement are first searched for the entry name. If the entry name is not found, the link library is searched.

If the DCB parameter is omitted or if DCB=0 is specified when the LOAD macro is issued by a subtask, the data sets associated with one or more data control blocks referred to by the TASKLIB operand of previous ATTACH macros in the subtask chain are first searched for the entry name. If the entry name is not found, the search is continued as if the LOAD had been issued by the job step task.

Note: DCB must reside in 24-bit addressable storage.

,ERRET=err rtn addr

Specifies the address of a routine to receive control when an error condition that would cause an abnormal termination of the task is detected. GPR 1 contains the abend code that would have resulted had the task abended, and GPR 15 contains the reason code that is associated with the abend. The routine does not receive control when input parameter errors are detected.

,LSEARCH=NO

,LSEARCH=YES

Specifies whether (YES) or not (NO) you want the library search limited to the job pack area and to the first library in the normal search sequence.

,ADDR=load addr

,ADRNAPF=load addr

Specifies that the module is to be loaded at the designated address. The address must begin on a doubleword boundary. Storage for the module must have been previously allocated in the key of the eventual user. The system does not search for the module and does not maintain a record of the module when it is loaded. If you code ADDR or ADRNAPF, you must also code the DCB parameter (not DCB=0) and you must not code GLOBAL or LOADPT. ADDR and ADRNAPF are only allowed with PLISTVER=0.

Note: The system assumes that the RMODE of the module is consistent with this address, but the system does not check.

To code: Specify the RS-type address, or address in register (2)-(12), of a 4–byte field.

If your program requires that the module be in an APF-authorized library, use ADDR; otherwise, use ADRNAPF.

• For the ADDR parameter, the system checks that the module being loaded is in an APF-authorized library.
• For the ADRNAPF parameter, the system does not check that the module resides in an APF-authorized library. Therefore, if the module is not in an APF-authorized library, the program must make sure that the loaded programs receive control only in problem state.

,ADDR64=load addr64

,ADRNAPF64=load addr64

Specifies that the module is to be loaded beginning at the designated address. The address must begin on a doubleword boundary. Storage for the module must have been previously allocated in the key of the eventual user. The system does not search for the module and does not maintain a record of the module when it is loaded. If you code ADDR64 or ADRNAPF64, you must also code the DCB parameter (not DCB=0), and you must not code GLOBAL or LOADPT. ADDR64 and ADRNAPF64 are only allowed with PLISTVER=1 or PLISTVER=MAX. The SYSSTATE ARCHLVL value (by specifying SYSSTATE ARCHLVL=n) must be greater than 1.

Note: The system assumes that the RMODE of the module is consistent with this address, but the system does not check. The data set from which an ADDR64 or ADRNAPF64 request is met must not be a VIO data set.

To code: Specify the AD-type address, or address in 64-bit register (2)-(12), of an 8-byte field.

If your program requires that the module is in an APF-authorized library, use ADDR64; otherwise, use ADRNAPF64.

• For the ADDR64 parameter, the system checks that the module being loaded is in an APF-authorized library.
• For the ADRNAPF64 parameter, the system does not check whether the module resides in an APF-authorized library. Therefore, if the module is not in an APF-authorized library, the program must make sure that the loaded programs receive control only in problem state.

,GLOBAL=YES

,GLOBAL=(YES,P)

,GLOBAL=(YES,F)

,GLOBAL=NO

Specifies whether the module is to be loaded into the pageable common service area (CSA) (GLOBAL=(YES,P) or GLOBAL=YES), or loaded into fixed CSA (GLOBAL=(YES,F)), or not loaded into CSA (GLOBAL=NO). (When the module is to be loaded into CSA, the module must not have been previously loaded with different attributes by the same job step. The module must also be reentrant and must reside in an APF-authorized library.)

For GLOBAL=(YES,F), the module must not be marked as requiring alignment on a page boundary. If you code the GLOBAL parameter, you cannot code the ADDR or ADRNAPF parameter.

If the requested module resides in the link pack area, the LOAD request performs as though the GLOBAL parameter was omitted. The LOAD request locates the module in the link pack area and allows access to it, but the request does not load a copy of the desired module into the common service area.

Note: A load request with the GLOBAL=YES, (YES,P), or (YES,F) option does not cause the loaded module to be implicitly known to other address spaces. The loaded module can be accessed by other address spaces, however, only the task that loaded the module may delete it.

,EOM=YES

,EOM=NO

Indicates whether a module in global storage is to be deleted when the address space terminates (EOM=YES) or when the task terminates (EOM=NO). If you code EOM, you must also code GLOBAL.

,LOADPT=addr

Specifies that the starting address at which the module was loaded is to be returned to the caller at the indicated address. If you code LOADPT, you cannot code ADDR or ADRNAPF.

,EXTINFO=addr

Specifies a 304-byte area which upon return is to contain extended information. This area is mapped by dsect EXTI within macro CSVEXTI. Included in this area are :

• the extent list (each entry is mapped by dsect EXTIXE within macro CSVEXTI)
• the authorization code
• the entry point address

By using the EXTINFO keyword you can avoid the need to call CSVQUERY after doing the LOAD to obtain information that would not otherwise be returned by LOAD. For example, if a program object length were greater than 128 megabytes or had been bound with RMODE=SPLIT, LOAD would not otherwise return the length information.

,RELATED=value

Specifies information used to self-document macros by “relating” functions or services to corresponding functions or services. The format and contents of the information specified are at the discretion of the user, and may be any valid coding values.

,PLISTVER=IMPLIED_VERSION

,PLISTVER=MAX

,PLISTVER=1

,PLISTVER=0

An optional input parameter that specifies the version of the macro. PLISTVER determines which parameter list the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form. When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are:

• IMPLIED_VERSION, which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
• MAX, if you want the parameter list to be the largest size currently possible. This size might grow from release to release and affect the amount of storage that your program needs.

  If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form, when both forms are assembled with the same level of the system. In this way, MAX ensures that the parameter list does not overwrite nearby storage.

• 1, may be used with any currently available parameters.
• 0, if you use any currently available parameters other than ADDR64 or ADRNAPF64; may not be used with ADDR64 and ADRNAPF64.

To code: Specify one of the following versions:

• IMPLIED_VERSION
• MAX
• A decimal value of 0 or 1

When the LOAD macro returns control to the caller, GPR 15 is set to zero if the load request was successful.

If the load request was not successful and a caller-provided error routine (specified using the ERRET keyword) receives control, GPR 1 contains the system completion code for the ABEND that would have been issued had the caller not provided an ERRET exit. GPR 15 contains the reason code associated with the system completion code in GPR 1.