December 6, 2006 This file contains corrections and additions to the OS/390 V2R10 C/C++ documentation. ======================================================================== 1. The OS/390 V2R6.0 C/C++ IBM Open Class Library User's Guide (SC09-2363 -03) has been reshipped for V2R10.0. Please observe the following when using this manual: Sections "About this Book" (topic FRONT_2) and "About IBM OS/390 C/C++" (topic FRONT_3) Please refer to these sections in any of the other V2R10 books in this library, as these sections have been updated for V2R10. ======================================================================== 2. The OS/390 V2R6.0 C/C++ IBM Open Class Library Reference (SC09-2364-04) has been reshipped for V2R10. Please observe the following when using this manual: Sections "About this Book" (topic FRONT_2) and "About IBM OS/390 C/C++" (topic FRONT_3) Please refer to these sections in any of the other V2R10 books in this library, as these sections have been updated for V2R10. --------------------------------------------------------------------- Messages 9900, 9901, 9902, 9903, 9904, 9905, and 9906 that are listed in Appendix B.3 Messages for Collection Class Library should all belong to Appendix B.1 Messages for I/O Stream and Complex Mathematics Class Libraries. --------------------------------------------------------------------- Two new messages have been added to Appendix B.2 Messages for Application Support Class Library -------------------------------------------------------------------- 9012 An attempt to allocate memory has failed. Explanation: The attempt at obtaining memory in order to satisfy the current library request has failed. Programmer Response: Run the program in a larger region or use the HEAP(,,FREE) run-time option instead of the HEAP(,,KEEP) option. System Action: The requested function will fail. -------------------------------------------------------------------- 9013 The referenced object is null. Explanation: Access to the referenced object failed. Programmer Response: Please make sure the IReference object has been properly constructed and point to a valid referenced object. System Action: None. ======================================================================== 3. The following information refers to the "INLRPT | NOINLRPT" compiler option section in Chapter 6 of the OS/390 V2R10 C/C++ User's Guide. As of the V2R10 release, the C and C++ inline report no longer specifies #pragma. The inline report contains reason characters, which provide an explanation for why a function is inlined or is not inlined. As of the V2R10 release, the meaning of the reason characters "F" and "P" has changed and a new reason character, "C", has been added. The reason "F", which means "inline was specified for this routine," can now be from #pragma inline for C or the inline keyword (or inline member function) for C++. The reason "P", which means "noinline was specified for this routine," can now be from #pragma noinline for both C and C++ if the COMPACT option is not specified. The reason "C", which means "compact was specified for this routine," can be from both C and C++ if COMPACT is specified in the compile command line or #pragma_override(FuncName,"OPT(COMPACT,yes)" is specified in the source code. As of the V2R10 release, "Called" and "Calls" in the actions section of the inline report, indicate how many times a function has been called or has called other functions, despite whether or not the callers or callees have been inlined. ======================================================================== 4. The following information refers to the "ROSTRING | NOROSTRING" compiler option section in Chapter 6 of the OS/390 V2R10 C/C++ User's Guide. The default for the ROSTRING option for C++ has been changed to ROSTRING. The default for the ROSTRING option for C remains the same or NOROSTRING. ======================================================================== 5. The following information refers to Chapter 6 of the OS/390 V2R10 C/C++ User's Guide. BOOL | NOBOOL +--------------------------------------------------------------------+ | Option Scope | +-------------+--------------+----------+----------------------------+ | | | | Special IPA Processing | | | | +--------------+-------------+ | C Compile | C++ Compile | IPA Link | IPA Compile | IPA Link | +-------------+--------------+----------+--------------+-------------+ | | yes | | | | +-------------+--------------+----------+--------------+-------------+ +--------------------------------------------------------------------+ | Option Default | +----------------------+---------------------------------------------+ | |Set by OS/390 UNIX System Services Utilities | | +---------------------------------------------+ | OS/390 C/C++ | Regular Compile | IPA Link | | Compiler (Batch and +---------------------------------------------+ | TSO Environments) | c89 | cc | c++ | c89 | cc | c++ | +----------------------+-------+-------+-------+------+------+-------+ | NOBOOL | | | yes | | | | +----------------------+-------+-------+-------+------+------+-------+ CATEGORY: Source Code Control >>--+-BOOL---+------------------------------------------------------>< +-NOBOOL-+ The BOOL option adds the bool functionality under option control. This option enables the ANSI 98 C++ language feature for the keyword bool, true, and false, as well as the supporting capabilities as bool interacts with existing C++ features already in the compiler. This is collectively called the bool feature. No other ANSI 98 C++ language feature is enabled. The default is to not enable the bool feature. If you turn on the BOOL option, you enable the recognition of the bool data type keyword. Note: We follow the C++ standard for the bool type. The following information in this note is a summary of the C++ standard. bool type is an integral type and has values of either true or false. It takes part in integral promotions. It can be converted into an int type; true is converted to 1 and false to 0. Integer, floating point, pointer and member pointer types can be converted to bool, zero (or null pointer) is converted to false, and all other values to true. The following operators take bool operands and produce a bool result: &&, || and ! The following operators produce a bool result: <, >, <=, >=, ==, != The test expressions in if, for, while and do statements, and the first operand of the conditional expression (..?..:) are converted to bool. Effect on IPA Compile Step The BOOL option is used for source code analysis, and has the same effect on IPA Compile step processing as it does on a regular compilation. Effect on IPA Link Step The IPA Link step accepts the BOOL option, but ignores it. ======================================================================== 6. APAR PQ55784: TRAP(ON) Requirement The OS/390 Language Environment run-time option TRAP(ON) should be set when using OS/390 C/C++. Refer to the OS/390 Language Environment for OS/390 & VM Programming Reference for details on the OS/390 Language Environment run-time options. ======================================================================== 7. The following information refers to Table 30. __last_op Codes and Diagnosis Information in Chapter 18 (Debugging I/O Programs) of the OS/390 V2R10 C/C++ Programming Guide: Further Information for __SVC99_UNALLOC should say Sets __alloc structure with info and error codes from SVC 99 unallocation. The __QSAM_CLOSE and __QSAM_OPEN codes do not exist. They should be __OS_CLOSE and __OS_OPEN instead. ======================================================================== 8. Compiling a program with virtual functions under C++ for OS/390 2.10 will generate a binder warning message IEW2689W. The message is issued even though the user is not exporting anything in the application and is not using XPLINK. If the application does not export any variables, and does not intend to be executed as a DLL, you can either: 1) Ignore the message as there will be no effect in execution. or 2) Use the -Wl,DLL option so the binder will create a side file. This will eliminate the warning and as the application is not intended to run as a DLL you may discard the side file that is created. ======================================================================== 9. The DYNAM/NODYNAM Prelinker option can be used to prevent the Prelinker from generating export symbols. If there are export symbols, they are simply ignored. ======================================================================== 10. The following information applies to "Under TSO Command" in Chapter 3 of the C/C++ Language Reference: The description for argv[1 to n] should be replaced by the following: argv[1 to n] Arguments entered in uppercase are returned in lowercase. Arguments entered in mixed or lowercase are returned as entered. ======================================================================== 11. Statement line numbers exceeding 99999 will wrap back to 00000 for the generated assembly listing for the C/C++ source file. This may occur when the compiler LIST option is used. ======================================================================== 12. The following change applies to the "TARGET Os/390 Release Suboptions" section of Chapter 6 in the OS/390 C/C++ User's Guide: The reference to __LIBREL__ macro has been removed from the following statement and the statement should now be as follows: When you invoke the TARGET(OSVxRy) release suboptions, the compiler sets the __TARGET_LIB__ macro. See the OS/390 C/C++ Language Reference for more information on this macro. ======================================================================== 13. The OS/390 C/C++ Compiler and Run-Time Migration Guide, Part 2. "From C/370 to OS/390 V2R10 C/C++", Chapter 4. "Source Program Compatibility" contains a section titled "The release() Function". This section is incorrect, and should be ignored. The limitation described in this section - the inability to issue a release() instruction against a fetched COBOL, Fortran, or PL/I module, or against OS/390 Language Environment-enabled assembler routines - no longer exists. ======================================================================== 14. The following change applies to the XPLINK and GOFF compiler option descriptions in Chapter 6 of the OS/390 C/C++ User's Guide: When using XPLINK or GOFF and source files with duplicate filenames, the linker may emit an error and discard one of the code sections. In this case, turn off the CSECT option by specifying NOCSECT. ======================================================================== 15. The following information applies to the FLOAT compiler option description in Chapter 6 of the OS/390 V2R10 C/C++ User's Guide: FLOAT(AFP(VOLATILE|NOVOLATILE)) The AFP(VOLATILE) suboption for the FLOAT compiler option enables you to flag the AFP registers 8-15 as volatile, which means they are not expected to be preserved by the called program. Note: The AFP registers are 1, 3, 5, 7 and 8-15. However, the AFP registers 0-7 are always considered volatile. The AFP(VOLATILE) suboption prevents AFP registers from becoming corrupted if the application runs in a CICS environment where the AFP registers are not preserved across task switching. When AFP(VOLATILE) is specified, the compiler generates extra code to protect the values in these registers. When no suboption is specified for AFP, the default is NOVOLATILE, which is exactly the same as specifying FLOAT(AFP). Notes: 1. The option FLOAT(AFP(VOLATILE)) is not supported by IPA. If the option FLOAT(AFP(VOLATILE)) is passed to the IPA compile or link phase, then the IPA phase will emit a severe diagnostic message. 2. The use of the AFP(VOLATILE) sub-option to save the contents of AFP registers across calls could have an impact on performance. The user should evaluate the performance costs prior to using this suboption. The following information applies to the OS/390 V2R10 C/C++ Compiler and Run-Time Migration Guide: The FLOAT(AFP) option instructs the compiler to generate code which makes use of the full complement of 16 floating point registers. These include the four original floating-point registers, numbered 0, 2, 4, and 6, and the Additional Floating Point (AFP) registers, numbered 1, 3, 5, 7 and 8 through 15. FLOAT(AFP) supports the VOLATILE | NOVOLATILE suboption. The default is NOVOLATILE. The NOVOLATILE suboption instructs the compiler to treat AFP registers 8-15 as non-volatile, i.e., the compiler assumes that any called subroutines will preserve the values in these registers. This convention is followed by code generated by the XL C/C++ compiler. It is safe to use NOVOLATILE under most environments. You can instruct the compiler to treat AFP registers 8-15 as volatile by specifying FLOAT(AFP(VOLATILE)), i.e., the compiler will generate instructions to save and restore the values in these registers across function calls. If you have C/C++ code which uses floating-point data types and which is to run under CICS, there is potential risk of data corruption or data loss or the program abending if the code is not compiled with the appropriate FLOAT sub-options. If the code is compiled with the old FLOAT(AFP) option or the new FLOAT(AFP(NOVOLATILE)) option, the code is at risk. The Load Module Analyzer (LMA) tool, described at http://www-1.ibm.com/ support/docview.wss?rs=1083&context=SSGMGV&dc=D400&uid= swg24010925&loc=en_US&cs=UTF-8&lang=en&rss=ct1083other can be used to identify which parts of the module are exploiting AFP registers 8-15. These parts should then be recompiled with FLOAT(AFP(VOLATILE) to correct the problem. Note that parts compiled with FLOAT(AFP(VOLATILE)) will be identified by LMA as using AFP registers 8-15. This is normal - the tool is detecting that the compiler has generated code to save and restore the registers, and there's no need to recompile code which is already built FLOAT(AFP(VOLATILE)). If the code is later changed, care must be taken to avoid introducing the potential risk of data corruption, etc., i.e., if floating point data types are added to the code, the parts containing the changed code must be compiled with FLOAT(AFP(VOLATILE)). CICS does its own task switching and does not preserve the AFP registers 8 through 15. CICS programs that have floating-point operations and use the AFP option must therefore set the VOLATILE suboption explicitly. There are no other environments known to have this issue, such as batch programs, since the full set of AFP registers are saved by the operating system during task switching. ======================================================================== 16. The following information applies to the #pragma pack description in Chapter 10 of the OS/390 V2R10 C/C++ Language Reference. The following description for the full suboption is incorrect: Is 4-byte boundary alignment. It is the system default boundary alignment. This is the same as #pragma pack() and #pragma pack(4). Instead, the description should state the following: Is 4-byte boundary alignment. This is the same as #pragma pack() and #pragma pack(4). ======================================================================== 17. The following information applies to Example 5 for SEARCH(LIB1.*,LIB2.+,LIB3) #include in Chapter 9 of the OS/390 V2R10 C/C++ User's Guide: The following information is incorrect: second opt in SEARCH PDS = userid.SYS(NAME@1) It should be the following: second opt in SEARCH PDS = userid.LIB2.SYS(NAME@1)