TOC PREV NEXT INDEX DOC LIST MASTER INDEX



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_Transfer

The 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_Transfer

This 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

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:

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

Data streams can be:

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:

Non-Array Type Conversion to Streams

Variables are converted to data streams by three classes of interfaces:

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

Expanded Name Asis.Portable_Transfer.Nil_Portable_Data

Defines an empty data stream.

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

Related type and subprogram:

Related concept:


Generic Package 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

Specifies the type of the array's elements.

Specifies the type of the array index.

Specifies the array type.

Converts the specified array value to a data stream.

Specifies the array value to be converted.

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

Related subprograms:

Related concept:


Generic Package 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

Specifies the type of the array's elements.

Specifies the type of the array index for the first dimension.

Specifies the type of the array index for the second dimension.

Specifies the array type.

Converts the specified array value to a data stream.

Specifies the array value to be converted.

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

Related subprograms:

Related concept:


Generic Package 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

Specifies the type of the array's elements.

Specifies the type of the array index for the first dimension.

Specifies the type of the array index for the second dimension.

Specifies the type of the array index for the third dimension.

Specifies the array type.

Converts the specified array value to a data stream.

Specifies the array value to be converted.

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

Related subprograms:

Related concept:


Generic Package 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

Specifies the type to be converted.

Converts the specified value to a data stream.

Specifies the value to be converted.

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

Related resources:

Related concept:


Type Portable_Data

Expanded Name Asis.Portable_Transfer.Portable_Data

Describes a data stream.

Description

Cross-References

Related types:

Related concept:


Package 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

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.

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.

Operates on a file of mode Out_File. Writes the specified portable data value to the specified file.

Operates on a file of mode Out_File. Writes the specified data stream to the specified file.

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

Related package:

Related concepts:


Type Portable_Index

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:

Cross-References

Related types:

Related concept:


Subtype Portable_Positive

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:

Cross-References

Related types:

Related concept:


Generic Package Portable_Unconstrained-
_Record_Type

Expanded Name Asis.Portable_Transfer.Portable_Unconstrained-
_Record_Type

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

Converts the specified value to a data stream.

Specifies the value to be converted.

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

Related resources:

Related concept:


Type Portable_Value

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

Related type:

Related concept:


Package 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

Related types:

Related concept:


Rational Software Corporation  http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2001, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS