Technical Specification

• Convert data values stored in structured Ada types into sequences of bytes (write or convert down)
• Convert byte strings back into structured data values (read or convert up)

This mechanism can be used to transmit data values (messages) between heterogeneous computers running code compiled by different compilation systems. The message sender can call an interchange subprogram for the message's type to write its current value into a byte string. The sender will then transmit the byte string over some communication medium to a receiver that will read its value into a local data structure by calling the corresponding interchange procedure. Agreed-upon formats for predefined type values (that is, integers, reals, and bytes) are used to ensure that the receiver gets a data value identical to that of the sender even if the layout used by each local compiler is different. This mechanism is similar to the stream-oriented attributes in Ada 95. It is implemented, however, in Ada 83 and is fully portable.

ATIG subprograms write composite data structures into the byte string one component at a time. The byte representation for each component is constructed by the write procedure for the component type. Nested structures are thus "flattened" into a sequence of predefined leaf values through a sequence of calls to write subprograms. The read process is analogous. Byte sequences are converted into values and stored in the components of the local data structure. ATIG attempts to minimize the number of bytes in each type's representation, especially for unconstrained types.

Automated generation and consistency checking of interchange subprograms is provided by ATIG for the following kinds of types:

• Predefined types (Integer, Float, Duration, Character, String, Calendar.Time)
• User-defined discrete, floating-point, and fixed-point types
• Constrained and unconstrained arrays with single and multiple indexes
• Simple records
• Mutable discriminant, limited mutable discriminant, and nonmutable discriminant records
• Types declared in a generic package whose components both reference generic formal types and other nonformal types
• Subtypes and derived types of any of the above types
• Private types whose completion is any of the above types

Several transfer formats for the predefined leaf values can be defined to serve diverse purposes:

• A lean format can be defined for internal communication within one local-area network (XDR for example).
• A more verbose or sophisticated format (such as OSI ASN.1 BER) can be used for external communication within a wide-area network.
• A human-legible transfer format can be used for debugging systems under development.
• A transfer format suitable for storage of information in some database can also be defined.

ATIG Commands

Two user commands are defined by ATIG. They can be invoked at the UNIX shell with a command line or via the GUI menu selection and dialog box. These commands provide the capability to:

• Create, update, or verify the consistency of interchange subprograms for a single type specified by the user
• Create, update, or verify the consistency of interchange subprograms for all types located in a specified set of Ada units
• Traverse the type hierarchy of any type to ensure that up-to-date interchange subprograms exist for all component types in the closure of the hierarchy

A log will report all work attempted and any problems that occur during processing. Warnings include unit access problems, missing interchange subprograms, and/or missing unit bodies. Warnings will also be generated for unsupported types or types whose bounds are too large to fit in the predefined leaf types. Some errors terminate processing of a specific type (see the section titled "Restrictions" below).

Detailed Command Descriptions

command For_Specific_Type
atig for_specific_type

-For_Type

-Recursive

-Recursive_Only_Within_Local_View

-Force_Overwrite

-Compile_After_Updates

-Use_Configuration [string-expression, default= ""]

Options

• For_Type: Specifies the pathname of the type for which interchange subprograms are desired. The syntax of this pathname follows standard UNIX notation up to the compilation-unit name. Ada dot notation is used to select a specific type declaration within the compilation unit.
• Recursive: Specifies whether to traverse the transitive closure of all component types to determine if they require generation or update of their interchange subprograms.
• Recursive_Only_Within_Local_View: Specifies whether only those types located in the same view as the original type (For_Type) shall be recursively processed or whether all types in the component closure shall be processed.
• Force_Overwrite: Specifies, if True, that interchange subprogram specifications are added if they do not exist. Subunit bodies are replaced even if they are determined to be consistent with the current type definition. Interchange procedure specifications and null implementations for access types can also be generated if Force_Overwrite is True.
• Compile_After_Updates: Specifies, if True, that all updated Ada units be compiled after all updates have been completed.
• Use_Configuration: This option requires that a pathname of a configuration file follow as its argument. When included, this option specifies that the configuration file specify where to find references to declarations in other, external views. The default is to use the views that are imported into the referencing view.

