![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Package Portable_Transfer This package provides resources that support the conversion of values into portable data streams. The data contained within these streams can be converted back into values with the resources in package Data_Decomposition.
This package and Data_Decomposition are part of the Data Decomposition Annex and are an optional ASIS capability.
This capability is available in Rational ASIS.
For more information, click on a topic:
Resources in Package Portable_TransferThe resources in package Portable_Transfer fall into several functional groups, as shown below.
To see detailed referenced information, click on the name of a resource:
Conversion to portable data:
package Portable_Constrained_Subtype package Portable_Unconstrained_Record_Type
Array conversion to portable data:
package Portable_Array_Type_1 package Portable_Array_Type_2 package Portable_Array_Type_3
Portable data input and output:
package Portable_Data_Io
Key Concepts for Package Portable_TransferThis package provides resources that support the conversion of values into portable data streams. The resources available to perform this conversion are described in the following categories. To see more information, click on a topic:
- "Portable-Transfer Use Considerations"
- "Description of a Portable Data Stream"
- "Operations on Portable Data Streams"
- "Properties of Portable Data"
- "Non-Array Type Conversion to Streams"
- "Scalar and Record Type Conversion to Streams"
- "Array Type Conversion to Streams"
- "Portable Data Input and Output"
Portable-Transfer Use Considerations
Unlike other ASIS packages, the resources in this package do not require the normal ASIS environment (see package Environment, "Controlling the ASIS Environment State"). As a result:
- Environment.Initialize need not be called before these resources are used.
- The memory cost of this facility is minimal because the full ASIS implementation is not linked into your application.
- Normal ASIS exceptions are not raised and Environment-.Status and Environment.Diagnosis facilities are not
available.Most subprograms in this package can raise only the Ada predefined exceptions, and only as a result of erroneous calling sequences or insufficient memory. Additionally, the Io_Exceptions defined in Ada83 LRM 14.4, Ada95 LRM A.13can be raised by the subprograms in package Portable_Data_Io.
Description of a Portable Data Stream
Portable data streams are encoded copies of the values of variables; they contain the values of all discriminants, index limits, and components.
Data streams are not simply unchecked conversions from the source type to the data-stream type. At a minimum, a data stream also contains information about its own size. It may also contain "dope" data to simplify decomposition. Do not attempt to decompose (or convert) a stream with your own routines.
Data streams are represented by the Portable_Data type. This is an unconstrained array, indexed by the Portable_Positive type and consisting of elements of the Portable_Value type. Each array element is called a portable data value. Note that portable data values do not represent individual encoded user variables; they are simply components of a fixed size that, taken together, represent a stream.
The Portable_Data type is purposefully not a private type. This allows you to access the individual portable data values to simplify storage or transmission.
Note: Data streams are portable only between machines of the same hardware architecture. No guarantee is made that data streams are portable across machines with different architectures. Data streams created by Rational ASIS implementations running on different hardware architectures are not compatible.
Operations on Portable Data Streams
- Constructed with the resources in this package or the Data_Decomposition.Construct_Artificial_Data_Stream function
- Read and written using resources defined in this package or by user subprograms
- Converted back into variables with the resources in package Data_Decomposition
- Decomposed into component streams that correspond to record components or array elements, using the resources in package Data_Decomposition
- Decomposed into individual portable data values that can be read and written using resources defined in this package or by user subprograms
Properties of Portable Data
ASIS does not specify definitions for the Portable_Value type or for the indexes used for the Portable_Data type. This allows an implementation to select the best representations for a particular computer or Ada environment. Instead, ASIS defines requirements for these types in terms of their use, as follows:
- The interfaces in this package, and in the nested package Operations, must be maintained.
- Portable data values and data streams should be readily decomposable by the subprograms in package Data_Decomposition, so that array and record component data streams can be efficiently extracted.
- Programs must be able to perform the following kinds of operations with portable data values:
- Read and write using Sequential_Io and Direct_Io
- Place them inside other types and then read and write the types
- Perform low-level I/O using 'Address and 'Size values
- Convert portable data values to a different type using Unchecked_Conversion; this use need not be portable across ASIS implementations
- Programs must be able to perform the following kinds of operations with data streams:
- Read and write a constrained subtype using Sequential_Io and Direct_Io
- Place values inside other types and then read and write those types
- Perform low-level I/O using 'Address and 'Size values
- Convert constrained data streams to a different type using Unchecked_Conversion; this use need not be portable across ASIS implementations
Non-Array Type Conversion to Streams
Variables are converted to data streams by three classes of interfaces:
- Generic package Portable_Constrained_Subtype converts scalar subtypes and fully constrained composite types
- Generic package Portable_Unconstrained_Record_Type converts unconstrained record types
- Generic packages Portable_Array_Type_1, Portable_Array_Type_2, and Portable_Array_Type_3 convert unconstrained array types
The array-conversion packages are described in "Array Type Conversion to Streams"; the other interfaces are described in "Scalar and Record Type Conversion to Streams."
Scalar and Record Type Conversion to Streams
Generic package Portable_Constrained_Subtype converts scalar subtypes or fully constrained composite types to data streams. The data stream can be converted back into a variable by instantiation and use of the Data_Decomposition.Portable-_Constrained_Subtype generic function with the same scalar type or constrained composite type.
Attempts to use this generic for other types will cause a compilation or runtime error.
Generic package Portable_Unconstrained_Record_Type converts unconstrained record types to data streams. Conversion of a data stream of an unconstrained record type back into a variable requires that a constrained subtype first be created. To create a constrained subtype from the data stream:
- 1. . Extract the data streams that represent the discriminant values from the record's data stream.
- 2. . Convert the extracted data streams into the actual discriminant values.
- 3. . Declare a subtype with the discriminant values.
The Data_Decomposition.Portable_Constrained_Subtype generic function then can be instantiated with the subtype, and the instantiation can be used to convert the data stream.
See package Data_Decomposition, "Constructing Artificial Data Streams," for more information.
Attempts to use the generic package Portable_Unconstrained_Record_Type with an unconstrained array type will not generate a compile or runtime error. No guarantee is made, however, that such instantiations will operate correctly. Instead, use generics provided for conversion of unconstrained arrays, which are described in the next section.
Array Type Conversion to Streams
Unconstrained array subtypes, particularly those with up to three dimensions, appear frequently in applications. For convenience, generic packages have been provided to convert such arrays to data streams.
A different package is provided for each different dimensionality: package Portable_Array_Type_1 for one-dimensional arrays, package Portable_Array_Type_2 for two-dimensional arrays, and package Portable_Array_Type_3 for three-dimensional arrays. If unconstrained arrays containing more dimensions need to be converted, place them into discriminated records and then convert the records.
To instantiate the generic packages, you need to specify the array subtype indicator, the types that represent the array indexes, and the array type itself. The Convert function, appearing in each package, converts a value of the array type to a data stream.
It is generally not possible to convert the stream generated back into an array with the Data_Decomposition.Portable_Constrained_Subtype function. This is a result of the differences between constrained and unconstrained subtypes. You can, however, convert each array element individually. To do this:
- 1. . Use any of the methods of identifying the individual array elements described in package Data_Decomposition, "Accessing Array Elements."
- 2. . Slice the individual element from the stream with the Data_Decomposition.Component_Data_Stream function.
- 3. . Convert the element into an instance of the array subtype indication with an instantiation of the Data_Decomposition.Portable_Constrained_Subtype function.
Portable Data Input and Output
Package Portable_Data_Io supports reading and writing of portable data values and data streams. It presents an interface that is functionally equivalent to generic package Sequential_Io, with an additional generic that can be used to perform both a conversion and a write. All resources that exist in Sequential_Io also exist in Portable_Data_Io.
Note: It is possible to intermix portable data values and data streams during output. When reading these files, you must ensure that portable data streams of the correct length are constructed. If a conversion is attempted on a partial or incorrect data stream, an exception is raised.
Constant Nil_Portable_Data
Nil_Portable_Data : Portable_Data (0 .. -1);Expanded Name Asis.Portable_Transfer.Nil_Portable_Data
Description
To begin the construction of an artificial data stream with the Data_Decomposition.Construction_Artificial_Data_Stream function, you must specify provide a nil data stream; this constant can be used as that value.
Cross-References
Generic Package Portable_Array_Type_1
generic type Element_Type is private; type Index_Type is (<>); type Array_Type is array (Index_Type range <>) of Element_Type;package Portable_Array_Type_1 is function Convert (Value : in Array_Type) return Portable_Data;end Portable_Array_Type_1;Expanded Name Asis.Portable_Transfer.Portable_Array_Type_1
Converts a one-dimensional array to a portable data stream.
Description
When instantiated with an unconstrained array subtype, this function converts values of the subtype into a corresponding data stream. The conversion correctly captures the index ranges and all array elements.
The resulting data stream can have a larger 'Size attribute value than the specified argument.
To convert a scalar subtype or a constrained composite subtype (records or arrays), use generic package Portable_Constrained-_Subtype. To convert an unconstrained record type, use generic package Portable_Unconstrained_Record_Type.
Parameters
type Element_Type is private;Specifies the type of the array's elements.
type Index_Type is (<>);Specifies the type of the array index.
type Array_Type is array (Index_Type range <>) of Element_Type;
function ConvertConverts the specified array value to a data stream.
Value : in Array_TypeSpecifies the array value to be converted.
return Portable_Data;Returns the data stream containing the converted array.
Errors
Ada predefined exceptions can be raised; in particular, Storage-_Error can be raised if insufficient space is available to declare or return the data stream represented by the array.
Cross-References
- generic package Portable_Array_Type_2
- generic package Portable_Array_Type_3
- generic package Portable_Constrained_Subtype
- generic package Portable_Unconstrained_Record_Type
Generic Package Portable_Array_Type_2
generic type Element_Type is private; type Index_Type_1 is (<>); type Index_Type_2 is (<>); type Array_Type is array (Index_Type_1 range <>, Index_Type_2 range <>) of Element_Type;package Portable_Array_Type_2 is function Convert (Value : in Array_Type) return Portable_Data;end Portable_Array_Type_2;Expanded Name Asis.Portable_Transfer.Portable_Array_Type_2
Converts a two-dimensional array to a portable data stream.
Description
When instantiated with an unconstrained array subtype, this function converts values of the subtype into a corresponding data stream. The conversion correctly captures the index ranges and all array elements.
The resulting data stream can have a larger 'Size attribute value than the specified argument.
To convert a scalar subtype or a constrained composite subtype (records or arrays), use generic package Portable_Constrained-_Subtype. To convert an unconstrained record type, use generic package Portable_Unconstrained_Record_Type.
Parameters
type Element_Type is private;Specifies the type of the array's elements.
type Index_Type_1 is (<>);Specifies the type of the array index for the first dimension.
type Index_Type_2 is (<>);Specifies the type of the array index for the second dimension.
type Array_Type is array (Index_Type_1 range <>, Index_Type_2 range <>) of Element_Type;
function ConvertConverts the specified array value to a data stream.
Value : in Array_TypeSpecifies the array value to be converted.
return Portable_Data;Returns the data stream containing the converted array.
Errors
Ada predefined exceptions can be raised; in particular, Storage-_Error can be raised if insufficient space is available to declare or return the data stream represented by the array.
Cross-References
- generic package Portable_Array_Type_1
- generic package Portable_Array_Type_3
- generic package Portable_Constrained_Subtype
- generic package Portable_Unconstrained_Record_Type
Generic Package Portable_Array_Type_3
generic type Element_Type is private; type Index_Type_1 is (<>); type Index_Type_2 is (<>); type Index_Type_3 is (<>); type Array_Type is array (Index_Type_1 range <>, Index_Type_2 range <>, Index_Type_3 range <>) of Element_Type;package Portable_Array_Type_3 is function Convert (Value : in Array_Type) return Portable_Data;end Portable_Array_Type_3;Expanded Name Asis.Portable_Transfer.Portable_Array_Type_3
Converts a three-dimensional array to a portable data stream.
Description
When instantiated with an unconstrained array subtype, this function converts values of the subtype into a corresponding data stream. The conversion correctly captures the index ranges and all array elements.
The resulting data stream can have a larger 'Size attribute value than the specified argument.
Array types with more than three dimensions can be converted to a data stream by placing them inside a discriminated record and then converting the record. The discriminants can be used to specify the values of any dynamic index constraints.
To convert a scalar subtype or a constrained composite subtype (records or arrays), use generic package Portable_Constrained-_Subtype. To convert an unconstrained record type, use generic package Portable_Unconstrained_Record_Type.
Parameters
type Element_Type is private;Specifies the type of the array's elements.
type Index_Type_1 is (<>);Specifies the type of the array index for the first dimension.
type Index_Type_2 is (<>);Specifies the type of the array index for the second dimension.
type Index_Type_3 is (<>);Specifies the type of the array index for the third dimension.
type Array_Type is array (Index_Type_1 range <>, Index_Type_2 range <>, Index_Type_3 range <>) of Element_Type;
function ConvertConverts the specified array value to a data stream.
Value : in Array_TypeSpecifies the array value to be converted.
return Portable_Data;Returns the data stream containing the converted array.
Errors
Ada predefined exceptions can be raised; in particular, Storage-_Error can be raised if insufficient space is available to declare or return the data stream represented by the array.
Examples
Cross-References
- generic package Portable_Array_Type_1
- generic package Portable_Array_Type_2
- generic package Portable_Constrained_Subtype
- generic package Portable_Unconstrained_Record_Type
Generic Package Portable_Constrained_Subtype
generic type Constrained_Subtype is private;package Portable_Constrained_Subtype is function Convert (Value : in Constrained_Subtype) return Portable_Data;end Portable_Constrained_Subtype;Expanded Name Asis.Portable_Transfer.Portable_Constrained_Subtype
Converts a scalar subtype or fully constrained composite subtype to a data stream.
Description
The resulting data stream can have a larger 'Size attribute value than the specified argument.
Instantiation of this generic, with arguments other than scalar types or fully constrained subtypes, will fail to compile or will fail to execute and raise Constraint_Error (Ada83 LRM 12.3.2(5), Ada95 LRM 12.5.1).
To convert an unconstrained record type, use generic package Portable_Unconstrained_Record_Type. To convert an unconstrained array type, use generic package Portable_Array_Type_1, Portable_Array_Type_2 or Portable_Array_Type_3.
Parameters
type Constrained_Subtype is private;Specifies the type to be converted.
function ConvertConverts the specified value to a data stream.
Value : in Constrained_SubtypeSpecifies the value to be converted.
return Portable_Data;Returns the data stream containing the converted value.
Errors
Ada predefined exceptions can be raised; in particular, Storage-_Error can be raised if insufficient space is available to declare or return the data stream represented by the specified value.
Cross-References
- generic package Portable_Array_Type_1
- generic package Portable_Array_Type_2
- generic package Portable_Array_Type_3
- generic package Portable_Unconstrained_Record_Type
Type Portable_Data
type Portable_Data is array (Portable_Positive range <>) of Portable_Value;Expanded Name Asis.Portable_Transfer.Portable_Data
Description
Cross-References
Package Portable_Data_Io
package Portable_Data_Io is ... function Read (File : in File_Type) return Portable_Value; function Read (File : in File_Type) return Portable_Data; procedure Write (File : in File_Type; Data_Stream : in Portable_Value); procedure Write (File : in File_Type; Data_Stream : in Portable_Data); generic type Data_Type is private; with function Convert (Value : in Data_Type) return Portable_Data; package Write_Data_Type is procedure Write (File : in File_Type; Value : in Data_Type); end Write_Data_Type; ...end Portable_Data_Io;Expanded Name Asis.Portable_Transfer.Portable_Data_Io
This package supports the reading and writing of portable data values and data streams.
Note: Package Portable_Data_Io provides many resources that are functionally equivalent to those in Sequential_Io (Ada83 LRM 14.2.2
, Ada95 LRM A.8.3). Only additional resources or resources with different definitions or parameters are shown in the declaration or described in "Parameters."Description
This package presents an interface that is functionally equivalent to generic package Sequential_Io. All resources that exist in Sequential_Io also exist in Portable_Data_Io.
Subprograms in Portable_Data_Io have been defined for reading and writing portable data values and data streams.
A generic is also provided that writes the data stream corresponding to a data type. The generic is functionality equivalent to your application converting the data type to a data stream and then writing the data stream.
Parameters
function Read (File : in File_Type) return Portable_Value;Operates on a file of mode In_File. Reads a portable data value from the specified file and returns the value. Note that this subprogram is implemented as a procedure in Sequential_Io.
If you read individual portable data values and construct a data stream from them, ensure that you use the correct number of values. Before any conversion, ASIS attempts to verify that the stream is valid and raises an exception if it is not.
function Read (File : in File_Type) return Portable_Data;Operates on a file of mode In_File. Reads a data stream from the specified file and returns the value. Note that this subprogram is implemented as a procedure in Sequential_Io.
procedure Write (File : in File_Type; Data_Stream : in Portable_Value);Operates on a file of mode Out_File. Writes the specified portable data value to the specified file.
procedure Write (File : in File_Type; Data_Stream : in Portable_Data);Operates on a file of mode Out_File. Writes the specified data stream to the specified file.
generic type Data_Type is private; with function Convert (Value : in Data_Type) return Portable_Data;package Write_Data_Type is procedure Write (File : in File_Type; Value : in Data_Type);end Write_Data_Type;When instantiated with a data type and a function that converts a value of the data type to a data stream, the Write procedure writes the data type as a data stream to the specified file.
Errors
The exceptions defined in the LRM package Io_Exceptions can be raised by the above subprograms as described in Ada83 LRM 14.4, Ada95 LRM A.13.
Cross-References
- LRM generic package Sequential_Io
Type Portable_Index
type Portable_Index is new Integer;Expanded Name Asis.Portable_Transfer.Portable_Index
Describes an index type for use in describing data streams.
Description
The implementation of Portable_Index is implementation-defined. All that is required of an implementation is that:
- The interfaces provided by this package, and by the nested package Operations, exist as originally defined
- The range of values be sufficient to encompass the data- stream representation for all possible runtime data values
Cross-References
Subtype Portable_Positive
subtype Portable_Positive is Portable_Index range 1 .. Portable_Index'Last;Expanded Name Asis.Portable_Transfer.Portable_Positive
Describes an index type for use in describing data streams.
Description
The implementation of Portable_Positive is implementation-defined. All that is required of an implementation is that:
- The interfaces provided by this package, and by the nested package Operations, exist as originally defined
- The range of values be sufficient to encompass the data- stream representation for all possible runtime data values
Cross-References
Generic Package Portable_Unconstrained-
_Record_Type
generic type Unconstrained_Record_Type is private;package Portable_Unconstrained_Record_Type is function Convert (Value : in Unconstrained_Record_Type) return Portable_Data;end Portable_Unconstrained_Record_Type;Expanded Name Asis.Portable_Transfer.Portable_Unconstrained-
_Record_TypeConverts an unconstrained record type to a data stream.
Description
Instantiation of this generic with an unconstrained array type will not generate a compile or runtime error. However, no guarantee is made that such instantiations will operate correctly.
To convert a scalar subtype or a constrained composite subtype, use generic package Portable_Constrained_Subtype. To convert an unconstrained array type, use generic package Portable-_Array_Type_1, Portable_Array_Type_2 or Portable_Array_Type_3.
Parameters
Specifies the type to be converted.
function ConvertConverts the specified value to a data stream.
Value : in Unconstrained_Record_TypeSpecifies the value to be converted.
return Portable_Data;Returns the data stream containing the converted value.
Errors
Ada predefined exceptions can be raised; in particular, Storage-_Error can be raised if insufficient space is available to declare or return the data stream represented by the specified value.
Cross-References
- generic package Portable_Array_Type_1
- generic package Portable_Array_Type_2
- generic package Portable_Array_Type_3
- generic package Portable_Constrained_Subtype
Type Portable_Value
type Portable_Value is range -(2 ** 31) .. 2 ** 31 - 1;Expanded Name Asis.Portable_Transfer.Portable_Value
Describes a portable data value.
Description
The implementation of Portable_Value is implementation-defined and it need not be a numeric type. All that is required of an implementation is that the interfaces provided by this package, and the nested package Operations, exist as originally defined.
Cross-References
Package Operations
package Operations is -- For Portable_Index ... -- contains all arithmetic and relational operators. -- For Portable_Value and Portable_Data function "&" (Left : Portable_Data; Right : Portable_Data) return Portable_Data; function "&" (Left : Portable_Data; Right : Portable_Value) return Portable_Data; function "&" (Left : Portable_Value; Right : Portable_Value) return Portable_Data; function "&" (Left : Portable_Value; Right : Portable_Data) return Portable_Data;end Operations;Expanded Name Asis.Portable_Transfer.Operations
Package Operations provides a simple way to obtain visibility to operators for types used in package Portable_Transfer. The package typically is referenced in a use clause by an application.
Cross-References
Rational Software Corporation
http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2001, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |