gtpi1m69System Installation Support Reference

Loading E-Type Programs to an Enabled System

Unlike the general file loader or the auxiliary loader, the E-type loader does not require an IPL.

The E-type loader:

If you load a new TARGET(TPF) C library function, you must perform a C000 load and an online module IPL to rebuild the quick enter directory segment name table. Otherwise, you will not be able to use the new TARGET(TPF) C library function. If you replace an existing TARGET(TPF) C library function, a C000 load is not necessary.

Perform the following steps to load new E-type programs to a TPF system:

  1. Create an E-type loader load deck.
  2. Load the E-type programs to a storage medium.
  3. Load a loadset of E-type programs from a storage medium to the system.

Creating an E-Type Loader Load Deck

Enter the JCL Cards

The following JCL cards are used to run the E-type loader offline segment (OLDR); nn is the release identification, and ssid is the subsystem ID.

Figure 25. OLDR Run Load Deck (To GDS) Example

//OLDRGDS  JOB MSGLEVEL=1,CLASS=A,MSGCLASS=A,REGION=2100K,
//       USER=mvsuser,PASSWORD=password
//NAME   EXEC PGM=TPFLDRnn,REGION=9000K,PARM='OLDR,CLMSIZE=9000000'
//STEPLIB  DD  DSN=ACP.LINK.RELnn.ssid,DISP=SHR
//         DD  DSN=SYS1.EDC.SEDCLINK,DISP=SHR
//         DD  DSN=SYS1.PLI.SIBMLINK,DISP=SHR
//LOADMOD  DD  DSN=ACP.LINK.RELnn.ssid,DISP=SHR
//OBJLIB   DD  DSN=ACP.OBJ.RELnn.ssid,DISP=SHR
//CPRTEMP  DD  UNIT=SYSDA,
//             DSN=&&CPTEMP,SPACE=(TRK,(100,20)),
//             DCB=(RECFM=FB,BLKSIZE=4095,LRECL=4095),
//             DISP=(NEW,DELETE)
//PROGTEMP DD  UNIT=SYSDA,
//             DSN=&&PRTEMP,SPACE=(TRK,(100,20)),
//             DCB=(RECFM=FB,BLKSIZE=4095,LRECL=4095),
//             DISP=(NEW,DELETE)
//OUTPUT   DD  UNIT=SYSDA,VOLUME=SER=dasd,
//             DSN=mvsuser.OUTPUT,SPACE=(TRK,(40,20)),
//             DCB=(RECFM=F,BLKSIZE=4095,LRECL=4095),
//             DISP=(OLD,KEEP,KEEP)
//SALTB    DD  DSN=ACP.SALTBL.RELnn.ssid,DISP=SHR
//ADATAIN  DD  DSN=xxx
//ADATATMP DD  DSN=&&SYSUT1,SPACE=(TRK,(100,20)),UNIT=SYSDA
//SYSOUT   DD  SYSOUT=*
//SYSPRINT DD  SYSOUT=*
//PRINTER  DD  SYSOUT=*
//SYSUDUMP DD  SYSOUT=*
//CEEDUMP  DD  SYSOUT=*
//LDRTRACE DD  SYSOUT=*
//SYSIN    DD  *
*** INPUT CONTROL CARDS ARE PLACED HERE

Notes:

  1. The DD names SALTB, OBJLIB, OUTPUT, PRINTER, and SYSIN are required.

  2. DD name LDRTRACE is required only if you specify TRACE(ON) as a parameter.

  3. Data set concatenation is sequence dependent.

  4. Figure 25 shows an OLDR load deck using a GDS as the storage medium. Appendix A, JCL Load Deck Examples shows JCL load decks using other storage medium.

  5. If the storage medium is tape, use standard label tapes.

TPFLDR Exec Card

The TPFLDR EXEC card identifies the specified version of the TPF offline loader program (TPFLDR).

