6 STORING AND USING PROGRAMS IN USERS LIBRARIES
6.1 Storing Programs in Single-Member User Libraries
6.2 Storing Programs in Multi-Member User Libraries
6.3 Using Programs from User Libraries
6.4 Using the Binder from a User Library
6 STORING AND USING PROGRAMS IN USERS LIBRARIESThe following procedures were developed to store user programs in l oad module form. Each user can develop and maintain private libraries, which are partitioned data sets.
A Partitioned Data Set (PDS) is divided into one or more sequential "members," each of which may be accessed independently. Each member has a unique name, up to 8 characters long, stored in a directory. The directory contains an entry for each member consisting of the member name and a pointer to the location of the member in the data set. When a member is deleted or replaced, only the member-name pointer is deleted or changed. The space used by the member cannot be reused until the data set is condensed. If there is not enough space for a new or replacement member, or if there are no more free entries in the directory, no members can be added. A job that attempts to add a new member to a PDS that is full usually ABENDs with a B37 or D37 completion code. A PDS must be stored on a disk and cannot exceed one disk pack in size.
Load modules (the output from the Binder) must be stored in PDSs. The programs may be either fully or partially resolved. The Binder will automatically search libraries defined by the SYSLIB DD statement to resolve calls or references to programs that are not included in the main input stream defined by the SYSLIN DD statement. The libraries are searched in the order they are defined. When a reference is found, no further searching is done, and the next search begins again at the first library. If all external references and subroutine calls are resolved, the program is fully resolved and is, therefore, directly executable without being resolved again. If the external references and calls are not to be resolved, the NCAL option must be specified in the EXEC statement for the procedure used to store the program. The program is then partially resolved and must be reprocessed by the Binder before it can be executed.
Executing fully resolved load modules may cost less because a Binder step is saved every time the program is run; however, problems may develop as a result of updates to the computer system. Fully resolved load modules cannot take advantage of some of these system improvements. In addition, a program may fail to run if it contains old interfaces to system modules.
To avoid these problems, fully resolved load modules should be re-created periodically, particularly whenever a new system release is installed. If re-creating the fully resolved modules is difficult, it may be better to keep partially resolved modules and do the final Binder step each time the program is run.
The LKSM procedure is used to fully resolve and store a load module (output of the Binder) a single-member partitioned data set (PDS). The COMP and OBJ procedures may be used to prepare input for the LKSM procedure. A short step, executed before the Binder step, deletes the PDS if it already exists on the specified disk. Then the Binder step creates the new data set. If the data set does not already exist, the delete step issues a message, but does not affect later processing. If the output library is to be created on the MSS, STORAGE=MSS must be specified. Additionally, the symbolic parameters SIZE, UNITS, and INCR must be coded with the appropriate values for requesting space on the MSS.
The user may define two private call libraries for resolving external references. They are searched in their order of concatenation; if members with duplicate names exist, the first one found will be selected. The private libraries are searched before NIH.UTILITY.
Symbolic Parameters for ASMHLKSM
Required |
Value to be supplied |
NAME='aaaaiii.dsname' |
Dsname of PDS to receive load module |
Optional |
Value to be supplied |
DISK=fileser |
Volume for PDS; required only if the data set is not cataloged |
STORAGE=type |
Unit name for PDS; FILE is the default |
OPTIONS=parms |
Binder parameters |
PROGRAM=progname |
Member name for load module; the default is MAIN |
SIZE=primary |
Primary space allocation for load module; the default is 100 units |
UNITS=type |
Allocation units for load module; the default is blocks of 1024 bytes |
INCR=secondary |
Number of units in each secondary allocation; the default is 12 |
STEPEND=disp |
Disposition for the load module; the default is KEEP |
UNUSED= |
Nullifying causes retention of unused space; the default is RLSE |
INDEX=blocks |
Number of directory blocks for load module PDS; the default is 1 |
LIBNAME='aaaaiii.dsname' |
Dsname of first user-defined library |
LIBDISK=fileser |
Volume for first library; required only if the data set is not cataloged |
LIBSTOR=type |
Unit name for first library; FILE is the default |
ALTNAME='aaaaiii.dsname' |
Dsname of second user-defined library |
ALTDISK=fileser |
Volume for second library; required only if the data set is not cataloged |
ALTSTOR=type |
Unit name for second library; FILE is the default |
The internal stepnames for the ASMHLKSM procedure are SCRATCH, for the step to scratch the data set if it already exists, and LOAD for the Binder step.
Example 13:
To assemble, fully resolve, and store a program into a single-member PDS.
//stepname EXEC ASMHCOMP //COMP.SYSIN DD * (source program) //stepname EXEC ASMHLKSM,NAME='aaaaiii.dsname'
Example 14:
To assemble, fully resolve, and store a program, overriding the default space allocation. If the program requires more than the default space allocation, the SIZE parameter should be used. The default SIZE parameter allows the user to obtain at least 10 tracks for the load module (unneeded space is released).
//stepname EXEC ASMHCOMP //COMP.SYSIN DD * (source program) //stepname EXEC ASMHLKSM,NAME='aaaaiii.dsname', // SIZE=primary
Example 15:
To fully resolve and store a main program and subroutines using input from the OBJ procedure. The user must supply a DD statement for each data set that contains a program or subroutine and insure that the main program is defined first.
//stepname EXEC ASMHLKSM,NAME='aaaaiii.dsname', // DISK=fileser //LOAD.SYSLIN DD DSN=aaaaiii.dsname1,DISP=SHR // DD DSN=aaaaiii.dsname2,DISP=SHR // DD DSN=aaaaiii.dsname3,DISP=SHR
Example 16:
To assemble a main program (ASMHCOMP), fully resolve it using subroutines previously assembled with the OBJ procedure, and create a fully resolved single-member load module (ASMHLKSM).
//stepname EXEC ASMHCOMP //COMP.SYSIN DD * (source program) //stepname EXEC ASMHLKSM,NAME='aaaaiii.dsname' //LOAD.SYSLIN DD // DD DSN=aaaaiii.dsname1,DISP=SHR // DD DSN=aaaaiii.dsname2,DISP=SHR
The procedures described below enable the user to add programs to multi-member partitioned data sets and execute them. Before using these procedures, see Batch Processing and Utilities at NIH for information on how to establish and maintain partitioned data sets. These procedures differ from the OBJ and LKSM procedures in that many programs can be stored in one data set. The OBJ and LKSM procedures store only one program in one data set.
The LKMM procedure adds a program to a private partitioned data set. If the program name already exists in the data set, it will be replaced. The Binder input is the same as for the LKGO procedure.
The user may define two private call libraries for resolving external references. They are searched in their order of concatenation; if members with duplicate names exist, the first one found will be selected. The private libraries are searched before NIH.UTILITY. If no libraries are to be searched (no external references are to be resolved), OPTIONS=NCAL must be specified for the ASMHLKMM step; this creates a partially resolved load module.
Symbolic Parameters for ASMHLKMM
Required |
Value to be supplied |
NAME='aaaaiii.dsname' |
Dsname of PDS to receive load module |
PROGRAM=progname |
Program name; member name in PDS |
Optional |
Value to be supplied |
DISK=fileser |
Volume for PDS; required only if the data set is not cataloged |
STORAGE=type |
Unit name for PDS; FILE is the default |
OPTIONS=parms |
Binder parameters |
LIBNAME='aaaaiii.dsname' |
Dsname of first user-defined library |
LIBDISK=fileser |
Volume for first library; required only if the data set is not cataloged |
LIBSTOR=type |
Unit name for first library; FILE is the default |
ALTNAME='aaaaiii.dsname' |
Dsname of second user-defined library |
ALTDISK=fileser |
Volume for second library; required only if the data set is not cataloged |
LTSTOR=type |
Unit name for second library; FILE is the default |
The procedure name is ASMHLKMM. The stepname within the cataloged procedure is LOAD.
Example 17
To create a multi-member PDS on a FILE volume and then assemble and add a partially resolved program to the PDS. The program must be fully resolved along with all of its subroutines, as shown in the next example, before it is executed.
// EXEC PGM=IEFBR14 //NEWPDS DD DSN=aaaaiii.dsname,DISP=(NEW,CATLG), // UNIT=FILE,SPACE=(TRK,(10,2,3)) //stepname EXEC ASMHCOMP //COMP.SYSIN DD * (source program) //stepname EXEC ASMHLKMM,NAME='aaaaiii.dsname', // PROGRAM=progname,OPTIONS=NCAL
Example 18
To fully resolve and add a program to a multi- member PDS, where the main program and its subroutines were previously stored in the same PDS as partially resolved load modules. If 'progname' and 'main progname' are the same, the partially resolved main program will be replaced.
//stepname EXEC ASMHLKMM,NAME='aaaaiii.dsname', // PROGRAM=progname, // LIBNAME='aaaaiii.dsname' //LOAD.SYSLIN DD * INCLUDE SYSLIB(main progname)
Example 19:
To fully resolve and add a program to a cataloged PDS, where one or more of the subroutines is being assembled. The same PDS is used to fully resolve external references; therefore, LIBNAME and NAME refer to the same data set.
//stepname EXEC ASMHCOMP //COMP.SYSIN DD * (source program) //stepname EXEC ASMHLKMM,LIBNAME='aaaaiii.dsname', // NAME='aaaaiii.dsname',PROGRAM=progname //LOAD.SYSLIN DD // DD * INCLUDE SYSLIB(main progname) ENTRY entryname
The INCLUDE and ENTRY control statements are passed to the Binder. They always begin after column 1. The INCLUDE statement is used to define as input to the Binder modules that would not automatically be brought in. The ENTRY statement indicates the starting point of the program. If the ENTRY statement is not provided and no entry point is specified in the Assembler program, the first byte of the first control section of the load module will be used as the entry point.
These control statements and the two preceding DD statements are not needed in this example if the main program is one of the routines being assembled. In general, the ENTRY statement is not needed for Assembler Language if the main program specified an entry point and is the first input to the Binder or is in object module form.
Example 20:
To fully resolve and execute a program where the main program and some subroutines are in two separate PDSs and other subroutines are being compiled.
//stepname EXEC ASMHCOMP //COMP.SYSIN DD * (source program) /* //stepname EXEC ASMHLKGO, // LIBNAME='aaaaiii.dsname1' // ALTNAME='aaaaiii.dsname2' //LOAD.SYSLIN DD // DD * INCLUDE SYSLIB(main program name) ENTRY entryname //GO.ddname DD etc. (as many as needed) //GO.SYSIN DD * (if needed) (data)
The CALL procedure is used to execute a fully resolved program. This procedure provides the user with the DD statements needed to use the printer (SYSOUT) and the SORT/MERGE messages data set (SORTMSGS). These DD statements are the same ones supplied in the ASMHLKGO procedure. The user must supply any additional DD statements required for the proper execution of the program.
Symbolic Parameters for ASMHCALL
Required |
Value to be supplied |
NAME='aaaaiii.dsname'
|
Dsname of PDS containing load module |
Optional |
Value to be supplied |
DISK=fileser |
Volume for PDS; required only if the data set is not cataloged |
STORAGE=type |
Unit name for PDS; FILE is the default |
PROGRAM=progname |
Member name for load module; the default is MAIN. |
CORE=nnnK |
Region for GO step; 500K is the default |
The internal stepname for the ASMHCALL procedure is GO.
Example 21:
To execute a program that has been previously stored by a LKSM procedure.
//stepname EXEC ASMHCALL,NAME='aaaaiii.dsname' //GO.ddname DD etc. (as many as needed) //GO.SYSIN DD * (if needed) (data)
Example 22:
To execute a fully resolved program previously stored in a PDS on the MSS.
//stepname EXEC ASMHCALL,NAME='aaaaiii.dsname', // PROGRAM=progname, //GO.ddname DD etc. (as many as needed) //GO.SYSIN DD * (if needed) (data)
User-defined libraries can be specified to be searched in resolving external references. Both the Binder and the Loader offer this facility. The symbolic parameter LIBNAME defines the first such library. ALTNAME is available if it is necessary to define a second private library. These private libraries are searched in their order of concatenation; if members with duplicate names exist, the first one found will be selected. The private libraries are searched before NIH.UTILITY. if members with duplicate names exist, the first one found will be selected. The private libraries are searched before NIH.UTILITY.
Symbolic Parameters for ASMHLKGO and ASMHLDGO
Required |
Value to be supplied |
None |
None |
Optional |
Value to be supplied |
OPTIONS=parms |
Binder or Loader parameters |
CORE=nnnK |
Region for GO step; 512K is the default |
EPT=entry |
Entry point for main program (Loader only); no default is supplied |
LIBNAME='aaaaiii.dsname' |
Dsname of first user-defined library |
LIBDISK=fileser |
Volume for first library; required only if the data set is not cataloged |
LIBSTOR=type |
Unit name for first library; FILE is the default |
ALTNAME='aaaaiii.dsname' |
Dsname of second user-defined library |
ALTDISK=fileser |
Volume for second library; required only if the data set is not cataloged |
ALTSTOR=type |
Unit name for second library; FILE is the default |
Example 23:
To use the Binder when the main program has been assembled and its subroutines are stored as load modules in a private user library on one of the FILE disks.
//stepname EXEC ASMHCOMP //COMP.SYSIN DD * (source program) //stepname EXEC ASMHLKGO,LIBNAME='aaaaiii.dsname' //GO.ddname DD etc.
Example 24:
To use the Loader when the main program has been assembled and its subroutines are stored as load modules in a private user library on the MSS.
//stepname EXEC ASMHCOMP //COMP.SYSIN DD * (source program) //stepname EXEC ASMHLDGO,LIBNAME='aaaaiii.dsname' //GO.ddname DD etc.
The LKGO procedure may also be used to fully re-resolve and execute a partially resolved load module stored in a partitioned data set.
The examples above assume the subroutines were stored using the same names they are called by. If these names are not the same, INCLUDE statements must be supplied for the subroutines.
Example 25:
To fully resolve and execute a main program and its subroutines that have been partially resolved and stored into a PDS.
//stepname EXEC ASMHLKGO, // LIBNAME='aaaaiii.dsname' //LOAD.SYSLIN DD * INCLUDE SYSLIB(main program name) /* //GO.ddname DD etc. (as many as needed) (data)
Example 26:
To fully resolve and execute a program where the main program and some subroutines are in two separate PDSs and other subroutines are being compiled.
//stepname EXEC ASMHCOMP //COMP.SYSIN DD * (source program) //stepname EXEC ASMHLKGO, // LIBNAME='aaaaiii.dsname1', // ALTNAME='aaaaiii.dsname2' //LOAD.SYSLIN DD // DD * INCLUDE SYSLIB(main program name) ENTRY entryname //GO.ddname DD etc. (as many as needed) //GO.SYSIN DD * (if needed) (data)
