This file contains corrections and additions to the OS/390 2.9.0 C/C++ documentation. Revision tags (|) have been inserted into this file to show where the corrections and additions occur. ======================================================================== 1. The OS/390 V2R4.0 C/C++ SOM-Enabled Class Library User's Guide and Reference (SC09-2366-02) has been reshipped for V2R9.0. Please observe the following when using this manual: a. In this release of OS/390, "OpenEdition" has been renamed to "OS/390 UNIX System Services" or "OS/390 UNIX" (the short form). Interpret any reference to "OpenEdition" in this book as "OS/390 UNIX". b. 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 V2R9.0 books in this library, as these sections have been updated for V2R9.0. ======================================================================== 2. The OS/390 V2R6.0 C/C++ IBM Open Class Library User's Guide (SC09-2363 -03) has been reshipped for V2R9.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 V2R9.0 books in this library, as these sections have been updated for V2R9.0. ======================================================================== 3. The OS/390 V2R6.0 C/C++ IBM Open Class Library Reference (SC09-2364-04) has been reshipped for V2R9.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 V2R9.0 books in this library, as these sections have been updated for V2R9.0. --------------------------------------------------------------------- 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. ======================================================================== 4. The following information replaces the "Changes for Version 2 Release 9" section of the OS/390 V2R9.0 C/C++ User's Guide, OS/390 V2R9.0 C/C++ Programming Guide, and OS/390 V2R9.0 C/C++ Language Reference. Note: For details on how to use these compiler options, see the chapter named "Compiler Options" in the OS/390 V2R9.0 C/C++ User's Guide. OS/390 C/C++ has also introduced the following #pragma directives: leaves Specifies that a named function never returns to the instruction following the call to that function. This pragma provides information to the compiler that enables it to explore additional opportunities for optimization. For details on using this directive, see "leaves" in topic 2.8.14.19. of the OS/390 V2R9.0 C/C++ Language Reference. | option_override Defines subprogram (C function, C++ method) specific options | that override those specified by the command line options when performing optimization for code and data in that subprogram. This enables finer control of program optimization. | The subprogram-specific OPTIMIZE option leaves specified | functions unoptimized, while optimizing the rest of your | application. | The subprogram-specific STRICT option allows you to have | rigidly controlled computational operations in some subprograms, | while allowing faster operations where this control is not | required. | For details on using this directive, see "option_override" in | topic 2.8.14.26 of the OS/390 V2R9.0 C/C++ Language Reference. | reachable | Specifies that during execution, the program can reach the | instruction after a specified function from a point in the | program other than the return statement in the named | function. | This pragma provides information to the compiler that | enables it to explore additional opportunities for | optimization. For details on using this directive, see | "reachable" in topic 2.8.14.31 of the | OS/390 V2R9.0 C/C++ Language Reference. a) The following information replaces the "option_override" section of the OS/390 V2R9.0 C/C++ Language Reference (2.8.14.26): | With the #pragma option_override directive, you can specify | optimization with more granularity in your applications. Specifically, | this pragma defines subprogram (C function, C++ method) specific | options that override those specified by the command line options | when performing optimizations for code and data in that subprogram. | This enables finer control of program optimization. | * The subprogram-specific OPTIMIZE option leaves specified functions | unoptimized, while optimizing the rest of your application. | One use of this directive is to isolate coding errors that occur | only under optimization. | * The subprogram-specific STRICT option allows you to have rigidly | controlled computational operations in some subprograms, while | allowing faster operations where this control is not required. ---------------------------------------------------------------------- >>--#--pragma--option_override--> <---------------------+ | >--(--function_name----,----"--option--"---+--)-->< ---------------------------------------------------------------------- In the above syntax diagram, option translates to the following equivalent OS/390 C/C++ option settings: option_override Value Equivalent Option Setting LEVEL, 0 OPT(0) LEVEL, 1 OPT(1) LEVEL, 2 OPT(2) STRICT STRICT STRICT, YES STRICT STRICT, NO NOSTRICT To use the LEVEL sub-option, you must specify a non-zero optimization level for your program, otherwise, the compiler ignores it. All other cases are meaningful, including increasing the optimization level. The #pragma option_override directive only affects functions that are defined in the compile unit. The pragma directive can appear anywhere in the compilation unit. That is, it can appear before or after the function definition, before or after the function declaration, before or after the function has been referenced, and inside or outside the function definition. Specifying this directive only affects the setting of the options you have specified. It does not affect the setting of any related options. Notice that option can be enclosed in double quotation marks, so the options are not subject to macro expansion. Following is an example of how you might use this directive. Suppose you compile the following code fragment containing the functions foo() and faa() using OPT(1). Since it contains the #pragma | option_override(faa,"OPT(LEVEL, 0)"), function faa() will not be optimized. foo(){ . . . } #pragma option_override(faa, "OPT(LEVEL, 0)") faa(){ . . . } (3) This pragma directive maintains compatiblity with the AIX platform, even though the compiler options supported on the OS/390 and AIX platforms are not the same. Thus, the option syntax for this directive is different from the OS/390 C/C++ command line option syntax for the same option. Within this directive, options are grouped by category. OPT here | signifies optimization-related options. Within the category are the actual options. The optimization-related options are LEVEL (equivalent to the command line option OPTIMIZE) and STRICT (equivalent to the command line option STRICT). This | syntax attempts to be sufficiently platform-neutral such that | this directive is portable between different platforms. 2.8.14.26.1 IPA Considerations You cannot specify the IPA compile-time option for #pragma option_override. | During IPA Compile processing, subprogram-specific options will be | used to control IPA Compile-time optimizations. | During IPA Link processing, subprogram-specific options will be | used to control IPA Link-time optimizations, as well as program | partitioning. They will be retained, even if the related IPA Link | command line option is specified. | Refer to the OS/390 C/C++ User's Guide for descriptions of how | different subprogram-specific compile options affect IPA processing. ======================================================================== 5. The following information replaces the "Effect on IPA Link step" section for the FLOAT compiler option in the OS/390 V2R9.0 C/C++ User's Guide: The IPA Link step merges and optimizes the application's code, and then divides it into sections for code generation. Each of these sections is a partition. The IPA Link step uses information from the IPA Compile step to determine if a subprogram can be placed in a particular partition. Only compatible subprograms are included in a given partition. Compatible subprograms have the same floating-point mode, and the same values for the FLOAT suboptions, and the ROUND and STRICT options: ... * STRICT option The value of the STRICT option for a partition is set to the value of the first subprogram that is placed in the partition. During IPA inlining, subprograms with different STRICT settings may be combined in the same partition. When this occurs, the resulting partition is always set to STRICT. You can override the setting of STRICT by specifying the option on | the IPA Link step. If you do so, the Prolog section of the IPA Link | step listing will display the value. | * If there are no Compilation Units with subprogram-specific | STRICT options, all partitions will have the same STRICT value. | * If there are any Compilation Units with subprogram-specific | STRICT options, separate partitions will continue to be generated | for those subprograms with a STRICT option which differs from the | IPA Link option. The Partition Map sections of the IPA Link step listing and the object module display the value of the STRICT option. ======================================================================== 6. Note: Refer to the OS/390 V2R9.0 C/C++ User's Guide for the option scope table, option default table, and syntax diagram for OPTIMIZE | NOOPTIMIZE. The following information replaces the "OPTIMIZE | NOOPTIMIZE" compiler option section (2.3.16.47) in the OS/390 V2R9.0 C/C++ User's Guide: The OPTIMIZE option instructs the compiler to optimize the generated machine instructions to produce a faster running object module. This type of optimization can also reduce the amount of main storage that is required for the generated object module. Using OPTIMIZE will increase compile time over NOOPTIMIZE and may have greater storage requirements. | During optimization, the compiler may move code to increase run-time efficiency; as a result, statement numbers in the program listing may not correspond to the statement numbers used in run-time messages. | A list of the valid suboptions for OPT and their descriptions follows: level can have the following values: 0 Indicates that no optimization is to be done; this is equivalent to NOOPTIMIZE. You should use this option in the early stages of your application development since the compilation is efficient but the execution is not. This option also allows you to take full advantage of the debugger. | 1 OPTIMIZE(1) is an obsolete artifact of the Version 2 Release 4 compiler. We suggest that you use OPTIMIZE(2), which ensures that you will have compatibility with future compilers. 2 Indicates that global optimizations are to be performed. You should be aware that the size of your functions, the complexity of your code, the coding style, and support of the ANSI standard may affect the global optimization of your program. You may need significant additional memory to compile at this optimization level. | no level OPTIMIZE specified with no level defaults, depending on the | compilation environment and IPA mode. See the Option Default | table in the OS/390 V2R9.0 C/C++ User's Guide for details. | In the OS/390 UNIX System Services environment, this option is turned | on by specifying -O (the letter) or -0 (the number), -1, or -2 when | using the c89, cc, or c++ commands. | You can specify this option using the #pragma option directive for C. | You can specify this option for a specific subprogram using the | #pragma option_override(subprogram_name, OPT(LEVEL,n)) directive. | The OPTIMIZE option will control the overall optimization value. Any | subprogram-specific optimization levels specified at compile time by | #pragma option_override(subprogram_name, OPT(LEVEL,n)) directives will | be retained. Subprograms with an OPT(LEVEL,0)) value will receive | minimal code generation optimization. Inlining is also affected. Inlining of functions in conjunction with other optimizations provides optimal run time performance. See "INLINE | NOINLINE" in topic 2.3.16.30 for more information about the INLINE option and the OS/390 C/C++ Programming Guide for more information about optimization. If you specify OPTIMIZE with TEST, you can only set breakpoints at function call, function entry, function exit, and function return points. The option INLINE is automatically turned on when you specify OPTIMIZE, unless you have explicitly specified the NOINLINE option. A comment that notes the level of optimization will be generated in your object module to aid you in diagnosing your program. Effect of ANSIALIAS: When the ANSIALIAS option is specified, the optimizer assumes that pointers can point only to objects of the same type, and performs more aggressive optimization. However, if this | assumption is not true and ANSIALIAS is specified, wrong program code may be generated. If you are not sure, use NOANSIALIAS. For more information, see "ANSIALIAS | NOANSIALIAS" in topic 2.3.16.4 of the OS/390 V2R9.0 C/C++ User's Guide. | 2.3.16.47.1 Effect on IPA(OBJONLY) Compilation | During a compilation with IPA compile-time optimizations active, any | subprogram-specific optimization levels specified by #pragma | option_override(subprogram_name, OPT(LEVEL,n)) directives will be | retained. Subprograms with an OPT(LEVEL,0)) value will receive minimal | IPA and code generation optimization. Inlining is also affected. 2.3.16.47.1 Effect on IPA Compile Step On the IPA Compile step, all values (except for (0)) of the OPTIMIZE compiler option and the OPT suboption of the IPA option have an equivalent effect. | Refer to the descriptions of the OPTIMIZE and LEVEL suboptions of the | IPA option in "IPA | NOIPA" topic 2.3.16.32 for information about using the OPTIMIZE option under IPA. 2.3.16.47.2 Effect on IPA Link Step | OPTIMIZE(2) is the default for the IPA Link step, but you can specify | any level of optimization. The IPA Link step Prolog listing section | will display the value of this option. | This optimization level will control the overall optimization value. | Any subprogram-specific optimization levels specified at IPA Compile | time by #pragma option_override(subprogram_name, OPT(LEVEL,n)) | directives will be retained. Subprograms with an OPT(LEVEL,0)) value | will receive minimal IPA and code generation optimization, and will | not participate in IPA Inlining. | The IPA Link step merges and optimizes your application's code, and | then divides it into sections for code generation. Each of these | sections is a partition. The IPA Link step uses information from the | IPA Compile step to determine if a subprogram can be placed in a | particular partition. Only compatible subprograms are included in a | given partition. Compatible subprograms have the same OPTIMIZE setting. | The OPTIMIZE setting for a partition is set to that of the first | subprogram that is placed in the partition. Subprograms that follow are | placed in partitions that have the same OPTIMIZE setting. A OPTIMIZE(0) | mode is placed in a OPTIMIZE(0) partition, and a OPTIMIZE(2) is placed | in a OPTIMIZE(2) partition. | The option value that you specified for each IPA object file on the IPA | Compile step appears in the IPA Link step Compiler Options Map listing | section. | The Partition Map sections of the IPA Link step listing and the object | module END information section display the value of the OPTIMIZE option. | The Partition Map also displays any subprogram-specific OPTIMIZE values. If you specify OPTIMIZE(1) or OPTIMIZE(2) for the IPA Link step, but only OPTIMIZE(0) for the IPA Compile step, your program may be slower or larger than if you specified OPTIMIZE(1) or OPTIMIZE(2) for the IPA Compile step. This situation occurs because the IPA Compile step does not perform as many optimizations if you specify OPTIMIZE(0). Refer to the descriptions for the OPTIMIZE and LEVEL suboptions of the IPA option in "IPA | NOIPA" in topic 2.3.16.32 for information about using the OPTIMIZE option under IPA. ======================================================================== 7. Note: Refer to the OS/390 V2R9.0 C/C++ User's Guide for the option scope table, option default table, and syntax diagram for ROCONST | NOROCONST. The following information replaces the ROCONST | NOROCONST compiler option section (2.3.16.54) in the OS/390 V2R9.0 C/C++ User's Guide: The ROCONST option informs the compiler that the const qualifier is respected by the program. Variables defined with the const keyword will not be overridden by a casting operation. Use ROCONST with the RENT option so that a const variable is not placed into the Writeable Static Area. This reduces the memory requirement for DLLs. This option has the same effect for all const variables as the #pragma variable(var_name, NORENT) directive. See the OS/390 C/C++ Language Reference for more information on pragma directives. | Note that such const variables cannot be exported. (See #pragma export | below.) 2.3.16.54.1 Interaction with #pragma variable If the specification for a const variable in a #pragma variable directive is in conflict with the option, the pragma variable takes precedence. The compiler issues an informational message. 2.3.16.54.2 Interaction with #pragma export If you set the ROCONST option, and if there is a #pragma export for a | const variable, which also has a #pragma variable (..., RENT), the pragma directive takes precedence. The variable will still be exported | and the variable will be reentrant. If there is no #pragma variable | (..., RENT), the variable will not be exported. 2.3.16.54.3 Effect on IPA Compile Step If you specify the ROCONST option during the IPA Compile step, the information in the IPA object file reflects the state of each symbol. 2.3.16.54.4 Effect on IPA Link Step If you specify the ROCONST option on the IPA Link step, it ignores | the option. The reentrant/nonreentrant and const/nonconst | states of each symbol are maintained during IPA optimization | and code generation. | The IPA Link step merges and optimizes your application's code, and | then divides it into sections for code generation. Each of these | sections is a partition. The IPA Link step uses information from the | IPA Compile step to determine if a subprogram can be placed in a | particular partition. Only compatible subprograms are included in a | given partition. Compatible subprograms have the same ROCONST setting. | The ROCONST setting for a partition is set to the specification of the | first subprogram that is placed in the partition. Subprograms that | follow are placed in partitions that have the same ROCONST setting. | A NOROCONST mode is placed in a NOROCONST partition, and a ROCONST is | placed in a ROCONST partition. | The option value that you specified for each IPA object file on the IPA | Compile step appears in the IPA Link step Compiler Options Map listing | section. | The RENT, ROCONST, and ROSTRING options all contribute to the | reentrant/nonreentrant state for each symbol. If any symbols within a | partition are reentrant, the option section of the Partition Map displays | the RENT compiler option. | The Partition Map sections of the IPA Link step listing and the object | module END information section display the value of the ROCONST option. ======================================================================== 8. Note: Refer to the OS/390 V2R9.0 C/C++ User's Guide for the option scope table, option default table, and syntax diagram for STRICT | NOSTRICT. The following information replaces the STRICT | NORSTRICT compiler option section (2.3.16.71) in the OS/390 V2R9.0 C/C++ User's Guide: The STRICT option instructs the compiler to perform computational | operations in a rigidly-defined order such that the results are always determinable and recreatable. NOSTRICT allows the compiler to reorder certain computations for better | performance. However, the end result may differ from the result obtained | when STRICT is specified. In IEEE floating-point mode, NOSTRICT turns on FLOAT(MAF) unless you explicitly specify FLOAT(NOMAF). | You can specify this option for a specific subprogram using the | #pragma option_override(subprogram_name, OPT(STRICT)) directive. 2.3.16.71.1 Effect on IPA Compile Step The IPA Compile step generates information for the IPA Link step. This option also affects the regular object module if you request one by specifying the IPA(OBJECT) option. 2.3.16.71.2 Effect on IPA Link Step The IPA Link step merges and optimizes the application's code, and then divides it into sections for code generation. Each of these sections is a partition. The IPA Link step uses information from the IPA Compile step to ensure that an object is included in a compatible partition. See "FLOAT" in topic 2.3.16.23 for more information on the effect of the STRICT option on the IPA Link step. ======================================================================== 9. For the ARCHITECTURE compiler option, which is described in the OS/390 C/C++ User's Guide, the 9672-Rx3 (G2) processor should be listed as an ARCH(2) processor instead of an ARCH(1) processor. ======================================================================== 10. APAR PQ33356 Codeset Conversion Using UCS-2 Additional values have been added to the _ICONV_UCS2 environment variable in support of direct unicode converters. The following information is being added to the OS/390 C/C++ Programming Guide, in Chapter 54. Code Set Conversion Utilities, in the section, "Codeset Conversion Using UCS-2." OS/390 C/C++ iconv supports use of UCS-2 as an intermediate code set for conversion of characters encoded in one code set to another. The _ICONV_UCS2 environment variable instructs iconv_open("Y", "X") on whether or not to set up indirect conversion from code set X to code set Y using UCS-2 as an intermediate code set. Values iconv_open() recognizes for _ICONV_UCS2 are: 1 Set up indirect conversion using UCS-2 first. The indirect conversions will use direct unicode converters if available. If not, iconv_open() will fopen/fread uconvTable binaries. If the set up of indirect conversion fails, iconv_open() will try to set up direct conversion. 2 Set up direct conversion first. If this fails, try to set up indirect conversion using UCS-2. The indirect conversions will use direct unicode converters if available. If not, iconv_open() will fopen/fread uconvTable binaries. This is the default. 3 Set up direct conversion first. If this fails, try to set up indirect conversion using UCS-2. The indirect conversions will use direct unicode converters. If direct unicode converters are unavailable, the iconv_open() request fails. N Never set up indirect conversion using UCS-2. If a direct converter cannot be found, the iconv_open() request fails. D Never set up indirect conversion using UCS-2. If a direct converter cannot be found, the iconv_open() request fails. O Only set up indirect conversion using UCS-2. iconv_open() will fopen/fread uconvTable binaries. Direct unicode converters will not be used. If required unconvTable binaries cannot be found, the iconv_open() request fails. U Only set up indirect conversion using UCS-2. The indirect conversions will use direct unicode converters if available. If not, iconv_open() will fopen/fread uconvTable binaries. Notes: If the value of the _ICONV_UCS2 environment variable allows iconv_open("Y", "X") to use UCS-2 as an intermediate code set when it cannot find a direct converter from X to Y, iconv_open() will attempt to do so even if X and Y are not compatible code sets. That is, even if character sets encoded by X and Y are not the same, iconv_open() will set up conversion from X to UCS-2 to Y. The application must specify compatible source and target code set names on various iconv_open() requests. For example, this can be accomplished by using a code set registry such as is used by DCE to prevent iconv setup for conversion from incompatible code sets. ======================================================================== 11. APAR II11576: Developing Applications with the Class Libraries and OS/390 In the TARGET OS/390 Release Sub-options section of the OS/390 V2R9.0 C/C++ User's Guide, there is the following reference to the Informational APAR for the class library: "For information on using previous releases of the class libraries and Language Environment, refer to Informational APARs II14576 and II11316." The APAR number II14576 is incorrect for the class library. It should be II11576. ======================================================================== 12. 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. ======================================================================== 13. APAR PQ68700: Prelinker Support for DYNAM/NODYNAM The prelinker now supports a DYNAM/NODYNAM option to control the exporting of symbols. If you compile with the EXPORTALL compiler option, or use #pragma export in your program source code, symbols will be marked as exported in the object file. You can suppress these exports during the prelink step by using the NODYNAM prelinker option (only the export status of the symbols is suppressed; the definition of the symbols themselves is otherwise unchanged). The default is DYNAM, which exports any symbols specified in the compile step.