gtpm1m12TPF V4R1 Migration Guide: 3.1 to 4.1

File Address Compute Program (FACE) Table Generation and System Initialization Program

Before this release, the file address compute program (FACE) table (FCTB) was generated as part of the system initialization program (SIP). RAMFIL macros were coded in SIP Stage I to specify the characteristics of different record types, and the FACEA and FACEC macros were processed during SIP Stage II to define FACE table items and build the table.

In the TPF 4.1 system, FACE table generation is handled separately from SIP Stage I by a new offline FACE table generator program called FCTBG.

While SIP uses macros for input, FCTBG uses statements. The CONFIG, ONLFIL, SSDEF, and RAM macros in the TPF 3.1 system are now both macros (when they provide input to SIP Stage I) and statements (when they provide input to FCTBG). Because RAMFIL is processed by FCTBG, it is considered a statement instead of a macro. A new statement called UFTFTI is used to specify universal format type (UFT) values and corresponding format type indicator (FTI) sizes.

Once you have run FCTBG, you can run SIP Stage I or complete the process manually. See Generating the File Address Compute Program (FACE) Table for more information.

See TPF System Generation for more information about the FACE table generator program (FCTBG) and system initialization.

System Installation Program (SIP) Changes

A summary of all new, changed, or obsolete system installation program (SIP) macros is contained in SIP Macros and Statements. New and obsolete parameters are listed in Table 3.

In the TPF 4.1 system, there is a distinction between the term macro and statement, depending on whether the information is interpreted by the assembler, the file address compute program (FACE) table generator (FCTBG), or both. For example, in the TPF 4.1 system, the ONLFIL macro is interpreted as both a macro and a statement. The RAMFIL and UFTFTI statements are interpreted only by the FCTBG offline program.

Defining the Database

The TPF 4.1 system makes substantial changes to addressing records in the database with the advent of File Address Reference Format 4 (FARF4) and File Address Reference Format 5 (FARF5). If you are not migrating immediately to FARF4 or FARF5 addressing, you still must regenerate the FACE table. The database is defined by coding RAMFIL statements for all the records in it, including the restart area and keypoints, and creating a FACE table using these statements.

If you anticipate migrating to FARF4 or FARF5 addressing, the UFTFTI macro must be coded. The UFTFTI macro defines areas of the database in terms of FARF4 or FARF5 addresses. See Expanded File Addressing Capacity and File Address Reference Format for more information about FARF4 and FARF5. Also see the TPF Database Reference for more information about database organization and FARF.

Parameters on the UFTFTI Statement

There are four parameters on the UFTFTI statement.

MODE
Specifies the default address dispense mode (FARF3, FARF4, or FARF5).

STAGE
Defines the migration stage (file address reference format 3 (FARF3) and FARF4, or FARF4 and FARF5).

UFACDATA
Defines the external name of a user data area that is attached to the FACE table (FCTB) at the FCTB level.

UFTI
Defines valid universal file types (UFT) and associated format type lengths for the FARF4 and FARF5 definitions of the database.

Universal File Types (UFT) and Format Type Lengths

The universal file types and format type lengths consist of 64 universal format types (6-bit UFTs) and format indicators (FTIs) up to 25-bits long. Taken together, a given UFT and FTI specify a particular record type. Adding an ordinal number to a UFT/FTI combination specifies an individual record within the record type. At least one bit is used for record type ordinal, so there are at least two ordinals in a record type. Likewise, at least one bit is required for FTIs, so there are at least two record types for any UFT.

All UFTs are essentially equivalent. There are no performance characteristics associated with them. Record type management schemes can help coordinate the uses of various kinds of records. Such schemes are based partly on the number of record types and ordinals required. When only a few record types are required, a smaller FTI can be chosen, one with fewer bits. When a large number of record types is required, a larger FTI provides a larger number of record types. For example, one UFT may specify FTIs being expressed with 3 bits while another UFT may specify FTIs being expressed with 21 bits.

The newer dispensing modes (FARF4 or FARF5) have an effect on the UFT/FTI combinations defined for record types, because FARF4 reserves 2 bits for migration and identification that are used by FARF5 for ordinal numbers. When a FARF4 record type is migrated to FARF5, the number of addressable ordinals is increased four times.

One possible record management scheme is to put the FARF4 record types in the lower half of the UFTs (up to UFT 31) and the FARF5 record types in the upper half of the UFTs (from UFT 32 to UFT 64). Another scheme is to put the FARF4 record types in the even-numbered UFTs and the FARF5 record types in the odd-numbered UFTs.

