B.4 Interfacing with COBOL

1. The facilities relevant to interfacing with the COBOL language are the package Interfaces.COBOL and support for the Import, Export and Convention pragmas with convention_identifier COBOL.
2. The COBOL interface package supplies several sets of facilities:
   1. A set of types corresponding to the native COBOL types of the supported COBOL implementation (so-called "internal COBOL representations"), allowing Ada data to be passed as parameters to COBOL programs
   2. A set of types and constants reflecting external data representations such as might be found in files or databases, allowing COBOL-generated data to be read by an Ada program, and Ada-generated data to be read by COBOL programs
   3. A generic package for converting between an Ada decimal type value and either an internal or external COBOL representation

1. The library package Interfaces.COBOL has the following declaration:

2. package Interfaces.COBOL is
      pragma Preelaborate(COBOL);
   

3.    -- Types and operations for internal data representations
   

4.    type Floating      is digits implementation-defined;
      type Long_Floating is digits implementation-defined;
   

5.    type Binary      is range implementation-defined;
      type Long_Binary is range implementation-defined;
   

6.    Max_Digits_Binary      : constant := implementation-defined;
      Max_Digits_Long_Binary : constant := implementation-defined;
   

7.    type Decimal_Element  is mod implementation-defined;
      type Packed_Decimal is
        array (Positive range <>) of Decimal_Element;
      pragma Pack(Packed_Decimal);
   

8.    type COBOL_Character is implementation-defined character type;
   

9.    Ada_To_COBOL : array (Character) of COBOL_Character
        := implementation-defined;
   

10.    COBOL_To_Ada : array (COBOL_Character) of Character
         := implementation-defined;
    

11.    type Alphanumeric is
         array (Positive range <>) of COBOL_Character;
       pragma Pack(Alphanumeric);
    

12.    function To_COBOL (Item : in String) return Alphanumeric;
       function To_Ada   (Item : in Alphanumeric) return String;
    

13.    procedure To_COBOL (Item       : in String;
                           Target     : out Alphanumeric;
                           Last       : out Natural);
    

14.    procedure To_Ada (Item     : in Alphanumeric;
                         Target   : out String;
                         Last     : out Natural);
    

15.    type Numeric is array (Positive range <>) of COBOL_Character;
       pragma Pack(Numeric);
    

16.    -- Formats for COBOL data representations
    

17.    type Display_Format is private;
    

18.    Unsigned             : constant Display_Format;
       Leading_Separate     : constant Display_Format;
       Trailing_Separate    : constant Display_Format;
       Leading_Nonseparate  : constant Display_Format;
       Trailing_Nonseparate : constant Display_Format;
    

19.    type Binary_Format is private;
    

20.    High_Order_First  : constant Binary_Format;
       Low_Order_First   : constant Binary_Format;
       Native_Binary     : constant Binary_Format;
    

21.    type Packed_Format is private;
    

22.    Packed_Unsigned   : constant Packed_Format;
       Packed_Signed     : constant Packed_Format;
    

23.    -- Types for external representation of COBOL binary data
    

24.    type Byte is mod 2**COBOL_Character'Size;
       type Byte_Array is array (Positive range <>) of Byte;
       pragma Pack (Byte_Array);
    

25.    Conversion_Error : exception;
    

26.    generic
          type Num is delta <> digits <>;
       package Decimal_Conversions is
    

27.       -- Display Formats: data values are represented as Numeric
    

28.       function Valid (Item   : in Numeric;
                          Format : in Display_Format) return Boolean;
    

29.       function Length (Format : in Display_Format) return Natural;
    

30.       function To_Decimal (Item   : in Numeric;
                               Format : in Display_Format) return Num;
    

31.       function To_Display (Item   : in Num;
                               Format : in Display_Format)
            return Numeric;
    

32.       -- Packed Formats:
          -- data values are represented as Packed_Decimal
    

33.       function Valid (Item   : in Packed_Decimal;
                          Format : in Packed_Format) return Boolean;
    

34.       function Length (Format : in Packed_Format) return Natural;
    

35.       function To_Decimal (Item   : in Packed_Decimal;
                               Format : in Packed_Format) return Num;
    

