In response to your request for a copy of a load module, the control program searches the task's load list and the job pack area. If a copy of the load module is found, the control program determines whether that copy can be used (see "Using an Existing Copy"). If an existing copy can be used, the search stops. If it cannot be used, the search continues until the module is located in a library or the link pack area. The load module is then brought into the job pack area or placed into the load list.
The order in which the control program searches the libraries, load list, and pack areas depends on the parameters used in the macro (LINK, LINKX, LOAD, XCTL, XCTLX, ATTACH or ATTACHX) requesting the load module. The parameters that define the order of the search are EP, EPLOC, DE, DCB, and TASKLIB.
Use the TASKLIB parameter only for ATTACH or ATTACHX. If you know the location of the load module, you should use parameters that eliminate as many of these searches as possible, as indicated in Figure 1, Figure 2, and Figure 3.
The EP, EPLOC, or DE parameter specifies the name of the entry point in the load module. Code one of the three every time you use a LINK, LINKX, LOAD, XCTL, XCTLX, ATTACH, or ATTACHX macro. The optional DCB parameter indicates the address of the data control block for the library containing the load module. Omitting the DCB parameter or using the DCB parameter with an address of zero specifies that the system is to do its normal search. If you specified TASKLIB and if the DCB parameter contains the address of the data control block for the link library, the control program searches no other library.
To avoid using "system copies" of modules resident in LPA and LINKLIB, you can specifically limit the search for the load module to the load list and the job pack area and the first library on the normal search sequence by specifying the LSEARCH parameter on the LINK, LOAD, or XCTL macro with the DCB for the library to be used.
The following paragraphs discuss the order of the search when the entry name used is a member name.
The EP and EPLOC parameters require the least effort on your part; you provide only the entry name, and the control program searches for a load module having that entry name. Figure 1 shows the order of the search when EP or EPLOC is coded, and the DCB parameter is omitted or DCB=0 is coded.
The control program searches:
When used without the DCB parameter, the EP and EPLOC parameters provide the easiest method of requesting a load module from the link, job, or step library. The control program searches the task libraries before the job or step library, beginning with the task library of the task that issued the request and continuing through the task libraries of all its antecedent tasks. It then searches the job or step library, followed by the link library.
//STEPLIB DD DSNAME=PDS1,...
// DD DSNAME=PDS2,...
Use extreme caution when specifying duplicate module names. Even if you code the DCB parameter, the wrong module can still receive control. For example, suppose there are two modules with the same name you want to invoke, one after the other. To distinguish between them in this example they are called PROG2 and PROG2'. PROG1 issues a LOAD for PROG2 and BALRs to it. PROG2 issues a LINK specifying a DCB for the library with the other copy of PROG2 (which we are calling PROG2'). The LINK will find a useable copy of PROG2 in the Job Pack Area and invoke it again, regardless of the DCB parameter. PROG2 again issues a LINK for PROG2'. This time the copy of PROG2 in the Job Pack Area is marked "not reusable" and PROG2' is loaded using the DCB parameter and given control.
Once a module has been loaded from a task library, step library, or job library, the module name is known to all tasks in the address space and may be used as long as the module is considered usable. Generally speaking, reenterable modules are always usable. Serially reusable modules are usable when they are currently in use. Non-reentrant, non-serially reusable modules are considered usable for LOAD if the use count is zero. A module is considered usable for ATTACH, LINK, or XCTL if it has not been marked NOT REUSABLE by a previous ATTACH, LINK, or XCTL. The use count is not considered.
If you know that the load module you are requesting is a member of one of the private libraries, you can still use the EP or EPLOC parameter, this time in conjunction with the DCB parameter. Specify the address of the data control block for the private library in the DCB parameter. The order of the search for EP or EPLOC with the DCB parameter (when the DCB parameter is not 0) is shown in Figure 2.
The control program searches:
Searching a job or step library slows the retrieval of load modules from the link library; to speed this retrieval, you should limit the size of the job and step libraries. You can best do this by eliminating the job library altogether and providing step libraries where required. You can limit each step library to the data sets required by a single step. Some steps (such as compilation) do not require a step library and therefore do not require searching and retrieving modules from the link library. For maximum efficiency, you should define a job library only when a step library would be required for every step, and every step library would be the same.
The DE parameter requires more work than the EP and EPLOC parameters, but it can reduce the amount of time spent searching for a load module. Before you can use this parameter, you must use the BLDL macro to obtain the directory entry for the module. The directory entry is part of the library that contains the module. See z/OS DFSMS Macro Instructions for Data Sets for more information about the BLDL macro.
To save time, the BLDL macro must obtain directory entries for more than one entry name. Specify the names of the load modules and the address of the data control block for the library when using the BLDL macro; the control program places a copy of the directory entry for each entry name requested in a designated location in virtual storage. If you specify the link library and the job or step library by specifying DCB=0, the directory information indicates from which library the directory entry was taken. The directory entry always indicates the relative track and block location of the load module in the library. If the load module is not located on the library you indicate, a return code is given. You can then issue another BLDL macro specifying a different library.
To use the DE parameter, provide the address of the directory entry and code or omit the DCB parameter to indicate the same library specified in the BLDL macro. The task using the DE parameter should be the same as the one which issued the BLDL or one which has the same job, step, and task library structure as the task issuing the BLDL. The order of the search when the DE parameter is used is shown in Figure 3 for the link, job, step, and private libraries.
Searching when Directory Entry is provided. First two steps are *always* search load list and search job pack queue.
As the discussion of the search indicates, you should choose the parameters for the macro that provide the shortest search time. The search of a library actually involves a search of the directory, followed by copying the directory entry into virtual storage, followed by loading the load module into virtual storage. If you know the location of the load module, you should use the parameters that eliminate as many of these unnecessary searches as possible, as indicated in Figure 1, Figure 2, and Figure 3. Examples of the use of these figures are shown in the following discussion of passing control.