Of_Type: This section appears at the top of the dialog box and is used to specify the pathname of the type declaration to process. Selection of an Ada type will automatically fill this section with the pathname of that type.
Non-operable Locator: This is a standard Apex file locator but it is not used by this command.

Configuration: The configuration section is used to specify whether import closure or a named configuration file should be used during analysis to resolve references. The default is to use the import closure of the units selected in the Objects locator. If the user desires another configuration, the Use configuration radio button can be selected and a pathname of .cfg file entered.

Report Name: This section is not used by ATIG.

Options: The section appears at the bottom left of the dialog box and contains Boolean options that can be selected by the user. The boolean options for this command are Recursive, Force_Overwrite, and Compile_After_Updates.

command For_Types_In_Units
atig for_types_in_units

-Recursive

-Recursive_Only_Within_Local_View

-Only_Required_Types

-Effort_Only

-Compile_After_Updates

-Use_Configuration [string-expression, default= ""] 

This command traverses all compiled Ada units specified by the to locate type declarations. Each located type declaration is checked to validate that the required interchange subprograms exist and that their implementations are up to date. All missing items are created. All out-of-date interchange implementations are replaced. The Effort-_Only option can be used to check and report the status of all types without actually doing any work.
Note that the comment annotation, "-- No Interchange Necessary" (this is customizable; see section titled "Customization" below) can be attached to those types in a package for which no interchange subprograms are desired. The annotation "-- Nonvisible Interchange" (also customizable) can be attached to type declarations for which interchange is required, but only for local use. The interchange specs will be placed in the body for these types.

Options

• Recursive: Specifies whether to traverse the transitive closure of all component types to determine if they require generation or update of their interchange subprograms.
• Recursive_Only_Within_Local_View: Specifies whether only those types located in the same view as the original type (For_Type) shall be recursively processed or whether all types in the component closure shall be processed.
• Only_Required_Types: Specifies, if True, that interchange-subprogram specifications are added only for types that must have them (that is, record, array, and private types). If False, interchange subprograms are added for all types located in the specified units.
• Effort_Only: Specifies, if True, that this command reports all required actions and logs all warnings and errors but does not actually perform any work.
• Compile_After_Updates: Specifies that all updated Ada units be compiled after all updates have been completed.
• Use_Configuration: This option requires that a pathname of a configuration file follow as its argument. When included, this option specifies that the configuration file specify where to find references to declarations in other, external views. The default is to use the views that are imported into the referencing view.
• : This list must appear after all named options. Items in the list specify which units to process and must be separated by spaces. Pathnames of configuration files, views, directories, or specific Ada units may be included. If a configuration file is specified, all units in all views listed in the configuration file will be included in the analysis. If a view or directory is specified, all Ada units contained within that view or directory will be included in the analysis. Only installed Ada units within the expanded list will actually be processed, however, with warning messages generated for objects of other classes or Ada units that are not installed or coded.

Objects: This is a standard Apex file locator and is used to specify which Ada units should be analyzed by a command. Objects selected within the window where the command menu item was invoked will appear as initial values in the right side of the locator. Configuration files, views, directories, and Ada objects can be added or removed from the right side as required to specify the desired list of Ada units to analyze.

Configuration: The configuration section is used to specify whether import closure or a named configuration file should be used during analysis to resolve references. The default is to use the import closure of the units selected in the Objects locator. If the user desires another configuration, the Use configuration radio button can be selected and a pathname of .cfg file entered.

Report Name: This section is not used by ATIG.

Options: The section appears at the bottom left of the dialog box and contains Boolean options that can be selected by the user. The boolean options for this command are Recursive, Only_Required_Types, Effort_Only, and Compile_After_Updates.

Special Capabilities

"No Interchange Necessary" Annotation

The annotation "-- No Interchange Necessary" can be used to specify that no interchange subprograms should be generated for a particular type. This is especially useful in conjunction with the For_Types_In_Units command when interchange is not required for every type within a set of packages.

"Nonvisible Interchange" Annotation

