gtpm2m0lMigration Guide: Program Update Tapes

Pool Expansion (PXP) Support (APAR PJ17912)

The following section discusses the migration considerations for pool expansion (PXP) support (referred to as new pool support from this point forward).

Prerequisite APARs

See the APEDIT for APAR PJ17912 for information about prerequisite APARs.

Functional Overview

In the TPF 4.1 system today, the system is limited to 64-K file pool directories (where 64-K equals 65 536, which is the largest number that can be represented by a halfword field). With the new pool support you can:

Changes to the Pool Maintenance Package

Changes have been made to the following areas of the pool maintenance package for the new pool support:

A discussion about these changes follows.

Halfword Directory Ordinals

The following changes have been made:

Functions that Access Halfword Fields

You must modify any user-defined functions that access a halfword directory field to access a 3 or 4 byte field.

Offline Pool Maintenance Program (DYOPM)

To support such a large number of file pool directories, the offline pool maintenance program (DYOPM) has been enhanced to use storage above 16 MB under the IBM Multiple Virtual Storage (IBM MVS) system. DYOPM is a program that runs under the IBM MVS system and contains those parts of the pool maintenance package that do not require direct access to the online directory records. DYOPM interfaces with the following programs through the pool maintenance general file (DGF):

Critical Information for Using DYOPM

  • The TPF 4.1 system only uses the new version of DYOPM after converting to the new keypoint 9 (CKT9) format included with the new pool support.
  • The existing version of DYOPM can only be used on an unmigrated processor.
  • DYOPM cannot be run on a migrated processor in a complex that has not been converted.

See Pool Conversion for more information about pool conversion.

See TPF Database Reference for more information about DYOPM and the pool maintenance package.

Keypoint Retrieval and Filing

The following changes have been made:

Utilities and Functions Accessing Keypoint 9 (CTK9)

If you have any user-defined utilities or functions accessing keypoint 9 (CTK9) or the CY$CR header record, you must modify those utilities or functions to use the following functions:

Once you make these modifications, you must put the changed segments in the same image as the new pool support. By doing so, you can take full advantage of the migration path provided by IBM to convert your complex to the new pool support.

Pool Conversion

To use the new pool support, you must convert your complex in 2 stages.

Critical Information for Using DYOPM

At this point you must use the new version of DYOPM because keypoint 9 (CTK9) has been converted to the new format.

See TPF Operations for more information about the ZPMIG and ZDFPC commands.

See Migration Scenarios for more information about the migration scenarios to consider when converting your complex to the new pool support.

Terminology Recap

The following terminology has been introduced in this section.

Term
Definition

Pool migration
To IPL a processor on an image that contains the new pool support. The new pool format will be used in core (main storage). The pool format previously defined in your complex remains on file in DASD until pool conversion is completed across the complex. Contrast with pool conversion.

Pool conversion
In pool file support, to convert the pool data structures from the pool format currently defined in your complex to the new pool format provided by the new pool support. When pool conversion is completed, the new pool data structures reside both in core (main storage) on each migrated processor and on file in DASD. Contrast with pool migration and pool conversion fallback. See Pool Conversion Fallback for a definition of pool conversion fallback.

Migration Tools

The new pool support takes advantage of the TPF 4.1 system multiple TPF images functions to perform the pool migration. Any processors running in an unmigrated state can remain active and online without interruption during pool migration. Unmigrated state refers to a processor that has not been migrated to the new pool support.

Accessing keypoint 9 (CTK9) is unchanged and continues to be the serialization point for pool maintenance functions.

The new pool support allows a complex of 2 or more processors to coexist indefinitely, as long as the limits of the pool format currently defined in your complex are not exceeded. Coexistence can include a mix of processors--those migrated to the new pool support and those without the new support.

The pool data structures used by unmigrated processors must be kept current by those processors that are already migrated so that the 2 levels of support can coexist. In addition, no changes were made to the supporting code in the unmigrated processor, which means the new pool data structures are not updated by any processors that have not been migrated yet. Rather, both levels of pool data structures are updated by processors that have not been migrated with the migration tool provided by the TPF 4.1 system.

Terminology Recap

The following terminology has been introduced in this section.

Term
Definition

Unmigrated state
In pool file support, refers to a processor that is not IPLed on an image that contains the new pool support. See also pool migration and pool conversion. See Pool Conversion for definitions of these terms.

Pool Conversion Fallback

Pool conversion fallback enables you to return the new pool format provided by new pool support back to the pool format previously defined in your complex once you have completed pool conversion. See Pool Conversion for more information about pool conversion.