When records are specified in a RAMFIL statement, the dispensing mode (FARF4 or FARF5) to use for them is also defined. When a record is dispensed to an online program, the existing dispensing mode is interrogated as well as the defined dispensing modes for the record. This selects a certain UFT/FTI pair. The UFT/FTI information is used in the FACE table to retain the actual record address dispensed for future use. Among other things, the FACE table contains information showing how to interpret a specific address.

Defining UFT/FTI pairs for a database is a critical activity. Much thought must be given to their coding because the future usability of the database depends on how these pairs are defined.

See Migrating File Addresses for more information about the UFT.

Defining Record Types for Capture and Restore

In order to use Capture and Restore in the TPF 4.1 system, you must do the following:

See the TPF Database Reference for more information about Capture and Restore.

Defining Record Types for Multiple TPF Images

The following new record types are required for multiple TPF images.

Record Type
Description

 #IPL1 
Initial program load (IPL) area for the primary image

 #PROG1 
E-type program base for the primary image

 #CIMR1 
Core image restart area for the primary image

 #CTKX 
Image-unique image pointer records

 #KSA1 
Keypoint staging area for the primary image

 #KBA 
Keypoint backup area for the primary image.

The Image History Record (IHR) in record type #IBMM4 is also required. This record type contains image information for each of the IPL areas and the CIMR components.

These record types are required for the primary image, regardless of whether you use multiple TPF images. If you plan to define more than one image, you must ensure that program records are not used as shared read/write data records.

In the TPF 3.1 system, SIP generated #RSTRI record types for the restart area. In the TPF 4.1 system, you must define #CIMRx record types for each image.

Defining Record Types for the E-Type Loader

