gtpm2m1oMigration Guide: Program Update Tapes

Coupling Facility (CF) Support (APAR PJ25781)

The following section discusses the migration considerations for coupling facility support (referred to as CF support throughout this section).

Prerequisite APARs

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

Functional Overview

CF support provides data sharing capabilities that allow TPF routines, subsystems, system products, and applications running in a processor configuration to use a CF for high-performance, high-availability data sharing. A coupling facility (CF) is an IBM processor (sometimes referred to as a central processing complex (CPC)) that is used to centralize storage for all attached processors in a processor configuration by providing shared storage and shared storage management functions.

At this time, CF support provides connectivity to a CF for use by TPF system functions.

Architecture

With CF support, you can add one or more CFs from a TPF processor to the processor configuration. Applications can connect to CF list structures on CFs that have been added to the processor configuration. A CF list structure is a named piece of storage on a CF that enables users to share information organized as entries on a set of lists or queues. A user refers to an application or an instance of an application using connection services to access a CF list structure. The first connect request issued to a particular CF list structure causes that list structure to be allocated before establishing the connection.

An application that connects to a CF list structure can monitor individual lists to determine when list entries have been created on that list. When a list changes from empty state to nonempty state (that is, when a list entry is added to a previously empty list), an application-defined exit is called. This eliminates the need for application polling of lists and simplifies programming requirements.

When an application no longer requires access to a CF list structure, the application can disconnect from the list structure. Depending on the parameters specified when the CF list structure was allocated, a disconnect by the last connector to a CF list structure either causes deallocation of the list structure or allows it to remain allocated for subsequent connections to occur.

A CF may be added to multiple processor configurations in a TPF multiprocessor complex. A CF that has been added to a TPF processor configuration may not be shared with any other processors that are not in the TPF multiprocessor complex even if the other processor is also running the TPF 4.1 system.

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 430 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 430. Changes to Build Scripts for CF Support

Build Script Type New, Changed, or No Longer Supported? Description of Change
CFLCBS DLM New Created by CF support for the common fixed file find.
CFLMBS DLM New Created by CF support for the ZMCFT parser.
CFLNBS DLM New Created by CF support for the ZMCFT service routines.
CFLPBS DLM New Created by CF support for building the core coupling facility status table (CFST) entry.
CFLQBS DLM New Created by CF support to refresh main storage in the CFST.
CFLRBS DLM New Created by CF support for part 1 of CF restart.
CFLSBS DLM New Created by CF support for part 2 of CF restart.
CFLTBS DLM New Created by CF support for the ZDCFT command handler.
CFLUBS DLM New Created by CF support for the ZMCFT common message routine.
CFLYBS DLM New Created by CF support for the CFDISC macro service routine.
CFLZBS DLM New Created by CF support for the CFCONC service routine.
CTALBS DLM Changed Updated by CF support for the TPF application programming interface (API) library.

Dynamic Load Module (DLM) Stubs

Table 431 summarizes changes to the dynamic load module (DLM) stubs. This information is presented in alphabetic order by the name of the DLM stub. See TPF Application Programming for more information about the DLM stubs.

Table 431. Changes to Dynamic Load Module (DLM) Stubs for CF Support

DLM Stub New, Changed, or No Longer Supported?
CFLC New
CFLN New
CFLP New
CFLQ New
CFLU New
CFLY New
CFLZ New

General Use C/C++ Language Header Files

Table 432 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 432. Changes to General Use C/C++ Language Header Files for CF Support

C/C++ Language Header File New, Changed, or No Longer Supported? Do You Need to Recompile Segments?
c$cfaa.h New No
c$cfcb.h New No
c$cfco.h New No
c$cfct.h New No
c$cfdi.h New No
c$cfeq.h New No
c$cfsb.h New No
c$cfst.h New No
c$cftt.h New No
c$cfvb.h New No
c$cinfc.h Changed No
c$fapi.h New No
c$fva0.h Changed No
c$msct.h New No
reusable.h Changed No

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

There are no changes.

Library Interface Scripts

Table 433 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 433. Changes to Library Interface Scripts for CF Support

Library Interface Script New, Changed, or No Longer Supported? Description of Change
CTALXV Changed Updated by CF support for the ISO-C TPF application programming interface (API) library.

Library Members (Object Files)

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

Table 434. Changes to Library Members (Object Files) for CF Support

Library Member (Object File) Library Module Name New, Changed, or No Longer Supported? Type Description of Change
CCFRQC CTAL New Assembler Created by CF support for the CFRQC function.
CGCFBC CTAL New Assembler Created by CF support for the GCFBC function.
CRCFBC CTAL New Assembler Created by CF support for the RCFBC function.