These are the parameters that can be specified on the EXEC card.

  1. OLDR

    indicates the E-type file loader program (OLDR) is to be executed.

  2. CLMSIZE = x

    where x is greater than or equal to the MVS file size of the largest C load module to be loaded. If a C load module contains a higher than normal ratio of VCONs to executable code, CLMSIZE must be larger.

  3. ADATASIZE = x

    where x is greater than or equal to the MVS file size of the largest ADATA file to be loaded. ADATA does not attempt to load ADATA files when ADATASIZE=0.

  4. TRACE(ON|OFF)

    If you specify TRACE(ON), selective trace data will be written to the LDRTRACE DD name. This trace data can be useful to system programmers to debug problems that occur while running TPFLDR. TRACE(ON) is primarily intended for TPF development personnel for this purpose. TRACE(OFF) is the default. If you specify TRACE(OFF), no trace data is written.

STEPLIB Card

The STEPLIB card identifies the partitioned data sets that contain the offline loader programs.

LOADMOD Card

The LOADMOD card identifies the partitioned data set (LOADMOD) that contains the link-edited C load modules. When an E-type program is being loaded, the data sets identified by the LOADMOD card are searched before the data sets identified by the OBJLIB card are searched. The C load modules are compiled and link-edited using standard MVS facilities. For more information, see TPF System Generation.

OBJLIB Card

The OBJLIB card identifies object libraries. Object libraries are partitioned data sets of assembled or compiled TARGET(TPF) programs. All programs to be loaded, with the exception of C load modules, must be in object libraries. You cannot load the control program and FACE table using the E-type loader. Library contents are maintained and updated using MVS procedures. For more information see TPF System Generation.

CPRTEMP Card

The CPRTEMP card creates temporary data sets that contain compacted program allocation table (PAT) records.

PROGTEMP Card

The CPRTEMP card creates temporary data sets that contain the program records associated with a loadset.

OUTPUT Card

The OUTPUT card identifies the output device to which offline programs and data are written.

SALTB Card

The SALTB card identifies partitioned data sets that contain the system allocator table (SALTBL). The SALTBL contains information necessary for the TPF linkage editor to resolve virtual address constants (VCONs). These VCONs can be program addresses, tape names, macro parameters, and others that are put in the SALTBL to allow relocation of resources in the online system. See System Allocator for more information on the SALTBL.

ADATAIN Card

The optional ADATAIN card identifies the partitioned data set (PDS) that contains ADATA files to be loaded with real-time programs. If the ADATAIN card is present, OLDR will attempt to find ADATA files in the data set specified by the ADATAIN card. SYSADATA files are generated by the high-level assembler (HLASM) and must be processed by the SYSADATA postprocessor (program TPFDBG) to create ADATA files before they can be loaded. When OLDR loads a basic assembly language (BAL) program, it will attempt to find an ADATA file by searching for a PDS member with a matching name. When OLDR loads an E-type load module, it will attempt to find an ADATA file for each object module linked into the load module. OLDR will ensure that the assembly date of the ADATA file matches the assembly date of the assembler language program before loading an ADATA file.

Note:
If a program was assembled more than once on a given date, it is possible for OLDR to load an incorrect ADATA file with an assembler language program. You must ensure this does not happen. Whenever an E-type program (BAL or load module) is loaded to the online system and accepted as a new base version by the E-type loader, any ADATA files associated with a previously loaded base version of that program is effectively erased. For more information, see TPF System Generation.

ADATATMP Card

The ADATATMP card specifies a temporary data set used to hold ADATA files before they are written to the output medium.

PRINTER Card

The PRINTER card produces an output listing that details all programs loaded to the storage medium. Errors that do not cause OLDR to abend are also written in this listing. Abend error messages and informational messages are sent to the operator console. For more information about error messages, see Messages (System Error and Offline) and Messages (Online).

Enter the Input Control Cards

The following control cards are presented in the order in which they should be placed in the load deck. This order is not affected by the addition of comment cards.

Comment Card

Comment cards can be placed anywhere in the load deck. Comments are identified by an asterisk (*) in card column 1.

Subsystem ID Card
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
 
SYSID=nnnn
 
nnnn = Subsystem ID

