

                                   Annex B
                                 (normative)

                        Interface to Other Languages


1     This Annex describes features for writing mixed-language programs.
General interface support is presented first; then specific support for C,
COBOL, and Fortran is defined, in terms of language interface packages for
each of these languages.


B.1 Interfacing Pragmas


1     A pragma Import is used to import an entity defined in a foreign
language into an Ada program, thus allowing a foreign-language subprogram to
be called from Ada, or a foreign-language variable to be accessed from Ada. In
contrast, a pragma Export is used to export an Ada entity to a foreign
language, thus allowing an Ada subprogram to be called from a foreign
language, or an Ada object to be accessed from a foreign language. The pragmas
Import and Export are intended primarily for objects and subprograms, although
implementations are allowed to support other entities.

2     A pragma Convention is used to specify that an Ada entity should use the
conventions of another language. It is intended primarily for types and ``
callback'' subprograms. For example, ``pragma Convention(Fortran, Matrix);'
' implies that Matrix should be represented according to the conventions of
the supported Fortran implementation, namely column-major order.

3     A pragma Linker_Options is used to specify the system linker parameters
needed when a given compilation unit is included in a partition.


                                   Syntax

4     An interfacing pragma is a representation pragma that is one of the
      pragmas Import, Export, or Convention. Their forms, together with that
      of the related pragma Linker_Options, are as follows:

5       pragma Import(
           [Convention =>] convention_identifier, [Entity =>] local_name
        [, [External_Name =>] string_expression] [, [Link_Name =>]
      string_expression]);

6       pragma Export(
           [Convention =>] convention_identifier, [Entity =>] local_name
        [, [External_Name =>] string_expression] [, [Link_Name =>]
      string_expression]);

7       pragma Convention([Convention =>] convention_identifier,[Entity =>]
      local_name);

8       pragma Linker_Options(string_expression);

9     A pragma Linker_Options is allowed only at the place of a
      declarative_item.

9.1/1 For pragmas Import and Export, the argument for Link_Name shall not be
      given without the pragma_argument_identifier unless the argument for
      External_Name is given.


                            Name Resolution Rules

10    The expected type for a string_expression in an interfacing pragma or in
pragma Linker_Options is String.


                               Legality Rules

11    The convention_identifier of an interfacing pragma shall be the name of
a convention. The convention names are implementation defined, except for
certain language-defined ones, such as Ada and Intrinsic, as explained in
6.3.1, ``Conformance Rules''. Additional convention names generally represent
the calling conventions of foreign languages, language implementations, or
specific run-time models. The convention of a callable entity is its calling
convention.

12    If L is a convention_identifier for a language, then a type T is said to
be compatible with convention L, (alternatively, is said to be an L-compatible
type) if any of the following conditions are met:

13    T is declared in a language interface package corresponding to L and is
      defined to be L-compatible (see B.3, B.3.1, B.3.2, B.4, B.5),

14    Convention L has been specified for T in a pragma Convention, and T is
      eligible for convention L; that is:

    15    T is an array type with either an unconstrained or
          statically-constrained first subtype, and its component type is
          L-compatible,

    16    T is a record type that has no discriminants and that only has
          components with statically-constrained subtypes, and each component
          type is L-compatible,

    17    T is an access-to-object type, and its designated type is
          L-compatible,

    18    T is an access-to-subprogram type, and its designated profile's
          parameter and result types are all L-compatible.

19    T is derived from an L-compatible type,

20    The implementation permits T as an L-compatible type.

21    If pragma Convention applies to a type, then the type shall either be
compatible with or eligible for the convention specified in the pragma.

22    A pragma Import shall be the completion of a declaration.
Notwithstanding any rule to the contrary, a pragma Import may serve as the
completion of any kind of (explicit) declaration if supported by an
implementation for that kind of declaration. If a completion is a pragma
Import, then it shall appear in the same declarative_part,
package_specification, task_definition or protected_definition as the
declaration. For a library unit, it shall appear in the same compilation,
before any subsequent compilation_units other than pragmas. If the local_name
denotes more than one entity, then the pragma Import is the completion of all
of them.

23     An entity specified as the Entity argument to a pragma Import (or
pragma Export) is said to be imported (respectively, exported).

24    The declaration of an imported object shall not include an explicit
initialization expression. Default initializations are not performed.

25    The type of an imported or exported object shall be compatible with the
convention specified in the corresponding pragma.

26    For an imported or exported subprogram, the result and parameter types
shall each be compatible with the convention specified in the corresponding
pragma.

27    The external name and link name string_expressions of a pragma Import or
Export, and the string_expression of a pragma Linker_Options, shall be static.


                              Static Semantics

28    Import, Export, and Convention pragmas are representation pragmas that
specify the convention aspect of representation. In addition, Import and
Export pragmas specify the imported and exported aspects of representation,
respectively.

29    An interfacing pragma is a program unit pragma when applied to a program
unit (see 10.1.5).

30    An interfacing pragma defines the convention of the entity denoted by
the local_name. The convention represents the calling convention or
representation convention of the entity. For an access-to-subprogram type, it
represents the calling convention of designated subprograms. In addition:

31    A pragma Import specifies that the entity is defined externally (that
      is, outside the Ada program).

32    A pragma Export specifies that the entity is used externally.

33    A pragma Import or Export optionally specifies an entity's external
      name, link name, or both.

34    An external name is a string value for the name used by a foreign
language program either for an entity that an Ada program imports, or for
referring to an entity that an Ada program exports.

35    A link name is a string value for the name of an exported or imported
entity, based on the conventions of the foreign language's compiler in
interfacing with the system's linker tool.

36    The meaning of link names is implementation defined. If neither a link
name nor the Address attribute of an imported or exported entity is specified,
then a link name is chosen in an implementation-defined manner, based on the
external name if one is specified.

