December 6, 2006 This file contains corrections and additions to the z/OS 1.5.0 C/C++ documentation. 1. The following change applies to the XPLINK and GOFF compiler option descriptions in Chapter 4 of the z/OS V1R5 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. ======================================================================== 2. The following revision refers to the description of the OBJECT|NOOBJECT|OBJONLY suboptions of the IPA compiler option in Chapter 4 of the z/OS V1R5 C/C++ User's Guide: The default is IPA(OBJECT). The abbreviations are IPA(OBJ|NOOBJ| OBJO). Note: If IPA is invoked via c89, the default suboption is NOOBJECT. ======================================================================== 3. The following change applies to the HTML version of the z/OS V1R5 C/C++ User's Guide that is available from the z/OS C/C++ web site. In Chapter 4, a table should appear after the syntax diagram for the TEST compiler option. It is currently formatted incorrectly. The table should appear as follows: +-----------------------------------------------------------------+ |HOOK | NOHOOK | When NOOPT is in effect | When OPT is in effect | +-----+--------+--------------------------+-----------------------+ |HOOK | - For C++ compile, | - Generates Function | | | generates all possible | Entry, Function | | | hooks. | Call and Function | | | - For C compile, | Return hooks. | | | generates all | - Does not generate | | | possible hooks based | symbol information. | | | on current settings of | | | | BLOCK, LINE, and PATH | | | | suboptions. | | | | For IPA Link, | | | | generates Function | | | | Entry, Function Exit, | | | | Function Call, and | | | | Function Return hooks. | | | | - For C++ compile, | | | | generates symbol | | | | information. | | | | For C compile, | | | | generates symbol | | | | information unless | | | | NOSYM is specified. | | | | For IPA Link, does not | | | | generate symbol | | | | information. | | +--------------+--------------------------+-----------------------+ |NOHOOK | - Does not generate any | - Does not generate | | | hooks. | any hooks. | | | - For C++ compile, | - Does not generate | | | generates symbol | symbol information. | | | information. | | | | For C compile, | | | | generates symbol | | | | information based on | | | | the current settings | | | | of SYM and BLOCK. | | | | For IPA Link, does not | | | | generate any symbol | | | | information. | | +--------------+--------------------------+-----------------------+ ======================================================================== 4. The following changes apply to the catalogued procedures in Chapter 7 and Appendix D in the z/OS V1R5 C/C++ User's Guide. Any references to CCNPD1L should be replaced by CCNPD1B and any references to CCNXPD1L should be replaced by CCNXPD1B. ======================================================================== 5. The following change applies to the TUNE compiler option description in Chapter 4 of the z/OS V1R5 C/C++ User's Guide. The Option Default table states that if the TUNE level is lower than the specified ARCH level, the compiler forces TUNE to match the ARCH level. This statement should be replaced by the following: If the TUNE level is lower than the specified ARCH level, the compiler forces TUNE to match the ARCH level, or use the default TUNE level, whichever is greater. ======================================================================== 6. The following changes apply to the NAMEMANGLING compiler option description in Chapter 4 of the z/OS V1R5 C/C++ User's Guide and the #pragma namemangling directive description in Chapter 9 of the z/OS V1R5 C/C++ Language Reference. The zOSV1R2 and OSV2R10 suboptions have been added to the NAMEMANGLING compiler option and the #pragma namemangling directive. NAMEMANGLING(zOSV1R2) instructs the compiler that the name mangling scheme is compatible with z/OS V1R2 link modules that were created with NAMEMANGLING(ANSI). NAMEMANGLING(OSV2R10) instructs the compiler that the name mangling scheme is compatible with OS/390 V2R10 and versions prior to OS/390 V2R10. A new #pragma namemanglingrule directive has been added that instructs the compiler on whether or not to mangle function names according to their function parameter types within the already specified name mangling scheme. ======================================================================== 7. The following changes apply to the DEBUG compiler option description in Chapter 4 of the z/OS V1R5 C/C++ User's Guide. The description for the HOOK suboption has been changed to: HOOK DEFAULT: HOOK(ALL) for NOOPTIMIZE, HOOK(NONE,PROFILE) for OPTIMIZE Controls the generation of LINE, BLOCK, PATH, CALL, and FUNC hook instructions. Hook instructions appear in the compiler pseudo assembly listing in the following form: EX r0,HOOK..[type of hook] The type of hook that each hook suboption controls is summarized in the list below: - LINE – STMT - General statement - BLOCK – BLOCK-ENTRY - Beginning of block – BLOCK-EXIT - End of block – MULTIEXIT - End of block and procedure - PATH – LABEL - A label – DOBGN - Start of a loop – TRUEIF - True block for an if statement – FALSEIF - False block for an if statement – WHENBGN - Case block – OTHERW - Default case block – GOTO - Goto statement – POSTCOMPOUND - End of a PATH block - CALL – CALLBGN - Start of a call sequence – CALLRET - End of a call sequence - FUNC – PGM-ENTRY - Start of a function – PGM-EXIT - End of a function There is also a set of shortcuts for specifying a group of hooks: NONE It is the same as specifying NOLINE, NOBLOCK, NOPATH, NOCALL, or NOFUNC. It instructs the compiler to suppress all hook instructions. ALL It is the same as specifying LINE, BLOCK, PATH, CALL, or FUNC. It instructs the compiler to generate all hook instructions. This is the ideal setting for debugging purposes. PROFILE It is the same as specifying CALL or FUNC. It is the ideal setting for tracing the program with the Performance Analyzer. The description for the SYMBOL suboption has been changed to: SYMBOL DEFAULT: SYMBOL(BLOCK) for NOOPT, NOSYMBOL for OPT Generates symbol information that gives you access to variable and other symbol information. The BLOCK suboption has no effect on the generated debug information. This suboption is reserved for future use. ======================================================================== 8. The following change applies to the LANGLVL compiler option description in Chapter 4 of the z/OS V1R5 C/C++ User's Guide. The macro __ANSI__ is not supported for C++. ======================================================================== 9. The following change applies to the IGNERRNO compiler option description in Chapter 4 of the z/OS V1R5 C/C++ User's Guide. For NOOPT and OPT(2), the default is NOIGNERRNO. For OPT(3), the default is IGNERRNO. ======================================================================== 10. The following information applies to Chapter 6 of the z/OS V1R5 C/C++ Compiler and Run-Time Migration Guide. Compilation procedures In z/OS V1R5 C/C++, a change was made to the STEPLIBs used on all PROCs that have compilation steps. The SCEERUN2 data set was added in addition to the SCEERUN data set on the compile STEPLIB. Every effort was made to make this addition in a way that would not affect existing JCL overrides. Users who have JCL that overrides the STEPLIB in the compile step of a PROC should verify that their overrides are still sufficient. ======================================================================== 11. The following information applies to Chapter 15 of the z/OS V1R5 C/C++ Compiler and Run-Time Migration Guide. Inlined virtual functions in a class Whenever a virtual function exists in a class, the compiler generates a virtual function table for the class and stores a pointer to the table. For any class that has at least one virtual function that is not defined as inline, the compiler can generate the virtual function table in the same module as the definition of the first non-inlined virtual function. Only one copy of the virtual function table for a class will exist. However, when all virtual functions for a class are inlined, the compiler has insufficient information to generate a unique virtual function table, and instead, generates a virtual function table in each module that uses the class. In the implementation of V2R10, a virtual function table was static, making it invisible to the binder. Starting in z/OS V1R2, the virtual function table is visible to the binder. Therefore, in the situation where a class has inlined virtual functions, the binder detects the virtual function tables in more than one module and generates duplicate object warnings, which were not emitted by the V2R10 compiler. ======================================================================== 12. The following information applies to the "Passing Function Arguments" section in Chapter 26 of the z/OS V1R5 C/C++ Programming Guide. Linkage convention or how arguments are passed is not specified in the C language, but is defined by the platform. Compilers in general follow the calling convention as described by the Application Binary Interface (ABI). An ABI can define more than one linkage due to performance considerations; for example, the XPLINK and non-XPLINK linkages on the z/OS platform. To correctly invoke a function, the arguments passed must match the parameters as defined in the function definition. For example, if you pass a pointer argument to a function expecting an integer, the code generated by the compiler for the call and for the function definition may not match. See the note at the end of this section of the readme. You can declare a function without providing information about the number and types of its parameters. For example: int func(); ... int a; func(a); ... int func(p) void *p; { ... } Because the function declaration has no parameter information, the compiler is not required to diagnose parameter mismatch. You can call this function, passing it any number of arguments of any type, but the compilation will not be guaranteed to work if the function is not defined to receive the arguments as passed, due to differences in linkage conventions. In the worse case, when the z/OS C/C++ compiler attempts inlining of such ill-formed function calls, it may get into an unrecoverable condition and the compilation is halted. To correct the situation, use the CHECKOUT(GEN) option to identify missing function declarations and non-prototype function declarators. Add or change the declarations to prototyped declarations, and proceed with compilation again. Should you receive diagnostic messages regarding incorrect function argument assignment, change the function call to pass the expected parameter type. Note: Such a mismatch may sometimes turn out not to be an issue, depending on the ABI; for example, if the ABI happens to allow both pointers and integers passed using general purpose registers. Even in this case, there is no guarantee that the optimized code would work as expected due to ambiguous information received by the compiler. ======================================================================== 13. The following information applies to the PLIST compiler option description in Chapter 4 of the z/OS V1R5 C/C++ User's Guide. If you specify PLIST(HOST), the parameters are presented to main() as an argument list (argv, argc). This information is incorrect. The argument list should be (argc, argv). ======================================================================== 14. The following information applies to the "Primary input (SYSIN)" description in Appendix A of the z/OS V1R5 C/C++ User's Guide. If the primary input to the prelinker consists of a mix of object modules and include control statements, include control statements must be placed last (or after all object modules). ======================================================================== 15. The following information applies to the FLAG compiler option description in chapter 4 of the z/OS V1R5 C/C++ User's Guide. The NOFLAG option is the same as the FLAG(S) option. This information is incorrect. It should state that the NOFLAG option is the same as the FLAG(U) option. ======================================================================== 16. The following information applies to the "TARGET release suboptions" section of Chapter 4 of the z/OS V1R5 C/C++ User's Guide. The last point in the list below is a new addition to the information. For example, to generate code that will execute on an OS/390 V2R10 system, using a z/OS V1R5 application development system: - Use the z/OS V1R5 Language Environment data sets (CEE.SCEE*) during the assembly, compilation, pre-link, link-edit, and bind phases. - Use the OS/390 V2R10 class library data sets (SCLBCPP, SCLBOBC, SCLBOXL, SCLBSID, SCLBXL) during pre-link, link-edit, and bind. Use the z/OS V1R5 class library header data sets (SCLBH.*) during compilation. - Specify the compiler option TARGET(OSV2R10) on the C/C++ compiles. Note: The programmer is responsible for ensuring that they are not exploiting any Language Environment functions that are unavailable on OS/390 V2R10. - Use the binder option COMPAT=PM3 or COMPAT=PM2 for the bind step. ======================================================================== 17. The following change applies to the LANGLVL compiler option C++ only suboptions description in Chapter 4 of the z/OS V1R5 C/C++ User's Guide. ANSISINIT|NOANSISINIT This suboption can be used to select between the old (prior to z/OS V1R1) and the current (z/OS V1R2 or later) compiler behaviors. It is useful for building an application that includes an existing DLL originally built with a z/OS V1R1 or earlier version of the C/C++ compilers. Specifying the NOANSISINIT suboption, ensures that the behavior of global (including static locals) objects with destructors in the newly-compiled objects is compatible with objects built with earlier compilers. If you specify the LP64 option and the LANGLVL(NOANSISINIT) option, the compiler issues a warning, ignores the LANGLVL(NOANSISINIT) option and turns on the LANGLVL(ANSISINIT) option. The default setting is LANGLVL(ANSISINIT). Note: LANGLVL(EXTENDED) and LANVLVL(ANSI) set LANGLVL(ANSISINIT). LANGLVL(COMPAT92) sets LANGLVL(NOANSISINIT). ======================================================================== 18. _Packed qualifier Prior to APAR PK05331, the C Compiler ignored the _Packed qualifier, when specified for union declarations. This potentially could affect the alignment of some of the aggregates in your application. The intended effect of the _Packed qualifier is to give all members of that union an alignment of 1 byte. But without this fix, _Packed union members would have their default alignment, and the members would not be packed to the 1 byte boundary. With this fix, the _Packed qualifier is correctly applied to unions. If your application uses objects that have been previously built with a C compiler that has this problem, the interaction between your application and these other objects may be compromised. The other objects may be expecting a different structure layout than the layout that a compiler with this fix would provide. To determine if you application code is effected by this fix, recompile your source with the CHECKOUT(MIGRATION(PK05331)) compiler command option. A message will be issued for every instance where a _Packed qualifier is specified for a union declaration. If the compiler issues such a message, you should manually inspect your source to determine if your source code relies on the _Packed qualifier to be in effect. If you feel that your code is affected, you should have the objects that were built with the older version of the C compiler re-built with a version of the C compiler with this fix. ======================================================================== 19. The following information applies to the CONVLIT compiler option description in Chapter 4 of the z/OS V1R5 C/C++ User's Guide. The existing CONVLIT compiler option has been extended through the addition of a new keyword named UNICODE. The z/OS XL C/C++ compiler interprets the CONVLIT(, UNICODE) suboption as a request to convert the wide string literals and wide character constants (wchar_t) to Unicode (UCS-2) regardless of the code page used for conversion of string literals and character constants (char). The conversion is supported for wide string literals and wide character constants that are coded using characters from the basic character set defined by the Programming languages - C (ISO/IEC 9899:1999) standard. The behavior is undefined if wide string literals and wide character constants are coded using characters outside the basic character set. The semantics of the #pragma convlit(suspend/resume) are not affected by this extension. No string literals or character constants (wide included), will be converted if #pragma convlit(suspend) is in effect. The interaction between the #pragma convlit(suspend/resume) and the #pragma convert is not affected by this extension. String literals and character constants will continue to be converted by the currently active #pragma convert. Wide string literals and wide character constants are not affected by #pragma convert, even when the new CONVLIT(, UNICODE) suboption is specified. ======================================================================== 20. The following information in the #pragma langlvl description in Chapter 9 of the z/OS V1R5 C/C++ Language Reference is incorrect: Note that #pragma langlvl(EXTENDED) has no effect in the z/OS UNIX System Services environment. In z/OS UNIX System Services, you must use the compile option LANGLVL(EXTENDED) instead of the pragma. This limitation applies only if the user exports the environment variable {_NOCMDOPTS}. Refer to the z/OS V1R5 C/C++ User's Guide for more information on {_NOCMDOPTS}. ======================================================================== 21. The following information applies to the FLOAT compiler option description in Chapter 4 of the z/OS V1R5 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 z/OS V1R5 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. ======================================================================== 22. The following information applies to Example 5 for SEARCH(LIB1.*,LIB2.+,LIB3) #include in Chapter 7 of the z/OS V1R5 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) ======================================================================== 23. z/OS C support for IBM DB2 UDB for z/OS V8 coprocessor: As of PTFs UK10308 and UK10309, the z/OS C compiler supports the IBM DB2 UDB for z/OS V8 coprocessor. For information on DB2 UDB for z/OS V8, refer to the DB2 Application Programming and SQL Guide.