The Subsystem ID card must be the first noncomment card in the deck. It identifies the subsystem to be loaded. This ID is also the prefix of the command that activates the online segment.

Program Allocation Table Card
Program Allocation Table Card (Format 1)
 
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
 
PATVERS=vv
 
vv = version number
Program Allocation Table Card (Format 2)
 
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
 
PATVERS=TIME
Program Allocation Table Card (Format 3)
 
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
 
PATVERS=NONE

The Program Allocation Table card tells the E-type loader to compare the specified version of the offline IPAT with the specified version of the online IPAT. If they are identical, processing continues. If they are not identical (they were not created at the same time), a check is made to determine if they are compatible. They are considered compatible if new programs in the offline version replaced spare slots in the online version, obsolete programs were changed to spare slots in the offline version instead of deleting the entry in the allocator deck, and all programs appear at the same relative location in both the offline and online version. If the 2 versions are compatible, but the offline version contains newly allocated programs, the E-type loader changes the online version to contain the new programs. If the versions are not compatible, a message tells you why they are not and the load ends.

You can use this feature to replace spare PAT slots with allocation information for newly added programs.

Notes:

  1. If you do not want to change the online IPAT or check the compatibility of the online and the offline versions of the IPAT during a ZOLDR LOAD, then the Program Allocation Table card must contain NONE in columns 9-13.

  2. If you want to check that the offline PAT is identical to the online IPAT by ensuring their time stamps are identical during a ZOLDR LOAD, the Program Allocation Table card must contain TIME in columns 9-13. If the time stamps are not identical, the load ends.

System Allocator Card
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
 
SALVERS=vv
 
vv = version

The System Allocator card tells the TPF linkage editor which version of the SALTBL to use for link-editing.

Loadset Card
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
 
LOADER   LOADSET  nnnnnnnn
 
nnnnnnnn = 5 to 8-character loadset name

The Loadset card puts the Call Program cards that follow it into a group of programs called a loadset. This loadset of programs is identified by the loadset name on the Loadset card. These loadsets are used to enter programs into a running TPF system.

Note:
There can be more than one Loadset card per load deck.

Call Program Card
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
 
LOADER   CALL  PROG nnnnvv
 
 
 
Alternate Call Program Card
 
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
 
nnnnvv
 
 
nnnn = program name
vv   = version number

One or more Call Program cards must follow the Loadset card. Call Program cards tell the offline segment which programs are to be loaded to storage mediums.

Patch Cards

Any REP cards for a particular program must follow the Call Program card for that program. Columns 75-80 must match columns 1-6 of the Call Program card (or columns 21-26 if the alternate format is used). The E-type loader permits a maximum of 255 patches per program.

REP cards are not supported for C load modules.

Note:
If you include a REP card to patch a real time program that will have an ADATA file loaded, the TPF Assembler Debugger for VisualAge Client may not display an accurate listing view of the program.

Loading E-Type Programs to a Storage Medium

Figure 26. E-Type Load via E-Type Loader (Offline -- MVS)




The E-type loader offline segment runs under MVS control and places loadsets of programs (identified by the input control cards) on a storage medium. The storage medium is then loaded to the system by the ZOLDR command.

Note:
If you are writing to a virtual reader, use the ELDRVRDR EXEC to convert OLDR JOB output to a spool file that supports virtual reader input. A sample ELDRVRDR EXEC is shipped as segment UELV.

Loading and Activating a Loadset of Programs

Figure 27. E-Type Load via E-Type Loader (Online -- TPF)




If you want to replace a base version of an E-type program, change the program in main storage using the ZAPGM command or load and activate a loadset of programs. Figure 27 shows how a loadset of programs are loaded from a storage medium to the system using the ZOLDR LOAD command.

Note:
ZAPGM should not be used for major program changes because it permits you to change only 16 bytes of a program. Also, ZAPGM is not supported for C load modules. ZAPGM can be used to make an immediate change to a program that is causing system problems. In most cases, make program changes by loading and activating a loadset of programs.

See TPF Operations for more information about the ZAPGM command.