E-type loader fixed file (#OLDx) records are required for the E-type loader. This record type contains all the fixed file records necessary for the E-type loader. It contains an ordinal number for each of the structures (LSD, ERD, ERT, and so on). In addition, the #OLDx record type contains a pool of ordinals that are used to store the programs that are loaded through the E-type loader and build additional E-type structures, such as EPDs. The number of ordinals defined for this record type determines how many programs can be loaded through the E-type loader.

The #OLDx record type is not required for the TPF 4.1 system, but if it is not defined, the E-type loader cannot be used.

Note:
The #OLDx record type is program base unique.

Allocating the #OLDx Records

In general, you need to allocate enough #OLDx records to satisfy the following equation:

Figure 1. Allocating #OLDx Records

Total number of records required =    (maximum number of loadsets
online in the subsystem *      average number of programs in each loadset)
* 1.1

The 1.1 factor will take into account EPDs, LSDs, and records that are required and reserved for the E-type loader.

If you want to determine the minimum number of records necessary for the #OLDx record type, you need to consider the # value of MAX_NUM_ACTIVE_LOADSETS. Because of the design of the WRT and the ELT, you are advised to allocate enough records in the #OLDx record type so as to have at least 200 available fixed file records for each processor generated in the complex. Use the following calculation to do so:

Figure 2. Calculation for Allocating #OLDx Records

Minimum number of #OLDx records required =      35
(reserved)  + (  32  *MAX_NUM_ACTIVE_LOADSETS / NUMBER ENTRIES PER ECR)
 (****)    (IBM default = 1000)  (See c$idsecr.h)  + (# CPUs genned * 200)
  (recommended number of available records)

In the previous calculation, **** is the maximum number of processors supported by the E-type loader. This value must always be 32.

The following is the RIAT definition for the #OLDx record types:

Figure 3. RIAT Definition for #OLDx Record Types

RIATA  ID=00E0,     /* record ID  */        LOG=NO,      /* #OLDx
is not to be logged  */        XCP=NO,      /* #OLDx is not to be exception
recorded  */        UEXIT=NO,    /* A user exit will not be defined for special
 */                     /* processing  */        VFAF=NO,     /* #OLDx is
not a VFA candidate  */        LOCKF=DASD,  /* the lock is maintained by the
DASD ELLF control unit    */        RCSF=RET,    /* retentive access --
#OLDx records are placed on    */                     /* the DASD surface &
cache when a file-type  */                     /* macro is issued.  */
    RESTORE=NO,  /* #OLDx is not to be restored  */

Defining Record Types for Program Version Information

Program version (#PVRx) records are used by the E-type loader (OLDR), auxiliary loader (TLDR), and general file loader (ALDR). These records contain program information such as the version code and assembly date. There is an entry in the #PVRx record type for each allocated program. Therefore, the number of ordinal numbers that need to be defined can be determined based on the:

The #PVRx record type is not required. If you do not define any version code records there will be no support for version codes or assembly date.

Note:
Like the #OLDx and #PROGx record types, the #PVRx record type is also program-base unique.

The following is the RIAT definition for the #PVRx record types:

Figure 4. RIAT Definition for #PVRx Record Types

RIATA  ID=FF0E,     /* record ID  */        LOG=NO,      /* #PVRx
is not to be logged  */        XCP=NO,      /* #PVRx is not to be exception
recorded  */        UEXIT=NO,    /* A user exit will not be defined for special
 */                     /* processing  */        VFAF=NO,     /* #PVRx is
not a VFA candidate  */        LOCKF=DASD,  /* if the lock is maintained by
the DASD ELLF control unit  */        RCSF=RET,    /* retentive access --
#PVRx records are placed on  */                     /* the DASD surface &
cache when a file-type  */                     /* macro is issued.  */
    RESTORE=NO   /*  #PVRx is not to be restored  */

Defining the New Record ID for the TPF Application Requester (TPFAR) Feature

Define the new record ID X'FF0F' to the system using the RIATA macro. The record IDs go into RIAT. The parameters you need to code are:

RIATA ID=X'FF0F'

RTP0=(4,ST,R)

VFAP=DELAY

Note:
Although the VFAP parameter has three options, it is recommended that you code VFAP=DELAY for performance reasons.

Generating the File Address Compute Program (FACE) Table

The file address compute program (FACE) table was changed to support the increased addressing capacity provided by the File Address Reference Format 5 (FARF5). Beginning with this release, the FACE table is generated by the FCTBG offline program.

The FCTBG offline program uses the ONLFIL, SSDEF, CONFIG, RAM, RAMFIL, and UFTFTI statements from the SIP Stage I deck as input. FCTBG generates the FACE table, the DASD format deck, CYMZ and OPMxxx tables in SYCON, most of SYSEQC and STCEQ, FMTRx, and a macro called SYFCTB, which is needed by SIP Stage 1 for validation.

The FCTBG offline program produces the FACE table in the form of an IBM Multiple Virtual Storage (MVS) object module. Use the IBM MVS linkage editor to convert this object module to an IBM MVS load module, which can then be loaded by the TPF 4.1 system. Use the IBM MVS linkage editor (LEDT) to attach CONK, CTSD, and

user data to the FACE table.

You must build a new FACE table for the TPF 4.1 system. See TPF System Generation for a summary of the record types that are checked by the FACE table generator program (FCTBG).

To Build a New FACE Table

  1. Code RAMFIL statements for all new and changed record types.
  2. Code a UFTFTI statement and UFTIx parameters on RAMFIL statements (optional).
  3. Run the FCTBG offline program.
  4. Complete the process by doing a full SIP (Stage 1 and II). Assemblies of parts of SIP may be attempted, however, this is not recommended. See TPF System Generation for more information about rebuilding the FACE table.
  5. Load the FCTB module.

Allocating Globals

In the TPF 4.1 system, I-stream shared globals and one copy of I-stream unique globals are under 16 MB. See Figure 5 for more information. Real storage in high memory is reserved for copies of the application program I-stream unique globals. The main I-stream's view of storage (VM) is essentially identical to real memory. Global directories for both I-stream unique and and I-stream shared globals reside in the I-stream unique global areas.

Each application program I-stream sees its own I-stream unique globals under 16 MB, even though these globals actually reside in high real memory. For this reason, application programs dispatched on any I-stream can access all the shared and unique globals they need using 24-bit addresses.

The size of the different global areas is specified during the system initialization program (SIP) on the GLOBAL macro.

There are four new parameters.

SSUISHRx
Specifies the number of 4 KB blocks required to contain the I-stream shared primary globals. This parameter is optional and may be coded with a value of 0.

SSUIUNQx
Specifies the number of 4 KB blocks required to contain the I-stream unique primary globals.

SSUXSHRx
Specifies the number of 4 KB blocks required to contain the I-stream shared extended globals.

SSUXUNQx
Specifies the number of 4 KB blocks required to contain the I-stream unique extended globals.

The global areas and the parameters that correspond to them are shown in Figure 5. Although the layout for extended globals in the TPF 4.1 system is the same as it was in the TPF 3.1 system, you must completely regenerate globals for the new layout of the primary global areas.

Figure 5. Location of Global Areas in a Multiprocessing Environment with Three I-Streams. This figure shows the use of SIP GLOBAL macro parameters.