The annotation "-- Nonvisible Interchange" can be used to specify that the interchange subprograms for a particular type should be located in the body of the package in which the type is declared. This mechanism can be used when a composite type references other local types in the package. For correct creation of the interchange subprogram for the composite type, interchange subprograms must be available for all referenced types, but they need not be made visible if all references are local. If external references to the type exist, then visible interchange routines are required. In this case, a message to this effect is placed in the log, and the interchange subprograms for types with external references will not compile. The user must manually make the required subprogram specifications visible or delete the annotation, remove all existing interchange subprograms for that type, and start fresh with the ATIG For_Specific_Type command.

"Hand-Generated Interchange" Annotation

The annotation "-- Hand-Generated Interchange" can be used to specify that the interchange subprograms for a particular type have been written by hand and that they should not be replaced by any command. ATIG commands will add required interchange specifications and subunit stubs if they do not exist, but they will not replace any subunit implementations.

"Message Id" Annotation

The annotation "-- Message Id: >>Id String<<" can be added before any type declaration to assign a string ID to that type. This could be added to the message byte string through a call in the body of the interchange write procedures. Reading this field would then be the responsibility of the receiver of this message. Note that this capability is not fully deÞned for this version of ATIG. This mechanism is currently designed as a placeholder for subsequent versions of this tool.

Read Interchange Functions for Unconstrainted Types

The procedural form of read is often inconvenient because the caller must know the discriminant and/or index constraints before calling the procedure. Although less efficient, a functional form of read allows the constraints to be read and set within the function. The return value can be assigned to a constant, avoiding the need for the caller to know the constraints in advance. A Boolean customization function specifies whether to create read functions for unconstrained types in addition to read procedures. See the section titled "Customization" at the end of this user's guide for more information.

Two conditions must be met in order to use this capability:

1. The Byte_Stream type in the Byte_Stream_Support package must be an access type. This allows it to be passed into the function as an in parameter even though the data (byte stream) that it points to will be updated by the read.

2. This capability cannot be used in conjunction with the creation of subunit conversion subprograms since the name of the functional read and procedural read are identical and will conflict.

Restrictions

ATIG requires that packages containing types have both a spec and a body. A body is necessary to contain the interchange subprograms. ATIG will recognize and report when a package body is missing and not attempt to create interchange subprograms for that type. The body must be created by the user and then ATIG can be re-executed.

Controlled Objects

When the unit containing a type declaration requires checkout and is not the latest generation, no processing of this type will be performed. In this case, the unit may be changed by CMVC when the latest generation is automatically accepted on checkout. For objects that are not the latest generation, the user must manually check out the unit and recompile it before ATIG will process it.

Generic Units

Types declared in generic packages will often reference types declared as formal parameters of the generic. If this is the case, read and write interchange subprograms must be present as formal parameters of the generic. See the section titled "Subprogram Interchange Formats" for requirements for the naming of these subprograms and their parameters. ATIG can add these required generic formal parameters but all instantiations of this generic will need to be updated by hand. Without restriction, the hierarchical traversal commands can validate generic formal subprogram consistency and replace interchange implementations as necessary.

Types Declared in Nested Packages

If a type is declared in a package that is nested one or more levels within the library-level package, the body of that package must be a subunit if the customization specifies that ATIG should create subunits.

Composite Types with Limited Private Components

Since the read interchange subprogram returns a value of the type through an out parameter, limited types cannot be used as components of any composite type used as the type mark of the parameter (see LRM 7.4.4 (4)). This is a restriction since assignment is not available for limited types and the out parameter cannot be set without it. If a type with this characteristic is encountered, an error message is generated and no interchange subprograms are generated.

Error and Warning Messages

Error messages may be generated for the following instances:

• An attempt to generate interchange subprograms for an access type, protected type, or task type
• An attempt to generate interchange subprograms for a private type that has no completion type
• An attempt to generate interchange subprograms for a type that is not declared in a static scope
• An attempt to generate interchange subprograms for a type in a package that is not compiled
• An attempt to generate interchange subprograms for a type located in a package with no body.
• An attempt to generate interchange subprograms for a type that is located in a nested package whose body is not a subunit
• An attempt to generate interchange subprograms for a type located in a unit that is not the latest CMVC generation
• Specification of an configuration option that is not a configuration file or does not exist