Once you have loaded an E-type loader load deck to a storage medium, load and activate the loadset of programs by doing the following:

  1. Load a loadset of programs from the storage medium to the system.
  2. Allocate programs that are unallocated (required to accept programs as base versions and to run programs with transfer vectors).
  3. Activate the loadset and test the new programs.
  4. Accept the loadset (if you want to replace the base version programs with the new versions).

Loading a Loadset of Programs

Use the ZOLDR LOAD command to load a loadset of programs. ZOLDR LOAD reads program records from an input device and writes them to 4KB fixed file records.

Note:
If you are loading from a virtual reader, make sure your OLDR job output has been converted. Use the ELDRVRDR EXEC to convert OLDR JOB output to a spool file that supports virtual reader input. A sample ELDRVRDR EXEC is shipped as segment UELV.

The names of the loaded loadsets are maintained in loadset directory (LSD) records. The names and temporary file locations of the loaded programs are maintained in E-type loader program directory (EPD) records. The versions of the loaded programs are maintained in program version records (PVRs). Loaded programs have no effect on system activity until they are activated.

Allocate Programs That are Unallocated

Programs must be allocated before they can be accepted as the base version. Programs that have transfer vectors must be base allocated or you will receive a CTL-063 condition when you try to run the transfer vector program.

Allocating new programs in an active TPF operating system can be done without an IPL by doing the following:

  1. Change the spare entries in your allocator deck to the unallocated programs you want to allocate.
  2. Run SALO with the updated allocator deck to create an updated offline allocator with a new Program Allocation Table (IPAT).
  3. Create an E-type loader load deck with the updated allocator version on the PATVERS card.
  4. Run the E-type loader offline segment to load the load deck to an intermediary device.
  5. Enter ZOLDR LOAD ddname PATU (where ddname is the data definition of the intermediary device) to update the online PAT on all processors. The previously unallocated programs are now allocated.
Note:
See System Allocator for more information about allocating programs and transfer vectors.

Activating a Loadset to Test New Programs

Use the ZOLDR ACTIVATE command to activate a loadset of programs. ZOLDR ACTIVATE causes programs in a loadset to become available for processing. You can activate a loadset of programs on one or all processors.

Selectively Activating E-Type Programs

You can control the use of E-type programs by selectively activating a loadset of programs. Use the SEL option of the ZOLDR ACTIVATE command to limit the use of new programs to specific terminals, lines, users, and others.

Note:
Use the selective activate user exits to specify the terminals, lines, users, and others that you want to allow to use a specific loadset of programs. Selective Activate Exits provides information to help you write the code needed to support the SEL option.

Using Loadsets

When using loadsets, use a ZOLDR command to do the following:

  1. Exclude a program from a loadset of programs.
  2. Reinclude a program to a loadset of programs.
  3. Display loadset information.
  4. Deactivate a loadset of E-type programs.
  5. Delete a loadset of E-type programs.
  6. Reclaim system resources.
  7. Change E-type loader program allocation characteristics.
  8. Change E-type loader values.
  9. Clear E-type loader file resident records.

You may want to use the ZDEAT command to display ECB status.

Note:
For online help, type ZOLDR ?, ZDEAT ?, or see TPF Operations for more information.

Excluding a Program from a Loadset

Use the ZOLDR EXCLUDE command to exclude a program from an existing loadset of programs. If a loadset is active, ZOLDR EXCLUDE deactivates the program on all processors. A program that is excluded from a loadset of programs will not be included in later functions performed on the loadset. For example, if you exclude the PRGM1 program from the GROUP1 loadset, PRGM1 is not activated when you activate GROUP1.

Reincluding a Program to a Loadset

Use the ZOLDR REINCLUDE command to reinclude a program to an existing loadset of programs. A program that is reincluded to a loadset of programs will be included in later functions performed on the loadset. For example, if you reinclude the program PRGM1 to loadset GROUP1 then PRGM1 (which had previously been excluded from GROUP1) is activated when you activate GROUP1.

You must deactivate an active loadset before an excluded program can be reincluded into the loadset.