37    Pragma Linker_Options has the effect of passing its string argument as a
parameter to the system linker (if one exists), if the immediately enclosing
compilation unit is included in the partition being linked. The interpretation
of the string argument, and the way in which the string arguments from
multiple Linker_Options pragmas are combined, is implementation defined.


                              Dynamic Semantics

38    Notwithstanding what this International Standard says elsewhere, the
elaboration of a declaration denoted by the local_name of a pragma Import does
not create the entity. Such an elaboration has no other effect than to allow
the defining name to denote the external entity.


                            Implementation Advice

39    If an implementation supports pragma Export to a given language, then it
should also allow the main subprogram to be written in that language. It
should support some mechanism for invoking the elaboration of the Ada library
units included in the system, and for invoking the finalization of the
environment task. On typical systems, the recommended mechanism is to provide
two subprograms whose link names are "adainit" and "adafinal". Adainit should
contain the elaboration code for library units. Adafinal should contain the
finalization code. These subprograms should have no effect the second and
subsequent time they are called.

40    Automatic elaboration of preelaborated packages should be provided when
pragma Export is supported.

41    For each supported convention L other than Intrinsic, an implementation
should support Import and Export pragmas for objects of L-compatible types and
for subprograms, and pragma Convention for L-eligible types and for
subprograms, presuming the other language has corresponding features. Pragma
Convention need not be supported for scalar types.

      NOTES

42    1  Implementations may place restrictions on interfacing pragmas; for
      example, requiring each exported entity to be declared at the library
      level.

43    2  A pragma Import specifies the conventions for accessing external
      entities. It is possible that the actual entity is written in assembly
      language, but reflects the conventions of a particular language. For
      example, pragma Import(Ada, ...) can be used to interface to an assembly
      language routine that obeys the Ada compiler's calling conventions.

44    3  To obtain ``call-back'' to an Ada subprogram from a foreign language
      environment, pragma Convention should be specified both for the
      access-to-subprogram type and the specific subprogram(s) to which
      'Access is applied.

45    4  It is illegal to specify more than one of Import, Export, or
      Convention for a given entity.

46    5  The local_name in an interfacing pragma can denote more than one
      entity in the case of overloading. Such a pragma applies to all of the
      denoted entities.

47    6  See also 13.8, ``Machine Code Insertions''.

48    7  If both External_Name and Link_Name are specified for an Import or
      Export pragma, then the External_Name is ignored.

49    8  An interfacing pragma might result in an effect that violates Ada
      semantics.


                                  Examples

50    Example of interfacing pragmas:

51    package Fortran_Library is
        function Sqrt (X : Float) return Float;
        function Exp  (X : Float) return Float;
      private
        pragma Import(Fortran, Sqrt);
        pragma Import(Fortran, Exp);
      end Fortran_Library;


B.2 The Package Interfaces


1     Package Interfaces is the parent of several library packages that
declare types and other entities useful for interfacing to foreign languages.
It also contains some implementation-defined types that are useful across more
than one language (in particular for interfacing to assembly language).


                              Static Semantics

2     The library package Interfaces has the following skeletal declaration:

3     
      package Interfaces is
         pragma Pure(Interfaces);

4        type Integer_n is range -2**(n-1) .. 2**(n-1) - 1;  --2's complement

5        type Unsigned_n is mod 2**n;

6        function Shift_Left  (Value : Unsigned_n; Amount : Natural)
            return Unsigned_n;
         function Shift_Right (Value : Unsigned_n; Amount : Natural)
            return Unsigned_n;
         function Shift_Right_Arithmetic (Value : Unsigned_n; Amount : Natural)
            return Unsigned_n;
         function Rotate_Left  (Value : Unsigned_n; Amount : Natural)
            return Unsigned_n;
         function Rotate_Right (Value : Unsigned_n; Amount : Natural)
            return Unsigned_n;
         ...
      end Interfaces;


                         Implementation Requirements

7     An implementation shall provide the following declarations in the
visible part of package Interfaces:

8     Signed and modular integer types of n bits, if supported by the target
      architecture, for each n that is at least the size of a storage element
      and that is a factor of the word size. The names of these types are of
      the form Integer_n for the signed types, and Unsigned_n for the modular
      types;

9     For each such modular type in Interfaces, shifting and rotating
      subprograms as specified in the declaration of Interfaces above. These
      subprograms are Intrinsic. They operate on a bit-by-bit basis, using the
      binary representation of the value of the operands to yield a binary
      representation for the result. The Amount parameter gives the number of
      bits by which to shift or rotate. For shifting, zero bits are shifted
      in, except in the case of Shift_Right_Arithmetic, where one bits are
      shifted in if Value is at least half the modulus.

10    Floating point types corresponding to each floating point format fully
      supported by the hardware.


                         Implementation Permissions

11    An implementation may provide implementation-defined library units that
are children of Interfaces, and may add declarations to the visible part of
Interfaces in addition to the ones defined above.


                            Implementation Advice

12    For each implementation-defined convention identifier, there should be a
child package of package Interfaces with the corresponding name. This package
should contain any declarations that would be useful for interfacing to the
language (implementation) represented by the convention. Any declarations
useful for interfacing to any language on the given hardware architecture
should be provided directly in Interfaces.

13    An implementation supporting an interface to C, COBOL, or Fortran should
provide the corresponding package or packages described in the following
clauses.


B.3 Interfacing with C


1/1   The facilities relevant to interfacing with the C language are the
package Interfaces.C and its children; support for the Import, Export, and
Convention pragmas with convention_identifier C; and support for the
Convention pragma with convention_identifier C_Pass_By_Copy.

2     The package Interfaces.C contains the basic types, constants and
subprograms that allow an Ada program to pass scalars and strings to C
functions.


                              Static Semantics

3     The library package Interfaces.C has the following declaration:

4     package Interfaces.C is
         pragma Pure(C);

5        -- Declarations based on C's <limits.h>

