gtpm2m1yMigration Guide: Program Update Tapes

C++ Class Library Support (APARs PJ26187 and PJ26173)

The following section discusses the migration considerations for C++ class library support.

Prerequisite APARs

See the APEDIT for APAR PJ26187 and APAR PJ26173 for information about prerequisite APARs.

Functional Overview

C++ class libraries provide you, the programmer, with more powerful tools for the development and maintenance of object-oriented programs. Built on the solid foundation of the C language, the C++ language adds support for object-oriented programs and many other features without sacrificing any of the power, elegance, or flexibility of the C language. C++ class library support provides specific class libraries that you can use and extends the power of the C++ language, which enables you to take advantage of more powerful C++ features and standards.

Although the TPF 4.1 system does not provide all the C++ class libraries that are available, it does provide the input/output (I/O) stream class libraries, which provide facilities for handling many varieties of I/O such as cin, cout, clog, and cerr. See OS/390 C/C++ IBM Open Class Library Reference for more information about these I/O stream class libraries.

Note:
The input/output (I/O) stream class library support provided by the TPF 4.1 system does not provide for a multi-threaded environment. However, you can use the fcntl function to control the level of access to files.

In addition, the TPF 4.1 system provides support for the STLport standard template library, which is available from Silicon Graphics, Inc. as a product called STLport Standard Template Library Version 3.01. This library, which is part of the ANSI/ISO C++ standard, contains generic container classes and algorithms that are designed to work together to provide you with a wide range of functions. The container classes are used as templates to define objects, while the algorithms are used to manage data in the containers. For example, the vector class can be used to represent vectors and the reverse algorithm can be used to reverse elements in vectors. The reverse algorithm can also be used to reverse elements in a list or in a C array. Therefore, generic C algorithms can be used to manage different containers. By providing a set of containers and algorithms to manage the containers, the STLport standard template library becomes a powerful tool for data representation and code development.

The TPF 4.1 system supports STLport Standard Template Library Version 3.01 compiled with IBM OS/390 C/C++ Version 2 Release 4. STLport Standard Template Library Version 3.01 is not shipped with the TPF 4.1 system. Rather, STLport Standard Template Library Version 3.01, which supports the IBM OS/390 environment, is available as freeware from the World Wide Web (WWW). You can port STLport Standard Template Library Version 3.01 to the TPF 4.1 system. See Migration Scenarios for more information.

C++ class library support is a follow-on to C++ support (APAR PJ25084), which provides support for:

See C++ Support (APAR PJ25084) for more information about C++ support (APAR PJ25084).

Benefits of Using C++ Class Libraries

I/O stream class libraries and the STLport standard template library provide the flexibility, productivity, and quality needed to gain a market advantage because C++ class libraries:

Architecture

There are no changes.

Operating Environment Requirements and Planning Information

To ensure that your TPF 4.1 system performs correctly with C++ class library support, you must establish the required operating environment. The following section describes hardware and software requirements specific to C++ class library support.

Operating Environment Requirements and Planning Information provides information about the minimum system configuration requirements that are necessary to operate the TPF 4.1 system. You may find it helpful to review that chapter along with the following information.

Hardware

There are no changes.

Software (Programming Requirements)

The following section contains information about software requirements.

If you want to take advantage of the power behind the STLport standard template library, you must port STLport Standard Template Library Version 3.01 from the WWW. See Migration Scenarios for more information about porting STLport Standard Template Library Version 3.01.

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 587 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 587. Changes to Build Scripts for C++ Class Library Support

Build Script Type New, Changed, or No Longer Supported? Description of Change
CPP1BS DLL Changed Added comments to state that the members are object code only (OCO).
CPP2BS DLL New Build script containing the C++ I/O stream class library function. CPP2 is a DLL and does not need a library interface script. Program update tape (PUT)10 contains the CPP240 DLL, which has been built for you already. You do not need to use the CPP2BS build script to build the DLL.

Dynamic Load Module (DLM) Stubs

There are no changes.

General Use C/C++ Language Header Files

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

C/C++ Language Header File New, Changed, or No Longer Supported? Do You Need to Recompile Segments?
fstream.h New No
generic.h New No
iomanip.h New No
iostream.h New No
irtllock.h New No
stdiostream.h New No
stream.h New No
strstream.h New No

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

There are no changes.

Library Interface Scripts

There are no changes.

Library Members (Object Files)

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

Table 589. Changes to Library Members (Object Files) for C++ Class Library Support

Library Member (Object File) Library Module Name New, Changed, or No Longer Supported? Type Description of Change
CSSDLL CISO Changed C Language Add the CPP2 name to the subsystem-shared DLL validation routine.

Link-Edited Modules

There are no changes.

Members (Object Files)

There are no changes.

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

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

There are no changes.

General Macros

There are no changes.

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

There are no changes.

System Initialization Program (SIP) Stage II Macros

Table 590 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 590. Changes to SIP Stage II Macros for C++ Class Library 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

There are no changes.

System Macros (IBM Use Only)

There are no changes.

Segments

There are no changes.

System Equates

There are no changes.

User Exits

There are no changes.

Functional and Operational Changes

There are no changes.

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 591 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 591. Changes to TPF Publications for C++ Class Library Support

Publication Title Softcopy File Name Description of Change
TPF Application Programming GTPAPP09 Updated with information about TPF restrictions using C++ class library support.
TPF Migration Guide: Program Update Tapes GTPMG200 Updated with migration considerations for C++ class library 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

This section provides migration scenario information for the I/O stream class libraries and the STLport standard template library.

I/O Stream Class Libraries

