gtpm1m2cTPF V4R1 Migration Guide: 3.1 to 4.1

Expanded File Addressing Capacity and File Address Reference Format

Before this release, file address reference format 3 (FARF3) was the only file address format supported by the TPF system. This limited the address capacity of a TPF system to a maximum of 256 million fixed records and 384 million pool records. Pool addresses were, by definition, divided between long term and short term, duplicated and nonduplicated, and small or not small. The lack of addressing capacity prevented you from addressing the maximum number of DASD that could be attached to a TPF subsystem.

The TPF 4.1 system supports two new address formats:

FARF3 addresses, of course, are still supported and have not changed. In FARF3, only 27 or 28 bits are available for addresses. FARF3 addresses are recognized by the 1 in the 31st bit (bit 30). Figure 8 shows the FARF3 address format.

Figure 8. File Address Reference Format 3 (FARF3)




In the TPF 4.1 system, FARF4 and FARF5 have the following characteristics:

Migrating File Addresses

There are three major steps for migrating your file addresses from FARF3 to FARF5.

  1. All your file addresses must be in File Address Reference Format 3 (FARF3).
  2. Migrating from FARF3 to FARF4.

    When you migrate to FARF4 addresses, your file addressing capacity increases from approximately 640 million to 1 billion addresses (1G equals 230 or 1,073,741,824). When you migrate to FARF5 addresses, your file addressing capacity increases to 4G. FARF4 addresses are an intermediate step between the FARF3 and FARF5 addresses. FARF3 and FARF4 addresses can coexist, and FARF4 and FARF5 addresses can coexist. However, FARF3 addresses and FARF5 addresses cannot coexist. FARF4 addresses can be thought of as a migration path; migrating from FARF3 to FARF4 addressing, then from FARF4 to FARF5 addressing. FARF5 addresses can only enter the TPF 4.1 system when no more FARF3 addresses exist in the database.

    The DUMPALTMODE parameter of the RAMFIL statement is provided as an aid to record migration. A SNAP dump (SNAPC macro) is taken to those records that are not in the address dispensing mode specified by the ZMODE command. The dump switches are manipulated by using the ZDECD command.

    See Migrating from FARF3 to FARF4 for more information.

  3. Migrating from FARF4 to FARF5.

    In the FARF4 to FARF5 migration stage, FARF4 and FARF5 addresses can coexist. FARF4 addresses are distinguished from FARF5 addresses in the UFT/FTI conversion table. Because FARF3 and FARF5 addresses are indistinguishable, they cannot be in the TPF 4.1 system at the same time. You must migrate completely to FARF4 before you can begin migration to FARF5.

    See Migrating from FARF4 to FARF5 for more information.

Note:
The migration stage determines which addresses can coexist in the database. In the FARF3 to FARF4 migration stage, FARF3 and FARF4 addresses can coexist. At this migration stage you can distinguish FARF4 addresses from FARF3 addresses by the 0 in the 31st bit (bit 30).

The Structure of FARF4 and FARF5

FARF4 and FARF5 are similarly structured using universal format types (UFT) and format type indicators (FTI). The UFT can range from 0 to 63. The UFT defines the size of the FTI, which in turn limits the size of the record ordinal numbers. If there are a large number of FTIs for a particular UFT, there is a correspondingly small number of record ordinals that can fit into each of those FTIs. When you code RAMFIL statements, you specify UFT/FTI combinations using the new UFTI4 and UFTI5 parameters for the records. One suggestion is to specify both FARF4 and FARF5 UFT/FTI combinations for the records, along with the existing FARF3 specifications. Another suggestion is to use UFTs 0 through 31 for pool addresses and 32 through 63 for fixed file addresses. The high-order bit is on for FARF3 pool addresses. This makes visible high-order bit testing that is not valid and must be eliminated when using FARF4 or FARF5 addresses.

Overall, the UFT/FTI design consists of one UFT conversion table with up to 64 entries. Each of these entries points to an FTI conversion table of variable size. Each FTI table is at least two entries long (because 1 bit is the smallest FTI length possible). Each FTI table entry provides a pointer to the appropriate FACE table entry (split). This FACE entry, combined with the record ordinal, yields the actual address of the record.

FARF4 address format is a restricted version of the more general FARF5 format. Figure 9 shows the FARF4 address format.

Figure 9. File Address Reference Format 4 (FARF4)




The FARF5 format is very similar to FARF4, except that the last 2 bits are available for the ordinal number. Figure 10 shows the FARF5 address format.

Figure 10. File Address Reference Format 5 (FARF5)




When UFT/FTI has FARF4 designators set up and UFTI4 definitions are added to the RAMFIL statements, a migration FACE table can be generated containing both FARF3 and FARF4 addresses.

The FACE table is built to reflect this stage. Addresses are dispensed initially in FARF3 format. When you are ready, you can dispense addresses in FARF4 format. You change address dispensing online by issuing the ZMODE command. This command specifies the preferred dispensing mode. If a record is not defined in the preferred mode, it is dispensed when requested in its defined mode.

In the FARF4 to FARF5 migration stage, addresses are dispensed initially in FARF4 format. When you are ready, you can begin dispensing addresses in FARF5 format by using the ZMODE command.