6        CHAR_BIT  : constant := implementation-defined;  -- typically 8
         SCHAR_MIN : constant := implementation-defined;  -- typically -128
         SCHAR_MAX : constant := implementation-defined;  -- typically 127
         UCHAR_MAX : constant := implementation-defined;  -- typically 255

7        -- Signed and Unsigned Integers
         type int   is range implementation-defined;
         type short is range implementation-defined;
         type long  is range implementation-defined;

8        type signed_char is range SCHAR_MIN .. SCHAR_MAX;
         for signed_char'Size use CHAR_BIT;

9        type unsigned       is mod implementation-defined;
         type unsigned_short is mod implementation-defined;
         type unsigned_long  is mod implementation-defined;

10       type unsigned_char is mod (UCHAR_MAX+1);
         for unsigned_char'Size use CHAR_BIT;

11       subtype plain_char is implementation-defined;

12       type ptrdiff_t is range implementation-defined;

13       type size_t is mod implementation-defined;

14       -- Floating Point

15       type C_float     is digits implementation-defined;

16       type double      is digits implementation-defined;

17       type long_double is digits implementation-defined;

18       -- Characters and Strings 

19       type char is <implementation-defined character type>;

20/1     nul : constant char := implementation-defined;

21       function To_C   (Item : in Character) return char;

22       function To_Ada (Item : in char) return Character;

23       type char_array is array (size_t range <>) of aliased char;
         pragma Pack(char_array);
         for char_array'Component_Size use CHAR_BIT;

24       function Is_Nul_Terminated (Item : in char_array) return Boolean;

25       function To_C   (Item       : in String;
                          Append_Nul : in Boolean := True)
            return char_array;

26       function To_Ada (Item     : in char_array;
                          Trim_Nul : in Boolean := True)
            return String;

27       procedure To_C (Item       : in String;
                         Target     : out char_array;
                         Count      : out size_t;
                         Append_Nul : in Boolean := True);

28       procedure To_Ada (Item     : in char_array;
                           Target   : out String;
                           Count    : out Natural;
                           Trim_Nul : in Boolean := True);

29       -- Wide Character and Wide String

30/1     type wchar_t is <implementation-defined character type>;

31/1     wide_nul : constant wchar_t := implementation-defined;

32       function To_C   (Item : in Wide_Character) return wchar_t;
         function To_Ada (Item : in wchar_t       ) return Wide_Character;

33       type wchar_array is array (size_t range <>) of aliased wchar_t;

34       pragma Pack(wchar_array);

35       function Is_Nul_Terminated (Item : in wchar_array) return Boolean;

36       function To_C   (Item       : in Wide_String;
                          Append_Nul : in Boolean := True)
            return wchar_array;

37       function To_Ada (Item     : in wchar_array;
                          Trim_Nul : in Boolean := True)
            return Wide_String;

38       procedure To_C (Item       : in  Wide_String;
                         Target     : out wchar_array;
                         Count      : out size_t;
                         Append_Nul : in  Boolean := True);

39       procedure To_Ada (Item     : in  wchar_array;
                           Target   : out Wide_String;
                           Count    : out Natural;
                           Trim_Nul : in  Boolean := True);

40       Terminator_Error : exception;

41    end Interfaces.C;

42    Each of the types declared in Interfaces.C is C-compatible.

43    The types int, short, long, unsigned, ptrdiff_t, size_t, double, char,
and wchar_t correspond respectively to the C types having the same names. The
types signed_char, unsigned_short, unsigned_long, unsigned_char, C_float, and
long_double correspond respectively to the C types signed char, unsigned
short, unsigned long, unsigned char, float, and long double.

44    The type of the subtype plain_char is either signed_char or
unsigned_char, depending on the C implementation.

45    function To_C   (Item : in Character) return char;
      function To_Ada (Item : in char     ) return Character;

    46    The functions To_C and To_Ada map between the Ada type Character and
          the C type char.

47    function Is_Nul_Terminated (Item : in char_array) return Boolean;

    48    The result of Is_Nul_Terminated is True if Item contains nul, and is
          False otherwise.

49    function To_C   (Item : in String;     Append_Nul : in Boolean := True)
         return char_array;
      
      function To_Ada (Item : in char_array; Trim_Nul   : in Boolean := True)
         return String;

    50    The result of To_C is a char_array value of length Item'Length (if
          Append_Nul is False) or Item'Length+1 (if Append_Nul is True). The
          lower bound is 0. For each component Item(I), the corresponding
          component in the result is To_C applied to Item(I). The value nul is
          appended if Append_Nul is True.

    51    The result of To_Ada is a String whose length is Item'Length (if
          Trim_Nul is False) or the length of the slice of Item preceding the
          first nul (if Trim_Nul is True). The lower bound of the result is 1.
          If Trim_Nul is False, then for each component Item(I) the
          corresponding component in the result is To_Ada applied to Item(I).
          If Trim_Nul is True, then for each component Item(I) before the
          first nul the corresponding component in the result is To_Ada
          applied to Item(I). The function propagates Terminator_Error if
          Trim_Nul is True and Item does not contain nul.

52    procedure To_C (Item       : in String;
                      Target     : out char_array;
                      Count      : out size_t;
                      Append_Nul : in Boolean := True);
      
      procedure To_Ada (Item     : in char_array;
                        Target   : out String;
                        Count    : out Natural;
                        Trim_Nul : in Boolean := True);

    53    For procedure To_C, each element of Item is converted (via the To_C
          function) to a char, which is assigned to the corresponding element
          of Target. If Append_Nul is True, nul is then assigned to the next
          element of Target. In either case, Count is set to the number of
          Target elements assigned. If Target is not long enough,
          Constraint_Error is propagated.

    54    For procedure To_Ada, each element of Item (if Trim_Nul is False) or
          each element of Item preceding the first nul (if Trim_Nul is True)
          is converted (via the To_Ada function) to a Character, which is
          assigned to the corresponding element of Target. Count is set to the
          number of Target elements assigned. If Target is not long enough,
          Constraint_Error is propagated. If Trim_Nul is True and Item does
          not contain nul, then Terminator_Error is propagated.