Displaying Loadset Information

Use the ZOLDR DISPLAY command to display the following information:

Deactivating a Loadset of E-Type Programs

Use the ZOLDR DEACTIVATE command to deactivate a loadset of programs. ZOLDR DEACTIVATE causes all programs in a loadset to become inactive when they finish processing. When all programs in a loadset are deactivated, previously active versions of the programs are used by new entries.

Note:
The FORCE option processes before any previously scheduled ZOLDR tasks. It should only be used if ZOLDR DEACTIVATE processing ends with an error. The FORCE option can change the version of a program that is currently in use by an entry. This could cause interface problems.

Deleting a Loadset of E-Type Programs

Use the ZOLDR DELETE command to delete a loadset of programs. ZOLDR DELETE causes all of the fixed file records associated with a loadset of programs to be returned to the pool of available fixed file records. ZOLDR DELETE cannot delete an active loadset until it has been deactivated.

If a program in the loadset is still active, the system changes the loadset name to -nnnn (where nnnn is 0000-9999) and marks it as delete pending. The system deletes the renamed loadset when all ECBs using the loadset are finished.

Reclaiming System Resources

Use the ZOLDR RECLAIM command to make inaccessible fixed file records available to the system.

If an E-type loader action is interrupted by a system error, some fixed file records may not be able to be accessed by the system. Although the information in the records is still available elsewhere, the original fixed file record may not be accessible. If the fixed file record is not accessible, the system cannot use that disk space. Therefore, you must enter ZOLDR RECLAIM to allow the system to be able to use that disk space again.

Note:
Your site's procedures will determine how you use the ZOLDR RECLAIM command. You may want to enter ZOLDR RECLAIM after any E-type loader RESTART, or you may want to enter ZOLDR RECLAIM every night to reclaim inaccessible disk space.

Changing E-Type Loader Program Allocation Characteristics

Use the ZOLDR ALTER PROGCHAR command to alter the allocation characteristics of unallocated E-type programs.

Changing E-Type Loader Threshold Values

Use the ZOLDR ALTER command to alter the following E-type loader threshold values:

Clearing E-Type Loader File Resident Records

Use the ZOLDR CLEAR command to clear and initialize all file resident records the first time the system is IPLed or if E-type loader records are damaged.

Displaying ECB Status

Use the ZDEAT commands to see the number of ECBs using each activation number and if the activation number corresponds to a selectively activated loadset.

Accepting a Loadset of E-Type Programs

Before Accepting a Loadset

Issue the ZOLDR ACCEPT command only if you are satisfied that the programs in the loadset work correctly and you want them online. If you are still testing the loadset of programs, you likely want to keep them activated only.

ZOLDR ACCEPT permanently replaces the base versions of the programs with an active loadset of programs. If you make a mistake, reload the base versions of programs, activate them, and accept them to correct your mistake.

Unallocated programs must first be allocated before you can accept them.

Use the ZOLDR ACCEPT command to accept a loadset of programs. ZOLDR ACCEPT causes the active loadset of programs to overlay existing programs at base allocated addresses. The fixed file records associated with an accepted loadset of programs are deleted after you perform the accept.

Notes:

  1. The loadset must be activated on all processors to be accepted.

  2. A new program will not be accepted if there is an ECB on any subsystem that can still use the base version program.

  3. If active loadsets intersect, you must accept them in the order they were activated. That is, the first activated loadset will be the first accepted loadset.

  4. Use the ZOLDR DISPLAY command before accepting a loadset of programs to make sure that you are accepting the correct version of a program.

Using E-Type Loader Functions

E-type loader functions affect only the program base that is being used on the processor from which the function was requested. If other processors are using a different program base, those processors do not see the effects of E-type loader functions until they begin using the same program base.

For example, in a loosely coupled environment where processor A is using program base 1 and processor B is using program base 2, if you issue the ZOLDR ACTIVATE command on processor A, the specified loadset is started on all processors using program base 1. Because processor B is using program base 2, the specified loadset is not actually activated on that processor until you perform an initial program load (IPL) using program base 1.