36.       function To_Packed (Item   : in Num;
                              Format : in Packed_Format)
            return Packed_Decimal;
    

37.       -- Binary Formats:
          -- external data values are represented as Byte_Array
    

38.       function Valid (Item   : in Byte_Array;
                          Format : in Binary_Format) return Boolean;
    

39.       function Length (Format : in Binary_Format) return Natural;
          function To_Decimal (Item   : in Byte_Array;
                               Format : in Binary_Format) return Num;
    

40.       function To_Binary (Item   : in Num;
                            Format : in Binary_Format)
            return Byte_Array;
    

41.       -- Internal Binary formats:
          -- data values are of type Binary or Long_Binary
    

42.       function To_Decimal (Item : in Binary)      return Num;
          function To_Decimal (Item : in Long_Binary) return Num;
    

43.       function To_Binary      (Item : in Num)  return Binary;
          function To_Long_Binary (Item : in Num)  return Long_Binary;
    

44.    end Decimal_Conversions;
    

45. private
       ... -- not specified by the language
    end Interfaces.COBOL;
    

46. Each of the types in Interfaces.COBOL is COBOL-compatible.
47. The types Floating and Long_Floating correspond to the native types in COBOL for data items with computational usage implemented by floating point. The types Binary and Long_Binary correspond to the native types in COBOL for data items with binary usage, or with computational usage implemented by binary.
48. Max_Digits_Binary is the largest number of decimal digits in a numeric value that is represented as Binary. Max_Digits_Long_Binary is the largest number of decimal digits in a numeric value that is represented as Long_Binary.
49. The type Packed_Decimal corresponds to COBOL's packed-decimal usage.
50. The type COBOL_Character defines the run-time character set used in the COBOL implementation. Ada_To_COBOL and COBOL_To_Ada are the mappings between the Ada and COBOL run-time character sets.
51. Type Alphanumeric corresponds to COBOL's alphanumeric data category.
52. Each of the functions To_COBOL and To_Ada converts its parameter based on the mappings Ada_To_COBOL and COBOL_To_Ada, respectively. The length of the result for each is the length of the parameter, and the lower bound of the result is 1. Each component of the result is obtained by applying the relevant mapping to the corresponding component of the parameter.
53. Each of the procedures To_COBOL and To_Ada copies converted elements from Item to Target, using the appropriate mapping (Ada_To_COBOL or COBOL_To_Ada, respectively). The index in Target of the last element assigned is returned in Last (0 if Item is a null array). If Item'Length exceeds Target'Length, Constraint_Error is propagated.
54. Type Numeric corresponds to COBOL's numeric data category with display usage.
55. The types Display_Format, Binary_Format, and Packed_Format are used in conversions between Ada decimal type values and COBOL internal or external data representations. The value of the constant Native_Binary is either High_Order_First or Low_Order_First, depending on the implementation.

56. function Valid (Item   : in Numeric;
                    Format : in Display_Format) return Boolean;
    

    1. The function Valid checks that the Item parameter has a value consistent with the value of Format. If the value of Format is other than Unsigned, Leading_Separate, and Trailing_Separate, the effect is implementation defined. If Format does have one of these values, the following rules apply:
       1. Format=Unsigned: if Item comprises zero or more leading space characters followed by one or more decimal digit characters then Valid returns True, else it returns False.
       2. Format=Leading_Separate: if Item comprises zero or more leading space characters, followed by a single occurrence of the plus or minus sign character, and then one or more decimal digit characters, then Valid returns True, else it returns False.
       3. Format=Trailing_Separate: if Item comprises zero or more leading space characters, followed by one or more decimal digit characters and finally a plus or minus sign character, then Valid returns True, else it returns False.

1. function Length (Format : in Display_Format) return Natural;
   

   1. The Length function returns the minimal length of a Numeric value sufficient to hold any value of type Num when represented as Format.

1. function To_Decimal (Item   : in Numeric;
                        Format : in Display_Format) return Num;
   

   1. Produces a value of type Num corresponding to Item as represented by Format. The number of digits after the assumed radix point in Item is Num'Scale. Conversion_Error is propagated if the value represented by Item is outside the range of Num.

