gtpm2m2nMigration Guide: Program Update Tapes

Logical Record Cache and Coupling Facility (CF) Cache Support (APAR PJ27083)

The following section discusses the migration considerations for logical record cache and coupling facility (CF) cache support.

Prerequisite APARs

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

Functional Overview

Logical record cache and CF cache support further exploits CF support and CF record lock support, which were provided on program update tape (PUT) 9 and 11 respectively. See File System Support (APAR PJ25089), Coupling Facility (CF) Support (APAR PJ25781), and Coupling Facility (CF) Record Lock Support (APAR PJ26707) for more information about CF support and CF record lock support.

Logical Record Cache Support

A logical record cache provides you with high-speed access to data that enables you to develop data sharing programs with improved performance. With logical record cache support, you can use the logical record cache for the following:

With logical record cache support you can create processor shared caches and processor unique caches. You can access and manage logical record caches by using the ZCACH command. See TPF Operations for more information about the ZCACH command.

The following C functions are now available for your use:

C Function
Description

deleteCache
Deletes a logical record cache from the processor.

deleteCacheEntry
Deletes a cache entry.

flushCache
Flushes the contents of the cache.

newCache
Creates a new logical record cache.

readCacheEntry
Reads a cache entry.

updateCacheEntry
Adds a new cache entry or updates an existing cache entry.

See the TPF C/C++ Language Support User's Guide for more information about these C functions.

Additionally, file system support has been updated to use processor shared caches in order to operate in a loosely coupled complex. See File System Support (APAR PJ25089) for more information about file system support.

CF Cache Support

CF cache support supports processor shared caches. A CF cache structure is a named piece of storage on the CF that allows multisystem applications to share information and allows high-performance sharing of frequently referenced data. The TPF 4.1 system supports directory-only CF cache structures. Data is not stored in a directory-only CF cache structure. You can manage CF cache structures by using the ZCFCH command.

In addition, the ZMCFT DISPLAY command has been enhanced to include an indicator about the type of CF structure (either a CF list structure or a CF cache structure) being displayed. See TPF Operations for more information about the ZCFCH and ZMCFT DISPLAY commands.

Architecture

To operate logical record caches in a loosely coupled complex, the CF cache architecture is used to maintain the consistency of data in the local caches.

Operating Environment Requirements and Planning Information

See the S/390 Processor Resource/Systems Manager Planning Guide for information about CF planning and operating environment requirements.

Interface Changes

The following section summarizes interface changes.

C/C++ Language

The following section summarizes C/C++ language changes. This information is presented in alphabetic order by the type of C/C++ language information. See the TPF C/C++ Language Support User's Guide and TPF Application Programming for more information about the C/C++ language.

Build Scripts

Table 924 summarizes changes to the build scripts used by the build tool. This information is presented in alphabetic order by the name of the build script.

Table 924. Changes to Build Scripts for Logical Record Cache and CF Cache Support

Build Script Type New, Changed, or No Longer Supported? Description of Change
CACHBS DLM New Created by logical record cache and CF cache support for the ZCACH command.
CBOTBS DLM Changed Updated by logical record cache and CF cache support to remove the cache module.
CFCHBS DLM New Created by logical record cache and CF cache support for the ZCFCH command.
CFINBS DLM Changed Updated by logical record cache and CF cache support to remove the cache module.
CFZFBS DLM Changed Updated by logical record cache and CF cache support to remove the cache module.
CFZIBS DLM Changed Updated by logical record cache and CF cache support to remove the cache module.
COMXBS DLM Changed Updated by logical record cache and CF cache support to add the CF cache module.
JCI1BS DLM Changed Updated by logical record cache and CF cache support to remove the CF cache module.

Dynamic Load Module (DLM) Stubs

There are no changes.

General Use C/C++ Language Header Files

Table 925 summarizes the general use C/C++ language header file changes. This information is presented in alphabetic order by the name of the general use C/C++ language header file.

General use means these header files are available for your use.

Table 925. Changes to General Use C/C++ Language Header Files for Logical Record Cache and CF Cache Support

C/C++ Language Header File New, Changed, or No Longer Supported? Do You Need to Recompile Segments?
c$cach.h Changed Yes
c$cfaa.h Changed Yes
c$cfcb.h Changed No
c$cfco.h Changed Yes
c$cfeq.h Changed No
c$cfsb.h Changed No
c$cfvb.h Changed No
c$cf2e.h Changed No
c$fapi.h Changed No
c$syseq.h Changed No

