From: Mike Stewart (pmstewart_at_lbl_dot_gov)
Date: 04/14/2004
The default version of the IBM C and C++ compilers on seaborg.nersc.gov
will be upgraded on Wednesday, 4/21/04. This version contains fixes to
several compiler bugs reported to IBM as well as some other minor
changes and new features. No bugs reported by NERSC were fixed in this
release. The attached README documents the changes and new features in
this release.
This new version is currently contained in the xlc module. To access
it, type in:
module load xlc
--
=========================
Michael Stewart
Consultant
NERSC User Services Group
510-486-6648
pmstewart_at_lbl_dot_gov
=========================
===========================================================================
*
* IBM VisualAge C++ Professional for AIX, Version 6.0
* 5765-F56-00
*
* Licensed Materials - Property of IBM
* (C) Copyright IBM Corp. 1991, 2003. All Rights Reserved.
*
* US Government Users Restricted Rights - Use, duplication or
* disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
*
===========================================================================
This README file contains the latest information about VisualAge C++
Professional for AIX, Version 6.0 that was not available for our
printed publications or our on-line help.
The latest information about installing VisualAge C++ Professional for
AIX, Version 6.0 with License Use Management (LUM) can be found in
/usr/vacpp/README.password. PLEASE READ THIS FILE BEFORE USING THE
PRODUCT.
By using VisualAge C++ Professional for AIX, Version 6.0, you agree to
the terms of the license information. The License Information document is
available as a PDF file and can be found in /usr/vacpp/pdf/en_US/license.pdf.
You will need to install Adobe Acrobat** Reader 3.0 or later to view the file.
You can download the reader from the Adobe website at http://www.adobe.com.
Note:
IBM VisualAge C++ Professional for AIX, Version 6.0 is licensed based on a
charge unit of one authorized user. The Program may be stored on more than
one machine, provided that the Program is not in active use on more than one
machine at the same time.
An authorized user is an individual or specific named user authorized to
have access to the program or any portion of the program. The Proof of
Entitlement for this program is evidence of your authorization. Each
individual or specific named user must obtain a Proof of Entitlement.
===============
README CONTENTS
1.0 Corrections to the Documentation
1.1 makeC++SharedLib and -qmkshrobj
1.2 Accepted/Ignored suboptions to -qlanglvl
1.3 New suboptions to -qlanglvl
1.4 -qipa=pdfname=filename
1.5 -qpdf
1.6 #pragma map
1.7 -qeh
1.8 Tempinc implementation file extension
1.9 -qlanglvl=newexcp
1.10 New Suboptions for -qshowinc
1.11 C compiler no longer supporting "inline" under -qlanglvl=extended
1.12 Two new pragmas that deal with templates: #pragma instantiate, #pragma do_not_instantiate
1.13 xlCcore: linking to run-time library with only C++ core language support
1.14 Addition of Support for -qweaksymbol Option
1.15 Support of -qroptr (read-only pointers) Option
1.16 Changes to -qnamemangling=ansi Option
1.17 New Option -Wm for Link Order Initialization of Static and Global Objects
2.0 Documentation Issues
2.1 Viewing Documentation
2.2 Browser Settings
2.3 Distributed Debugger Online Help
2.4 IMNSearch
2.5 -qdatalocal=names and -qdataimported=names
3.0 Miscellaneous
3.1 -lpthreads removed from non-threadsafe stanzas
3.2 Installation fails due to IMNSearch or LUM
3.3 Export Temporaries
3.4 Using USL I/O stream with C99 clog function
3.5 Deployment Considerations
4.0 Other Sources of Information
4.1 Product Home Page
5.0 Operating System Migration from AIX Version 4.3.3 to AIX Version 5.1
======================================================================
1.0 Corrections to the Documentation
======================================================================
--------------------------------------------------------------------
1.1 makeC++SharedLib and -qmkshrobj
--------------------------------------------------------------------
The following table shows equivalent options between
makeC++SharedLib and -qmkshrobj:
+-------------------------+---------------------+
| makeC++SharedLib option | xlC option |
+-------------------------+---------------------+
| -p nnn | -qmkshrobj=nnn |
+-------------------------+---------------------+
| -e file_name | -qexpfile=file_name |
+-------------------------+---------------------+
| -E export_file | -bE:export_file |
+-------------------------+---------------------+
| -I import_file | -bI:import_file |
+-------------------------+---------------------+
| -x | -qnolib |
+-------------------------+---------------------+
| -X 32|64 | -q32|-q64 |
+-------------------------+---------------------+
| -n entry_point | -e entry_point |
+-------------------------+---------------------+
--------------------------------------------------------------------
1.2 Accepted/Ignored suboptions to -qlanglvl
--------------------------------------------------------------------
The following -qlanglvl suboptions are accepted but ignored by the
C compiler. Use -qlanglvl=extended, -qlanglvl=extc99, or -qlanglvl=extc89
to enable the functions that these suboptions imply. For other values
of -qlanglvl, the functions implied by these suboptions are disabled.
a) [no]gnu_assert GNU C portability option.
b) [no]gnu_explicitregvar GNU C portability option.
c) [no]gnu_include_next GNU C portability option.
d) [no]gnu_locallabel GNU C portability option.
e) [no]gnu_warning GNU C portability option.
--------------------------------------------------------------------
1.3 New suboptions to -qlanglvl
--------------------------------------------------------------------
The following -qlanglvl suboptions are new for the C++ compiler:
a) [no]gnu_assert - GNU C portability option to enable or disable
support for the following GNU C system identification
assertions: #assert, #unassert, #cpu, #machine,
#system
b) [no]gnu_explicitregvar - GNU C portability option to control whether
the compiler accepts and ignores the
specification of explicit registers for
variables.
c) [no]gnu_include_next - GNU C portability option to enable or disable
support for the GNU C #include_next
preprocessor directive.
d) [no]gnu_locallabel - GNU C portability option to enable or disable
support for locally-declared labels.
e) [no]gnu_warning - GNU C portability option to enable or disable
support for the GNU C #warning preprocessor
directive.
--------------------------------------------------------------------
1.4 -qipa=pdfname=filename
--------------------------------------------------------------------
The -qipa compiler option includes a new suboption with the following
syntax:
-qipa=pdfname=filename
This option specifies the name of the profile data file containing
the PDF profiling information. If you do not specify a filename, the
compiler uses ._pdf as the default file name. The profile is placed
in the current working directory or in the directory named by the
PDFDIR environment variable. This lets you do simultaneous runs of
multiple executables using the same PDFDIR, which can be useful when
tuning with PDF on dynamic libraries.
--------------------------------------------------------------------
1.5 -qpdf1 / -qpdf2
--------------------------------------------------------------------
The -qpdf1 / -qpdf2 documentation should be changed as follows.
a) Disregard any references to -lpdf in the documentation.
b) You must specify at least the -O2 level of optimization when using
the -qpdf option. For best performance, use the -O3, -O4, or -O5
optimization levels.
c) Do not compile or run two different applications that use the same
PDFDIR directory at the same time, unless you have used the
-qipa=pdfname suboption to distinguish the sets of profiling
information.
d) The showpdf utility is not supported.
e) The resetpdf utility, found in /usr/xlopt/bin, can be used to reset
all profiling information to zeros. The profiling data files are
not removed, and remain in the pathname directory or in the PDFDIR
directory if the pathname is not specified, or in the current
directory if PDFDIR is not set. When you make changes to the
application and recompile some files, the profiling information
for those files is automatically reset because the changes may
alter the program flow. Run resetpdf to reset the profiling
information for the entire application after you make significant
changes that may change execution counts for parts of the program
that were not recompiled.
--------------------------------------------------------------------
1.6 #pragma map
--------------------------------------------------------------------
Please note the following corrections and additions to the #pragma map
documentation.
In the Syntax section, the following note should be added to the
description for the "name" variable:
"In C++ programs, if linking into a C++ name (a name that will have
C++ linkage signature, which is the default signature in C++), please
specify the mangled name (see example 3)."
In the Notes section, the last line in the list of items you should
not map with #pragma map should read:
"Functions with built-in linkage."
In the Examples section, replace the examples with the following:
Example 1 (C)
int funcname1()
{
return 1;
}
#pragma map( func, "funcname1" ) // maps::func to funcname1
int main()
{
return func(); // no function prototype needed in C
}
Example 2 (C++)
extern "C" int funcname1()
{
return 0;
}
extern "C" int func(); // function prototypes needed in C++
#pragma map( func, "funcname1" ) // maps ::func to funcname1
int main()
{
return func();
}
Example 3 (C++)
#pragma map( foo, "bar__Fv" )
int foo(); // function prototypes needed in C++
int main()
{
return foo();
}
int bar() {return 7;}
Note: The user can avoid using the mangled name "bar_FV" by
declaring "bar" as having C linkage (see example 4)
Example 4 (C++)
#pragma map( foo, "bar" )
int foo(); //function prototypes needed in C++
int main()
{
return foo();
}
extern "C" int bar() {return 7;}
--------------------------------------------------------------------
1.7 -qeh
--------------------------------------------------------------------
The -qeh compiler option includes two new suboptions with the
following syntax:
-qeh=v5
-qeh=v6
The v5 suboption instructs the compiler to generate exception
handling code that is the compatible with VisualAge C++ for AIX,
Version 5.0.
The v6 suboption instructs the compiler to generate new exception
handling code that correctly handles a try-catch block nested within
another catch block.
The default for the compiler is -qeh=v5. When -qeh is specified
without any suboption, -qeh=v5 is used.
--------------------------------------------------------------------
1.8 Tempinc implementation file extension
--------------------------------------------------------------------
When using the tempinc option to efficiently handle multiple
instantiations in different files, the template implementations must
be separated from the header file. The default tempinc implementation
file name has been expanded from just "template_header_name.c" to
include the file extensions ".t" and ".T". The first one found
(searched in the order ".c", ".t", ".T") will be the file used.
--------------------------------------------------------------------
1.9 -qlanglvl=newexcp
--------------------------------------------------------------------
The documentation incorrectly indicates that the suboption "newexcp"
exists for the "-qlanglvl" option. This suboption is not supported.
--------------------------------------------------------------------
1.10 New Suboptions for -qshowinc
--------------------------------------------------------------------
Suboptions have been added to the -qshowinc option as follows:
-qshowinc: Include all of the included files in the source listing.
-qnoshowinc: Do not include any of the included files in the source listing.
-qshowinc=<option1>:<option2>: ...
The available suboptions are:
all same as -qshowinc
usr include only the user header files
sys include only the system header files
--------------------------------------------------------------------
1.11 C compiler no longer supporting "inline" under -qlanglvl=extended
--------------------------------------------------------------------
The C compiler previously supported the "inline" keyword with
-qlanglvl=extended and -qlanglvl=extc89 options. This support is no longer
available by default for these language levels. If you need to use the
"inline" keyword under these language levels, specify the -qkeyword=inline
option.
--------------------------------------------------------------------
1.12 Two new pragmas that deal with templates: #pragma instantiate, #pragma do_not_instantiate
--------------------------------------------------------------------
Two new pragmas that deal with templates have been added,
#pragma instantiate
The #pragma instantiate directive causes a specific instance of a
template declaration to be immediately instantiated. Use this pragma
if you are migrating existing code. If you are writing new code, use the
standard C++ explicit instantiation.
The syntax of the #pragma instantiate directive is as follows:
#pragma instantiate entity
where entity is a class template-id
#pragma do_not_instantiate
The #pragma do_not_instantiate directive suppresses the instantiation
of a specified entity. It is typically used to suppress the implicit
instantiation of an entity for which a definition is supplied.
The syntax of the #pragma do_not_instantiate directive is as follows:
#pragma do_not_instantiate entity
where entity is a class template-id
--------------------------------------------------------------------
1.13 xlCcore: linking to run-time library with only C++ core language support
--------------------------------------------------------------------
This feature is intended for users who use third party (non IBM) C++
Standard Library implementations. The C++ core language run-time
library is required for proper functioning of C++ core language features
such as exception handling, operator new, RTTI, static initialization.
The following commands have been added:
xlCcore, xlC128core, xlCcore_r, xlC128core_r, xlCcore_r7, xlC128core_r7
Use one of these commands when you want your application to be linked
to the C++ core language run-time library but you do not want your
application to be linked to IBM-supplied standard C++ libraries
(such as iostreams) that are not required for core language support.
To ensure the proper header files are included and symbols are resolved
from the third party shared library. specify the third party C++
library header files in the include path and link to third party shared
library.
--------------------------------------------------------------------
1.14 Addition of Support for -qweaksymbol Option
--------------------------------------------------------------------
On AIX Version 5.1 with APAR IY31207 or AIX Version 5.2, you may use
-qweaksymbol to enable generation of weak symbols.
-qweaksymbol: enable generation of weak symbols
-qnoweaksymbol: disable generation of weak symbols (default)
When -qweaksymbol option is turned on, the compiler generates weak
symbols for the following:
a) inline functions with external linkage
You may use the -qweaksymbol option when compiling C++ programs
containing extern inline functions to suppress the linker
messages of:
ld: 0711-224 WARNING: Duplicate symbol:
b) identifiers specified as weak with #pragma weak or
functions specified as weak with __attribute__((weak))
1. #pragma weak id
If id is defined in the same compilation unit, it makes id
a weak definition. If id is not defined in the same compilation
unit, it makes references to id weak references.
2. #pragma weak id1=id2
Defines id1 as a weak global symbol, and references to id1 will
use the value of id2.
For C++ functions, id, id1, and id2 must be specified using
mangled names. #pragma weak may not be used for member functions.
3. __attribute__((weak))
If the function is defined, make it a weak definition. If it is
only referenced, make all references weak references.
--------------------------------------------------------------------
1.15 Support of -qroptr (read-only pointers) Option
--------------------------------------------------------------------
On AIX Version 5.2 with APAR IY49415, you may use -qroptr to enable
read-only pointers (address constants) to be moved from the .data
section to the .text section. The .text section is always read-only
and is never modified by either the loader or by an application.
Since .text is shared among multiple processes, but .data is not, a
reduction in memory usage is possible when a move has been made of
an application's constant pointers using -qroptr. This option is
not supported for linked libraries, ie. code that links into a share
library.
-qroptr: enable read-only pointers to be moved to the .text section
-qnoroptr: leave read-only pointers in the .data section (default)
--------------------------------------------------------------------
1.16 Change to -qnamemangling=ansi Option
--------------------------------------------------------------------
a) Function parameter list mangling for repeated parameters of the
same function parameter type has changed under -qnamemangling=ansi
option. Repeated parameters of the same function parameter type
are mangled according to the compressed encoding scheme as following:
<parameter> ::= T <param number> [_] #single repeat of a previous parameter
::= N <repetition digit> <param number> [_] #2-9 repetitions
where
<param number> indicates the previous parameter number, which is
repeated. It is followed by an '_' if <param number>
contains multiple digits.
<repetition digit> must be greater than 1 and less than 10. If
an argument is repeated more than 9 times, this
rule is applied multiple times. For example, a
sequence of 38 parameters that are the same as
parameter 1 mangles to "N91N91N91N91N21".
Under -qnamemangling=ansi scheme change, repeated function parameters
now ignore top-level cv-qualifiers when they are compared to determine
if they have the same type.
b) Previously, the mangling of non-type integral template arguments
was written as a 32-bit unsigned decimal number and prefixed by 'SP'.
Due to ambiguities introduced by this in mangling 64-bit values,
this scheme has been changed for -qnamemangling=ansi:
<non-type template argument> ::= SM #value of INT_MIN
::= SP <number> #positive integral argument
::= SN <number> #negative integral argument
When a non-type integral template argument is positive, the number
is prefixed with SP. When a non-type integral template argument
is negative, the number is prefixed with SN, and the decimal number
is written without the minus sign. There is no limit in the range
of decimal numbers which can be represented.
This breaks binary compatibility with templates using negative
non-type integral arguments other than INT_MIN, as well as positive
integral values, which cannot be represented in a 32-bit quantity.
To preserve binary compatibility, namemangling scheme prior to this
change may be obtained by specifying -qnamemangling=v6 option or
corresponding #pragma namemangling(v6).
--------------------------------------------------------------------
1.17 New Option -Wm for Link Order Initialization of Static and Global Objects
--------------------------------------------------------------------
By default, static objects are initialized in the order of priority
specified by #pragma priority or the -qpriority option. The order of
initialization is nondeterministic for static and global objects of
the same priority level. The new -Wm option and its two suboptions:
-c and -r, allow users to change the default initialization method.
a) The -Wm,-c option will instruct the compiler to perform the link
order initialization. This means that static and global objects
of the same priority level will be initialized in the order in
which they were encountered during the linking phase.
b) The -Wm,-r option is the opposite of the -Wm,-c option. It will
instruct the compiler to perform the reverse link order
initialization. Static and global objects of the same priority
level will be initialized in the opposite order in which they
were encountered during the linking phase.
======================================================================
2.0 Documentation Issues
======================================================================
--------------------------------------------------------------------
2.1 Viewing Documentation
--------------------------------------------------------------------
Documentation is in HTML format and must be viewed with a
frames-capable HTML browser. Documentation is also available in
PDF format.
To start the HTML help system, invoke "/usr/vacpp/bin/vacpphelp".
This tool is contained in the vacpp.html.help fileset.
Note:
Certain versions of Netscape Communicator have a well-known problem
with HTML frames when they are first loaded. According to Netscape,
you should restart the browser to make subsequent calls to framesets
will display properly.
--------------------------------------------------------------------
2.2 Browser Settings
--------------------------------------------------------------------
a) Ensure that the environment SOCKS_NS is not set.
b) Your browser must not have proxy handling for the localhost port.
Ensure you turn off proxy handling for localhost in your browser.
In Netscape 4 (Communicator):
1. Select Edit... Preferences..
2. Double-click Advanced in the Category tree
3. Click Proxies in the Advanced subtree
4. Click View at the Manual Proxy Configuration selection
5. Type:
localhost:49213
in the "Exceptions... Do not use proxy servers for
domains beginning with" box.
If you have other entries here, separate the new entry
with a comma.
6. Click OK, then click OK to exit the Preferences Window.
c) If you experience a problem installing the IMNSearch component,
completely remove the component and re-install.
Do not rely on installp -u to clean up everything, such as
"group" creates.
Note:
This only applies to new installs of the IMNSearch component.
If you have a previous version of the IMNSearch component, you
should not remove the component before trying to re-install.
--------------------------------------------------------------------
2.3 Distributed Debugger Online Help
--------------------------------------------------------------------
a) To access the Distributed Debugger online help that is specific
to this product, ensure that the product name is selected in the
Select product context dialog box. To access this dialog box, select
Change Product Context from the Distributer Debugger's Help
pull-down menu.
b) When using an English version of Netscape to view Japanese or
Simplified Chinese versions of the Distributed Debugger online
help, fly-over help may be corrupted when it is used over the
navigation bar of the online help.
--------------------------------------------------------------------
2.4 IMNSearch
--------------------------------------------------------------------
In the "Getting Started" and "Memo to Users" documentation under
the section about filesets required for the Online Help, the IMNSearch
filesets are shipped with the AIX operating system. The latest level
of the IMNSearch filesets should be obtained and installed prior to
installing the VisualAge C++ for AIX product.
For convenience, a version of IMNSearch is available on the CD-ROM.
See Section 3.2 in this README file.
--------------------------------------------------------------------
2.5 -qdatalocal=names and -qdataimported=names
--------------------------------------------------------------------
The documentation states the following:
-qdatalocal=names marks the named variables as local, where
names is a list of identifiers separated by colons (:).
-qdataimported=names marks the named variables as imported,
where names is a list of identifiers separated by colons (:).
The default is not changed.
The documentation should also indicate that the names should be
specified with their mangled variable name.
For example:
struct C
{
static int i;
}
To specify C::i is local data, the option -qdatalocal=i__1C should be
used. The same name should also be used for -qproclocal -qprocimported
and -qprocunknown.
======================================================================
3.0 Miscellaneous
======================================================================
--------------------------------------------------
3.1 -lpthreads removed from non-threadsafe stanzas
--------------------------------------------------
-lpthreads has been removed from the xlC and xlC128 stanza's within
the configuration file. This is a change in behaviour from
VisualAge C++ for AIX, V5.0.
--------------------------------------------------
3.2 Installation fails due to IMNSearch or LUM
--------------------------------------------------
Installation fails due to missing or down level of IMNSearch or
LUM filesets on system.
For convenience, a version of IMNSearch and LUM are available
with this product on the CD-ROM. However, the version on the CD
may not be the latest version. It is recommended that the latest
version be installed on your system.
To install LUM from the CD, insert the CD-ROM into the CD-ROM drive.
Mount the CD-ROM as follows:
a) As root, invoke "smit".
b) Select "System Storage Management (Physical & Logical Storage)",
press the "enter" key.
c) Select "File Systems", press the "enter" key.
d) Select "Add / Change / Show / Delete File Systems", press the "enter"
key.
e) Select "CDROM File Systems", press the "enter" key.
f) Select "Add a CDROM File System", press the "enter" key.
g) Enter the "DEVICE" name (e.g. "cd0").
h) Enter the "MOUNT POINT" where you would like to mount the CD-ROM
(e.g. "/cdrom").
i) Press the "enter" key.
j) Exit "smit".
The IMNSearch installp images are available in the sub-directory
"IMNSearch" indicated by the mount point of the CD-ROM
(e.g. "/cdrom/IMNSearch".)
The LUM installp images are available in the sub-directory
"lum" indicated by the mount point of the CD-ROM
(e.g. "/cdrom/lum".)
--------------------------------------------------
3.3 Exporting Temporaries
--------------------------------------------------
The compiler incorrectly exported temporary variables. As of
6.0.0.1, the compiler no longer exports temporary variables.
--------------------------------------------------
3.4 Using USL I/O stream with C99 clog function
--------------------------------------------------
The C run-time library in AIX version 5.2 now supports the C99
complex functions. These include a function called clog
(i.e. the complex logarithm), which has the same name as the
USL ::clog stream (see footnote below). The clog function
resides in the math library libm.a. The compiler's default
configuration file links libm.a after libC.a so that
the USL ::clog stream is available by default; the
C99 clog function is not available in this configuration.
The reverse would happen if you change the link order by
explicitly specifying libm.a before the C++ library on the
command line.
The following are possible scenarios in your application:
1) The C99 clog function is not used. The compiler's default
configuration file would work. If you specify libraries on
the linker command line, make sure libm.a is linked after
the C++ libraries.
2) C code that uses C99 clog() is linked with C++ code that
doesn't use the USL ::clog stream.
Make sure that libm.a is linked before the C++ libraries,
for example by specifying -lm to the link step.
3) C code that uses C99 clog() is linked with C++ code that uses
the USL ::clog stream.
This is a limitation due to the introducing of the C99 clog
function. Try the following as workarounds.
a. Change the application to use the C++ std I/O stream. The std
name space separates std::clog stream from C99 clog().
b. Avoid using C99 clog(). Use the other elementary functions
and formulae as substitute if the algorithm permits.
c. Change the application to avoid using the USL ::clog stream
and use other streams instead.
Note: The USL I/O stream class library was part of the IBM
Open Class Library in previous releases. Please refer
to the IBM Open Class Library Transistion Guide for
more information.
--------------------------------------------------
3.5 Deployment Considerations
--------------------------------------------------
When an application is built and linked to the run-time, it must
use that level of the run-time or later when deployed.
======================================================================
4.0 Other Sources of Information
======================================================================
----------------------
4.1 Product Home Page
----------------------
For the latest information about VisualAge C++ Professional for AIX,
Version 6.0, see the VisualAge C++ home page at:
http://www.ibm.com/software/awdtools/vacpp
========================================================================
5.0 Operating System Migration from AIX Version 4.3.3 to AIX Version 5.1
========================================================================
DURING AN OPERATING SYSTEM MIGRATION, USERS ARE REQUIRED TO PERFORM
TWO STEPS TO ENSURE VISUALAGE C++ WILL CONTINUE TO OPERATING
CORRECTLY. THIS IS DUE TO THE LIMITATION OF THE AIX MIGRATION
PROCESS.
The VisualAge C++ product contains a number of filesets specific
to the operating system level which are not contained on the AIX
media. Therefore, after migrating from an earlier version of AIX
to AIX 5L Version 5.1, users will be required to manually install
the AIX 5L versions of the filesets from the VisualAge C++ media.
Only the filesets which are required by the users need to be installed.
These filesets are:
memdbg.aix50.adt
vacpp.cmp.aix50.lib
vacpp.cmp.aix50.tools
vacpp.memdbg.aix50.lib
vacpp.memdbg.aix50.rte
xlopt.aix50.lib
xlsmp.aix50.rte
After the migration, if there exists AIX 4.3.3 version of the above
filesets but are missing the AIX 5L versions, you will be required
to install them.