1. function To_Display (Item   : in Num;
                        Format : in Display_Format) return Numeric;
   

   1. This function returns the Numeric value for Item, represented in accordance with Format. Conversion_Error is propagated if Num is negative and Format is Unsigned.

1. function Valid (Item   : in Packed_Decimal;
                   Format : in Packed_Format) return Boolean;
   

   1. This function returns True if Item has a value consistent with Format, and False otherwise. The rules for the formation of Packed_Decimal values are implementation defined.

1. function Length (Format : in Packed_Format) return Natural;
   

   1. This function returns the minimal length of a Packed_Decimal value sufficient to hold any value of type Num when represented as Format.

1. function To_Decimal (Item   : in Packed_Decimal;
                        Format : in Packed_Format) return Num;
   

   1. Produces a value of type Num corresponding to Item as represented by Format. Num'Scale is the number of digits after the assumed radix point in Item. Conversion_Error is propagated if the value represented by Item is outside the range of Num.

1. function To_Packed (Item   : in Num;
                       Format : in Packed_Format)
     return Packed_Decimal;
   

   1. This function returns the Packed_Decimal value for Item, represented in accordance with Format. Conversion_Error is propagated if Num is negative and Format is Packed_Unsigned.

1. function Valid (Item   : in Byte_Array;
                   Format : in Binary_Format) return Boolean;
   

   1. This function returns True if Item has a value consistent with Format, and False otherwise.

1. function Length (Format : in Binary_Format) return Natural;
   

   1. This function returns the minimal length of a Byte_Array value sufficient to hold any value of type Num when represented as Format.

1. function To_Decimal (Item   : in Byte_Array;
                        Format : in Binary_Format) return Num;
   

   1. Produces a value of type Num corresponding to Item as represented by Format. Num'Scale is the number of digits after the assumed radix point in Item. Conversion_Error is propagated if the value represented by Item is outside the range of Num.

1. function To_Binary (Item   : in Num;
                       Format : in Binary_Format) return Byte_Array;
   

   1. This function returns the Byte_Array value for Item, represented in accordance with Format.

1. function To_Decimal (Item : in Binary)      return Num;
   
   function To_Decimal (Item : in Long_Binary) return Num;
   

   1. These functions convert from COBOL binary format to a corresponding value of the decimal type Num. Conversion_Error is propagated if Item is too large for Num.

1. function To_Binary      (Item : in Num)  return Binary;
   
   function To_Long_Binary (Item : in Num)  return Long_Binary;
   

   1. These functions convert from Ada decimal to COBOL binary format. Conversion_Error is propagated if the value of Item is too large to be represented in the result type.

1. An implementation shall support pragma Convention with a COBOL convention_identifier for a COBOL-eligible type, See section B.1 Interfacing Pragmas.
   Implementation Permissions
   
2. An implementation may provide additional constants of the private types Display_Format, Binary_Format, or Packed_Format.
3. An implementation may provide further floating point and integer types in Interfaces.COBOL to match additional native COBOL types, and may also supply corresponding conversion functions in the generic package Decimal_Conversions.
   Implementation Advice
   
4. An Ada implementation should support the following interface correspondences between Ada and COBOL.
   1. An Ada access T parameter is passed as a "BY REFERENCE" data item of the COBOL type corresponding to T.
   2. An Ada in scalar parameter is passed as a "BY CONTENT" data item of the corresponding COBOL type.
   3. Any other Ada parameter is passed as a "BY REFERENCE" data item of the COBOL type corresponding to the Ada parameter type; for scalars, a local copy is used if necessary to ensure by-copy semantics.

NOTES


1. (15) An implementation is not required to support pragma Convention for access types, nor is it required to support pragma Import, Export or Convention for functions.
2. (16) If an Ada subprogram is exported to COBOL, then a call from COBOL call may specify either "BY CONTENT" or "BY REFERENCE".
   Examples
   
3. Examples of Interfaces.COBOL:

4. with Interfaces.COBOL;
   procedure Test_Call is
   