You will use the ZPMIG command with the FALLBACK parameter specified to perform pool conversion fallback. See TPF Operations for more information about the ZPMIG command and restrictions associated with pool conversion fallback.

See Pool Conversion Fallback Scenarios for more information about fallback scenarios to consider when performing pool conversion fallback.

Terminology Recap

The following terminology has been introduced in this section.

Term
Definition

Pool conversion fallback
In pool file support, to return the new pool format provided by the new pool support back to the pool format previously defined in your complex. In core (main storage) the new pool format exists, while the pool format previously defined in your complex remains on file in DASD. All processors have been returned to a migrated state; the complex is not converted. See also pool conversion and pool migration in Pool Conversion and Migration Tools for definitions of these terms.

Architecture

The new pool support expands the ordinal fields to 3-byte ordinals. This expansion increases the CY2KT data macro. To keep the size of keypoint 9 (CTK9) within 4K, each set size array in CTK9 is halved. Currently, the set size arrays contain elements of 2 bytes each. The maximum set size array allowed is 255, which is represented by 1 byte. By reducing the set size array element size to 1 byte, space becomes available to expand the ordinal fields in the CY2KT data macro.

By retaining data in keypoint 9 (CTK9), all functions that need the data can use the same access methods as today. A processor running with the new pool support will have a different relative offset to the data in CTK9 as opposed to a processor running without the new pool support.

In addition, any other pool data structures that contain a CY2KT data macro are impacted in the following areas:

A discussion about these impacts follows.

New Record Structures

The following section discusses the new record structures:

New Functions

The following functions were added to present the pool data structures in a way acceptable to processors running with the new pool support:

Operating Environment Requirements and Planning Information

There are none.

Interface Changes

The following section summarizes interface changes.

C/C++ Language

There are no changes.

Configuration Constant (CONKC) Tags

There are no changes.

Control Program Interface (CINFC) Tags

There are no changes.

Copy Members

There are no changes.

Fixed File Records

There are no changes.

Macros

The following section summarizes the macro changes. This information is presented in alphabetic order by the type of macro.

Advanced Program-to-Program Communications (APPC) Macros

There are no changes.

Communication Macros and Statements

There are no changes.

Data Macros

Table 34 summarizes the data macro changes. This information is presented in alphabetic order by the name of the data macro.

Table 34. Changes to Data Macros for the New Pool Support

Data Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs Using This Data Macro?
CY1KR Changed Yes
CY2KT Changed Yes
CY9KP Changed Yes
CY$CR Changed Yes
ICYCWB Changed Yes
IDR0CB Changed Yes
IRECBK Changed Yes

General Macros

Table 35 summarizes the general macro changes. This information is presented in alphabetic order by the name of the general macro. See TPF General Macros for a complete description of all general macros.

Table 35. Changes to General Macros for New Pool Support

General Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs?
GENMSG Changed No

Selected Equate Macros

There are no changes.

Structured Programming Macros (SPMs)

There are no changes.

System Initialization Program (SIP) Skeleton and Internal Macros (Inner Macros)

There are no changes.

System Initialization Program (SIP) Stage I Macros and Statements

Table 36 summarizes system initialization program (SIP) Stage I macro and statement changes. This information is presented in alphabetic order by the name of the SIP Stage I macro. See TPF System Generation for a complete description of the SIP Stage I macros. If the SIP Stage I macro is changed, you must run the appropriate job control language (JCL) jobs from the SIP Stage II deck.

See System Initialization Program (SIP) and System Generation Changes for a description of other system generation changes you must make for the new pool support.

Table 36. Changes to SIP Stage I Macros and Statements for the New Pool Support

SIP Stage I Macro New, Changed, or No Longer Supported?
GENSIP Changed
IBMPAL Changed
SPPGML Changed

System Initialization Program (SIP) Stage II Macros

There are no changes.

System Communication Keypoint (SCK) Generation Macros

There are no changes.

System Macros

There are no changes.

System Macros (IBM Use Only)

There are no changes.

Segments

Table 37 summarizes segment changes. This information is presented in alphabetic order by the name of the segment.

Table 37. Changes to Segments for the New Pool Support