Implementation-Specific C/C++ Language Header Files (IBM Use Only)

Table 926 summarizes the general use C/C++ language header file changes that are for IBM use only. This information is presented in alphabetic order by the name of the general use C/C++ language header file.

Table 926. Changes to Implementation-Specific C/C++ Language Header Files (IBM Use Only) for Logical Record Cache and CF Cache Support

C/C++ Language Header File (IBM Use Only) New, Changed, or No Longer Supported? Do You Need to Recompile Segments?
i$cach.h New No
i$cfch.h New No

Library Interface Scripts

Table 927 summarizes changes to the library interface scripts used by the library interface tool and the build tool. This information is presented in alphabetic order by the name of the library interface script.

Table 927. Changes to Library Interface Scripts for Logical Record Cache and CF Cache Support

Library Interface Script New, Changed, or No Longer Supported? Description of Change
COMXXV Changed Updated by logical record cache and CF cache support to add cache functions.

Library Members (Object Files)

Table 928 summarizes the library member (object file) changes. This information is presented in alphabetic order by the name of the library member (object file).

Table 928. Changes to Library Members (Object Files) for Logical Record Cache and CF Cache Support

Library Member (Object File) Library Module Name New, Changed, or No Longer Supported? Type Description of Change
CACHE COMXBS Changed Assembler Updated for logical record cache and CF cache support.
CFCA COMXBS New C Language Added for logical record cache and CF cache support.
CFS028 COMXBS Changed C Language Updated by logical record cache and CF cache support to add the cache parameter list.
CFS108 COMXBS Changed C Language Updated by logical record cache and CF cache support to add the cache parameter list.
CFS130 COMXBS Changed C Language Updated by logical record cache and CF cache support to add the cache parameter list.
CFS131 COMXBS Changed C Language Updated by logical record cache and CF cache support to add the cache parameter list.
CFS157 COMXBS Changed C Language Updated by logical record cache and CF cache support to add the cache parameter list.

Link-Edited Modules

There are no changes.

Members (Object Files)

Table 929 summarizes changes to members (object files). This information is presented in alphabetic order by the name of the member (object file).

Notes:

  1. You must recompile or reassemble a member (object file) if it has changed.

  2. You must prelink and link a dynamic load module (DLM) if it has changed.

Table 929. Changes to Members (Object Files) for Logical Record Cache and CF Cache Support

Member (Object File) DLM/DLL New, Changed, or No Longer Supported? Type Description of Change
CACH CACH New C Language Added support for the ZCACH command.
CFCH CFCH New C Language Added support for the ZCFCH command.
CFCNC CFLZ Changed C Language Updated by logical record cache and CF cache support to add support for CF cache structures.
CFDSC CFLY Changed C Language Updated by logical record cache and CF cache support for changed header field names.
CFLDEL CFLK Changed C Language Updated by logical record cache and CF cache support to add support for CF cache structures.
CFLIPD CFLG Changed C Language Updated by logical record cache and CF cache support to add support for CF cache structures.
CFLL CFLG, CFLK Changed C Language Updated by logical record cache and CF cache support to add support for CF cache structures.
CFMCLE CFLN Changed C Language Updated by logical record cache and CF cache support to add support for CF cache structures.
CFMDIS CFLN Changed C Language Updated by logical record cache and CF cache support to add support for CF cache structures in the display information.
CFMENA CFLN Changed C Language Updated by logical record cache and CF cache support for changed header field names.
CFRST2 CFLS Changed C Language Updated by logical record cache and CF cache support to add support for CF cache structures.
CFSBFD CFLZ Changed C Language Updated by logical record cache and CF cache support to preserve the storage protection key.
CFSBFL CFLY, CFLZ Changed C Language Updated by logical record cache and CF cache support for changed header field names.
CFSTBE CFLP Changed C Language Updated by logical record cache and CF cache support for an additional header field.
JCI1 JCII Changed C Language Updated by logical record cache and CF cache support to add caching.

Object Code Only (OCO) Stubs

There are no changes.

Configuration Constant (CONKC) Tags

There are no changes.

Control Program Interface (CINFC) Tags

There are no changes.

Copy Members

Table 930 summarizes the copy member changes. This information is presented in alphabetic order by the name of the copy member.