• Processing of access types with an attached "-- Hand-Generated" annotation.
• Recognition that the read or write procedures for a referenced type do not exist. This is a warning since they may in fact be generated during execution of the command.
• Recognition that an interchange subprogram must be replaced. This will be the case when the type definition is changed or when explicit read and write subprograms have been added for a component type.

Testing

Base Interfaces

System_Types
package System_Types is

type Integer8	is	range -2 ** 7 .. 2 ** 7 - 1;
subtype Positive8	is	Integer8 range 1 .. Integer8'Last;
subtype Natural8	is	Integer8 range 0 .. Integer8'Last;
type Integer16	is	range -2 ** 15 .. 2 ** 15 - 1;
subtypePositive16	is	Integer16 range 1 .. Integer16'Last;
subtype Natural16	is	Integer16 range 0 .. Integer16'Last;
type Integer32	is	range -2 ** 31 .. 2 ** 31 - 1;
subtype Positive32	is	Integer32 range 1 .. Integer32'Last;
Tsubtype Natural32	is	Integer32 range 0 .. Integer32'Last;
type Local_String	is	array (Positive16 range <>) of Character;

type	Float6	is	digits 6;
type	Float9	is	digits 9;
type	Float13	is	digits 13;

end System_Types;

Interchange of these predefined types is provided by the following package.

Byte_Stream_Support
with Calendar;
with System_Types;
package Byte_Stream_Support is
type Byte_Stream is implementation defined;

procedure Integer8_Read	(From : in out Byte_Stream; Into : out System_Types.Integer8);
procedure Integer16_Read	(From : in out Byte_Stream; Into : out System_Types.Integer16);
procedure Integer32_Read	(From : in out Byte_Stream; Into : out System_Types.Integer32);
procedure Character_Read	(From : in out Byte_Stream; Into : out Character);
procedure String_Read	(From : in out Byte_Stream; Into : out String);
procedure Local_String_Read	(From : in out Byte_Stream; Into : out System_Types.Local_String);
procedure Float6_Read	(From : in out Byte_Stream; Into : out System_Types.Float6);
procedure Float9_Read	(From : in out Byte_Stream; Into : out System_Types.Float9);
procedure Float13_Read	(From : in out Byte_Stream; Into : out System_Types.Float13);
procedure Duration_Read	(From : in out Byte_Stream; Into : out Duration);
procedure Time_Read	(From : in out Byte_Stream; Into : out Calendar.Time);
procedure Integer8_Write	(From : in System_Types.Integer8; Into : in out Byte_Stream);
procedure Integer16_Write	(From : in System_Types.Integer16; Into : in out Byte_Stream);
procedure Integer32_Write	(From : in System_Types.Integer32; Into : in out Byte_Stream);
procedure Character_Write	(From : in Character; Into : in out Byte_Stream);
procedure String_Write	(From : in String; Into : in out Byte_Stream);
procedure Local_String_Write	(From : in System_Types.Local_String; Into : in out Byte_Stream);
procedure Float6_Write	(From : in System_Types.Float6; Into : in out Byte_Stream);
procedure Float9_Write	(From : in System_Types.Float9; Into : in out Byte_Stream);
procedure Float13_Write	(From : in System_Types.Float13; Into : in out Byte_Stream);
procedure Duration_Write	(From : in Duration; Into : in out Byte_Stream);
procedure Time_Write	(From : in Calendar.Time; Into : in out Byte_Stream);
end Byte_Stream_Support;

An implementation (body) of this package is provided for execution on the release hardware platform. This is located in the base_interfaces subdirectory of the atig_testing.ss subsystem. These packages or their equivalent should be moved into an application subsystem since they will in fact be part of the executable application. It is expected that users will write alternative implementations of the body to support different formats and optimizations and to provide support for specific compilation systems.

