December 6, 2006 This readme file contains the latest information about the "C/C++ without Debug Tool" optional feature of z/OS V1R6 that was not previously available for our documentation. 1. CMDOPTS feature in the c89 utility Starting with the z/OS V1R5 release, the CMDOPTS feature in the c89 utility enables compilers to distinguish between c89 defaults and options specified by the user on the command line. Because this feature requires that the compiler recognize this new option, users cannot simply point to the OS/390 V2R10 data sets and access the old compiler. The OS/390 V2R10 compiler does not support this new option and will terminate with an error. Note: The OS/390 V2R10 C/C++ compiler is reshipped with z/OS for a limited time as a migration aid. Users who want to use the OS/390 V2R10 compiler must do either of the following: - export _Cxx_CVERSION=0x220A0000 - export _Cxx_NOCMDOPTS=1 in addition to exporting _Cxx_CNAME=CBCDRVR and STEPLIB="CBC.SCBCCMP:$STEPLIB" Note: "xx" stands for "C", "89", or "XX". ======================================================================== 2. DEBUG|NODEBUG Effect on IPA Compile step: For the IPA Compile step, you can specify all of the DEBUG suboptions that are appropriate for the language of the code that you are compiling. However, they affect processing only if you have requested code generation, and only the conventional object file is affected. If you specify the NOOBJECT suboption of the IPA compiler option on the IPA Compile step, the IPA Compile step ignores the DEBUG option, even though the listing still indicates that the DEBUG option has been specified. Effect on IPA Link step: The IPA Link step only supports the generation of function calls, entry, exit, and return hooks for profiling. If you specify any other DEBUG suboptions for the IPA Link step, it turns them off and issues a warning message. If IPA(OBJONLY) object files from the IPA Compile step are specified in the IPA Link step, only hooks for profiling are supported in the input object file. Setting up an IPA-optimized application for profiling: For an IPA-optimized application, the DEBUG option inserts additional instructions (the hooks mentioned above) into the application for profiling. Note that this is different from the IPA Profile Directed Feedback option, which is used for tuning optimizations. During the compilation phase, in addition to the existing IPA compilation options, you must specify DEBUG(HOOK(NONE,PROFILE), NOSYMBOL). During the IPA Link phase, in addition to the existing IPA link options, you must specify DEBUG(HOOK(NONE,PROFILE)). Note that the use of these options can affect the performance of your routine. You might need to remove the options and recompile your routine before delivering your application. ======================================================================== 3. OS_NOSTACK NOTE: This information updates the Language Reference, Chapter 9 Preprocessor Directives, z/OS Pragma Directives, under the subsection for "Linkage": Designates an entry point ("identifier" in the syntax diagram) as an OS linkage entry point in XPLINK mode with no preallocated stack frame. An argument list is constructed containing the addresses of the actual arguments. Register 1 is set to point to this argument list. If the ILP32 compiler option is specified, the last item in this list has its high order bit set. Also, register 13 points to a full-word aligned 72-byte save area (under ILP32), or a double-word aligned 144-byte save area (under LP64), that may not be followed by z/OS Language Environment control structures, such as the NAB. Register 14 contains the return address. Register 15 contains the entry point of the called function. ======================================================================== 4. OS31_NOSTACK NOTE: This information updates the Language Reference, Chapter 9 Preprocessor Directives, z/OS Pragma Directives, under the subsection for "Linkage": Designates an entry point ("identifier" in the syntax diagram) as an OS linkage entry point in XPLINK mode with no preallocated stack frame. This is supported only under ILP32 and is synonymous with OS_NOSTACK. ======================================================================== 5. The following information applies to the "Passing function arguments" section in Chapter 32 of the z/OS V1R6 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. ======================================================================== 6. The following information applies to the PLIST compiler option description in Chapter 4 of the z/OS V1R6 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). ======================================================================== 7. The following change applies to the LANGLVL compiler option description in Chapter 4 of the z/OS V1R6 C/C++ User's Guide. The macro __ANSI__ is not supported for C++. ======================================================================= 8. The following information applies to the "Primary input (SYSIN)" description in Appendix A of the z/OS V1R6 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). ======================================================================= 9. The following information applies to the FLAG compiler option description in chapter 4 of the z/OS V1R6 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. ======================================================================= 10. The following information applies to the "TARGET release suboptions" section of Chapter 4 of the z/OS V1R6 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 V1R6 application development system: - Use the z/OS V1R6 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 V1R6 class library header data sets (CBC.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. ======================================================================= 11. The following change applies to the LANGLVL compiler option C++ only suboptions description in Chapter 4 of the z/OS V1R6 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). ======================================================================= 12. _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. ======================================================================= 13. The following information applies to the CONVLIT compiler option description in Chapter 4 of the z/OS V1R6 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. ======================================================================== 14. The following information in the #pragma langlvl description in Chapter 9 of the z/OS V1R6 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 V1R6 C/C++ User's Guide for more information on {_NOCMDOPTS}. ======================================================================== 15. The following information applies to Chapter 16 of the z/OS V1R6 C/C++ Compiler and Run-Time Migration Guide for the Application Programmer: #pragma linkage NOSTACK in LP64, when using int parameter: The OS linkage passes parameters via the argument area. An array of pointers points to a temporary variable containing the value of the argument to be passed. char or short are widened to int before they are passed. This means that char, short, or int arguments are copied to a temporary variable of size 4 bytes, effectively an int, and then the address of this temporary int is passed in the argument area. A error occurs under LP64, when char, short, or int are copied to a temporary variable of size 8 bytes (effectively a long type), and the address of this temporary long variable is passed. Since the high-order 4 bytes in the temporary area is always zero, if the callee follows the OS calling convention, the arguments appear to be zero. To avoid this problem for existing LP64 programs using the OS linkage, do not use char, short, or int in the prototype of OS functions. Use the long (or unsigned long) type instead. The caller can still pass arguments as char, short, or int. Implicit conversion will handle the parameters correctly. Code on the callee side should expect a long (or unsigned long) parameter. Note that if an existing program follows the above procedures to work around this problem, there will be no migration hit when the compiler applies this fix. After this fix, the LP64 program will be able to use char, short, or int in function prototypes. ======================================================================= 16. The following information applies to the FLOAT compiler option description in Chapter 4 of the z/OS V1R6 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 V1R6 C/C++ Compiler and Run-Time Migration Guide for the Application Programmer: 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. ======================================================================= 17. The following information applies to Example 5 for SEARCH(LIB1.*,LIB2.+,LIB3) #include in Chapter 7 of the z/OS V1R6 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) ======================================================================= 18. z/OS C support for IBM DB2 UDB for z/OS V8 coprocessor: As of PTF UK09698, 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. ======================================================================= 19. z/OS C++ support for IBM DB2 UDB for z/OS V7 and V8 coprocessor: As of PTFs UK18186 and UK18187, the z/OS V1R6 C++ compiler supports the IBM DB2 UDB for z/OS V7 and V8 levels of the coprocessor. For information on DB2 UDB for z/OS V7 and V8, refer to the DB2 Application Programming and SQL Guide.