December 6, 2006 This file contains corrections and additions to the z/OS 1.2.0 C/C++ documentation. 1. Installation Note to system programmers: If you are installing this product on a model 2064, please ensure that you have the latest level of hardware instruction millicode installed. ======================================================================== 2. The following revision refers to the "enum" preprocessor directive in Chapter 9 of the C/C++ Language Reference: If the specified storage size for an enum variable is smaller than that required by the range of enum constants, the C and C++ compiler issues a diagnostic message. #pragma enum(1) enum e_tag { a=0, b=SHRT_MAX /* diagnostic message */ } e_var; #pragma enum(reset) ======================================================================== 3. The following revision refers to Chapter 2, "About IBM z/OS C/C++" of the User's Guide and Programming Guide: The new option HALTONMSG is for both C and C++. ======================================================================== 4. The following information is applicable to both Chapter 3, "z/OS C Example" and Chapter 4, "z/OS C++ Examples", of the User's Guide: Compiling, Binding, and Running the z/OS C (or C++) Example The z/OS C and C++ compilers do not support TSO PROFILE NOPREFIX. ======================================================================== 5. The following information refers to Chapter 5, "Compiler Options" of the User's Guide. ===================================================================== ASCII | NOASCII Note: The EBCDIC option is synonymous with NOASCII. There is no negative form for EBCDIC; that is, there is no NOEBCDIC. Since EBCDIC is the default, there is usually no need to specify it. If you must specify it, use EBCDIC instead of NOASCII as the former is self-documenting. ===================================================================== FLOAT(IEEE) The FLOAT(IEEE) option is currently not supported in the C++ compiler when it is used with the TARGET(OSV2R6) option. ===================================================================== HALTONMSG | NOHALTONMSG The HALTONMSG option for C++ can only accept one message number. It is the intention to relax this restriction in the future. This option is not accepted by the IPA Link Step. In Table 7. "Summary of Compiler Options Used for Input Source File Processing Control", the HALTONMSG option applies to both C and C++ compiles. +-----------+--------------------+---------+---------+------+------+ | Option | Description | C | C++ | IPA | More | | | | Compile | Compile | Link | Info | +-----------+--------------------+---------+---------+------+------+ | HALTONMSG | | yes | yes | | | +-----------+--------------------+---------+---------+------+------+ ===================================================================== INFO | NOINFO The C++ INFO option may not produce the same diagnostic messages as the previous releases. ===================================================================== LANGLVL(ILLPTOM | NOILLPTOM) The suboption is currently shown as ILLPTOMEM | NOILLPTOMEM. The correct form for the suboption is ILLPTOM | NOILLPTOM. ===================================================================== LANGLVL(IMPLICITINT | NOIMPLICITINT) The last sentence in the following paragraph has been revised: This option controls whether z/OS C++ will accept missing or partially specified types as implicitly specifying int. This is no longer accepted in the standard but may exist in legacy code. When LANG(NOIMPLICITINT) is specified, all types must be fully specified. Also, when LANG(NOIMPLICITINT) is specified, a function declaration at namespace scope or in a member list will implicitly be declared to return int. The last sentence should read as follows: When LANG(IMPLICITINT) is specified, a function declaration at namespace scope or in a member list will implicitly be declared to return int. ===================================================================== LANGLVL(OLDFRIEND | NOOLDFRIEND) The following paragraphs have been revised: This option controls whether friend declarations that name classes without elaborated class names are treated as C++ errors. When LANG(OLDFRIEND) is in effect, you can declare a friend class without elaborating the name of the class with the keyword class. This is an extension to the C++ standard. For example, the statement below declares the class IFont to be a friend class and will result in a warning when LANG(OLDFRIEND) is in effect. friend IFont; The example declaration above causes a warning unless you modify it to the statement below, or suppress the message with the SUPPRESS(CCN5070) option. Specify LANG(NOOLDFRIEND) for compliance with ISO standard C++. Specifying this option will cause an error condition and message to be generated for the example declaration above. friend class IFont; The default for batch and TSO is LANG(OLDFRIEND). ===================================================================== LANGLVL(OLDSTR | NOOLDSTR) This is a new addition to the LANGLVL suboptions. In Table 20. "Compatibility options for OS/390 V2R10 and V1R2 Compilers", the following row is added: +--------------------------------------------------------------------+ | Options | Description | | |----------------------------------------| | | COMPAT92 | STRICT98/ANSI | EXTENDED | +---------------------------+-----------+---------------+------------+ | LANGLVL(OLDSTR|NOOLDSTR) | On | Off | Off | +---------------------------+-----------+---------------+------------+ The following information is added under heading "For C++, the following suboptions apply:" LANGLVL(OLDSTR | NOOLDSTR) This option provides backward compatibility with previous versions of z/OS C++ and predecessor products, by controlling which string function declarations are introduced by the string.h and wchar.h header files. For conformance with the current C++ standard, string.h and the wchar.h header files declare several C++ string functions differently for C++ source files than they were declared in previous releases. These new function declarations may cause an existing C++ program to become invalid and therefore to fail to compile. The OLDSTR option specifies that the new C++ string function declarations are not to be introduced by the string.h and wchar.h header files, thereby causing only the C versions of these functions to be declared, as in previous releases. Note that when a C source file is compiled, these declarations remain unchanged from previous releases. Background A number of the string function signatures that are defined in the 1989 C International Standard and the C Amendment are not const-safe. For example, consider the following standard C signature: char * strchr(const char *s, int c); The behavior of this function is specified as follows: -The strchr function locates the first occurrence of c (converted to a char) in the string pointed to by s. The terminating null character is considered to be part of the string. -The strchr function returns a pointer to the located character, or a null pointer if the character does not occur in the string. Since the parameter s is of type const char *s, the string being searched by the strchr function is potentially composed of characters whose type is const char. The strchr function returns a pointer to one of the constituent characters of the string, but this pointer is of type char * even though the character that it points to is potentially of type const char. For this reason, strchr can be used to implicitly (and unintentionally) defeat the const- qualification of the string referenced by the pointer s. To correct this problem, the C++ standard replaces the above signature from the C standard with the following overloaded signatures: const char * strchr(const char *s, int c); char * strchr( char *s, int c); Both of these overloaded functions have the same behavior as the original C version of strchr. In a similar manner, the signatures of several other standard C library routines are replaced in the C++ standard. The affected routines are: strchr strpbrk strrchr strstr memchr wcschr wcspbrk wcsrchr wcsstr wmemchr Because of the changes mandated by the C++ standard, the following unsafe example will not compile in C++: #include const char s[] = "foobar"; int main(void) { char * c = strchr(s, 'b'); } To preserve backward compatibility with previous releases (and thus enable the code example above), specify LANGLVL(OLDSTR). ===================================================================== LANGLVL(OLDTYPEDEFCLASS | NOOLDTYPEDEFCLASS) This option has been deprecated. ===================================================================== OBJECTMODEL(IBM) In order to use the OBJECTMODEL(IBM) option, the XPLINK option must be specified. If XPLINK is not specified, the compiler will issue a warning and use the default OBJECTMODEL() setting. ===================================================================== OPTFILE | NOOPTFILE The following new information is added for this option: Comments are now supported in an option file used in the OPTFILE option. When a line begins with the # (octothorpe) character, the entire line is ignored, including any continuation character. Note that option files are encoded in the IBM-1047 codepage. ===================================================================== ROCONST | NOROCONST The table below shows the correct option defaults for the batch and TSO environments. +--------------------------------------------------------------------+ | 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++ | +----------------------+-------+-------+-------+------+------+-------+ | For C: NOROCONST | | | | | | | | For C++: ROCONST | | | | | | | +----------------------+-------+-------+-------+------+------+-------+ Note: The following change applies to the "Compiler Options with Default Setting Changes" section in Chapter 12 of the z/OS V1R2 C/C++ Compiler and Run-Time Migration Guide: ROCONST compiler option: For C++, the ROCONST option default changed from NOROCONST in OS/390 V2R10 to ROCONST in z/OS V1R2. ===================================================================== The User's Guide states that if any of the following options is used in the IPA Link Step, the compiler accepts but ignores the option. OBJECTMODEL RTTI | NORTTI TEMPLATERECOMPILE | NOTEMPLATERECOMPILE The IPA Link Step does not accept these options; the compiler issues a warning message if you specify any of these options in the IPA Link step. ===================================================================== Using the z/OS C++ Compiler Listing Notes: 1. Although the compiler listing is for your use, it is not a programming interface and is subject to change. 2. The compiler always attempts to put diagnostic messages in the listing, as close as possible to the location where the condition occurred. The exact location or line number within the listing may not be the same from release to release. ======================================================================== 6. The following information refers to Chapter 6, "Binder Options" of the z/OS V1R2.0 C/C++ User's Guide. ===================================================================== DYNAM(DLL | NO) The following new information is added for this option: A C++ compilation now exports certain system generated symbols for internal use. These symbols are needed only if you are building a DLL. If you are not building a DLL, and the binder step sets the DYNAM=DLL option, the binder will attempt to output these symbols to the definition side-deck. If the side-deck data set is not defined, the binder will issue the following message: IEW2689W 4C40 DEFINITION SIDE FILE IS NOT DEFINED You can do either one of the following: - If you are building a DLL, specify a side-deck data set in the bind step. - If you are not building a DLL, specify DYNAM=NO in the bind step or ignore the message. Note that DYNAM=DLL is the default setting for the JCL PROCs that invoke the binder, and in the compiler shell utilities (c89, cc, cxx, and c++). The BPARM parameter is used to pass binder options to a JCL PROC. The -Wl option is used to pass binder options to the compiler shell utilities. The following examples show how to use the compiler shell utilities: - To define a side-deck data set, use -Wl,DLL. - To build a non-DLL executable, use -Wl,DYNAM=NO. ======================================================================== 7. There is additional information for IOC's ITieredTextBuffer and ITest classes. The affected information can be found in the IOC Library Reference and in Chapter 7 "Error Handling, Tracing, and Testing" of the IOC User's Guide: ITieredTextBuffer behaves like the C++ ostream class. It supports the use of endl with its << operator but does not allow streaming of std::endl. The following will result in a compilation error: ITieredTextBuffer fOutputTextBuffer; fOutputTextBuffer << std::endl; The user will get the following compilation error: CCN5218 (S) The call does not match any parameter list for "operator<<". Since ITest makes use of ITieredTextBuffer class to report progress and test results, the use of ITest::outputTextStream() with std::endl will also result in compilation error. The following example will result in the same compilation error: class MyTest : public ITest { public: void FnA() { outputTextStream( ) << std::endl; } } ======================================================================== 8. Enumeration Constants Information There is additional information for "Enumeration Constants" in Chapter 3 of the C/C++ Language Reference: Enum in C In C, enumeration constants have type int. If a constant expression is used as the initializer, the value of the expression cannot exceed the range of int (that is, INT_MIN to INT_MAX). Otherwise, a diagnostic message will be issued. In previous releases, this message is an error. As of z/OS V1R2, this message is now a warning. The condition is tolerated but the value of the enumeration constant is undefined. In Chapter 9 of the C/C++ Language Reference, the last entry in the "int" column of "Table 8. ENUM Constants for C and C++" applies to C++ only. This same restriction applies to "Table 19. ENUM Constants for C and C++" in the C/C++ User's Guide. ======================================================================== 9. Using function pointers in a mixed non-XPLINK/XPLINK environment, which affects the use of Facets in the C++ Standard Library There are restrictions in passing a function pointer from a non-XPLINK application into an XPLINK function (where the function pointer is used as callback). In this case, a callback is supported only if the function pointer is passed explicitly as an argument into the XPLINK function. That is, the function pointer has to be a parameter in the XPLINK function's prototype. If the function pointer is passed in any other way, for example as a member in a structure or a class (which itself is an argument to the XPLINK function), the function pointer cannot be used correctly inside the XPLINK function. There are code situations like this in the C++ Standard Library, in particular when handling locale facets. That is, a non-XPLINK application calling the XPLINK C++ Standard Library (DLL) may not work properly when locale facets are involved; we will provide a fix to handle facets in a future PTF. ======================================================================== 10. Using #pragma langlvl(ansi) in a C program Using #pragma langlvl(ansi) does not disable all of the non-ANSI functions in system header files. As a result, functions that are z/OS extensions to the C Standard are still visible to the program code. This does not normally affect the program unless the same name is used inside the code for some other purpose. In this case, you can explicitly specify the compiler option LANGLVL(ANSI), which will disable all the non-ANSI functions in system header files. We will provide a fix to #pragma langlvl(ansi) in the future. ======================================================================== 11. Changes to Data Control Block (DCB) parameters for SCLBH.H The DCB parameters for the SCLBH.H data set have changed with this release (used to be FB80, now it's FB120). If SCLBH.H is not the first data set in your DD:SYSLIB concatenation, you will encounter an SA78 abend, R=00000018 in ppReadSourceData. However, we do not recommend that you use the DD:SYSLIB concatenation to search for C++ header files with the z/OS V1R2 compiler, because searching the DD:SYSLIB concatenation cannot distinguish between the old UNIX Systems Laboratories header files and new ISO Standard Library header files. For example, #include (old USL) and #include (ISO Standard) are indistinguishable using the DD:SYSLIB concatenation. Use the SEARCH compiler option so that the correct header files are included. ======================================================================== 12. The following applies to the IPA link step: Autocall for XPLINK members of PDS/PDSE object libraries is not currently supported. Linking using attributed libraries is not currently supported for both archive and PDS/PDSE object libraries. An 'attributed library' is one where there are multiple definitions for the same symbol, with different XPLINK/non-XPLINK linkage characteristics; the attributes for each implementation of the symbol are used to select the appropriate library member. ======================================================================== 13. Prelinking C++ Object Modules When you use the prelinker to prelink C++ object modules, you may get duplicate symbol warnings due to virtual function symbols generated by the compiler. You can ignore these symbols and warnings. You will not get these messages if you use the binder. ======================================================================== 14. Replacement functions [lib.replacement.functions] and XPLINK The following information relates to replacement functions [lib.replacement.functions] documented in section 17.4.3.4 of the 1998 ANSI/Iso c++ Language Standard, also known as ISO/IEC14882:1998(E): When a scalar operator new is replaced in the user's code, the standard default behavior of the vector operator new is to call the replacement operator new defined in the user's code. This is not possible in the case of XPLINK because the run-time library is a DLL with vector operator new bound to the run-time version of the scalar operator new. In the non-XPLINK case, the references to scalar operator new are resolved at application bind time, so the vector operator new gets properly bound to the replacement scalar operator new in the users code. The same applies to the operator delete. Since the XPLINK version of the C++ run-time library is a DLL, this is a permanent limitation for XPLINK applications. To work around this particular limitation, and use their own new or delete, users must replace both scalar and vector versions of operators new and delete. ======================================================================== 15. Sunsetting of IBM Open Class Libraries It has been announced that IBM will be sunsetting the IBM Open Class libraries on z/OS in the near future. In response to this we have received the following questions from customers: 1) How do I recognize that an application is using the IBM Open Class Libraries? You are using the Open Class library if you include any of the following header files: i0string.hpp iabag.h iacllct.h iadqu.h iaeqkey.h iaeqksrt.h iaeqsrt.h iaequal.h iaes.h iahp.h iakb.h iakey.h iaks.h iaksb.h iaksrt.h iakss.h iamap.h iamwt.h iaorder.h iappl.h iapqu.h iaqu.h iarel.h iargdict.hpp iarstrct.h iasb.h iaseq.h iaset.h iasm.h iasqntl.h iasr.h iasrt.h iass.h iastk.h iastr.h iatname.hpp iatree.h iattribt.hpp ibag.h ibagavl.h ibagbst.h ibagdil.h ibaghsh.h ibaglst.h ibagtab.h ibcllct.h ibhandle.hpp ibtree.h ibuffer.hpp iccsid.hpp icmpdnam.hpp icmptest.hpp icntptr.hpp icodecvt.hpp icolitr.hpp iconditn.hpp icritsec.hpp idate.hpp idatstrm.hpp idbcsbuf.hpp idecimal.hpp idllmod.hpp idqu.h idqudil.h idqulst.h idqutab.h ies.h iesdil.h ieslst.h iestab.h ievtdata.hpp iexc.h iexcbase.hpp iexcfile.hpp iextproc.hpp ififostr.hpp ifileitr.hpp ifilestr.hpp ifilesys.hpp igenexc.hpp ihp.h ihpdil.h ihplst.h ihptab.h iiatree.h iimwt.h iintrst.hpp ikb.h ikbdil.h ikbhsh.h ikblst.h ikbtab.h iks.h iksavl.h iksb.h iksbdil.h iksblst.h iksbst.h iksbtab.h iksdil.h ikshsh.h ikslst.h ikss.h ikssavl.h ikssbst.h ikssdil.h iksslst.h iksstab.h ikstab.h ilanglvl.hpp ilocale.hpp ilonglng.hpp imap.h imapavl.h imapbst.h imapdil.h imaphsh.h imaplst.h imaptab.h imrefcnt.hpp imsgtext.hpp imstrmbl.hpp imtabrl.hpp imwt.h ingapp.hpp ingthrd.hpp inotadr.hpp inotifev.hpp inotify.hpp inumfrmt.hpp iobservr.hpp iobslist.hpp ipathnam.hpp iperfset.hpp iperthr.hpp ipoint.hpp ipqu.h ipqudil.h ipqulst.h ipqutab.h iprcenv.hpp iprimlck.hpp iptarray.hpp iptr.h iqu.h iqudil.h iqulst.h iqutab.h irbag.h irdeque.h irect.hpp irel.h ireldil.h irelhsh.h irellst.h ireltab.h ireqseq.h ireslib.hpp ireslock.hpp irheap.h irkeybag.h irkeyset.h irksbag.h irksset.h irmap.h irprioqu.h irqueue.h irrel.h irseq.h irset.h irsrtbag.h irsrtmap.h irsrtrel.h irstack.h irstset.h isb.h isbavl.h isbbst.h isbdil.h isblst.h isbtab.h iseq.h iseqdil.h iseqlst.h iseqtab.h iset.h isetavl.h isetbst.h isetdil.h isethsh.h isetlst.h isettab.h ism.h ismavl.h ismbst.h ismdil.h ismlst.h ismtab.h isr.h isrdil.h isrtab.h iss.h issavl.h issbst.h issdil.h isslst.h isstab.h issttest.hpp istdcnr.hpp istdkcnr.hpp istdntfy,hpp istdops.h istk.h istkdil.h istklst.h istktab.h istparse.hpp istrenum.hpp istrgen.hpp istring.hpp istrmcf.hpp istrmexc.hpp istrmio.hpp istrmmod.hpp istrmtst.hpp istrtest.hpp istyles.hpp istylset.hpp isynchr.hpp itest.hpp itestcol.hpp itestmul.hpp itext.hpp ithrdexc.hpp itime.hpp itimer.hpp itimetst.hpp itmstamp.hpp itrace.hpp itrancod.hpp itree.h ittxtbuf.hpp itxtbdry.hpp itxtcoll.hpp itxtiter.hpp itxtplmt.hpp itxtstyl.hpp ityperep.hpp iucmpbty.hpp iueasia.hpp iueeuro.hpp iugnrl.hpp iumeast.hpp iunicode.hpp iusasia.hpp iusyms.hpp iversion.hpp 2) What is the recommended migration path? IBM is working on documentation to help you transition from the Open Class Libraries. We will update this file with a web reference when the documentation is available. ======================================================================== 16. Compiler Message: "CCN5505 (S) The build failed and there are no messages." The compiler may emit the following message: CCN5505 (S) The build failed and there are no messages. CCN5527 (I) The build failure may be because of an Internal Compiler Error or because a tool failed to generate a message. CCN0793(I) Compilation failed for file ./abc.C. Object file not created. FSUM3065 The COMPILE step ended with return code 12. FSUM3017 Could not compile abc.C. Correct the errors and try again. instead of the following message: "./abc.C", line 19.29: CCN5016 (S) The expression must be an integral constant expression. CCN0793(I) Compilation failed for file ./abc.C. Object file not created. FSUM3065 The COMPILE step ended with return code 12. FSUM3017 Could not compile abc.C. Correct the errors and try again. This specific message problem occurs only when user code contains static class members, with initializers inside the class definition, which are not const. If your code does not contain any const static class members initialized in the class definition, and you get the "build failed" message, please contact your service representative. The following source with an inline initializer for a const static member will generate the "build failed" message: int B = 24; class sample { public: static int xOutOfLine; const static int yInline=B; }; A workaround for avoiding the "build failed" message is to initialize the static const members outside the class. The following code generates the desired error message "The expression must be an integral constant expression": int B = 24; class sample { public: static int xOutOfLine; const static int yInline; }; const int sample::yInline=B; A better solution is to correct the user code in error by making sure that the initializer is const: const int B = 24; class sample { public: static int xOutOfLine; const static int yInline=B; }; ======================================================================== 17. APAR PQ55784: TRAP(ON) Requirement The z/OS Language Environment run-time option TRAP(ON) should be set when using z/OS C/C++. Refer to the z/OS Language Environment Programming Reference for details on the z/OS Language Environment run-time options. ======================================================================== 18. The following information refers to Table 30. __last_op Codes and Diagnosis Information in Chapter 18 (Debugging I/O Programs) of the z/OS V1R2.0 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. ======================================================================== 19. Pre-z/OS V1R2.0 C++ compilers generated an error when a user attempted to assign pointers with different linkage specifications (i.e. trying to assign a C function pointer to a C++ function pointer). This is required as different linkage specifications may require different calling conventions on this platform. In addition, this error is the correct language standard behavior. The z/OS V1R2 compiler did not generate an error for this condition; this may have resulted in run-time failures. After PTF UQ64170 and PTF UQ64171 are applied, some users may start to get compile time errors indicating this problem. The linkage specification must be respected on this platform. The message is of the type: CCN5257 (S) An object or reference of type "int (*)()" cannot be initialized with an expression of type "extern "C" int ()". ======================================================================== 20. You can build a non-XPLINK application by ensuring that there are no references to the C++ Standard Library header files and by using the STLport which is freely available on the web at (http://www.stlport.org/product.html). The C++ Standard library header files do not have suffixes, so to find the references to the C++ Standard Library header files look for include statements that reference header file names without a suffix. For iostream classes, you can either statically link the USL iostream Class Library objects from the CBC.SCLBCPP or use the side deck from the CBC.SCLBSID(IOSTREAM) for the DLL version. For all other classes, you can use the STLport package. The following URL has useful information about the STLport on z/OS: http://www-3.ibm.com/software/ad/c390/cmvsstlp.htm Once you make the necessary source code changes, you need to recompile the code with the NOXPLINK compiler option. To ensure that you are not referencing C++ Standard Library header files, you should make sure that the CBC.SCLBH.* header file datasets are concatenated in front of the following Language Environment system header file datasets: CEE.SCEEH.H, CEE.SCEEH.SYS.H, CEE.SCEEH.NET.H, CEE.SCEEH.NETINET.H, and CEE.SCEEH.ARPA.H, which should be the only Language Environment header file datasets used. To get the proper dataset allocation at prelink/link time, the following c89 environment variables should be exported: For static binding with USL iostream objects: _CXX_PSYSLIB="CEE.SCEEOBJ:CEE.SCEECPP:CBC.SCLBCPP" _CXX_LSYSLIB="CEE.SCEELKEX:CEE.SCEELKED" For USL iostream DLL: _CXX_PSYSIX="CBC.SCLBSID(IOSTREAM)" _CXX_PSYSLIB="CEE.SCEEOBJ:CEE.SCEECPP" _CXX_LSYSLIB="CEE.SCEELKEX:CEE.SCEELKED" ======================================================================== 21. 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. ======================================================================== 22. The following information refers to Table 16. CHECKOUT Suboptions, Abbreviations, and Descriptions, found in Chapter 5 of the z/OS C/C++ User's Guide: The ENUMSIZE description should be replaced by the following information: CHECKOUT suboption Abbreviated Name Description ENUM|NOENUM EN|NOEN Usage of enumerations ======================================================================== 23. The following information has been added to the XPLINK compiler option description, found in Chapter 5 of the z/OS C/C++ User's Guide: CALLBACK|NOCALLBACK DEFAULT: NOCALLBACK XPLINK(CALLBACK) is primarily intended to enable function pointer calls across XPLINK DLLs and non-XPLINK programs. With XPLINK, function calls are supported across a DLL boundary with certain restrictions. In particular, if a function pointer is created by a non-XPLINK caller pointing to an XPLINK function, it can be passed as an argument via an exported function into the DLL, which can then use it as callback. This is because the compiler knows about the function pointer argument and is able to insert code to fix-up the function pointer. However, non-XPLINK function pointers passed into the DLL by other means are not supported. If you specify CALLBACK, all calls via function pointers will be considered potentially incompatible, and fix-up code will be inserted by the compiler at the locations of the incompatible DLL callbacks through function pointers to assist the call. The application will be impacted by a performance penalty. In an XPLINK(NOCALLBACK) compilation, if a function pointer is declared using the __callback qualifier keyword, the compiler will insert fix-up code to assist the call. For more information on this keyword, see the C/C++ Language Reference. ======================================================================== 24. The explanation for point 4 for figure 30 "Testing If filename Is In Absolute Form" in Chapter 8 of the C/C++ User's Guide is amended with the following: If filename is enclosed in single quotation marks ('), then it is an absolute data set. The compiler directly opens the file and ignores the libraries that are specified in the LSEARCH or SEARCH options. If there are any invalid characters in filename, the compiler converts the invalid characters to at signs (@, hex 7c). ======================================================================== 25. The following information applies to "Under TSO Command" in Chapter 7 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. ======================================================================== 26. Compiler Listings 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. ======================================================================== 27. The following change applies to the "TARGET Release Suboptions" section of Chapter 5 in the z/OS 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 C/C++ Language Reference for more information on this macro. ======================================================================== 28. The following change applies to the "IPA Linking with XPLINK" section of Chapter 9 in the z/OS C/C++ User's Guide: The third paragraph in this section has been replaced by: z/OS Version 1 Release 2 provides an alternative to SCEELIB to handle this situation. The SCEELIB members remain as before, but a new SCEEBND2 library is introduced. This contains the static parts in object format, which must be used if you are using IPA Link. ======================================================================== 29. The following change applies to the "Prelinker Options" section of Appendix B in the z/OS C/C++ User's Guide: ER|NOER Note: For the z/OS UNIX Systems Services environment, the default is NOER. ======================================================================== 30. The following change applies to the "COMPAT" binder option description in chapter 6 of the C/C++ User's Guide and the "TARGET" compiler option description in chapter 5 of the z/OS C/C++ User's Guide: As of z/OS V1R3, the binder output defaults to PM4. A PM4 object module will fail to load on operating systems prior to z/OS V1R3. If you are building on z/OS V1R3 and targetting back to earlier releases, you will need to pass COMPAT=PM3 or COMPAT=PM2 to the binder. ======================================================================== 31. The z/OS C/C++ Compiler and Run-Time Migration Guide, Part 2. "From C/370 to z/OS V1R2 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 z/OS Language Environment-enabled assembler routines - no longer exists. ======================================================================== 32. The following change applies to "Table 4. Compiler Options, Abbreviations, and IBM Supplied Defaults" in Chapter 5 of the C/C++ User's Guide: TEMPINC has does not accept "TEMP" or "NOTEMP" as abbreviations. No abbreviation is provided for TEMPINC. ======================================================================== 33. Using the IBM Open Class Library and the z/OS V1R2 C++ compiler The z/OS C/C++ Compiler and Run-Time Migration Guide states several times that you can use the OS/390 V2R10 level of the IBM Open Class Library by compiling with the z/OS V1R2 C++ compiler with the TARGET(OSV2R10) compiler option. This is incorrect. You must not specify the TARGET compiler option with a previous level of the operating system if you use the IBM Open Class Library with the z/OS V1R2 C++ compiler. To use the OS/390 V2R10 IBM Open Class Library, you must use the OS/390 V2R10 C++ compiler. The error occurs in the following places: a. Part 3. "From Pre-OS/390 Releases of C/C++ to z/OS V1R2 C/C++" - Chapter 8. "Application Executable Program Compatibility" contains a section titled "Class Library Execution Incompatibilities". This section refers to the possibility of using the z/OS V1R2 C++ compiler with the TARGET(OSV2R10) compiler option. This is not possible with the IBM Open Class Library. b. Part 4. "From OS/309 C/C++ to z/OS V1R2 C/C++" - Chapter 14. "Class Library Changes Between OS/390 C/C++ and z/OS V1R2 C/C++" states several times that you can specify the TARGET(OSV2R10) compiler option with the z/OS V1R2 IBM Open Class Library. This is not possible. The IBM Open Class Library User's Guide states several times that you can use the OS/390 V2R10 level of the IBM Open Class Library by compiling with the z/OS V1R2 C++ compiler with the TARGET(OSV2R10) compiler option. This is incorrect. You must not specify the TARGET compiler option with a previous level of the operating system if you use the IBM Open Class Library with the z/OS V1R2 C++ compiler. To use the OS/390 V2R10 IBM Open Class Library, you must use the OS/390 V2R10 C++ compiler. The error occurs in the following places: a. Chapter 1. "IBM Open Class Overview" - "Migration Issues: What Version of IBM Open Class Library Should I Use?" point 2 states that you can use the TARGET compiler option to specify a previous release of the operating system. This is incorrect. To use the OS/390 V2R10 IBM Open Class Library, you must use the OS/390 V2R10 C++ compiler. b. Chapter 1. "IBM Open Class Overview" - "Specify a Different Target Release on z/OS" applies if you are using the OS/390 V2R10 C++ compiler. This section does not apply if you are using the z/OS V1R2 C++ compiler. c. Chapter 2. "Application Control" - "Open Class Threading Model" - "GUI and Non-GUI Threads" states that the IThread class is not supported in the current version of the IBM Open Class Library in the z/OS environment. This is correct. However, it incorrectly states that you can use the TARGET compiler option to access an older version of the IBM Open Class Library. If you want to use the IThread class, you must use the OS/390 V2R10 C++ compiler not the z/OS V1R2 C++ compiler. ======================================================================== 34. Hiperspace Memory Files The C compiler uses hiperspace memory files for work files. If for any reason the compiler is unable to open the work files, message CCN3351 is issued and the compilation terminates. Ensure hiperspace is available, and that your userid has authority to create hiperspace memory files. As an alternative, you may use the MEMORY option to specify that memory files are to be used instead. ======================================================================== 35. The following change applies to the CONVLIT compiler option description in Chapter 5 of the C/C++ User's Guide: The default for the CONVLIT option is NOCONVLIT(, NOWCHAR). ======================================================================== 36. The following change applies to Chapter 12 and Chapter 15 of the z/OS V1R2 C/C++ Compiler and Run-Time Migration Guide: As of z/OS V1R2, the ROSTRING option default for C changed from NOROSTRING to ROSTRING. The ROSTRING option default for C++ is ROSTRING and is the same for OS/390 V2R10 and z/OS V1R2. As of z/OS V1R2, the compiler supports the STATICINLINE compiler option and the default is NOSTATICINLINE. Specify STATICINLINE for compatibility with C++ compilers provided by previous versions of the compiler. ======================================================================== 37. Non-XPLINK Standard C++ Library DLL A non-XPLINK Standard C++ Library DLL has been requested to provide Standard C++ Library support for CICS and IMS. The CICS and IMS subsystems do not currently support XPLINK linkage, rendering the XPLINK Standard C++ Library DLL supplied with the compiler inoperable under both subsystems. The non-XPLINK Standard C++ Library DLL will allow support for the Standard C++ Library in the CICS and IMS subsystems for V1R2. Since CICS and IMS do not currently support XPLINK linkage, a non-XPLINK DLL will enable the Standard C++ Library under these subsystems. The following points should be noted: - To use the non-XPLINK DLL with c++/cxx, the appropriate environment variables must be specified. - To use the non-XPLINK DLL with procs, the appropriate proc overrides must be used. - The non-XPLINK DLL does not support enhanced ASCII functionality as enhanced ASCII functionality is dependent on XPLINK linkage. DLL/Side-deck Name The non-XPLINK Standard C++ Library DLL is provided in the SCEERUN data set as member C128N. The corresponding system definition side-deck file is provided in the SCEELIB data set as member C128N. Usage with c++/cxx To use the non-XPLINK Standard C++ Library DLL, you must first link your object modules with the non-XPLINK system definition side-deck. Use the {_PSYSIX} environment variable to pass the non-XPLINK side-deck information to c++/cxx. The {_PSYSIX} environment variable specifies the system definition side-deck list to be used to resolve symbols during the non-XPLINK link-editing phase. The following concatenation should be used: export _CXX_PSYSIX=\ "{_PLIB_PREFIX}.SCEELIB(C128N)":\ "{_CLIB_PREFIX}.SCLBSID(IOC,IOSTREAM,COMPLEX,COLL)" where {_PLIB_PREFIX} and {_CLIB_PREFIX} are set to a default (for example, CEE and CBC, respectively) during custom installation, or using user overrides. It is only necessary to specify {_PSYSIX} in order to use the non-XPLINK side-deck with IPA. Corresponding non-XPLINK IPA link step environment variables default to the value of {_PSYSIX}. To run a program with the non-XPLINK DLL, ensure that the SCEERUN data set containing the non-XPLINK DLL is in the MVS search path; that is, either specified in your STEPLIB or already loaded into LPA. Usage with Procs All non-XPLINK C++ procs containing bind and pre-link steps need to be overridden in order to use the non-XPLINK Standard C++ Library DLL. These procs are: CBCB, CBCBG, CBCCB, CBCCBG, CBCCL, CBCCLG, CBCL, CBCLG The appropriate DD statements in these procs must be overridden: - For a bind step, the non-XPLINK side-deck must be added to the SYSLIN concatenation. - For a pre-link step, the non-XPLINK side-deck must be added to the SYSIN concatenation. The following concatenations added to the calling JCL will override the appropriate DD statement of the corresponding CBC proc: CBCB, CBCBG //SYSLIN DD // DD DSN=&LIBPRFX..SCEELIB(C128N),DISP=SHR CBCCB, CBCCBG //BIND.SYSLIN DD // DD DSN=&LIBPRFX..SCEELIB(C128N),DISP=SHR CBCL, CBCLG //SYSIN DD // DD DSN=&LIBPRFX..SCEELIB(C128N),DISP=SHR CBCCL, CBCCLG //PLKED.SYSIN DD // DD DSN=&LIBPRFX..SCEELIB(C128N),DISP=SHR Restriction: - No Enhanced ASCII Functionality Support The non-XPLINK Standard C++ Library DLL does not provide enhanced ASCII functionality support as ASCII run-time functions require XPLINK linkage. Classes and functions sensitive to character encoding are provided in EBCDIC alone in the non-XPLINK DLL. Performance: Due to peformance differences between XPLINK and non-XPLINK linkages, it is expected that an XPLINK program using the XPLINK Standard C++ Library DLL will outperform a non-XPLINK program using the non-XPLINK Standard C++ Library DLL. It is possible to use the non-XPLINK DLL with an XPLINK application, although this is not preferred. A call to a function of different linkage than the callee will result in a performance degradation due to the overhead cost required to swap from one stack type to the other. ======================================================================== 38. The following change applies to the XPLINK and GOFF compiler option descriptions in Chapter 5 of the z/OS V1R2 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. ======================================================================== 39. The following change applies to the HTML version of the z/OS V1R2 C/C++ User's Guide that is available from http://www.ibm.com/software/awdtools/czos/library/libv1r2.html. In Chapter 5, 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. | | +--------------+--------------------------+-----------------------+ ======================================================================== 40. The following change affects the LANGLVL compiler option description in Chapter 5 of the z/OS V1R2 C/C++ User's Guide. The macro __ANSI__ is not supported for C++. ======================================================================== 41. The following information applies to Chapter 15 of the z/OS V1R2 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. ======================================================================== 42. The following information applies to the "Passing Function Arguments" section in Chapter 28 of the z/OS V1R2 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. ======================================================================== 43. The following information applies to the PLIST compiler option description in Chapter 5 of the z/OS V1R2 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). ======================================================================== 44. The following information applies to the FLOAT compiler option description in Chapter 5 of the z/OS V1R2 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 V1R2 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. ======================================================================== 45. The following information applies to the #pragma pack description in Chapter 9 of the z/OS V1R2 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). ======================================================================== 46. The following information applies to Example 5 for SEARCH(LIB1.*,LIB2.+,LIB3) #include in Chapter 8 of the z/OS V1R2 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)