Segment Type New, Changed, or No Longer Supported? Description of Change
BDBP Online Assembler Changed Updated to support the new pool support.
BRPB Online Assembler Changed Updated to support the new pool support.
BRYA Online Assembler Changed Updated to support the new pool support.
BRYE Online Assembler Changed Updated to support the new pool support.
BRYQ Online Assembler Changed Updated to support the new pool support.
BRYU Online Assembler Changed Updated to support the new pool support.
CTIN Copy Segment Changed Updated to support the new pool support.
CT01 Copy Segment Changed Updated to support the new pool support.
CT10 Copy Segment Changed Updated to support the new pool support.
CT55 Copy Segment Changed Updated to support the new pool support.
CVAB Online Assembler Changed Updated to support the new pool support.
CYAR Online Assembler Changed Updated to support the new pool support.
CYA1 Online Assembler Changed Updated to support the new pool support.
CYA2 Online Assembler Changed This segment finds and files the STCCR records. With the new pool support, the find and file functions have been moved into the following functions:
  • REARRANGE_CTK9 (CYH0)
  • DEARRANGE_CTK9 (CYH1)
  • GET_CY$CR (CYH2)
  • FILE_CY$CR (CYH3).
CYA3 Online Assembler Changed Updated to support the new pool support.
CYA4 Online Assembler Changed Updated to support the new pool support.
CYC0 Online Assembler Changed Updated to support the new pool support.
CYC1 Online Assembler Changed This segment finds and files the STCCR records. With the new pool support, the find and file functions have been moved into the following functions:
  • REARRANGE_CTK9 (CYH0)
  • DEARRANGE_CTK9 (CYH1)
  • GET_CY$CR (CYH2)
  • FILE_CY$CR (CYH3).
CYC2 Online Assembler Changed Updated to support the new pool support.
CYC6 Online Assembler Changed This segment finds and files the STCCR records. With the new pool support, the find and file functions have been moved into the following functions:
  • REARRANGE_CTK9 (CYH0)
  • DEARRANGE_CTK9 (CYH1)
  • GET_CY$CR (CYH2)
  • FILE_CY$CR (CYH3).
CYD4 Online Assembler Changed This segment finds and files the STCCR records. With the new pool support, the find and file functions have been moved into the following functions:
  • REARRANGE_CTK9 (CYH0)
  • DEARRANGE_CTK9 (CYH1)
  • GET_CY$CR (CYH2)
  • FILE_CY$CR (CYH3).
CYE2 Online Assembler Changed Updated to support the new pool support.
CYF8 Online Assembler Changed Updated to support the new pool support.
CYF9 Online Assembler Changed Updated to support the new pool support.
CYH0 ECB-Controlled Assembler Language New Added to support the new pool support.
CYH1 ECB-Controlled Assembler Language New Added to support the new pool support.
CYH2 ECB-Controlled Assembler Language New Added to support the new pool support.
CYH3 ECB-Controlled Assembler Language New Added to support the new pool support.
CYH4 ECB-Controlled Assembler Language New Added to support the new pool support.
CYYA Online Assembler Changed This keypoint filing segment has been modified to call the new DEARRANGE_CTK9 function (the CYH1 segment).
CYYM Online Assembler Changed This keypoint retrieval segment has been modified to call the REARRANGE_CTK9 function (the CYH0 segment).
DYDC Online Assembler Changed Updated to support the new pool support.
DYDD Online Assembler Changed Updated to support the new pool support.
DYDG Online Assembler Changed Updated to support the new pool support.
DYDK Online Assembler Changed Updated to support the new pool support.
DYDL Online Assembler Changed Updated to support the new pool support.
DYDQ Online Assembler Changed Updated to support the new pool support.
DYDS Online Assembler Changed Updated to support the new pool support.
DYDU Online Assembler Changed Updated to support the new pool support.
DYDX Online Assembler Changed Updated to support the new pool support.
DYDY Online Assembler Changed Updated to support the new pool support.
DYOM Offline Assembler Changed Updated to support the new pool support.
DYO0 Offline Assembler Changed Updated to support the new pool support.
DYO1 Offline Assembler Changed Updated to support the new pool support.
DYO6 Offline Assembler Changed Updated to support the new pool support.
DYO7 Offline Assembler New This new segment has been added to the list of pool maintenance programs to be linked.
GRFS Copy Segment Changed Updated to support the new pool support.
UPX0 ECB-Controlled Assembler Language New Added to support the new pool support.
UPX1 ECB-Controlled Assembler Language New Added to support the new pool support.
UPX2 ECB-Controlled Assembler Language New Added to support the new pool support.
UXP3 ECB-Controlled Assembler Language New Added to support the new pool support.

Although the following segments were not changed by the new pool support, you must reassemble them.