Table 930. Changes to Copy Members for Logical Record Cache and CF Cache Support

Copy Member Type CSECT Where Copy Member Is Located DLM Where CSECT Is Located New, Changed, or No Longer Supported? Description of Change
CDC1 Control Program CCDCOL Not Applicable Changed Updated by logical record cache and CF cache support to support CF cache structures.
CFCC Control Program CCCFCC Not Applicable Changed Updated by logical record cache and CF cache support to support CF cache structures.
CFCM Control Program CCCFCC Not Applicable Changed Updated by logical record cache and CF cache support to support CF cache structures.
CFCR Control Program CCCFCC Not Applicable Changed Updated by logical record cache and CF cache support to support CF cache structures.
CFCS Control Program CCCFCC Not Applicable Changed Updated by logical record cache and CF cache support for changed data macro field names.
CFL2 Control Program CCCFLC Not Applicable Changed Updated by logical record cache and CF cache support to add an external entry.

Fixed File Records

Table 931 summarizes fixed file record changes. This information is presented in alphabetic order by the name of the fixed file record.

Table 931. Changes to Fixed File Records for Logical Record Cache and CF Cache Support

Fixed File Record New, Changed, or No Longer Supported? Description of Change
#IBMM4 Changed Updated by logical record cache and CF cache support to assign cache control record ordinal 166.
#IBMMP4 Changed Updated by logical record cache and CF cache support to assign cache control record ordinal 19.

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 932 summarizes the data macro changes. This information is presented in alphabetic order by the name of the data macro.

Table 932. Changes to Data Macros for Logical Record Cache and CF Cache Support

Data Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs Using This Data Macro?
DC0DC Changed Yes
ICACH Changed Yes
ICFAA Changed Yes
ICFCB Changed No
ICFCO Changed Yes
ICFEQ Changed No
ICFMB Changed No
ICFSB Changed No
ICFVB Changed No
IFAPI Changed No

General Macros

There are no changes.

Selected Equate Macros

Table 933 summarizes the selected equate macro changes. This information is presented in alphabetic order by the name of the selected equate macro.

Table 933. Changes to Selected Equate Macros for Logical Record Cache and CF Cache Support

Selected Equate Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs?
CZ1SE Changed No
SYSEQ Changed No

Structured Programming Macros (SPMs)

There are no changes.

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

Table 934 summarizes the system initialization program (SIP) skeleton and internal macro changes. This information is presented in alphabetic order by the name of the SIP skeleton and internal macro. If the SIP skeleton and internal macro (inner macro) is changed, you must reassemble the SIP Stage I deck and run the appropriate job control language (JCL) jobs from the SIP Stage II deck.

Table 934. Changes to SIP Skeleton and Internal Macros for Logical Record Cache and CF Cache Support

SIP Skeleton and Internal Macro New, Changed, or No Longer Supported?
SPPGML Changed

System Initialization Program (SIP) Stage I Macros and Statements

There are no changes.

System Initialization Program (SIP) Stage II Macros

Table 935 summarizes system initialization program (SIP) Stage II macro changes. This information is presented in alphabetic order by the name of the SIP Stage II macro. If IBMPAL is changed, you must run the system allocator (SALO) and load the new program allocation table (PAT) to the TPF 4.1 system.

Table 935. Changes to SIP Stage II Macros for Logical Record Cache and CF Cache Support

SIP Stage II Macro New, Changed, or No Longer Supported?
IBMPAL Changed

System Communication Keypoint (SCK) Generation Macros

There are no changes.

System Macros

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

Table 936. Changes to System Macros for Logical Record Cache and CF Cache Support

System Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs?
CFCONC Changed No
CFDISC Changed No

System Macros (IBM Use Only)

Table 937 summarizes system macro changes that are for IBM use only. This information is presented in alphabetic order by the name of the system macro.

Table 937. Changes to System Macros (IBM Use Only) for Logical Record Cache and CF Cache Support

System Macro (IBM Use Only) New, Changed, or No Longer Supported? Do You Need to Reassemble Programs?
CFRQC Changed No

Segments

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

Table 938. Changes to Segments for Logical Record Cache and CF Cache Support

