z/OS V1R10 XL C/C++ readme

This readme file contains the latest information about the
"C/C++ without Debug Tool" optional feature of z/OS V1R10 that
was not previously available for the documentation.

This file will be updated from time to time via PTF, so that you can
get the latest information possible.


========================================================================
August 15, 2008

1. The following information relates to Chapter 19 of the z/OS V1R10
   XL C/C++ Language Reference in "Macros indicating the z/OS XL C/C++
   compiler product":

   The predefined value of macro __COMPILER_VER__ reads "In z/OS
   Version 1 Release 10, the value of the macro is X'410100000."
   It should read: "In z/OS Version 1 Release 10, the value of
   the macro is X'410A0000."

   The predefined value of macro __IBMC__ reads "In z/OS XL C/C++
   Version 1 Release 10, the value of the macro is 410100." It should
   read: "In z/OS XL C/C++ Version 1 Release 10, the value of the macro
   is 41100."

   The predefined value of macro __IBMCPP__ reads "In z/OS XL C/C++
   Version 1 Release 10, the value of the macro is 410100." It should
   read: "In z/OS XL C/C++ Version 1 Release 10, the value of the macro
   is 41100."

2. If message "CCN1107 Program too complex in function &1" is
   accompanied by an Internal Compiler Error message indicating
   "FPR save area > 4095 bytes", this may be mitigated by:

   a) Recompilation with ARCH<=5, or
   b) Recompilation with XPLINK enabled, or
   c) Reduce number and/or size of parameters being passed to &1.
      Avoid passing large data structures by value.
      

========================================================================
October, 2009

What's New?
* A new suboption added to the dbgld command to capture source file
  content in the module map.
* A new MVS batch utility -- CDADBGLD.  This utility is functionally
  equivalent to the dbgld command.
* The compiler DEBUG option stores the source file codeset information
  into the .dbg debug side file.  Debuggers can use this information to
  display source file in the correct codeset.

The full support of captured source for dbgld/CDADBGLD require the
following APAR:
z/OS XL C/C++ compiler: PK96534
z/OS Run-Time Library Extensions (CDA): PK96539
Language Environment for z/OS: PK98956

Description of dbgld command:
The compiler creates a .dbg file for each compilation unit if the DEBUG
compiler option is specified. The path names of all of the .dbg files
are then stored in the module, which is an executable file or a DLL. The
dbgld command opens all of the .dbg files associated with the module and
stores all of the functions, global variables, external types, and
source file names in a single module map file with a .mdbg extension. In
addition, the contents of all of the .dbg files are packaged together
into this same .mdbg file. The dbgld command only needs to be executed
once after binding. Debuggers that support demand load can use the .mdbg
file for faster access to debug information.  For more information on
using the module map to improve debugger performance, see z/OS Common
Debug Architecture User's Guide.
If the original source files are not available at debugging time (for
example, the source files are moved into a different directory or the
compiling and debugging are performed on different machines), you can
add the source file contents to the .mdbg file before the source files
are relocated. By default, dbgld does not capture source file contents
into the .mdbg file.  To do so, you can specify the '-c' option when
invoking the dbgld command. A debugger that supports captured source can
then retrieve the source file contents from the .mdbg file.

Description of CDADBGLD utility:
A new cataloged procedure CDADBGLD is available, and is functionally
equivalent to the dbgld command. The following example shows how to
invoke the CDADBGLD utility, specify the module name of MYHLQ.MOD(TEST),
display the version of CDADBGLD, and create a module level debug side
file called MYHLQ.MDBG(TEST):
   //CDADBGLD EXEC CDADBGLD,
   // INFILE='MYHLQ.MOD(TEST)',
   // CPARM='VERSION',
   // OUTFILE='MYHLQ.MDBG(TEST),DISP=SHR'
Where:
  INFILE  - Specifies the module name.
  OUTFILE - Specifies the module level debug side file that will be
            written to.
  CPARM   - Passes options into the CDADBGLD utility. The valid options
            are:
             VERSION:	Displays the version of CDADBGLD as well
                        as the Common Debug Architecture run-time
                        phaseid information.
	     CAPSRC:	Store source text into the module map.

dbgld/CDADBGLD utility restriction:
In addition to the restrictions documented in the documentation,
source files compiled with NOGOFF and NOLONGNAME are not processed by
the utility. If the entire module is made up of these compilation units,
an error message will be generated to indicate that no debug information
was found. Compile your application with LONGNAME or GOFF to mitigate
this restriction.


========================================================================
December, 2009

The following information relates to Chapter 3 of the z/OS V1R10 
Metal C Programming Guide and Reference:
In the "Example" section under the section "__cinit() - Initialize a 
Metal C environment", the following note is added after the example code:
"Note: To compile this example code, you must specify the LONGNAME 
option, or the LP64 option, or both."


========================================================================
July 2010

Additional information about the LONGNAME compiler option and 
prelinking z/OS XL C/C++ programs

- The following information is added to the section "Specifying 
z/OS XL C compiler options using #pragma options" in the z/OS V1R10 XL 
C/C++ User's Guide.
"You can use the #pragma preprocessor directive to override the 
default values for compiler options. The exception is 
LONGNAME/NOLONGNAME, where the compiler options override the #pragma 
preprocessor directives."

- The following note is added to the section "Pragma equivalent" 
under "LONGNAME | NOLONGNAME" in the z/OS V1R10 XL C/C++ User's Guide.
"You can use the #pragma preprocessor directive to override the 
default values for compiler options. However, for LONGNAME/NOLONGNAME, 
the compiler options override the #pragma preprocessor directives."

- The following note is added to the section "Mapping long names 
to short names" in the z/OS V1R10 XL C/C++ User's Guide.
"Programs compiled with the LONGNAME compiler option and which use 
POSIX functions must define _LONGMAP when using the prelinker outside 
of a z/OS UNIX shell environment. If __LONGNAME__ is defined and 
_LONGMAP is not defined, you will not get the right mapping of POSIX 
functions."
 

========================================================================
August 2010

Description changes of message CCN2320

- The "User response" part of message CCN2320 in the z/OS V1R10 XL 
C/C++ Messages is changed to:
"User response: No user response is required."   


========================================================================