Note: Before any attempt is made to generate interchange programs with ATIG, the subsystems containing these packages must be imported into any application subsystem containing software to be updated with ATIG. This is necessary because the generated subprograms will reference these specifications.

Subprogram Interchange Formats

The Write procedure converts a value of the type to a sequence of bytes and appends it to a specified byte stream. The Read procedure removes a sequence of bytes from the specified stream, converts it to a value of the type, and returns it in an object of the type. It expects the next sequence of bytes from the stream to have the form written by the corresponding Write; if the elements do not have that form, or do not satisfy the constraints of the actual out parameter, then the Constraint_Error exception will be raised.

It is possible for users to manually add specifications and subunit stubs and to create subunit implementations for any type that requires interchange. It is required that users manually add subprogram formal parameters to generics whose formal parameter specification contains types requiring interchange. Manually added specifications must have the exact parameter profile shown in the example above. The name of the subprogram is constructed as follows:

• If the type is declared directly within a library-level package and not nested within other packages, then the subprogram names are:

_Write
_Read
• If the type declaration appears in a nested package, then the subprogram names are:

__Write
__Read

The same process is used to construct the names for generic formal parameters. The simple name of the formal type parameter and any nested package names are used in the same way.

Note: It is possible to change the names "Read" and "Write" to any other string names desired by the user of ATIG. If these names are changed with the customization options described below, then they must be used consistently in all interchange subprograms. Formats for Specific Types

The following list describes the interchange-subprogram format for each supported type.

• Predefined types (Integer, Real, Character, String, Duration, Calendar.Time): Package Byte_Stream_Support defines read and write interchange subprograms for all predefined type s (see above). A body suitable for execution on the Rational Environment is provided by ATIG. This implementation is based on Unchecked_Conversion and is therefore suitable only for testing on the homogeneous systems. Alternative bodies should be developed by the user to improve efficiency or support alternative stream formats.
• User-defined integer and modular types: Type conversion from user-defined integer types to predefined types is used with calls to package Byte_Stream_Support.
• User-defined real types: Type conversion from user-defined real types to predefined types is used with calls to package Byte_Stream_Support.
• User-defined fixed-point and decimal fixed point types: Fixed-point values are placed in the byte stream as integer values. The value will be the number of actual deltas from 'First to the value being sent.
• Enumeration types: Enumeration values are converted with 'Pos and 'Val into and from Short_Integer values. The read implementation requires the declaration of a local Integer8 variable to temporarily hold a value for subsequent conversion into the enumeration value.
• Constrained arrays: Each component of the array is written in "last dimension varying faster" order.
• Unconstrained arrays: The actual length of each index is written first, followed by each component in "last dimension varying faster" order.
• Simple records, tagged types and extension types: Components are written and read in textual order. A components of extension types are flattened into a sequential list.
• Nonmutable discriminant records: Components are written and read in textual order. Actual discriminants are written first. Only the components for the actual variant part of the record are sent.
• Mutable discriminant records: Discriminants are written first, followed by the components of the record. The following strategy for read is used:

-Read all discriminants first.

-If the actual out parameter is mutable (i.e., not constrained), then make sure that it currently has the right set of discriminants.

-If not, provoke a mutation of the actual.

-Then proceed as for a simple record with the rest of the components, with case statements paralleling the variants.

• Types declared in generic packages whose components both reference formal types and other nongeneric types: Interchange is identical to above with calls made to formal read and write procedures when available.
• Subtypes: Interchange calls are made directly to those of the base type.
• Private types: Private types are generally handled no differently than other types, with the contents of the interchange subprograms based on the completion of the private type.

Private type declarations have two parts, an incomplete declaration in the visible part and a completion part in the private part of the package. If the user specifies the visible part declaration to an ATIG command, visible interchange subprograms will be added to that package (immediately before the private part). If the user specifies the completion part (with selection), then the interchange subprograms will be added in the nonvisible, private part of the package.
• Linearizing complex data structures: It is not a good idea to try to interchange access values. However, when a complex data structure is built using access types, a pair of write and read procedures can be provided manually. With the "Hand-Generated Interchange" annotation, the implementations of read and write will not be overwritten by ATIG. Consider the interchange of a link list as a very primitive example.