BDBF BDBL BDBP BRCM BRCQ
BRTV BRYD CYAA CYAB CYAE
CYA7 CYA9 CYB0 CYD0 CYD1
CYD2 CYD3 CYF0 CYF1 CYF2
CYF3 CYF4 CYF6 CYF8 CYF9
CYGM DYDE DYDF DYDI DYDZ
JCDR        

System Equates

There are no changes.

User Exits

Control Program (CP) User Exits and ECB User Exits summarize the control program and ECB user exit changes. See TPF System Installation Support Reference for a complete description of all user exits.

Control Program (CP) User Exits

There are no changes.

ECB User Exits

This information is presented in alphabetic order by the name of the function.

Table 38. Changes to ECB Control Program (CP) User Exits for the New Pool Support

Function User Exit Activated In User Exit Program New, Changed, or No Longer Supported? Description of Change
Pool Migration CYH0 UPX0 New REARRANGE_CTK9
Pool Migration CYH1 UPX1 New DEARRANGE_CTK9
Pool Migration CYH2 UPX2 New GET_CY$CR
Pool Migration CYH3 UPX3 New FILE_CY$CR

Functional and Operational Changes

The following section summarizes functional and operational changes. This information is presented in alphabetic order by the functional or operational change.

See Appendix A, PUT 2-15 Interface Changes by Authorized Program Analysis Report (APAR) for a summary of functional and operational changes by APAR.

Commands

Table 39 summarizes command changes. This information is presented in alphabetic order by the name of the command. See TPF Operations for a complete description of all commands.

Attention: Changes to commands can impact any automation programs you are using in your complex.

Table 39. Changes to Commands for the New Pool Support

Command New, Changed, or No Longer Supported? Description of Change
ZPMIG New Use this command to:
  • Convert the pool data structures from the pool format currently defined in your complex to the new pool format
  • Return the new pool format back to the pool format previously defined in your complex when fallback has been completed
  • Display the migration state of each processor in the complex.

Messages and System Errors

Table 40 summarizes message (offline and online messages) and system error changes.

The message IDs or system error numbers are listed in numeric order preceded by their alphabetic prefix. Some offline and online messages do not have a standard message ID. For these, the messages are presented in alphabetic order based on the initial message text; or for those messages that begin with variable information, the initial message text that follows that variable information. See Messages (System Error and Offline) and Messages (Online) for a complete description of all messages and system errors.

Attention: Changes to offline messages, online messages, and system errors may impact any automation programs you are using in your complex.

Table 40. Changes to Messages and System Errors for New Pool Support

Message ID or System Error Number Message Type New, Changed, or No Longer Supported?
CYC00001W Online Changed
CYC00003I Online Changed
DYDU0008I Online Changed
DYO01000W Offline New
DYO02000E Offline New
PMIG0001I Online New
PMIG0002I Online New
PMIG0003T Online New
PMIG0004I Online New
PMIG0005I Online New
PMIG0006W Online New
PMIG0007T Online New
PMIG0008T Online New
PMIG0009T Online New

Performance or Tuning Changes

There are improvements in offline pool maintenance because of the new pool support.

Storage Considerations and Changes

There are no changes.

System Initialization Program (SIP) and System Generation Changes

Changes were made to the:

See TPF Database Reference for a sample JCL.

Loading Process Changes

There are no changes.

Online System Load Changes

There are no changes.

Publication Changes

Table 41 summarizes changes to the publications in the TPF library. This information is presented in alphabetic order by the publication title.

See the TPF Library Guide for more information about the TPF library.

Table 41. Changes to TPF Publications for the New Pool Support

Publication Title Softcopy File Name Description of Change
TPF Database Reference GTPDBR02 Added information for the new pool support.
TPF Library Guide GTPDOC02 Updated with definitions for new terminology in the master glossary.
Messages (System Error and Offline) and Messages (Online) Not Applicable Updated with information about the messages and system errors that were added, changed, and no longer supported for new pool support.
TPF Migration Guide: Program Update Tapes GTPMIG02 Updated with migration considerations for new pool support.
TPF Operations GTPOPR02 Updated with information about the commands that were added and changed for new pool support.
TPF System Generation GTPSYG02 Added information for the new pool support.
TPF System Installation Support Reference GTPINR02 Added information for the new pool support.

Host System Changes

There are no changes.

Application Programming Interface (API) Changes

There are no changes.

Database Changes

There are no changes.

Feature Changes

There are no changes.

Installation Validation

There are no changes.

Migration Scenarios

Before You Begin

Before you begin the following migration scenarios it is recommended you read Pool Conversion again, paying close attention to the information in the boxes labelled Critical Information for Using DYOPM.