When you migrate to the TPF 4.1 system and build your new FACE table, you will be in FARF3 to FARF4 mode, with only FARF3 addresses. You can convert these addresses to the FARF4 format gradually by changing the dispense mode to FARF4 and coding UFTI4 on the corresponding RAMFIL statements. Preferred dispensing eases the transition by moving the database addresses to the next format as the database itself changes. Once you have converted all your FARF3 addresses to FARF4, you begin to migrate to the next addressing format by coding STAGE=FARF45 on the UFTFTI macro. Assuming UFTI5 combinations are coded on the RAMFIL statements generating a new FACE table based on them results in a FACE table supporting FARF4 and FARF5 addresses. When all your addresses are in FARF5 format, you achieve maximum addressing capacity.

Whether you are migrating from FARF3 to FARF4 or FARF4 to FARF5, you can have some record types that are defined in only one of the two supported address formats, and others that are defined in both. The value you coded on the MODE parameter of the UFT/FTI statement determines which mode addresses are dispensed for that record type, unless overridden by the ZMODE command. If your record type is defined in both supported address formats, addresses will be dispensed in the currently specified dispensing mode (preferred mode). If your record type is defined in only one of the supported address formats, and this is not the current dispense mode, it will be dispensed in the mode in which it is defined.

If there are no imbedded FARF3 addresses in the database, the database can be immediately migrated from FARF3 to FARF5 (without passing through FARF4). This is done by following the same procedures suggested for migration from FARF4 to FARF5.

Database Reorganization Considerations

Imbedded file addresses present a difficult database reorganization problem. With FARF3 addresses, the primary concern is with keeping the band number and pool PSONS consistent. With FARF4 and FARF5 address, the UFT/FTI combination of the fixed file and pool record structure must be kept consistent.

Migrating from FARF3 to FARF4

This section discusses migrating from FARF3 to FARF4. During this migration, keep the following in mind:

To Migrate from FARF3 to FARF4

  1. Your entire database must be in FARF3 format.
  2. You must remove all dependencies on specific file address formats in both your application programs and system code.

    To remove these dependencies, use the SONIC macro to determine address format, rather than testing control bits. The new ESFAC macro provides the extended feature of the SONIC macro. The address format interrogation portion of the SONIC macro was implemented in IBM C language support as well.

  3. Code UFTFTI statements to structure the addressing for your database.
  4. Code RAMFIL statements with the new UFTI4 and UFTI5 parameters. When you code your FARF4 RAMFILs, you should also code FARF5 RAMFILs so the system can determine there is enough addressing capacity to migrate to FARF5. The FARF5 combinations are not used to generate addresses in the FARF3 to FARF4 migration stage. The FARF3 information is not used in the FARF4 to FARF5 migration stage.
  5. Run the FCTBG offline program to generate a new FACE table for the FARF3 to FARF4 migration stage.
  6. Load the new FACE table and the TPF 4.1 code.
  7. Reload CTHx segments because they contain embedded FARF addresses.
  8. Allow embedded FARF3 addresses to age out or write a conversion tool to change them to FARF4 addresses.
  9. Use the ZDECD command or the DUMPALTMODE parameter on the RAMFIL statement to flag any old FARF3 addresses. See Making Sure All FARFx Records Are Removed for more information.

Migrating from FARF4 to FARF5

This section discusses migrating from FARF4 to FARF5. You can use the new ZMODE command to display the current FARF dispense mode or change the dispensing mode. For example, enter the ZMODE D command to display the current dispensing mode; enter the ZMODE 4 command to set the current dispensing mode to FARF4.

To Migrate from FARF4 to FARF5

  1. Ensure that all FARF3 addresses are removed from the TPF 4.1 system.
  2. Specify STAGE=FARF45 and MODE=FARF5 on the UFT/FTI statement.
  3. Code records with FARF5 indicators (UFTI5) in their RAMFIL statements.
  4. Rebuild and reload the FACE table, COHx segments, and any other table that contains embedded FARF addresses.
  5. When all FARF4 addresses are gone, regenerate and load a FACE table that only has UFTI5 specified on the RAMFIL statements.
  6. Reinitialize the ZPTCH root file, which is located in the #IBMMS fixed file record, to rebuild the FARF4 addresses by entering ZAREC LIBMMS.17 00 00000000.

    See the SYSEQ label for the appropriate ordinal numbers. See TPF Operations for more information about the ZAREC command.

  7. Verify that the fixed file records containing imbedded file addresses do not have FARF3 addresses.

Making Sure All FARFx Records Are Removed

When in FARFn preferred mode request that records accessed by FARFn-1 addresses have a SNAP dump taken. This makes the record visible where it can be converted manually, if necessary. This is done by coding the DUMPALTMODE parameter on the RAMFIL statement for the record. When a record in an addressing format different from the current dispensing mode is decoded, the program issuing the decode is displayed in a SNAPC dump. Once this record is identified, the dump can be suppressed prior to changing the record to the current dispensing mode. The ZDECD command is used to

alter the record attributes and suppress the dump.

The SNAPC dump (SNAP 1CA) for a record in the alternate file format contains the registers active at the time and the input/output block (IOB). The IOB supplies the file address of the record. By decoding this file address you can identify the alternate mode record and the program issuing the decode request. For FARF3 records, either the band number for a fixed file record or the ordinal of a pool record leads to the record type in the RAMFIL definition of the database. For FARF4 or FARF5, the file address is decoded into the corresponding UFT/FTI combination. You can identify the record by scanning the RAMFIL definition using this combination.

Selected activation of the DUMPALTMODE parameter on portions of the database is suggested. This approach will isolate the SNAPC dumps to certain parts of the database and will minimize the amount of effort required to suppress the dumps (enter the ZDECD command to do so) once the records are identified.