Segment Type Link-Edit Module (Where Offline Segment Is Linked) New, Changed, or No Longer Supported? Description of Change
CFZF Real-Time Assembler Not Applicable Changed Updated by logical record cache and CF cache support.
CLM6 Real-Time Assembler Not Applicable Changed Updated by logical record cache and CF cache support for changed data macro field names.
CNAH Real-Time Assembler Not Applicable Changed Updated by logical record cache and CF cache support to detach CF connections.
CVAB Real-Time Assembler Not Applicable Changed Updated by logical record cache and CF cache support to add the ZCACH and ZCFCH commands.
JCD1 Real-Time Assembler Not Applicable Changed Updated by logical record cache and CF cache support for caching.
JCS0 Real-Time Assembler Not Applicable Changed Updated by logical record cache and CF cache support for caching.
JRA1 Offline PL/I DATAREAD Changed Updated by logical record cache and CF cache support to update the data reduction reports.
JRA2 Offline PL/I DATAREAD Changed Updated by logical record cache and CF cache support to update the data reduction reports.
JRS3 Offline PL/I DATAREAD Changed Updated by logical record cache and CF cache support to update the data reduction reports.

System Equates

The following section summarizes system equate changes.

SYSEQ Tags

Table 939 summarizes changes to equates that are not configuration dependent (in SYSEQ). This information is presented in alphabetic order by the name of the SYSEQ tag.

Table 939. Changes to SYSEQ Tags for Logical Record Cache and CF Cache Support

SYSEQ Tag Equate Value New, Changed, or No Longer Supported?
#CFCACHE 166 New
#TPFCACHE 19 New

User Exits

There are no changes.

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 940 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 940. Changes to Commands for Logical Record Cache and CF Cache Support

Command New, Changed, or No Longer Supported? Description of Change
ZCACH New Created by logical record cache and CF cache support to manage logical record caches.
ZCFCH New Created by logical record cache and CF cache support to manage CF cache structures.
ZMCFT DISPLAY Changed Updated by logical record cache and CF cache support to include an indicator about the type of CF structure (a CF list structure or a CF cache structure) being displayed.

Messages and System Errors

Table 941 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 941. Changes to Messages and System Errors for Logical Record Cache and CF Cache Support

Message ID or System Error Number Message Type New, Changed, or No Longer Supported?
00460B System Error Changed
004628 System Error Changed
007547 System Error No Longer Supported
007549 System Error No Longer Supported
00754A System Error New
CACH0001I Online New
CACH0002I Online New
CACH0003E Online New
CACH0004I Online New
CACH0005I Online New
CACH0006I Online New
CACH0008E Online New
CACH0009E Online New
CACH0010E Online New
CACH0011E Online New
CACH0013E Online New
CACH0016I Online New
CACH0017I Online New
CACH0018E Online New
CACH0019I Online New
CACH0020I Online New
CACH0022I Online New
CACH0023I Online New
CACH0024E Online New
CACH0025E Online New
CACH0026I Online New
CACH0027E Online New
CACH0032W Online New
CACH0034W Online New
CFCA0002E Online New
CFCA0003E Online New
CFCA0004E Online New
CFCA0006E Online New
CFCH0001I Online New
CFCH0002I Online New
CFCH0003E Online New
CFCH0005I Online New
CFCH0008E Online New
CFCH0009E Online New
CFCH0010E Online New
CFCH0011E Online New
CFCH0016I Online New
CFCH0017I Online New
CFCH0018E Online New
CFLK0046E Online New
MCFT0046I Online No Longer Supported
MCFT0047I Online New
RHLD0027I Online New

Performance or Tuning Changes

There are no changes.

Storage Considerations and Changes

There are no changes.

System Initialization Program (SIP) and System Generation Changes

There are no changes.

Loading Process Changes

There are no changes.

Online System Load Changes

There are no changes.

Publication Changes

Table 942 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 942. Changes to TPF Publications for Logical Record Cache and CF Cache Support