Use the following procedure to install I/O stream class libraries in your TPF 4.1 system:

  1. Make sure C++ support (APAR PJ25084) is installed in your TPF 4.1 system. See C++ Support (APAR PJ25084) for more information.
  2. Install program update tape (PUT) 10 in your TPF 4.1 system. Make sure you include APAR PJ26188 for open systems infrastructure. See Open Systems Infrastructure (APAR PJ26188) for more information about open systems infrastructure (APAR PJ26188).

Porting STLport Standard Template Library Version 3.01 from the WWW to the TPF 4.1 System

Use the following sets of procedures, in the order they are presented, to port STLport Standard Template Library Version 3.01 from the WWW to your TPF 4.1 system and then test it using the STLport test suite program:

Before you begin, do the following:

Obtaining STLport Standard Template Library Version 3.01 and the STLport Test Suite Program

Use the following procedure to obtain STLport Standard Template Library Version 3.01 and the modules in the STLport test suite program from the WWW:

  1. In the TPF Web page, click STLPort Standard Template Library to go to the IBM OS/390 C/C++ Standard Template Web page. You will find links on this Web page that enable you to download STLport Standard Template Library Version 3.01, the modules in the STLport test suite program, and the ibm390.mak file.
  2. Load the STLport standard template library from STLport Standard Template Library Version 3.01 into a hierarchical file system (HFS), which allows file names greater than 8 characters.

    If you want to use the STLport test suite program to test the STLport standard template library, continue with Making Setup Modifications for the TPF 4.1 System and Making Modifications to the Expected Results File for the TPF 4.1 System to modify the expected results file.

    If you do not want to test the STLport standard template library, there is no further action for you to take.

Making Setup Modifications for the TPF 4.1 System

You can use either the TPF C Debugger for VisualAge Client or the ibm390.mak file to compile the modules in the STLport test suite program. The ibm390.mak file uses the IBM OS/390 UNIX System Services in the IBM OS/390 environment as well as the Compile ANSI C/MVS Source Code and Create an Executable File command with CXX specified to compile the modules in the STLport test suite program. See OS/390 UNIX System Services Command Reference for more information about this command.

  1. Make sure you have completed the procedure Obtaining STLport Standard Template Library Version 3.01 and the STLport Test Suite Program.
  2. Edit the ibm390.mak file to change the STL_INCL=/stl line to include the HFS directory where you placed the STLport C++ header files. For example:
    STL_INCL=/u/stlport
    

    If you want to include additional libraries, separate each library by a blank and place -I (dash-capital I) in front of the second library, the third library, and so on. For example:

    STL_INCL=/u/stlport -I/u/lib2 -I/u/lib3
    
  3. Set the environment variables in your IBM OS/390 system to reference the correct data sets for compile, prelink, and link. For example:
    _CXX_INCDIRS,_CXX_PSYSIX,_CXX_PSYSLIB
    
  4. Set the following environment variables in your IBM OS/390 system:
  5. Uncomment the following line in the stlcomp.h header file to prevent a return code of 12 when compiling the uniqcpy1.cpp module in the STLport test suite program:

    Change: //# define _STL_NONTEMPL_BASE_MATCH_BUG 1

    To: # define _STL_NONTEMPL_BASE_MATCH_BUG 1

  6. Compile the modules in the STLport test suite program.
  7. Transfer the HFS files to an IBM OS/390 partitioned data set (PDS).
  8. Use the E-type loader to load the load module to the TPF 4.1 system. When you run the STLport test suite, the istmit1.cpp module issues a cin C++ function to obtain input.
  9. Use the TPF file system C functions to prime the input/output (I/O) buffer to contain the data for the cin C++ function. If you do not prime the I/O buffer, a CTL-4 system error occurs in the TPF 4.1 system when the cin C++ function tries to obtain input, but there is none available.

    Notes:

    1. See the TPF C/C++ Language Support User's Guide for more information about file system C functions that you can use to prime the I/O buffer.

    2. See the echo statement in the istmit1.out:istmit1.cpp section of the ibm390.mak file for the input data that should be primed.
  10. Run the STLport test suite in your TPF 4.1 system. You can start the STLport load module by running a program that issues the system C function to dispatch the modules in the STLport test suite program in the TPF 4.1 system. For example:
    system("STL1");
    
  11. Continue with Making Modifications to the Expected Results File for the TPF 4.1 System to modify the expected results file.

Making Modifications to the Expected Results File for the TPF 4.1 System

The STLport test suite program issues cout C++ functions to print results from the test cases. The STLport standard template library provides the stl_test.ibm390.exp expected-results file. You can use this file to compare your actual results.

The results file expects the output lines to be in the order in which the cout C++ functions were issued. However, because these output messages are not chained together, the TPF 4.1 system may not print the messages in the order in which the cout C++ functions were issued. To avoid this sequencing problem, use the file system functions to direct the output to a file on the TPF file system. See File System Support (APAR PJ25089) for more information about file system support and the TPF C/C++ Language Support User's Guide for more information about file system C functions.

You must edit and modify the actual results file before doing the comparison because of TPF-unique messages.

  1. Make sure you have completed the procedures Obtaining STLport Standard Template Library Version 3.01 and the STLport Test Suite Program and Making Setup Modifications for the TPF 4.1 System.
  2. Place your actual TPF results into a file and edit that file as follows:
    1. Remove all TPF messages such as the CSMP0097I header messages.
    2. Remove the space on any blank line. The TPF 4.1 system prints a space for back-to-back new-line escape sequences (\n\n).
    3. Remove any plus sign (+) line control that the TPF 4.1 system adds at the end of each message.
    4. The TPF 4.1 system replaces any plus sign (+) and greater-than sign (>) in a message with a period (.). Replace these periods with the correct character. For example, replace all dash/period (-.) combinations with dash/greater-than (->) combinations in the actuall results file.

    You are now ready to compare the actual results file with the expected results file.