In Storage Debug (ISD) Information Conversion Utility

In Storage Debug (ISD) information is produced by C/C++ compilers and other language translators to enable debugging tools to present information and aid developers in debugging. ISD information is not a programmable interface as the knowledge and understanding of the information is encapsulated in the debugging tools. This effectively limits the field of debug related tools. To remove this limitation a new form of debugging information has been introduced. The data uses the DWARF format, and is stored in ELF object files. For the convenience of the zSeries user, the debugging information can be accessed using the Common Debug Architecture (CDA) libraries and utilities. One of these utilities is the isdcnvt utility.

Prior to z/OS® V1R6, the only method for generating debugging information was to use the TEST option to generate ISD information. As of z/OS V1R6, the DWARF debugging information is generated by using the DEBUG compiler option. However, DWARF debugging information can also be generated from ISD information by using isdcnvt.

The input to isdcnvt is an object file generated by the C/C++ compiler using the TEST or DEBUG(FORMAT(ISD)) compiler options. The utility produces a file containing the new debugging information which is suitable for use with debug tools that support ELF and DWARF interfaces, such as dbx.

The following syntax is used to invoke isdcnvt:

isdcnvt [-v] -o object_file_name
where:
  • -v is an optional command line flag that produces version information for the libelf, libdwarf, and libddpi libraries
  • object_file_name is the name of an object file that contains the ISD information

Object file formats supported by isdcnvt are OBJ, XOBJ and GOFF. Object files can have XPLINK or non-XPLINK linkage, but only object files produced by the IBM® XL C/C++ compilers are currently supported.

Note: For more information about the supported compilers, see CDA requirements and recommendations.

The output file name is based on object_file_name. Although the object file name can have any suffix, only the standard .o suffix is recognized and replaced with the standard .dbg suffix when constructing the output file name. All other suffixes, including no suffix at all, are kept, and the standard .dbg suffix is appended when constructing the output file name.

Note: This process will overwrite any existing file with the same name as the expected output file.
isdcnvt is a UNIX System Services utility that runs in the shell environment. It supports only zFS files for input and output. If no errors are encountered during the conversion, the utility terminates with return code zero. If an error condition is detected during the conversion, the utility returns an error code with the following format: 
CRR
where
  • C is a decimal digit indicating the error code
  • RR is a two-digit decimal number indicating the reason code
The error codes are:
  • 1 - a recoverable error condition
  • 2 - an internal error that should be reported to the IBM service team.
The reason codes associated with the error code 1 are:
  • 01 - empty compilation unit

    This error indicates that the compilation unit contained no code sections, which is typical for data-only compilation units. If this is an expected condition, the build process can check for this return code and continue processing.

  • 02 - invalid usage
    This error indicates that the utility was not invoked using the correct invocation syntax. To resolve the problem, ensure that the correct invocation syntax is used.
    Note: The isdcnvt utility uses the getopt() runtime library function, which may emit error messages.
  • 03 - failed to load debug APIs

    To perform the conversion, the conversion utility requires debug APIs that are loaded at initialization. The APIs are provided in the CDAEED DLL, which is found in the CEE.SCEERUN2 MVS™ data-set. To resolve the problem, ensure that CDAEED is found by the loader using the MVS search order. For example, ensure that CEE.SCEERUN2 is in the STEPLIB environment variable.

  • 04 - compilation unit has no debugging information

    This error indicates that the compilation unit did not contain any debugging information. To resolve this problem, ensure that the compilation unit is compiled with the TEST or DEBUG(FORMAT(ISD)) compiler option.

  • 05 - failed to open input file

    This error can occur if an invalid object file has been specified, or if it does not have sufficient read permission. To resolve the problem, ensure that a valid object file is specified and that it has sufficient read permission.

  • 06 - failed to open output file

    An output file for the converted debugging information could not be opened. This can be caused by conditions such as insufficient space in the file system that is hosting the current directory, or no write permission for the current directory. To resolve the problem, ensure that the file system has sufficient space (usually one third of the input file size), and that the write permission is set for the current directory.

  • 07 - version mismatch

    The conversion utility dynamically loads debug APIs, so the version of the utility may not match the version of the debug APIs. To resolve the problem, ensure that the correct version of the debug APIs is found by the loader using the MVS search order.

The reason code associated with the error code 2 is a two-digit decimal number providing further information that can help diagnose the problem. This error code usually indicates a problem in the conversion utility or a language translator that produced the object file. To resolve this problem, contact IBM support and provide the test case that reproduces the problem.