There are 3 migration scenarios to consider when converting your complex to the new pool support:

A description of these scenarios follows.

Scenario for a New User of the TPF 4.1 System

If you are installing the TPF 4.1 system for the first time (in other words, you are not a previous TPF 4.1 or TPF 3.1 system user), use the following migration scenario.

Install the TPF 4.1 system using the system installation information provided in TPF System Generation, the TPF System Installation Support Reference, and the program directories. The new pool support will be installed and initialized automatically.

Scenario for an Established TPF 4.1 System User

If you already have the TPF 4.1 system installed in your complex and want to add the new pool support to that system, use the following migration scenario.

See Pool Conversion for information about converting your complex in 2 stages.

To Convert Your Complex to the New Pool Support
  1. Do the following to migrate each active processor, one at a time. This is Stage 1 of pool conversion.
    1. Determine the migration state of each active processor by entering ZPMIG STATUS.

      An informational message is displayed indicating the migration state of each processor in your complex.

    2. Use multiple TPF images to create a new image on the processor in your complex.
    3. IPL the processor to 1052 state using the new image. The new pool support is now active for this processor.
    4. Repeat step 1a through step 1c on each processor that you want to migrate.

      When all the active processors in your complex are migrated, continue with step 2 to convert the entire complex.

    Critical Information for Using DYOPM

    At this point:

    • The existing version of DYOPM can only be used on an unmigrated processor.
    • DYOPM cannot be run on a migrated processor in a complex that has not been converted. If you want to run DYOPM before conversion is completed, DYOPM must be run on an unmigrated processor. To do this, see Scenario to Fall Back Migrated Processors.
  2. Enter ZPMIG CONVERT to perform the pool conversion.

    When the pool conversion process has completed, an informational message is displayed informing you of that completion.

    Critical Information for Using DYOPM

    At this point, you must use the new version of DYOPM because keypoint 9 (CTK9) has been converted to the new format.

Additional Information:

Scenario for Established Users of the TPF 3.1 System

If you are an established user of the TPF 3.1 system migrating to the TPF 4.1 system for the first time, use the following migration scenario.

To Convert Your Complex to the New Pool Support
  1. Migrate the TPF 3.1 system to the TPF 4.1 system using the migration information and the system installation provided in:
  2. Enter ZPMIG CONVERT to perform the pool conversion.

Additional Information:

See TPF Operations for more information about the ZPMIG command.

Pool Conversion Fallback Scenarios

Pool conversion fallback enables you to return the new pool format back to the pool format previously defined in your complex after pool conversion is completed.

There are 2 fallback levels to consider:

A description of these scenarios follows.

Scenario to Fall Back a Complex That Has Been Converted

If your complex has been converted to the new pool support and you want to return the pool data structures on DASD to the pool format previously defined in it, use the following scenario.

To Fall Back an Entire Complex
  1. Enter ZPMIG FALLBACK from any processor to perform the pool conversion fallback.

    The pool data structures on DASD are returned to the pool format previously defined. The new pool support remains on the processor.

    Critical Information for Using DYOPM

    At this point:

    • The existing version of DYOPM can only be used on an unmigrated processor.
    • DYOPM cannot be run on a migrated processor in a complex that has not been converted. If you want to run DYOPM before conversion is completed, DYOPM must be run on an unmigrated processor. To do this, see Scenario to Fall Back Migrated Processors.

Additional Information:

See TPF Operations for more information about the ZPMIG command.

Scenario to Fall Back Migrated Processors

If any of the processors in your complex have been migrated to the new pool support and you want to remove the new pool support from a processor, use the following scenario.

To Fall Back a Migrated Processor
  1. Stop all functions that use the new pool format and cycle the TPF 4.1 system to 1052 state.
  2. Determine the migration state of the processor to ensure it has been migrated to the new pool support by entering ZPMIG STATUS.

    An informational message is displayed indicating the migration state of each processor in your complex.

  3. IPL the processor to 1052 state using an old image. CTIN loads CTK9 from DASD into core and the processor is returned to the pool format previously defined on it.

    The processor is no longer running with the new pool support.

    Note:
    When you return a migrated processor to the pool format previously defined on it, you must:
    • Set the bit in CY1PMG to 0 for the migrated processor
    • Use the existing version of DYOPM on an unmigrated processor.
  4. Repeat step 1 through step 3, as necessary, to fall back additional migrated processors.

Additional Information:

See TPF Operations for more information about the ZPMIG command.