Publication Title Softcopy File Name Description of Change
TPF C/C++ Language Support User's Guide GTPCLU0D Updated with information about the new C functions for logical record cache and CF cache support.
TPF Concepts and Structures GTPCON0A Updated with information about logical record cache and CF cache support.
TPF Database Reference GTPDBR0B Updated with information about logical record cache and CF cache support.
TPF Library Guide GTPDOC0D Updated with definitions for new terminology in the master glossary.
Messages (System Error and Offline) and Messages (Online) Not Applicable Updated with information about messages and system errors that were added, changed, and no longer supported for logical record cache and CF cache support.
TPF Migration Guide: Program Update Tapes GTPMG203 Updated with migration considerations for logical record cache and CF cache support.
TPF Operations GTPOPR0D Updated with information about the commands that were added and changed for logical record cache and CF cache support.
TPF Programming Standards GTPPSM09 Updated with information about naming conventions for logical record cache and CF cache support.
TPF System Performance and Measurement Reference GTPSPPR0C Updated with changes for data collection and reduction reports for logical record cache and CF cache support.
TPF System Generation GTPSYG0D Updated to include system generation information for logical record cache and CF cache support.
TPF System Macros GTPSYS0D Updated the CFCONC and CFDISC macros logical record cache and CF cache support.

Host System Changes

There are no changes.

Application Programming Interface (API) Changes

Logical record cache support provides several new C functions:

See the TPF C/C++ Language Support User's Guide for more information about these C functions and updates to the tpf_cfconc C function.

Database Changes

There are no changes.

Feature Changes

There are no changes.

Installation Validation

There are no changes.

Migration Scenarios

Use the following procedure to install logical record cache and CF cache support on your TPF 4.1 system.

  1. Install program update tape (PUT) 13, which contains APAR PJ27083, on your TPF 4.1 system.
  2. Install the following:
  3. Run the system allocator (SALO) using IBMPAL and SPPGML additions for newly created segments to create an updated program allocation table (PAT) and system allocator (SAL) table.
  4. Update the record ID attribute table (RIAT) as appropriate. See TPF System Generation for more information about the RIAT.
  5. Do one of the following:
    • If cache control record ordinal 166 is not defined in the #IBMM4 fixed file record and cache control record ordinal 19 is not defined in the #IBMMP4 fixed file record, continue with step 6.
    • If the ordinals are defined already, continue with step 8.
  6. Update the SIP RAMFIL macro input statements to the FACE table generator (FCTBG) by specifying the #IBMM4 fixed file record type with 166 ordinals defined and the #IBMMP4 fixed file record type with 19 ordinals defined. See TPF System Generation for more information about the RAMFIL macro.
  7. Run the FCTBG to create a new FACE table.
  8. Run stubs and module build from VisualAge TPF for Windows NT for all library interface scripts listed in Table 927.
  9. Reassemble or recompile the following:
  10. Reassemble or recompile the following segments. These segments were not modified by logical record cache and CF cache support, but must be reassembled or recompiled because there were logical record cache and CF cache support modifications made to macros, data macros (DSECTs), or header files used by these segments.

     CBOT 
    CCENBK

     CDCR 
    CFIN

     CFLA 
    CFLIPA

     CFLO 
    CFS111

     CFS152 
    CFZI

     JCD0 
    JCD2

     JCD3 
    JCD4

     JCD6 
    JCD0

     JCM0 
    JCP0
  11. Link-edit the build scripts (DLMs) listed in Table 924.
  12. Link-edit the following build scripts (DLMs):
    • CDCP
    • CFLA.
  13. Link-edit the control program (CP).
  14. Define a load deck for the auxiliary loader (TLDR) that includes the following:
    • Updated programs
    • Updated CP
    • Updated IPAT
    • Updated RIAT
    • Updated FACE table, if necessary.
  15. Run TLDR.
  16. IPL the TPF 4.1 system.
  17. Re-IPL all processors in the processor configuration. Logical record cache and CF cache support is now installed on your TPF 4.1 system.

Fallback and Coexistence

If you have defined processor shared caches on a TPF 4.1 system with logical record cache and CF cache support installed, you must delete these caches or change them to be processor unique caches before falling back to a TPF 4.1 system that does not have logical record cache and CF cache support installed. Otherwise, errors like the 005006 system error may occur.

Note:
With logical record cache and CF cache support the TPF 4.1 system performs an interprocessor communication (IPC) to all active processors in the complex so that the cache is created or changed at that point in time on all active processors. Previously, the cache was created or changed only on the processor from which the create or change was initiated.

If your complex has a mix of processors running with or without logical record cache and CF cache support installed and you have processor shared caches defined, errors like the 005006 system error may occur on the processors running TPF 4.1 systems without logical record cache and CF cache support installed. Define processor shared caches only when all processors in the complex are running a TPF 4.1 system with logical record cache and CF cache support installed.