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. Implementation Requirements 2/3 Support for interfacing to any foreign language is optional. However, an implementation shall not provide any optional aspect, attribute, library unit, or pragma having the same name as an aspect, attribute, library unit, or pragma (respectively) specified in the subclauses of this Annex unless the provided construct is either as specified in those subclauses or is more limited in capability than that required by those subclauses. A program that attempts to use an unsupported capability of this Annex shall either be identified by the implementation before run time or shall raise an exception at run time. B.1 Interfacing Aspects 0.1/3 An interfacing aspect is a representation aspect that is one of the aspects Import, Export, Link_Name, External_Name, or Convention. 1/3 Specifying the Import aspect to have the value True 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, specifying the Export aspect to have the value True 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 Import and Export aspects are intended primarily for objects and subprograms, although implementations are allowed to support other entities. The Link_Name and External_Name aspects are used to specify the link name and external name, respectively, to be used to identify imported or exported entities in the external environment. 2/3 The Convention aspect is used to indicate that an Ada entity should use the conventions of another language. It is intended primarily for types and "callback" subprograms. For example, "with Convention => Fortran" on the declaration of an array type 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/3 The form of a pragma Linker_Options is as follows: Paragraphs 5 through 7 were moved to Annex J, "Obsolescent Features ". 8 pragma Linker_Options(string_expression); 9 A pragma Linker_Options is allowed only at the place of a declarative_item. 9.1/3 This paragraph was deleted. Name Resolution Rules 9.2/3 The Import and Export aspects are of type Boolean. 10/3 The Link_Name and External_Name aspects are of type String. 10.1/3 The expected type for the string_expression in pragma Linker_Options is String. Legality Rules 11/3 The aspect Convention shall be specified by a convention_identifier which 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/3 * Convention L has been specified for T, and T is eligible for convention L; that is: 14.1/4 * T is an enumeration type such that all internal codes (whether assigned by default or explicitly) are within an implementation-defined range that includes at least the range of values 0 .. 2**15-1; 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/3 * T is an access-to-object type, its designated type is L-compatible, and its designated subtype is not an unconstrained array subtype, 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/3 If the Convention aspect is specified for a type, then the type shall either be compatible with or eligible for the specified convention. 22/3 Notwithstanding any rule to the contrary, a declaration with a True Import aspect shall not have a completion. 23/3 An entity with a True Import aspect (or Export aspect) is said to be imported (respectively, exported). An entity shall not be both imported and exported. 24 The declaration of an imported object shall not include an explicit initialization expression. Default initializations are not performed. 25/3 The type of an imported or exported object shall be compatible with the specified Convention aspect, if any. 26/3 For an imported or exported subprogram, the result and parameter types shall each be compatible with the specified Convention aspect, if any. 27/3 The aspect_definition (if any) used to directly specify an Import, Export, External_Name, or Link_Name aspect shall be a static expression. The string_expression of a pragma Linker_Options shall be static. An External_Name or Link_Name aspect shall be specified only for an entity that is either imported or exported. Static Semantics Paragraphs 28 and 29 were deleted. 30/3 The Convention aspect 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/3 * A True Import aspect indicates that the entity is defined externally (that is, outside the Ada program). This aspect is never inherited; if not directly specified, the Import aspect is False. 32/3 * A True Export aspect indicates that the entity is used externally. This aspect is never inherited; if not directly specified, the Export aspect is False. 33/3 * For an entity with a True Import or Export aspect, an external name, link name, or both may also be specified. 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/3 Notwithstanding what this International Standard says elsewhere, the elaboration of a declaration with a True Import aspect does not create the entity. Such an elaboration has no other effect than to allow the defining name to denote the external entity. Erroneous Execution 38.1/3 It is the programmer's responsibility to ensure that the use of interfacing aspects does not violate Ada semantics; otherwise, program execution is erroneous. Implementation Advice 39/3 If an implementation supports Export for 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/3 Automatic elaboration of preelaborated packages should be provided when specifying the Export aspect as True is supported. 41/4 For each supported convention L other than Intrinsic, an implementation should support specifying the Import and Export aspects for objects of L-compatible types and for subprograms, and the Convention aspect for L-eligible types and for subprograms, presuming the other language has corresponding features. Specifying the Convention aspect need not be supported for scalar types, other than enumeration types whose internal codes fall within the range 0 .. 2**15-1. NOTES 42/3 1 Implementations may place restrictions on interfacing aspects; for example, requiring each exported entity to be declared at the library level. 43/3 2 The Convention aspect in combination with the Import aspect indicates 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, with Convention => Ada can be used to interface to an assembly language routine that obeys the Ada compiler's calling conventions. 44/3 3 To obtain "call-back" to an Ada subprogram from a foreign language environment, the Convention aspect should be specified both for the access-to-subprogram type and the specific subprogram(s) to which 'Access is applied. Paragraphs 45 and 46 were deleted. 47 4 See also 13.8, "Machine Code Insertions". 48/3 5 If both External_Name and Link_Name are specified for a given entity, then the External_Name is ignored. 49/2 This paragraph was deleted. Examples 50/4 Example of interfacing aspects: 51/3 package Fortran_Library is function Sqrt (X : Float) return Float with Import => True, Convention => Fortran; type Matrix is array (Natural range <>, Natural range <>) of Float with Convention => Fortran; function Invert (M : Matrix) return Matrix with Import => True, Convention => Fortran; 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. 11.1/3 A child package of package Interfaces with the name of a convention may be provided independently of whether the convention is supported by the Convention aspect and vice versa. Such a child 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. Implementation Advice 12/2 This paragraph was deleted. 13/3 An implementation supporting an interface to C, COBOL, or Fortran should provide the corresponding package or packages described in the following subclauses. B.3 Interfacing with C and C++ 1/4 The facilities relevant to interfacing with the C language and the corresponding subset of the C++ language are the package Interfaces.C and its children, and support for specifying the Convention aspect with convention_identifiers C, C_Pass_By_Copy, and any of the C_Variadic_n conventions described below. 2/3 The package Interfaces.C contains the basic types, constants, and subprograms that allow an Ada program to pass scalars and strings to C and C++ functions. When this subclause mentions a C entity, the reference also applies to the corresponding entity in C++. 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 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 ; 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/3 type char_array is array (size_t range <>) of aliased char with Pack; 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 ; 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/3 type wchar_array is array (size_t range <>) of aliased wchar_t with Pack; 34/3 This paragraph was deleted. 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); 39.1/2 -- ISO/IEC 10646:2003 compatible types defined by ISO/IEC TR 19769:2004. 39.2/2 type char16_t is ; 39.3/2 char16_nul : constant char16_t := implementation-defined; 39.4/2 function To_C (Item : in Wide_Character) return char16_t; function To_Ada (Item : in char16_t) return Wide_Character; 39.5/3 type char16_array is array (size_t range <>) of aliased char16_t with Pack; 39.6/3 This paragraph was deleted. 39.7/2 function Is_Nul_Terminated (Item : in char16_array) return Boolean; function To_C (Item : in Wide_String; Append_Nul : in Boolean := True) return char16_array; 39.8/2 function To_Ada (Item : in char16_array; Trim_Nul : in Boolean := True) return Wide_String; 39.9/2 procedure To_C (Item : in Wide_String; Target : out char16_array; Count : out size_t; Append_Nul : in Boolean := True); 39.10/2 procedure To_Ada (Item : in char16_array; Target : out Wide_String; Count : out Natural; Trim_Nul : in Boolean := True); 39.11/2 type char32_t is ; 39.12/2 char32_nul : constant char32_t := implementation-defined; 39.13/2 function To_C (Item : in Wide_Wide_Character) return char32_t; function To_Ada (Item : in char32_t) return Wide_Wide_Character; 39.14/3 type char32_array is array (size_t range <>) of aliased char32_t with Pack; 39.15/3 This paragraph was deleted. 39.16/2 function Is_Nul_Terminated (Item : in char32_array) return Boolean; function To_C (Item : in Wide_Wide_String; Append_Nul : in Boolean := True) return char32_array; 39.17/2 function To_Ada (Item : in char32_array; Trim_Nul : in Boolean := True) return Wide_Wide_String; 39.18/2 procedure To_C (Item : in Wide_Wide_String; Target : out char32_array; Count : out size_t; Append_Nul : in Boolean := True); 39.19/2 procedure To_Ada (Item : in char32_array; Target : out Wide_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/2 The types int, short, long, unsigned, ptrdiff_t, size_t, double, char, wchar_t, char16_t, and char32_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/2 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. If Append_Nul is False and Item'Length is 0, then To_C propagates Constraint_Error. 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/2 function Is_Nul_Terminated (Item : in char16_array) return Boolean; 60.2/2 The result of Is_Nul_Terminated is True if Item contains char16_nul, and is False otherwise. 60.3/2 function To_C (Item : in Wide_Character) return char16_t; function To_Ada (Item : in char16_t ) return Wide_Character; 60.4/2 To_C and To_Ada provide mappings between the Ada and C 16-bit character types. 60.5/2 function To_C (Item : in Wide_String; Append_Nul : in Boolean := True) return char16_array; function To_Ada (Item : in char16_array; Trim_Nul : in Boolean := True) return Wide_String; procedure To_C (Item : in Wide_String; Target : out char16_array; Count : out size_t; Append_Nul : in Boolean := True); procedure To_Ada (Item : in char16_array; Target : out Wide_String; Count : out Natural; Trim_Nul : in Boolean := True); 60.6/2 The To_C and To_Ada subprograms that convert between Wide_String and char16_array have analogous effects to the To_C and To_Ada subprograms that convert between String and char_array, except that char16_nul is used instead of nul. 60.7/2 function Is_Nul_Terminated (Item : in char32_array) return Boolean; 60.8/2 The result of Is_Nul_Terminated is True if Item contains char16_nul, and is False otherwise. 60.9/2 function To_C (Item : in Wide_Wide_Character) return char32_t; function To_Ada (Item : in char32_t ) return Wide_Wide_Character; 60.10/2 To_C and To_Ada provide mappings between the Ada and C 32-bit character types. 60.11/2 function To_C (Item : in Wide_Wide_String; Append_Nul : in Boolean := True) return char32_array; function To_Ada (Item : in char32_array; Trim_Nul : in Boolean := True) return Wide_Wide_String; procedure To_C (Item : in Wide_Wide_String; Target : out char32_array; Count : out size_t; Append_Nul : in Boolean := True); procedure To_Ada (Item : in char32_array; Target : out Wide_Wide_String; Count : out Natural; Trim_Nul : in Boolean := True); 60.12/2 The To_C and To_Ada subprograms that convert between Wide_Wide_String and char32_array have analogous effects to the To_C and To_Ada subprograms that convert between String and char_array, except that char32_nul is used instead of nul. 60.13/3 The Convention aspect with convention_identifier C_Pass_By_Copy shall only be specified for a type. 60.14/2 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 an unchecked union type or 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.15/3 If a type is C_Pass_By_Copy-compatible, then it is also C-compatible. 60.16/4 The identifiers C_Variadic_0, C_Variadic_1, C_Variadic_2, and so on are convention_identifiers. These conventions are said to be C_Variadic. The convention C_Variadic_n is the calling convention for a variadic C function taking n fixed parameters and then a variable number of additional parameters. The C_Variadic_n convention shall only be specified as the convention aspect for a subprogram, or for an access-to-subprogram type, having at least n parameters. A type is compatible with a C_Variadic convention if and only if the type is C-compatible. Implementation Requirements 61/3 An implementation shall support specifying aspect Convention with a C convention_identifier for a C-eligible type (see B.1). An implementation shall support specifying aspect 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. 62.1/3 An implementation need not support specifying the Convention aspect with convention_identifier C in the following cases: 62.2/3 * for a subprogram that has a parameter of an unconstrained array subtype, unless the Import aspect has the value True for the subprogram; 62.3/3 * for a function with an unconstrained array result subtype; 62.4/3 * for an object whose nominal subtype is an unconstrained array subtype. Implementation Advice 62.5/3 The constants nul, wide_nul, char16_nul, and char32_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. 65.1/4 * An Ada enumeration type corresponds to a C enumeration type with corresponding enumeration literals having the same internal codes, provided the internal codes fall within the range of the C int type. 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/2 * An Ada parameter of a (record) type T of convention C_Pass_By_Copy, 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/2 * An Ada parameter of a record type T, of any mode, other than an in parameter of a type of convention C_Pass_By_Copy, 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. 71.1/3 * An Ada parameter of a private type is passed as specified for the full view of the type. 71.2/3 * The rules of correspondence given above for parameters of mode in also apply to the return object of a function. 71.3/3 This paragraph was deleted. NOTES 72 6 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 7 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/2 This paragraph was deleted. 75/4 8 A variadic C function 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 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/3 -- 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) with Import => True, Convention => C, External_Name => "strcpy"; 79/3 This paragraph was deleted. 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/3 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 with Import => True, Convention => C has been specified, 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/2 type chars_ptr is private; pragma Preelaborable_Initialization(chars_ptr); 6/2 type chars_ptr_array is array (size_t range <>) of aliased 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/3 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/3 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/3 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/2 Equivalent to Update(Item, Offset, To_C(Str, Append_Nul => False), 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 9 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/3 function "+" (Left : in Pointer; Right : in ptrdiff_t) return Pointer with Convention => Intrinsic; function "+" (Left : in ptrdiff_t; Right : in Pointer) return Pointer with Convention => Intrinsic; function "-" (Left : in Pointer; Right : in ptrdiff_t) return Pointer with Convention => Intrinsic; function "-" (Left : in Pointer; Right : in Pointer) return ptrdiff_t with Convention => Intrinsic; 11/3 procedure Increment (Ref : in out Pointer) with Convention => Intrinsic; procedure Decrement (Ref : in out Pointer) with Convention => Intrinsic; 12/3 This paragraph was deleted. 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 10 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.3.3 Unchecked Union Types 1/3 Specifying aspect Unchecked_Union to have the value True defines an interface correspondence between a given discriminated type and some C union. The aspect requires that the associated type shall be given a representation that allocates no space for its discriminant(s). Paragraphs 2 through 3 were moved to Annex J, "Obsolescent Features". Static Semantics 3.1/3 For a discriminated record type having a variant_part, the following language-defined representation aspect may be specified: 3.2/3 Unchecked_Union The type of aspect Unchecked_Union is Boolean. If directly specified, the aspect_definition shall be a static expression. If not specified (including by inheritance), the aspect is False. Legality Rules Paragraphs 4 and 5 were deleted. 6/3 A type for which aspect Unchecked_Union is True is called an unchecked union type. A subtype of an unchecked union type is defined to be an unchecked union subtype. An object of an unchecked union type is defined to be an unchecked union object. 7/2 All component subtypes of an unchecked union type shall be C-compatible. 8/2 If a component subtype of an unchecked union type is subject to a per-object constraint, then the component subtype shall be an unchecked union subtype. 9/3 Any name that denotes a discriminant of an object of an unchecked union type shall occur within the declarative region of the type, and shall not occur within a record_representation_clause. 10/3 The type of a component declared in a variant_part of an unchecked union type shall not need finalization. In addition to the places where Legality Rules normally apply (see 12.3), this rule also applies in the private part of an instance of a generic unit. For an unchecked union type declared within the body of a generic unit, or within the body of any of its descendant library units, no part of the type of a component declared in a variant_part of the unchecked union type shall be of a formal private type or formal private extension declared within the formal part of the generic unit. 11/2 The completion of an incomplete or private type declaration having a known_discriminant_part shall not be an unchecked union type. 12/2 An unchecked union subtype shall only be passed as a generic actual parameter if the corresponding formal type has no known discriminants or is an unchecked union type. Static Semantics 13/2 An unchecked union type is eligible for convention C. 14/2 All objects of an unchecked union type have the same size. 15/2 Discriminants of objects of an unchecked union type are of size zero. 16/2 Any check which would require reading a discriminant of an unchecked union object is suppressed (see 11.5). These checks include: 17/2 * The check performed when addressing a variant component (i.e., a component that was declared in a variant part) of an unchecked union object that the object has this component (see 4.1.3). 18/2 * Any checks associated with a type or subtype conversion of a value of an unchecked union type (see 4.6). This includes, for example, the check associated with the implicit subtype conversion of an assignment statement. 19/2 * The subtype membership check associated with the evaluation of a qualified expression (see 4.7) or an uninitialized allocator (see 4.8). Dynamic Semantics 20/2 A view of an unchecked union object (including a type conversion or function call) has inferable discriminants if it has a constrained nominal subtype, unless the object is a component of an enclosing unchecked union object that is subject to a per-object constraint and the enclosing object lacks inferable discriminants. 21/2 An expression of an unchecked union type has inferable discriminants if it is either a name of an object with inferable discriminants or a qualified expression whose subtype_mark denotes a constrained subtype. 22/2 Program_Error is raised in the following cases: 23/2 * Evaluation of the predefined equality operator for an unchecked union type if either of the operands lacks inferable discriminants. 24/2 * Evaluation of the predefined equality operator for a type which has a subcomponent of an unchecked union type whose nominal subtype is unconstrained. 25/2 * Evaluation of a membership test if the subtype_mark denotes a constrained unchecked union subtype and the expression lacks inferable discriminants. 26/2 * Conversion from a derived unchecked union type to an unconstrained non-unchecked-union type if the operand of the conversion lacks inferable discriminants. 27/2 * Execution of the default implementation of the Write or Read attribute of an unchecked union type. 28/2 * Execution of the default implementation of the Output or Input attribute of an unchecked union type if the type lacks default discriminant values. Paragraph 29 was deleted. NOTES 30/2 11 The use of an unchecked union to obtain the effect of an unchecked conversion results in erroneous execution (see 11.5). Execution of the following example is erroneous even if Float'Size = Integer'Size: 31/3 type T (Flag : Boolean := False) is record case Flag is when False => F1 : Float := 0.0; when True => F2 : Integer := 0; end case; end record with Unchecked_Union; 32/2 X : T; Y : Integer := X.F2; -- erroneous B.4 Interfacing with COBOL 1/3 The facilities relevant to interfacing with the COBOL language are the package Interfaces.COBOL and support for specifying the Convention aspect 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/3 type Decimal_Element is mod implementation-defined; type Packed_Decimal is array (Positive range <>) of Decimal_Element with Pack; 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/3 type Alphanumeric is array (Positive range <>) of COBOL_Character with Pack; 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/3 type Numeric is array (Positive range <>) of COBOL_Character with Pack; 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/3 type Byte is mod 2**COBOL_Character'Size; type Byte_Array is array (Positive range <>) of Byte with Pack; 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/3 * 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/3 An implementation shall support specifying aspect 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/3 12 An implementation is not required to support specifying aspect Convention for access types, nor is it required to support specifying aspects Import, Export, or Convention for functions. 100 13 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/3 type COBOL_Record is record Name : COBOL.Numeric(1..20); SSN : COBOL.Numeric(1..9); Salary : COBOL.Binary; -- Assume Binary = 32 bits end record with Convention => COBOL; 107/3 procedure Prog (Item : in out COBOL_Record) with Import => True, Convention => COBOL; 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/3 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 with Convention => COBOL; 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/3 The facilities relevant to interfacing with the Fortran language are the package Interfaces.Fortran and support for specifying the Convention aspect 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/3 type Fortran_Character is array (Positive range <>) of Character_Set with Pack; 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/3 An implementation shall support specifying aspect 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 14 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/3 type Fortran_Matrix is array (Integer range <>, Integer range <>) of Double_Precision with Convention => Fortran; -- stored in Fortran's -- column-major order procedure Invert (Rank : in Fortran_Integer; X : in out Fortran_Matrix) with Import => True, Convention => Fortran; -- 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;