5.    -- Calling a foreign COBOL program
      -- Assume that a COBOL program PROG has the following declaration
      --  in its LINKAGE section:
      --  01 Parameter-Area
      --     05 NAME   PIC X(20).
      --     05 SSN    PIC X(9).
      --     05 SALARY PIC 99999V99 USAGE COMP.
      -- The effect of PROG is to update SALARY based on some algorithm
   

6.    package COBOL renames Interfaces.COBOL;
   

7.    type Salary_Type is delta 0.01 digits 7;
   

8.    type COBOL_Record is
         record
            Name   : COBOL.Numeric(1..20);
            SSN    : COBOL.Numeric(1..9);
            Salary : COBOL.Binary;  -- Assume Binary = 32 bits
         end record;
      pragma Convention (COBOL, COBOL_Record);
   

9.    procedure Prog (Item : in out COBOL_Record);
      pragma Import (COBOL, Prog, "PROG");
   

10.    package Salary_Conversions is
          new COBOL.Decimal_Conversions(Salary_Type);
    

11.    Some_Salary : Salary_Type := 12_345.67;
       Some_Record : COBOL_Record :=
          (Name   => "Johnson, John       ",
           SSN    => "111223333",
           Salary => Salary_Conversions.To_Binary(Some_Salary));
    

12. begin
       Prog (Some_Record);
       ...
    end Test_Call;
    

13. with Interfaces.COBOL;
    with COBOL_Sequential_IO;
    -- Assumed to be supplied by implementation
    procedure Test_External_Formats is
    

14.    -- Using data created by a COBOL program
       -- Assume that a COBOL program has created a sequential file with
       --  the following record structure, and that we need to
       --  process the records in an Ada program
       --  01 EMPLOYEE-RECORD
       --     05 NAME    PIC X(20).
       --     05 SSN     PIC X(9).
       --     05 SALARY  PIC 99999V99 USAGE COMP.
       --     05 ADJUST  PIC S999V999 SIGN LEADING SEPARATE.
       -- The COMP data is binary (32 bits), high-order byte first
    

15.    package COBOL renames Interfaces.COBOL;
    

16.    type Salary_Type      is delta 0.01  digits 7;
       type Adjustments_Type is delta 0.001 digits 6;
    

17.    type COBOL_Employee_Record_Type is  -- External representation
          record
             Name    : COBOL.Alphanumeric(1..20);
             SSN     : COBOL.Alphanumeric(1..9);
             Salary  : COBOL.Byte_Array(1..4);
             Adjust  : COBOL.Numeric(1..7);  -- Sign and 6 digits
          end record;
       pragma Convention (COBOL, COBOL_Employee_Record_Type);
    

18.    package COBOL_Employee_IO is
          new COBOL_Sequential_IO(COBOL_Employee_Record_Type);
       use COBOL_Employee_IO;
    

19.    COBOL_File : File_Type;
    

20.    type Ada_Employee_Record_Type is  -- Internal representation
          record
             Name    : String(1..20);
             SSN     : String(1..9);
             Salary  : Salary_Type;
             Adjust  : Adjustments_Type;
          end record;
    

21.    COBOL_Record : COBOL_Employee_Record_Type;
       Ada_Record   : Ada_Employee_Record_Type;
    

22.    package Salary_Conversions is
          new COBOL.Decimal_Conversions(Salary_Type);
       use Salary_Conversions;
    

23.    package Adjustments_Conversions is
          new COBOL.Decimal_Conversions(Adjustments_Type);
       use Adjustments_Conversions;
    

24. begin
       Open (COBOL_File, Name => "Some_File");
    

25.    loop
         Read (COBOL_File, COBOL_Record);
    

26.      Ada_Record.Name := To_Ada(COBOL_Record.Name);
         Ada_Record.SSN  := To_Ada(COBOL_Record.SSN);
         Ada_Record.Salary :=
            To_Decimal(COBOL_Record.Salary, COBOL.High_Order_First);
         Ada_Record.Adjust :=
            To_Decimal(COBOL_Record.Adjust, COBOL.Leading_Separate);
         ... -- Process Ada_Record
       end loop;
    exception
       when End_Error => ...
    end Test_External_Formats;
    

Go to the first, previous, next, last section, table of contents.