55    function Is_Nul_Terminated (Item : in wchar_array) return Boolean;

    56    The result of Is_Nul_Terminated is True if Item contains wide_nul,
          and is False otherwise.

57    function To_C   (Item : in Wide_Character) return wchar_t;
      function To_Ada (Item : in wchar_t       ) return Wide_Character;

    58    To_C and To_Ada provide the mappings between the Ada and C wide
          character types.

59    function To_C   (Item       : in Wide_String;
                       Append_Nul : in Boolean := True)
         return wchar_array;
      
      function To_Ada (Item     : in wchar_array;
                       Trim_Nul : in Boolean := True)
         return Wide_String;
      
      procedure To_C (Item       : in Wide_String;
                      Target     : out wchar_array;
                      Count      : out size_t;
                      Append_Nul : in Boolean := True);
      
      procedure To_Ada (Item     : in wchar_array;
                        Target   : out Wide_String;
                        Count    : out Natural;
                        Trim_Nul : in Boolean := True);

    60    The To_C and To_Ada subprograms that convert between Wide_String and
          wchar_array have analogous effects to the To_C and To_Ada
          subprograms that convert between String and char_array, except that
          wide_nul is used instead of nul.

60.1/1 A Convention pragma with convention_identifier C_Pass_By_Copy shall
only be applied to a type.

60.2/1 The eligibility rules in B.1 do not apply to convention C_Pass_By_Copy.
Instead, a type T is eligible for convention C_Pass_By_Copy if T is a record
type that has no discriminants and that only has components with statically
constrained subtypes, and each component is C-compatible.

60.3/1 If a type is C_Pass_By_Copy-compatible then it is also C-compatible.


                         Implementation Requirements

61/1  An implementation shall support pragma Convention with a C
convention_identifier for a C-eligible type (see B.1). An implementation shall
support pragma Convention with a C_Pass_By_Copy convention_identifier for a
C_Pass_By_Copy-eligible type.


                         Implementation Permissions

62    An implementation may provide additional declarations in the C interface
packages.


                            Implementation Advice

62.1/1 The constants nul and wide_nul should have a representation of zero.

63    An implementation should support the following interface correspondences
between Ada and C.

64    An Ada procedure corresponds to a void-returning C function.

65    An Ada function corresponds to a non-void C function.

66    An Ada in scalar parameter is passed as a scalar argument to a C
      function.

67    An Ada in parameter of an access-to-object type with designated type T
      is passed as a t* argument to a C function, where t is the C type
      corresponding to the Ada type T.

68    An Ada access T parameter, or an Ada out or in out parameter of an
      elementary type T, is passed as a t* argument to a C function, where t
      is the C type corresponding to the Ada type T. In the case of an
      elementary out or in out parameter, a pointer to a temporary copy is
      used to preserve by-copy semantics.

68.1/1 An Ada parameter of a C_Pass_By_Copy-compatible (record) type T, of
      mode in, is passed as a t argument to a C function, where t is the C
      struct corresponding to the Ada type T.

69/1  An Ada parameter of a record type T, of any mode, other than an in
      parameter of a C_Pass_By_Copy-compatible type, is passed as a t*
      argument to a C function, where t is the C struct corresponding to the
      Ada type T.

70    An Ada parameter of an array type with component type T, of any mode, is
      passed as a t* argument to a C function, where t is the C type
      corresponding to the Ada type T.

71    An Ada parameter of an access-to-subprogram type is passed as a pointer
      to a C function whose prototype corresponds to the designated
      subprogram's specification.

      NOTES

72    9  Values of type char_array are not implicitly terminated with nul. If
      a char_array is to be passed as a parameter to an imported C function
      requiring nul termination, it is the programmer's responsibility to
      obtain this effect.

