Issue 020401.1: Cobol Data Types

Author: Ron Brender
Champion: Ron Brender
Date submitted: 2002-04-01
Date revised:
Date closed:
Type: Extension
Status: Accepted with modifications
DWARF Version: 3
PROBLEM STATEMENT

Support for COBOL-specific data types is not available in DWARF.
Desirable capabilities include support for packed and unpacked
decimal, edited and fixed point types as well as COBOL "level-88"
conditions.


HISTORY

A draft proposal for COBOL data types was sent to the DWARF list
by Bob Monteleone (then of Compaq) in December 2001. During
January 2002, there was significant discussion of alternative
possible formulations.

In April 2002, Ron Brender distributed a copy of the final
specification that (then) Compaq had adopted. That specification
is attached below.


PROPOSAL

See attached.


DISCUSSION

This specification is currently being used by two OS environments
within HP:

  - OpenVMS for Itanium Systems

  - NonStop (formerly Tandem NSK) for Itanium Systems

OpenVMS support is currently in field test and expected to ship
by the end of the year. NonStop support is fully implemented in
internal development versions (but I am not aware of the rollout
schedule).

ATTACHMENT ("The Proposal")



                         DWARF spec for COBOL support
                                22 April 2002



     1  INTRODUCTION

     In order to support the COBOL language in DWARF, enhancements to the
     DWARF  V3 specification are necessary.  Specifically, extensions are
     required to describe decimal,  packed  decimal,  edited  and  scaled
     binary data types; also to describe 'level-88' conditions.


     Five new base types and one new tag will be introduced to  represent
     the new COBOL types and level-88 conditions.

          Base Types
          ----------
          DW_ATE_CPQ_packed_decimal
          DW_ATE_CPQ_zoned_decimal
          DW_ATE_CPQ_edited
          DW_ATE_CPQ_signed_fixed
          DW_ATE_CPQ_unsigned_fixed

          Tags
          ----
          DW_TAG_CPQ_condition



     2  BASE TYPES

     New base type values are needed for the DW_AT_encoding attribute  to
     represent fundamental COBOL types.


     2.1  Packed Decimal And Zoned Decimal Types

     The  DW_ATE_CPQ_packed_decimal  and  DW_ATE_CPQ_zoned_decimal   base
     types  are  used  to  represent  decimal  string numeric data types;
     packed and unpacked, and, signed and unsigned.


     The  DW_ATE_CPQ_packed_decimal  and  DW_ATE_CPQ_zoned_decimal   base
     types  have  a  DW_AT_CPQ_decimal_sign,  DW_AT_CPQ_digit_count and a
     DW_AT_CPQ_decimal_scale attribute.


     A  DW_AT_CPQ_decimal_sign  attribute   is   used   to   convey   the
     representation  of  the  sign  of  the  decimal  type.   Its integer
     constant value is interpreted to mean that the type  has  a  leading
     overpunch, trailing overpunch, leading separate or trailing separate
     sign representation or, alternatively, no sign at all.

     The DW_AT_CPQ_digit_count attribute is  an  integer  constant  value
     that represents the number of digits in an instance of the type.


     The DW_AT_CPQ_decimal scale attribute is an integer  constant  value
     that  represents  the  exponent  of  the base ten scale factor to be
     applied to an instance of the type.  Zero  scale  puts  the  decimal
     point  immediately  to  the  right  of  the least significant digit.
     Positive scale moves the decimal point to the right and implies that
     additional zero digits on the right are not stored in an instance of
     the type.  Negative scale moves the decimal point to  the  left;  if
     the absolute value of the scale is larger than the digit count, this
     implies additional zero digits on the left not stored in an instance
     of the type.


          Values and Meanings for DW_AT_CPQ_decimal_sign
          ----------------------------------------------
          DW_DS_CPQ_unsigned (=1)
                    Unsigned

          DW_DS_CPQ_leading_overpunch (=2)
                    Sign is encoded in the most significant  digit  in  a
                    target-dependent manner.

          DW_DS_CPQ_trailing_overpunch (=3)
                    Sign is encoded in the least significant digit  in  a
                    target-dependent manner.

          DW_DS_CPQ_leading_separate (=4)
                    Sign is a '+' or '-' character to  the  left  of  the
                    most significant digit.

          DW_DS_CPQ_trailing_separate (=5)
                    Decimal type:  Sign is a '+' or '-' character to  the
                    right of the least significant digit.  Packed decimal
                    type:    Least   significant   nibble   contains    a
                    target-dependent   value   indicating   positive   or
                    negative.



     2.2  Edited Numeric And Edited Alphanumeric Types

     The DW_ATE_CPQ_edited base type is used to represent a COBOL  edited
     numeric or alphanumeric data type.


     The edited type entry has a DW_AT_CPQ_picture_string attribute whose
     value  is  a  null-terminated string containing the target-dependent
     picture string associated with the type.

    If the edited base type entry describes an edited numeric data type,
     the   edited   type   entry   has   a  DW_AT_CPQ_digit_count  and  a
     DW_AT_CPQ_decimal_scale attribute.  These attributes are interpreted
     as   in   the   context   of   the   DW_ATE_CPQ_packed_decimal   and
     DW_ATE_CPQ_zoned_decimal base  types.   If  the  edited  type  entry
     describes  an  edited  alphanumeric data type, the edited type entry
     does not have these attributes.


     The  presence  or   absence   of   the   DW_AT_CPQ_digit_count   and
     DW_AT_CPQ_decimal_scale  attributes  allows  a  debugger  to  easily
     distinguish edited numeric from  edited  alphanumeric,  although  in
     principle  the  digit  count and scale are derivable by interpreting
     the picture string.



     2.3  Signed And Unsigned Fixed-Point Types

     The DW_ATE_CPQ_signed_fixed  and  DW_ATE_CPQ_unsigned_fixed  entries
     describe   signed   and  unsigned  fixed-point  binary  data  types,
     respectively.


     The fixed binary type entries have a DW_AT_CPQ_digit_count attribute
     with    the    same    interpretation    as    described   for   the
     DW_ATE_CPQ_packed_decimal and DW_ATE_CPQ_zoned_decimal base types.


     For a data type with a decimal scale factor, the fixed  binary  type
     entry   has   a  DW_AT_CPQ_decimal_scale  attribute  with  the  same
     interpretation as described for  the  DW_ATE_CPQ_packed_decimal  and
     DW_ATE_CPQ_zoned_decimal base types.

     For a data type with a binary scale factor, the  fixed  binary  type
     entry     has     a     DW_AT_CPQ_binary_scale    attribute.     The
     DW_AT_CPQ_binary_scale attribute is an integer constant  value  that
     represents  the  exponent of the base two scale factor to be applied
     to an instance of the  type.   Zero  scale  puts  the  binary  point
     immediately  to  the  right  of the least significant bit.  Positive
     scale  moves  the  binary  point  to  the  right  and  implies  that
     additional  zero  bits on the right are not stored in an instance of
     the type.  Negative scale moves the binary point to the left; if the
     absolute  value of the scale is larger than the number of bits, this
     implies additional zero bits on the left not stored in  an  instance
     of the type.


     For a data type with an arbitrary scale  factor,  the  fixed  binary
     type  entry  has  a  DW_AT_CPQ_small  attribute.   It  references  a
     DW_TAG_constant entry with an arbitrary type attribute.   The  scale
     factor  value is interpreted in accordance with the value enumerated
     in the DW_TAG_constant entry.  The value represented is the  product
     of  the integer value in memory and the associated contant entry for
     the type.

     3  CONDITIONS

     The DW_TAG_CPQ_condition debugging  information  entry  describes  a
     COBOL  level-88  condition.   A level-88 condition associates a data
     item, called the conditional variable, with a set  of  one  or  more
     constant values and/or value ranges.  Semantically, the condition is
     'true' if the  conditional  variable's  value  matches  any  of  the
     described constants, and the condition is 'false' otherwise.


     If a name has been given to the condition, the condition entry has a
     DW_AT_name  attribute whose value is a null-terminated string giving
     the condition name as it appears in the source program.


     The  condition  entry's  parent  entry  describes  the   conditional
     variable;  normally  this will be a DW_TAG_variable or DW_TAG_member
     entry.  The  type  of  the  condition  entry  is  derived  from  the
     DW_AT_type attribute of the parent entry.


     The condition entry owns DW_TAG_constant and/or DW_TAG_subrange_type
     entries  that  describe  the  constant  values  associated  with the
     condition.  If any child entry  has  a  DW_AT_type  attribute,  that
     attribute  should  describe  a type compatible with the type derived
     from the condition entry's parent.


     For conditional variables with alphanumeric types, COBOL  permits  a
     source  program  to  provide ranges of alphanumeric constants in the
     condition.  Normally a subrange type entry does not describe  ranges
     of  strings;  however,  it can be done using bounds' attributes that
     are references to constant entries describing strings.   A  subrange
     type  entry  may  refer to constant entries that are siblings of the
     subrange type entry.

          Tags and Attributes
          -------------------

          DW_TAG_CPQ_condition
          DECL
          DW_AT_name
          DW_AT_sibling