Customization

• Byte
• Local_String
• Standard_String
• Standard_Character
• Standard_Boolean
• Standard_Duration
• Calendar_Time
• Short_Int
• Int
• Long_Int
• Long_Long_Int
• Real
• Long_Real
• Long_Long_Real
• Long_Long_Long_Real

The following items describe ATIG parameters that are customizable and their default values.

• Name of the package containing the actual predeÞned types defined by the local application; default = System_Types.
• Name of the package declaring the actual type definition for Byte; default = Machine_Types.
• Name of the byte-stream support package; default = Byte_Stream_Support.
• Name of the byte-stream type; default = Byte_Stream.
• Whether or not interchange is supported for each of the abstract predefined types listed above; default = True for Local_String, Standard_String, Standard_Character, Standard_Boolean, Standard_Duration, Calendar_Time, Short_Int, Int, Long_Int, Real, Long_Real, and Long_Long_Real; default = False for Long_Long_Int and Long_Long_Long_Real.
• The simple name of each supported predeÞned type; defaults: Local_String = "Local_String", Standard_String = "String", Standard_Character = "Character", Standard_Boolean = "Boolean", Standard_Duration = "Duration", Calendar_Time = "Time", Short_Int = "Integer8", Int = "Integer16", Long_Int= "Integer32", Real = "Float6", Long_Real = "Float9", and Long_Long_Real = "Float13".
• The Ada qualified name of each predefined type; example default = System_Types.Float9.
• The upper and lower bound for each predefined integer type.
• Whether or not to normalize integer values to save space at the expense of additional computation time. When the total number of discrete values will fit in a particular integer type but one of the bounds exceeds the bounds of that type, the larger integer container must normally be chosen. If normalization is enabled, a constant value will either be added or subtracted to bring the value within bounds of the smaller predefined type.
• The number of specified digits for each predefined real type.
• The names of all predefined packages where the ATIG should not attempt to add interchange subprograms; default = Standard, System, Text_Io, Calendar, predefined types package (first item above), machine types package (second item above).
• Annotation to designate that interchange for a type is hand-generated; default = "Hand-Generated Interchange".
• Annotation to designate the message ID for a type; default = "Message Id:".
• Annotation to designate that no interchange subprograms should be generated for a specific type; default: = "No Interchange Necessary".
• Annotation to designate that the interchange subprograms should be located in the body of the package in which the type is declared; default = "Nonvisible Interchange".
• Comment annotation in interchange subunits containing the hash code; default = "-- HASH: ". The hash code is used to determine if the subunit is out of date. Once a new image for the interchange procedure is generated by ATIG, it is hashed and compared with the value stored in the subunit annotation. If the hash codes match, the subunit is consistent. If they do not match, the subunit requires replacement.
• Whether or not calls to interchange subprograms should be made with named notation or not; default = True.
• Whether or not interchange subprograms should be created as subunits; default = False.
• Whether or not to leave existing interchange subprograms that are subunits as subunits even if the previous switch is set to True; default = True.
• Whether or not to generate functions for reading unconstrained types. If True, a functional form of the read conversion subprogram will be created in addition to the procedural form; default = False.
• The name of the exception to raise when reading a discriminant record type that is not the correct discriminant; default = "constraint_error".
• Simple name for the read interchange subprogram; default = "Read".
• Simple name for the write interchange subprogram; default = "Write".
• Pathname location of predefined types package (first item above).
• Pathname location of machine types package (second item above).
• Pathname location of byte-stream support package (third item above).
• Whether or not to search for the predefined packages within the pathnames above or within the view closure of the software being processed.

References

2. Ada Semantic Interface Specification (ASIS)

3. XDR: External Data Representation Standard, RFC 104, Sun Microsystems, 1987.

4. Basic Encoding Rules for Abstract Syntax Notation One (ASN.1), ISO standard 8825, 1987.

5. Philippe Kruchten: Byte Streams: A proposed solution to the problem of data transfer in a heterogeneous network, CAATS Architecture Note #47, Hughes Canada, April 1993.