73    10  To obtain the effect of C's sizeof(item_type), where Item_Type is
      the corresponding Ada type, evaluate the expression:
      size_t(Item_Type'Size/CHAR_BIT).

74    11  There is no explicit support for C's union types. Unchecked
      conversions can be used to obtain the effect of C unions.

75    12  A C function that takes a variable number of arguments can
      correspond to several Ada subprograms, taking various specific numbers
      and types of parameters.


                                  Examples

76    Example of using the Interfaces.C package:

77    --Calling the C Library Function strcpy
      with Interfaces.C;
      procedure Test is
         package C renames Interfaces.C;
         use type C.char_array;
         -- Call <string.h>strcpy:
         -- C definition of strcpy:  char *strcpy(char *s1, const char *s2);
         --    This function copies the string pointed to by s2 (including the terminating null character)
         --     into the array pointed to by s1. If copying takes place between objects that overlap, 
         --     the behavior is undefined. The strcpy function returns the value of s1.

78       -- Note: since the C function's return value is of no interest, the Ada interface is a procedure
         procedure Strcpy (Target : out C.char_array;
                           Source : in  C.char_array);

79       pragma Import(C, Strcpy, "strcpy");

80       Chars1 :  C.char_array(1..20);
         Chars2 :  C.char_array(1..20);

81    begin
         Chars2(1..6) := "qwert" & C.nul;

82       Strcpy(Chars1, Chars2);

83    -- Now Chars1(1..6) = "qwert" & C.Nul

84    end Test;


B.3.1 The Package Interfaces.C.Strings


1     The package Interfaces.C.Strings declares types and subprograms allowing
an Ada program to allocate, reference, update, and free C-style strings. In
particular, the private type chars_ptr corresponds to a common use of ``char
*'' in C programs, and an object of this type can be passed to a subprogram to
which pragma Import(C,...) has been applied, and for which ``char *'' is the
type of the argument of the C function.


                              Static Semantics

2     The library package Interfaces.C.Strings has the following declaration:

3     package Interfaces.C.Strings is
         pragma Preelaborate(Strings);

4        type char_array_access is access all char_array;

5        type chars_ptr is private;

6        type chars_ptr_array is array (size_t range <>) of chars_ptr;

7        Null_Ptr : constant chars_ptr;

8        function To_Chars_Ptr (Item      : in char_array_access;
                                Nul_Check : in Boolean := False)
            return chars_ptr;

9        function New_Char_Array (Chars   : in char_array) return chars_ptr;

10       function New_String (Str : in String) return chars_ptr;

11       procedure Free (Item : in out chars_ptr);

12       Dereference_Error : exception;

13       function Value (Item : in chars_ptr) return char_array;

14       function Value (Item : in chars_ptr; Length : in size_t)
            return char_array;

15       function Value (Item : in chars_ptr) return String;

16       function Value (Item : in chars_ptr; Length : in size_t)
            return String;

17       function Strlen (Item : in chars_ptr) return size_t;

18       procedure Update (Item   : in chars_ptr;
                           Offset : in size_t;
                           Chars  : in char_array;
                           Check  : in Boolean := True);

19       procedure Update (Item   : in chars_ptr;
                           Offset : in size_t;
                           Str    : in String;
                           Check  : in Boolean := True);

20       Update_Error : exception;

21    private
         ... -- not specified by the language
      end Interfaces.C.Strings;

22    The type chars_ptr is C-compatible and corresponds to the use of C's `
`char *'' for a pointer to the first char in a char array terminated by nul.
When an object of type chars_ptr is declared, its value is by default set to
Null_Ptr, unless the object is imported (see B.1).

23    function To_Chars_Ptr (Item      : in char_array_access;
                             Nul_Check : in Boolean := False)
         return chars_ptr;

    24/1  If Item is null, then To_Chars_Ptr returns Null_Ptr. If Item is not
          null,Nul_Check is True, and Item.all does not contain nul, then the
          function propagates Terminator_Error; otherwise To_Chars_Ptr
          performs a pointer conversion with no allocation of memory.

25    function New_Char_Array (Chars   : in char_array) return chars_ptr;

    26    This function returns a pointer to an allocated object initialized
          to Chars(Chars'First .. Index) & nul, where

        27    Index = Chars'Last if Chars does not contain nul, or

        28    Index is the smallest size_t value I such that Chars(I+1) = nul.

    28.1  Storage_Error is propagated if the allocation fails.

29    function New_String (Str : in String) return chars_ptr;

    30    This function is equivalent to New_Char_Array(To_C(Str)).

31    procedure Free (Item : in out chars_ptr);

    32    If Item is Null_Ptr, then Free has no effect. Otherwise, Free
          releases the storage occupied by Value(Item), and resets Item to
          Null_Ptr.

33    function Value (Item : in chars_ptr) return char_array;

    34    If Item = Null_Ptr then Value propagates Dereference_Error.
          Otherwise Value returns the prefix of the array of chars pointed to
          by Item, up to and including the first nul. The lower bound of the
          result is 0. If Item does not point to a nul-terminated string, then
          execution of Value is erroneous.

35    function Value (Item : in chars_ptr; Length : in size_t)
         return char_array;

    36/1  If Item = Null_Ptr then Value propagates Dereference_Error.
          Otherwise Value returns the shorter of two arrays, either the first
          Length chars pointed to by Item, or Value(Item). The lower bound of
          the result is 0. If Length is 0, then Value propagates
          Constraint_Error.

37    function Value (Item : in chars_ptr) return String;

    38    Equivalent to To_Ada(Value(Item), Trim_Nul=>True).

39    function Value (Item : in chars_ptr; Length : in size_t)
         return String;

    40/1  Equivalent to To_Ada(Value(Item, Length) & nul, Trim_Nul=>True).

41    function Strlen (Item : in chars_ptr) return size_t;

    42    Returns Val'Length-1 where Val = Value(Item); propagates
          Dereference_Error if Item = Null_Ptr.

43    procedure Update (Item   : in chars_ptr;
                        Offset : in size_t;
                        Chars  : in char_array;
                        Check  : Boolean := True);

    44/1  If Item = Null_Ptr, then Update propagates Dereference_Error.
          Otherwise, this procedure updates the value pointed to by Item,
          starting at position Offset, using Chars as the data to be copied
          into the array. Overwriting the nul terminator, and skipping with
          the Offset past the nul terminator, are both prevented if Check is
          True, as follows:

        45    Let N = Strlen(Item). If Check is True, then:

            46    If Offset+Chars'Length>N, propagate Update_Error.

            47    Otherwise, overwrite the data in the array pointed to by
                  Item, starting at the char at position Offset, with the data
                  in Chars.

        48    If Check is False, then processing is as above, but with no
              check that Offset+Chars'Length>N.

49    procedure Update (Item   : in chars_ptr;
                        Offset : in size_t;
                        Str    : in String;
                        Check  : in Boolean := True);

    50    Equivalent to Update(Item, Offset, To_C(Str), Check).


                             Erroneous Execution

51    Execution of any of the following is erroneous if the Item parameter is
not null_ptr and Item does not point to a nul-terminated array of chars.

52    a Value function not taking a Length parameter,

53    the Free procedure,

54    the Strlen function.

55    Execution of Free(X) is also erroneous if the chars_ptr X was not
returned by New_Char_Array or New_String.

56    Reading or updating a freed char_array is erroneous.

57    Execution of Update is erroneous if Check is False and a call with Check
equal to True would have propagated Update_Error.

      NOTES

58    13  New_Char_Array and New_String might be implemented either through
      the allocation function from the C environment (``malloc'') or through
      Ada dynamic memory allocation (``new''). The key points are

    59    the returned value (a chars_ptr) is represented as a C ``char *'' so
          that it may be passed to C functions;

    60    the allocated object should be freed by the programmer via a call of
          Free, not by a called C function.


B.3.2 The Generic Package Interfaces.C.Pointers


1     The generic package Interfaces.C.Pointers allows the Ada programmer to
perform C-style operations on pointers. It includes an access type Pointer,
Value functions that dereference a Pointer and deliver the designated array,
several pointer arithmetic operations, and ``copy'' procedures that copy the
contents of a source pointer into the array designated by a destination
pointer. As in C, it treats an object Ptr of type Pointer as a pointer to the
first element of an array, so that for example, adding 1 to Ptr yields a
pointer to the second element of the array.

2     The generic allows two styles of usage: one in which the array is
terminated by a special terminator element; and another in which the
programmer needs to keep track of the length.


                              Static Semantics

3     The generic library package Interfaces.C.Pointers has the following
declaration:

4     generic
         type Index is (<>);
         type Element is private;
         type Element_Array is array (Index range <>) of aliased Element;
         Default_Terminator : Element;
      package Interfaces.C.Pointers is
         pragma Preelaborate(Pointers);

5        type Pointer is access all Element;

6        function Value(Ref        : in Pointer;
                        Terminator : in Element := Default_Terminator)
            return Element_Array;

7        function Value(Ref    : in Pointer;
                        Length : in ptrdiff_t)
            return Element_Array;

8        Pointer_Error : exception;

9        -- C-style Pointer arithmetic

10       function "+" (Left : in Pointer;   Right : in ptrdiff_t) return Pointer;
         function "+" (Left : in ptrdiff_t; Right : in Pointer)   return Pointer;
         function "-" (Left : in Pointer;   Right : in ptrdiff_t) return Pointer;
         function "-" (Left : in Pointer;   Right : in Pointer) return ptrdiff_t;

11       procedure Increment (Ref : in out Pointer);
         procedure Decrement (Ref : in out Pointer);

12       pragma Convention (Intrinsic, "+");
         pragma Convention (Intrinsic, "-");
         pragma Convention (Intrinsic, Increment);
         pragma Convention (Intrinsic, Decrement);

13       function Virtual_Length (Ref        : in Pointer;
                                  Terminator : in Element := Default_Terminator)
            return ptrdiff_t;

14       procedure Copy_Terminated_Array
            (Source     : in Pointer;
             Target     : in Pointer;
             Limit      : in ptrdiff_t := ptrdiff_t'Last;
             Terminator : in Element :=  Default_Terminator);

15       procedure Copy_Array (Source  : in Pointer;
                               Target  : in Pointer;
                               Length  : in ptrdiff_t);

16    end Interfaces.C.Pointers;

17    The type Pointer is C-compatible and corresponds to one use of C's ``
Element *''. An object of type Pointer is interpreted as a pointer to the
initial Element in an Element_Array. Two styles are supported:

18    Explicit termination of an array value with Default_Terminator (a
      special terminator value);

19    Programmer-managed length, with Default_Terminator treated simply as a
      data element.

20    function Value(Ref        : in Pointer;
                     Terminator : in Element := Default_Terminator)
         return Element_Array;

    21    This function returns an Element_Array whose value is the array
          pointed to by Ref, up to and including the first Terminator; the
          lower bound of the array is Index'First.
          Interfaces.C.Strings.Dereference_Error is propagated if Ref is null.

22    function Value(Ref    : in Pointer;
                     Length : in ptrdiff_t)
         return Element_Array;

    23    This function returns an Element_Array comprising the first Length
          elements pointed to by Ref. The exception
          Interfaces.C.Strings.Dereference_Error is propagated if Ref is null.

24    The "+" and "-" functions perform arithmetic on Pointer values, based on
the Size of the array elements. In each of these functions, Pointer_Error is
propagated if a Pointer parameter is null.

25    procedure Increment (Ref : in out Pointer);

    26    Equivalent to Ref := Ref+1.

27    procedure Decrement (Ref : in out Pointer);

    28    Equivalent to Ref := Ref-1.

29    function Virtual_Length (Ref        : in Pointer;
                               Terminator : in Element := Default_Terminator)
         return ptrdiff_t;

    30    Returns the number of Elements, up to the one just before the first
          Terminator, in Value(Ref, Terminator).

31    procedure Copy_Terminated_Array
         (Source     : in Pointer;
          Target     : in Pointer;
          Limit      : in ptrdiff_t := ptrdiff_t'Last;
          Terminator : in Element := Default_Terminator);

    32    This procedure copies Value(Source, Terminator) into the array
          pointed to by Target; it stops either after Terminator has been
          copied, or the number of elements copied is Limit, whichever occurs
          first. Dereference_Error is propagated if either Source or Target is
          null.

33    procedure Copy_Array (Source  : in Pointer;
                            Target  : in Pointer;
                            Length  : in ptrdiff_t);

    34    This procedure copies the first Length elements from the array
          pointed to by Source, into the array pointed to by Target.
          Dereference_Error is propagated if either Source or Target is null.


                             Erroneous Execution

35    It is erroneous to dereference a Pointer that does not designate an
aliased Element.

36    Execution of Value(Ref, Terminator) is erroneous if Ref does not
designate an aliased Element in an Element_Array terminated by Terminator.

37    Execution of Value(Ref, Length) is erroneous if Ref does not designate
an aliased Element in an Element_Array containing at least Length Elements
between the designated Element and the end of the array, inclusive.

38    Execution of Virtual_Length(Ref, Terminator) is erroneous if Ref does
not designate an aliased Element in an Element_Array terminated by Terminator.

39    Execution of Copy_Terminated_Array(Source, Target, Limit, Terminator) is
erroneous in either of the following situations:

40    Execution of both Value(Source,Terminator) and Value(Source,Limit) are
      erroneous, or

41    Copying writes past the end of the array containing the Element
      designated by Target.

42    Execution of Copy_Array(Source, Target, Length) is erroneous if either
Value(Source, Length) is erroneous, or copying writes past the end of the
array containing the Element designated by Target.

      NOTES

43    14  To compose a Pointer from an Element_Array, use 'Access on the first
      element. For example (assuming appropriate instantiations):

44    Some_Array   : Element_Array(0..5) ;
      Some_Pointer : Pointer := Some_Array(0)'Access;


                                  Examples

45    Example of Interfaces.C.Pointers:

46    with Interfaces.C.Pointers;
      with Interfaces.C.Strings;
      procedure Test_Pointers is
         package C renames Interfaces.C;
         package Char_Ptrs is
            new C.Pointers (Index              => C.size_t,
                            Element            => C.char,
                            Element_Array      => C.char_array,
                            Default_Terminator => C.nul);

47       use type Char_Ptrs.Pointer;
         subtype Char_Star is Char_Ptrs.Pointer;

48       procedure Strcpy (Target_Ptr, Source_Ptr : Char_Star) is
            Target_Temp_Ptr : Char_Star := Target_Ptr;
            Source_Temp_Ptr : Char_Star := Source_Ptr;
            Element : C.char;
         begin
            if Target_Temp_Ptr = null or Source_Temp_Ptr = null then
               raise C.Strings.Dereference_Error;
            end if;

49/1        loop
               Element             := Source_Temp_Ptr.all;
               Target_Temp_Ptr.all := Element;
               exit when C."="(Element, C.nul);
               Char_Ptrs.Increment(Target_Temp_Ptr);
               Char_Ptrs.Increment(Source_Temp_Ptr);
            end loop;
         end Strcpy;
      begin
         ...
      end Test_Pointers;


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:

3     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

4     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

5     A generic package for converting between an Ada decimal type value and
      either an internal or external COBOL representation


                              Static Semantics

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

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

8     -- Types and operations for internal data representations

9        type Floating      is digits implementation-defined;
         type Long_Floating is digits implementation-defined;

10       type Binary      is range implementation-defined;
         type Long_Binary is range implementation-defined;

11       Max_Digits_Binary      : constant := implementation-defined;
         Max_Digits_Long_Binary : constant := implementation-defined;

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

13       type COBOL_Character is implementation-defined character type;

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

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

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

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

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

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

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

21    -- Formats for COBOL data representations

22       type Display_Format is private;

23       Unsigned             : constant Display_Format;
         Leading_Separate     : constant Display_Format;
         Trailing_Separate    : constant Display_Format;
         Leading_Nonseparate  : constant Display_Format;
         Trailing_Nonseparate : constant Display_Format;

24       type Binary_Format is private;

25       High_Order_First  : constant Binary_Format;
         Low_Order_First   : constant Binary_Format;
         Native_Binary     : constant Binary_Format;

26       type Packed_Format is private;

27       Packed_Unsigned   : constant Packed_Format;
         Packed_Signed     : constant Packed_Format;

28    -- Types for external representation of COBOL binary data

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

30       Conversion_Error : exception;

31       generic
            type Num is delta <> digits <>;
         package Decimal_Conversions is

32          -- Display Formats: data values are represented as Numeric

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

34          function Length (Format : in Display_Format) return Natural;

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

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

37          -- Packed Formats: data values are represented as Packed_Decimal

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

39          function Length (Format : in Packed_Format) return Natural;

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

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

42          -- Binary Formats: external data values are represented as Byte_Array

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

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

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

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

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

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

49       end Decimal_Conversions;

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

51    Each of the types in Interfaces.COBOL is COBOL-compatible.

52    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.

53    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.

54    The type Packed_Decimal corresponds to COBOL's packed-decimal usage.

55    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.

56    Type Alphanumeric corresponds to COBOL's alphanumeric data category.

57    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.

58    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.

59    Type Numeric corresponds to COBOL's numeric data category with display
usage.

60    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.

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

    62    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:

        63/1  Format=Unsigned: if Item comprises one or more decimal digit
              characters then Valid returns True, else it returns False.

        64/1  Format=Leading_Separate: if Item comprises 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.

        65/1  Format=Trailing_Separate: if Item comprises one or more decimal
              digit characters and finally a plus or minus sign character,
              then Valid returns True, else it returns False.

66    function Length (Format : in Display_Format) return Natural;

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

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

    69    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.

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

    71/1  This function returns the Numeric value for Item, represented in
          accordance with Format. The length of the returned value is
          Length(Format), and the lower bound is 1. Conversion_Error is
          propagated if Num is negative and Format is Unsigned.

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

    73    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.

74    function Length (Format : in Packed_Format) return Natural;

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

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

    77    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.

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

    79/1  This function returns the Packed_Decimal value for Item, represented
          in accordance with Format. The length of the returned value is
          Length(Format), and the lower bound is 1. Conversion_Error is
          propagated if Num is negative and Format is Packed_Unsigned.

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

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

82    function Length (Format : in Binary_Format) return Natural;

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

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

    85    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.

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

    87/1  This function returns the Byte_Array value for Item, represented in
          accordance with Format. The length of the returned value is
          Length(Format), and the lower bound is 1.

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

    89    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.

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

    91    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.


                         Implementation Requirements

92    An implementation shall support pragma Convention with a COBOL
convention_identifier for a COBOL-eligible type (see B.1).


                         Implementation Permissions

93    An implementation may provide additional constants of the private types
Display_Format, Binary_Format, or Packed_Format.

94    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

95    An Ada implementation should support the following interface
correspondences between Ada and COBOL.

96    An Ada access T parameter is passed as a ``BY REFERENCE'' data item of
      the COBOL type corresponding to T.

97    An Ada in scalar parameter is passed as a ``BY CONTENT'' data item of
      the corresponding COBOL type.

98    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

99    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.

100   16  If an Ada subprogram is exported to COBOL, then a call from COBOL
      call may specify either ``BY CONTENT'' or ``BY REFERENCE''.


                                  Examples

101   Examples of Interfaces.COBOL:

102   with Interfaces.COBOL;
      procedure Test_Call is

103      -- 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

104      package COBOL renames Interfaces.COBOL;

105      type Salary_Type is delta 0.01 digits 7;

106      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);

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

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

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

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

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

112      -- 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

113      package COBOL renames Interfaces.COBOL;

114      type Salary_Type      is delta 0.01  digits 7;
         type Adjustments_Type is delta 0.001 digits 6;

115      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);

116      package COBOL_Employee_IO is
            new COBOL_Sequential_IO(COBOL_Employee_Record_Type);
         use COBOL_Employee_IO;

117      COBOL_File : File_Type;

118      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;

119      COBOL_Record : COBOL_Employee_Record_Type;
         Ada_Record   : Ada_Employee_Record_Type;

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

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

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

123      loop
           Read (COBOL_File, COBOL_Record);

124        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;


B.5 Interfacing with Fortran


1     The facilities relevant to interfacing with the Fortran language are the
package Interfaces.Fortran and support for the Import, Export and Convention
pragmas with convention_identifier Fortran.

2     The package Interfaces.Fortran defines Ada types whose representations
are identical to the default representations of the Fortran intrinsic types
Integer, Real, Double Precision, Complex, Logical, and Character in a
supported Fortran implementation. These Ada types can therefore be used to
pass objects between Ada and Fortran programs.


                              Static Semantics

3     The library package Interfaces.Fortran has the following declaration:

4     with Ada.Numerics.Generic_Complex_Types;  -- see G.1.1
      pragma Elaborate_All(Ada.Numerics.Generic_Complex_Types);
      package Interfaces.Fortran is
         pragma Pure(Fortran);

5        type Fortran_Integer is range implementation-defined;

6        type Real             is digits implementation-defined;
         type Double_Precision is digits implementation-defined;

7        type Logical is new Boolean;

8        package Single_Precision_Complex_Types is
            new Ada.Numerics.Generic_Complex_Types (Real);

9        type Complex is new Single_Precision_Complex_Types.Complex;

10       subtype Imaginary is Single_Precision_Complex_Types.Imaginary;
         i : Imaginary renames Single_Precision_Complex_Types.i;
         j : Imaginary renames Single_Precision_Complex_Types.j;

11       type Character_Set is implementation-defined character type;

12       type Fortran_Character is array (Positive range <>) of Character_Set;
         pragma Pack (Fortran_Character);

13       function To_Fortran (Item : in Character) return Character_Set;
         function To_Ada (Item : in Character_Set) return Character;

14       function To_Fortran (Item : in String) return Fortran_Character;
         function To_Ada     (Item : in Fortran_Character) return String;

15       procedure To_Fortran (Item       : in String;
                               Target     : out Fortran_Character;
                               Last       : out Natural);

16       procedure To_Ada (Item     : in Fortran_Character;
                           Target   : out String;
                           Last     : out Natural);

17    end Interfaces.Fortran;

18    The types Fortran_Integer, Real, Double_Precision, Logical, Complex, and
Fortran_Character are Fortran-compatible.

19    The To_Fortran and To_Ada functions map between the Ada type Character
and the Fortran type Character_Set, and also between the Ada type String and
the Fortran type Fortran_Character. The To_Fortran and To_Ada procedures have
analogous effects to the string conversion subprograms found in
Interfaces.COBOL.


                         Implementation Requirements

20    An implementation shall support pragma Convention with a Fortran
convention_identifier for a Fortran-eligible type (see B.1).


                         Implementation Permissions

21    An implementation may add additional declarations to the Fortran
interface packages. For example, the Fortran interface package for an
implementation of Fortran 77 (ANSI X3.9-1978) that defines types like
Integer*n, Real*n, Logical*n, and Complex*n may contain the declarations of
types named Integer_Star_n, Real_Star_n, Logical_Star_n, and Complex_Star_n.
(This convention should not apply to Character*n, for which the Ada analog is
the constrained array subtype Fortran_Character (1..n).) Similarly, the
Fortran interface package for an implementation of Fortran 90 that provides
multiple kinds of intrinsic types, e.g. Integer (Kind=n), Real (Kind=n),
Logical (Kind=n), Complex (Kind=n), and Character (Kind=n), may contain the
declarations of types with the recommended names Integer_Kind_n, Real_Kind_n,
Logical_Kind_n, Complex_Kind_n, and Character_Kind_n.


                            Implementation Advice

22    An Ada implementation should support the following interface
correspondences between Ada and Fortran:

23    An Ada procedure corresponds to a Fortran subroutine.

24    An Ada function corresponds to a Fortran function.

25    An Ada parameter of an elementary, array, or record type T is passed as
      a T(F) argument to a Fortran procedure, where T(F) is the Fortran type
      corresponding to the Ada type T, and where the INTENT attribute of the
      corresponding dummy argument matches the Ada formal parameter mode; the
      Fortran implementation's parameter passing conventions are used. For
      elementary types, a local copy is used if necessary to ensure by-copy
      semantics.

26    An Ada parameter of an access-to-subprogram type is passed as a
      reference to a Fortran procedure whose interface corresponds to the
      designated subprogram's specification.

      NOTES

27    17  An object of a Fortran-compatible record type, declared in a library
      package or subprogram, can correspond to a Fortran common block; the
      type also corresponds to a Fortran ``derived type''.


                                  Examples

28    Example of Interfaces.Fortran:

29    with Interfaces.Fortran;
      use Interfaces.Fortran;
      procedure Ada_Application is

30       type Fortran_Matrix is array (Integer range <>,
                                       Integer range <>) of Double_Precision;
         pragma Convention (Fortran, Fortran_Matrix);    -- stored in Fortran's
                                                         -- column-major order
         procedure Invert (Rank : in Fortran_Integer; X : in out Fortran_Matrix);
         pragma Import (Fortran, Invert);                -- a Fortran subroutine

31       Rank      : constant Fortran_Integer := 100;
         My_Matrix : Fortran_Matrix (1 .. Rank, 1 .. Rank);

32    begin

33       ...
         My_Matrix := ...;
         ...
         Invert (Rank, My_Matrix);
         ...

34    end Ada_Application;