Link-Edited Modules

Table 435 summarizes changes to the link-edited modules shipped by IBM, which should go into a data set with attributes DCB=(RECFM=U,LRECL=80,BLKSIZE=1200). This information is presented in alphabetic order by the name of the link-edited module.

Table 435. Changes to Link-Edited Modules for CF Support

Link-Edited Module New, Changed, or No Longer Supported? Description of Change
CPS0 Changed Updated by CF support to add CCCFCC.

Members (Object Files)

Table 436 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 436. Changes to Members (Object Files) for CF Support

Member (Object File) DLM/DLL New, Changed, or No Longer Supported? Type Description of Change
CFCNC CFLZ New C Language Created by CF support for the CFCONC service routine.
CFDCFT CFLT New C Language Created by CF support for the ZDCFT command handler.
CFDSC CFLY New C Language Created by CF support for the CFDISC service routine.
CFFIND CFLC New C Language Created by CF support for the common fixed file routine.
CFMADD CFLN New C Language Created by CF support for ZMCFT ADD processing.
CFMDEL CFLN New C Language Created by CF support for ZMCFT DELETE processing.
CFMDIS CFLN New C Language Created by CF support for the ZMCFT DISPLAY service routine.
CFMENA CFLN New C Language Created by CF support for the ZMCFT ENABLE service routine.
CFMFRE CFLN New C Language Created by CF support for the ZMCFT service routine front end.
CFMPAR CFLM New C Language Created by CF support for the ZMCFT parser.
CFMRES CFLN New C Language Created by CF support for ZMCFT RESETLOCK processing.
CFMSGS CFLU New C Language Created by CF support for the CF output message processor.
CFRST1 CFLR New C Language Created by CF support for part 1 of CF restart.
CFRST2 CFLS New C Language Created by CF support for part 2 of CF restart.
CFSBFD CFLZ New C Language Created by CF support to locate the coupling facility structure block (CFSB) in the fixed file records.
CFSBFL CFLY, CFLZ New C Language Created by CF support to file a new or updated CF list structure.
CFSTBE CFLP New C Language Created by CF support to build the coupling facility status table (CFST) entry in main storage.
CFSTRF CFLQ New C Language Created by CF support to refresh the main storage copy of the CFST.

Object Code Only (OCO) Stubs

There are no changes.

Configuration Constant (CONKC) Tags

There are no changes.

Control Program Interface (CINFC) Tags

Table 437 summarizes the control program interface (CINFC) tag changes. The information in this table is ordered numerically by the equate value.

Table 437. Changes to CINFC Tags for CF Support

CINFC Tag Equate Value New, Changed, or No Longer Supported?
CMMCFC 357 New

Copy Members

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

Table 438. Changes to Copy Members for CF Support

Copy Member Type CSECT Where Copy Member Is Located New, Changed, or No Longer Supported? Description of Change
CAAA Control Program CCNUCL Changed Updated by CF support for the control program (CP) table of contents.
CCIO Control Program IPLB Changed Updated by CF support for the common input/output (I/O) copy code.
CCIT Control Program CCNUCL Changed Updated by CF support for the interrupt routines.
CEDM Control Program CCMCDC Changed Updated by CF support for the macro decoder.
CFCC Control Program CCCFCC New Created by CF support for the CF CP constants and equates.
CFCE Control Program CCCFCC New Created by CF support for the CF message error routines.
CFCM Control Program CCCFCC New Created by CF support for CF message initiation and completion.
CFCP Control Program CCCFCC New Created by CF support for the CF macro service routines.
CFCR Control Program CCCFCC New Created by CF support for the CF CFRQC macro service routine.
CFCS Control Program CCCFCC New Created by CF support for the CF general service routines.
CIDP Control Program CCCPSE Changed Updated by CF support for IBM dump overrides.
CLHL Control Program CCCLHR Changed Updated by CF support for the dispatch list management services.
CNCE Control Program CCMCKH Changed Updated by CF support for the machine check handler.
CPSE Control Program CCCPSE Changed Updated for CF support.
CPSL Control Program CCCPSE Changed Updated by CF support for the write system error dump.
CSYN Control Program CCNUCL Changed Updated by CF support.
CTME Control Program CCNUCL Changed Updated by CF support for the external interrupt handler.
CT38 Control Program CCCTIN Changed Updated by CF support to allocate CF control structures.

Fixed File Records

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

Table 439. Changes to Fixed File Records for CF Support

Fixed File Record New, Changed, or No Longer Supported? Description of Change
#CFREC New Created by CF support.

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

Table 440. Changes to Data Macros CF Support