----------------------------------
Added 05/09/2005:

The "proposal" in issue 020401.1 is not quite a proper proposal
in that it uses the vendor-specific names adopted by (then)
Compaq which include "CPQ_" in the attribute and code names.
Clearly the "CPQ_" substrings should be removed.

One other naming change is recommended: the base type name
DW_ATE_CPQ_zoned_decimal have proven obscure and confusing. For
the DWARF standard, the name DW_ATE_numeric_string is much more
descriptive and suggestive.

Finally, the write-up does not propose where text should be
included. This can be handled as follows:


    Proposal    What            Goes here in DWARF V3
    Section
    --------    ----            ---------------------

      1     list of base types  Figure 12 (Sec 5.1, p64)

                    Add new DW_ATE codes in
                    Figure 23 (p141)

      2.1   description of base Insert at end of 5.1
        types           (prior to Fig 12)

                    Create a new Figure
                    in Section 7.8 for the
                    Decimal Sign (DW_DS_*)
                    encoding

        Note: while 2.1 has subsections, I don't propose
        to add corresponding subsections to 5.1

      3     Condition       Insert as new 5.7 (and
                    renumber the following
                    Sections)

                    Add DW_TAG_condition
                    in Figure 1 (p6) and
                    in Figure 16 (p127)


With these changes and supplemental information, 020401.1 should
be appropriate for consideration.

================================================================
5/17/2005:  Accepted with modifications:
  Remove CPQ from names.
  Replace "zoned decimal" with "decimal string".