Data Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs That Use This Data Macro?
DCTCTL Changed No
DCTDOR Changed No
DCTIRB Changed No
DCTMDR Changed No
DCTMFS Changed No
DCTMIO Changed No
DCTMOR Changed No
DCTPFX Changed No
DCTSCH Changed No
DLTEC Changed Yes
DLTGC Changed Yes
ICFAA New No
ICFCB New No
ICFCO New No
ICFCT New No
ICFDI New No
ICFEQ New No
ICFPL New No
ICFRB New No
ICFSB New No
ICFST New No
ICFTT New No
ICFVB New No
IFAPI New No
IMDDB New No
IMSCT New No
STDHD Changed No

General Macros

Table 441 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 441. Changes to General Macros for CF Support

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

Selected Equate Macros

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

Table 442. Changes to Selected Equate Macros for CF Support

Selected Equate Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs?
CLHEQ Changed No
CZOCP Changed No
CZ1SE Changed No
NODEQ Changed No
TRMEQ Changed No

Structured Programming Macros (SPMs)

There are no changes.

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

Table 443 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 443. Changes to SIP Skeleton and Internal Macros for CF Support

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

System Initialization Program (SIP) Stage I Macros and Statements

Table 444 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 Stae II deck.

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

Table 444. Changes to SIP Stage I Macros and Statements for CF Support

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

System Initialization Program (SIP) Stage II Macros

Table 445 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 445. Changes to SIP Stage II Macros for CF 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 446 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 446. Changes to System Macros for CF Support

System Macro New, Changed, or No Longer Supported? Do You Need to Reassemble Programs?
CFCONC New No
CFDISC New No
CFVCTC New No
IBMSVC Changed Yes
IDATB Changed Yes
IDATG Changed Yes
SLNKC Changed No

System Macros (IBM Use Only)

Table 447 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 447. Changes to System Macros (IBM Use Only) for CF Support

System Macro (IBM Use Only) New, Changed, or No Longer Supported? Do You Need to Reassemble Programs?
CFMCC Changed Yes
CFMDC Changed Yes
CFRQC New No
GCFBC New No
RCFBC New No
$GCFBC New No
$RCFBC New No

Segments

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

Table 448. Changes to Segments for CF Support

Segment Type Link-Edit Module (Where Offline Segment Is Linked) New, Changed, or No Longer Supported? Description of Change
CCCFCC CSECT Not Applicable New Created by CF support for the CF control program (CP).
CPLKMP CSECT Not Applicable Changed Updated by CF support for the copy cards for CP link map.
CTKS Real-Time Assembler Not Applicable Changed Updated by CF support.
CVAB Real-Time Assembler Not Applicable Changed Updated by CF support.
FTVA03 Offline C Language Not Applicable Changed Updated by CF support.

System Equates

There are no changes.

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 449 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 449. Changes to Commands for CF Support

Command New, Changed, or No Longer Supported? Description of Change
ZDCFT New Created by CF support to display entries in the coupling facility trace table (CFTT).
ZMCFT ADD New Created by CF support to add a CF to a processor configuration.
ZMCFT DELETE New Created by CF support to remove a CF from a processor configuration.
ZMCFT DISPLAY New Created by CF support to display the status of one or more CFs in the complex.
ZMCFT ENABLE New Created by CF support to resume normal operation of a CF when it becomes inactive because of an error.
ZMCFT RESETLOCK New Created by CF support to reset the CF lock to an available state.

Messages and System Errors

Table 450 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 450. Changes to Messages and System Errors for CF Support

Message ID or System Error Number Message Type New, Changed, or No Longer Supported?
005001 System Error New
005002 System Error New
005003 System Error New
005004 System Error New
005005 System Error New
005006 System Error New
005007 System Error New
005008 System Error New
005009 System Error New
00500A System Error New
CFCC0020E Online New
CFCC0021E Online New
CFCC0024W Online New
CFCC0025I Online New
CFCC0028E Online New
CFCC0029E Online New
CFCC0031E Online New
CFCC0034E Online New
CFCE0001E Online New
CFCE0002E Online New
CFCE0003E Online New
CFCE0004E Online New
CFCE0005E Online New
CFCR0001I Online New
DCFT0001I Online New
DCFT0002I Online New
DCFT0003E Online New
MCFT0001I Online New
MCFT0002I Online New
MCFT0003I Online New
MCFT0004I Online New
MCFT0005T Online New
MCFT0006T Online New
MCFT0007E Online New
MCFT0008I Online New
MCFT0009T Online New
MCFT0010T Online New
MCFT0011T Online New
MCFT0019E Online New
MCFT0020T Online New
MCFT0022T Online New
MCFT0024I Online New
MCFT0025E Online New
MCFT0026E Online New
MCFT0027E Online New
MCFT0028T Online New
MCFT0029I Online New
MCFT0030T Online New
MCFT0031I Online New
MCFT0032T Online New
MCFT0033T Online New
MCFT0034T Online New

Performance or Tuning Changes

There are no changes.

Storage Considerations and Changes

CF support uses the system work blocks (SWBs) for many types of control blocks. Consider increasing the number of SWBs allocated in your TPF 4.1 system to account for the SWBs used by CF support. The following identifies the additional number of SWBs you will need:

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 451 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 451. Changes to TPF Publications for CF Support

Publication Title Softcopy File Name Description of Change
TPF C/C++ Language Support User's Guide GTPCLU09 Updated with information about new C functions for CF support.
TPF Database Reference GTPDBR07 Added a new chapter that discusses CF concepts.
TPF General Macros GTPGEN09 Updated with changed general macros for CF support.
TPF Library Guide GTPDOC09 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 CF support.
TPF Migration Guide: Program Update Tapes GTPMIG09 Updated with migration considerations for CF support.
TPF Operations GTPOPR09 Updated with information about the commands that were added for CF support.
TPF Programming Standards GTPPSM08 Updated with conventions for CF list structure names.
TPF Program Development Support Reference GTPPDR09 Updated with information about new dump labels that were added for CF support.
TPF System Macros GTPSYS09 Updated with information about new and changed system macros for CF 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

Use the following procedure to install CF support on your TPF 4.1 system.

  1. Update the library system with the contents of program update tape (PUT) 9.
  2. In a basic subsystem (BSS), enter the ZIMAG DEFINE command to define a new image using a new program base. This image is referred to as the new image throughout the remainder of this procedure.
  3. Initialize the new image by copying from the old image to the new image. To do so, enter the ZIMAG COPY command.
    Note:
    You can also initialize the new image by performing a full load to the image.
  4. Create a new system allocator (SALO) that includes the newly created segments.
  5. Recompile and run SALO to create an updated program allocation table (PAT).
  6. Create a new file address compute (FACE) program table that includes the new fixed file records by defining the #CFREC fixed file record. The number of #CFREC fixed file records to define varies on your individual requirements. If you intend to create CF list structures in one or more CFs, use the following formula to determine the number of #CFREC fixed file records you need to define.

    In this formula M represents the maximum number of CF list structures that may be in use at any given time by all processors in the processor configuration. ICFSBNUMSLOTS is an equate defined in the ICFSB data macro. The number of #CFREC records to allocate is then given by the formula:

    1 + (M + (ICFSBNUMSLOTS - 1)) / ICFSBNUMSLOTS

    For #CFREC ordinal 0, enter ZIFIL CFREC/FC2E/01/0/0/NNN/N.

    For the remaining #CFREC ordinals that are defined (ordinals 1 through x-1), enter ZIFIL CFREC/FC2E/02/1/y/NNN/N where y is x-1.

    Notes:

    1. The division operation is integer division where any remainder is ignored.

    2. Currently ICFSBNUMSLOTS is 9.

    3. The records must be allocated as 4KB fixed file records.

    4. No #CFREC fixed file records are required if CF support is not actually being used.
  7. Reassemble and recompile all required programs. Be sure to recompile CFMDIS and CFMPAR using the RENT option.
  8. Link all applicable programs again.
  9. Link the control program (CP) again.
  10. Define a load deck for the auxiliary loader (TLDR) that includes the following:
    • Updated programs
    • Updated CP
    • Updated IPLB program
    • Updated IPAT
    • Updated FACE table.
  11. Run TLDR.
  12. Perform a load to the new image.
  13. Perform an IPL CLEAR of the TPF 4.1 system and choose the new image as the active image.
  14. Enter the ZIFIL command to initialize the fixed file records by entering ZIFIL equate/recid/code/start/end/NNN/N

    Where:

    equate
    Is a 1- to 8-character SYSEQ label (for FACS).

    recid
    Is a 2-character alphanumeric record ID or a 4-digit hexadecimal record ID.

    code
    Is the 2-digit hexadecimal value for the record code check (RCC) byte for the records.

    start
    Is the 1- to 8-character decimal starting ordinal number for the initialization.

    end
    Is the 1- to 8-character decimal ending ordinal number for the initialization.
  15. Re-IPL all processors in the processor configuration. CF support is now installed on your TPF 4.1 system.

Additional Information:

See TPF Operations for more information about the ZIMAG COPY, ZIMAG DEFINE, and ZIFIL commands.