TOC PREV NEXT INDEX DOC LIST MASTER INDEX




Constant Nil_Array_Component

Expanded Name Asis.Data_Decomposition.Nil_Array_Component

Defines a value that does not reference an array component.

Description

A newly created variable of the type Array_Component has the value Nil_Array_Component and tests as Is_Nil.

Cross-References

Related subprogram and type:

Related concept:


Constant Nil_Array_Component_Iterator

Expanded Name Asis.Data_Decomposition.Nil_Array_Component_Iterator

Defines an iterator that does not reference any array component.

Description

A newly created variable of the type Array_Component_Iterator has the value Nil_Array_Component_Iterator and tests as Done.

Cross-References

Related subprogram and type:

Related concept:


Constant Nil_Record_Component

Expanded Name Asis.Data_Decomposition.Nil_Record_Component

Defines a value that does not reference a record component.

Description

A newly created variable of the type Record_Component has the value Nil_Record_Component and tests as Is_Nil.

Cross-References

Related subprogram and type:

Related concept:


Generic Function Portable_Constrained_Subtype

Expanded Name Asis.Data_Decomposition.Portable_Constrained_Subtype

Returns a value of the specified subtype from the specified data stream.

Description

The generic can be used only with a scalar or a fully constrained record subtype. If an unconstrained subtype is specified, a compilation error results. If a fully constrained array is specified, no compilation error results but function might not work as intended.

Instantiations with constrained array subtypes will not correctly convert array values created by the Portable_Array_Type_1, Portable_Array_Type_2, or Portable_Array_Type_3 interfaces.

Parameters

Specifies the data stream to be converted.

Returns a value of the specified subtype from the specified data stream.

Errors

Constraint_Error can be raised if the subtype is scalar and the converted value is not in the subtype's range.

Examples

Cross-References

Related subprograms and packages:

Related concept:


Function Position

Expanded Name Asis.Data_Decomposition.Position

For the first form, returns the offset, from the start of the first storage unit occupied by the enclosing composite type, of the first of the storage units occupied by the specified component.

For the last three forms, returns the offset, from the start of the first storage unit occupied by the enclosing composite type, of the first of the storage units occupied by the specified element.

Description

The offset is measured in storage units.

This function is meant to reflect the value of the 'Position predefined language attribute (LRM Annex A).

Parameters

Specifies the component to query. All non-nil component values are appropriate.

Specifies the linear index value for the array component that is being queried. The value must be in the range 1 .. Array_Length (Component).

Specifies the dimensional index values for the array component that is being queried. There must be one value for each dimension of the array type, and the value must be in the range 1 .. Array_Length (Component, N), where N represents the dimension of interest.

Specifies the array component to query.

Returns the offset, from the start of the first storage unit occupied by the enclosing composite type, of the first of the storage units occupied by the specified component.

Errors

Asis_Inappropriate_Element is raised and Environment.Status is set to Value_Error if a parameter references a library variable that is no longer open or a parameter is specified that is not appropriate for the query.

Asis_Inappropriate_Element is raised and Environment.Status is set to Data_Error if any index is not in the expected range or if Done (Iterator) is True.

Examples

Cross-References

Related subprograms and type:

Related concepts:


Type Record_Component

Expanded Name Asis.Data_Decomposition.Record_Component

Describes one discriminant or component of a record type.

Description

A record type definition contains 0 or more discriminants and components. In ASIS, such types are represented by an element with an Element_Kinds of A_Record_Type_Definition or A_Derived_Type_Definition whose parent type is a record type. For purposes of data decomposition, the Record_Component type (referred to as a record component) describes either one discriminant or one component of a record type definition.

Record-Component Properties

Discriminants must be scalar, but the other components can represent scalars, records, or arrays. You can determine what kind of data a particular record component represents with the Is_Array and Is_Record functions.

The equality operator (=) is not meaningful between record- component values and should not be used unless one component is equal to Nil_Record_Component. Uninitialized record- component variables are equal to Nil_Record_Component. The Is_Equal and Is_Identical functions should be used to compare component values.

Record components become invalid and must not be used after the library containing the type definition they were derived from is closed; an exception is raised if this occurs.

Obtaining a Record's Components

The Discriminant_Components function can be used to obtain a list containing all discriminants of a record; the Record_Com-ponents function can be used to obtain a list containing all discriminants and components of a record. The components can themselves be composite, representing records or arrays.

Two methods are available to decompose composite array components and obtain the constituent record components or array component:

Both methods return the same values. See "Obtaining Components and Nested Components" for more information.

Using Record Components to Obtain Data

Each record component contains the information necessary to:

Recall that a data stream represents the encoding of a variable. If the variable is a record, the encoding includes the discriminants and all component values. By specifying a data stream and a record component to the Component_Data_Stream function, you can extract the stream that represents the component.

If the component is a composite, the resulting data stream represents all values. Streams that represent composite values can be decomposed repeatedly, until a component is no longer a composite.

Cross-References

Related resources:

Related concepts:


Type Record_Component_List

Expanded Name Asis.Data_Decomposition.Record_Component_List

Defines a list of record components.

Description

A record component list is nil if the value of its 'Length attribute
is 0.

Cross-References

Related subprograms and type:

Related concepts:


Function Record_Components

Expanded Name Asis.Data_Decomposition.Record_Components

Returns a list containing the discriminants and components of the specified array component, record component, or record type definition.

Description

The returned list includes implementation-defined components (Ada83 LRM 13.4(8), Ada95 LRM 13.5.1). Refer to the Appendix F for your compilation system to determine whether your compiler generates implementation-defined components.

The returned components can be used with a data stream representing a value of the specified component or type.

All returned values are valid parameters for all functions.

If a simple static type is specified, it always returns the same component list (Is_Equal components) regardless of the data stream. The layout of a simple static type does not change with changes in discriminant values because there are no variant parts in the definition.

If a simple dynamic type is specified, it can return different component lists (non-Is_Equal components). The layout of a dynamic data type changes with changes in discriminant values because of the variant parts in the definition.

If a data stream is specified, it can represent an actual stream or an artificial stream as constructed with Construct_Artificial-_Data_Stream. Only the discriminant portion of the data stream is checked for validity, and only some discriminant fields might need to be checked, depending on the complexity of the record type. It is not necessary to provide values for nondiscriminant fields, but it is safer to do so.

If a data stream is specified, the returned list contains components that describe the locations of the record's discriminants and all components of the appropriate variant parts. The con-tents of the list are determined by the discriminant values in the data stream, and some components might not exist in the list (because they are not in an active variant part).

Parameters

Specifies the component to query. All components with a record subtype (Is_Record = True) are appropriate.

For the first three forms of the function, the component must be A_Simple_Static_Model. For the last three forms of the function, the component must be A_Simple_Static_Model or A_Simple-_Dynamic_Model.

Specifies the record type definition to be queried. The type definition must be of the following kinds:
Element_Kinds
Type_Definition_Kinds
A_Type_Definition
A_Derived_Type_Definition1
A_Record_Type_Definition
1 Whose parent type is a record type.

For the first form of the function, the type definition must be A_Simple_Static_Model. For the second form of the function, it must be A_Simple_Static_Model or A_Simple_Dynamic_Model.

Specifies the data stream containing at least discriminant values.

Returns a list containing the discriminants and components of the specified or referenced record type.

Errors

Asis_Inappropriate_Element is raised and Environment.Status is set to Value_Error if a parameter references a library variable that is no longer open or a parameter is specified that is not appropriate for the query.

Examples

Cross-References

Related subprograms:

Related concept:


Procedure Reset

Expanded Name Asis.Data_Decomposition.Reset

Resets the iterator so that it references the first array component.

Description

Use the Next procedure to iterate to the next array component.

Parameters

Specifies the iterator to reset.

Errors

Asis_Inappropriate_Element is raised and Environment.Status is set to Value_Error if a parameter references a library variable that is no longer open or a parameter is specified that is not appropriate for the query.

Examples

Cross-References

Related subprograms:

Related concept:


Function Size

Expanded Name Asis.Data_Decomposition.Size

For the first three forms, returns the 'Size attribute value for the specified component or type definition.

For the fourth form, returns the 'Size attribute value for the specified type definition with the discriminants as defined in the specified data stream.

Description

Returns the minimum number of bits required to hold a simple static type, the number of bits allocated to hold a record field, or the number of bits allocated to hold each array component.

The size is measured in bits.

If a component is specified, the returned value represents the actual number of bits allocated to the component. The size can be greater than the number of bits normally occupied by values of this type and is typically the result of a representation specification. If this is the case, the value can be preceded, followed, or surrounded by pad bits to fully occupy the space allotted.

If a data stream is specified, it can represent an actual stream or an artificial stream as constructed with Construct_Artificial-_Data_Stream. Only the discriminant portion of the data stream is checked for validity, and only some discriminant fields might need to be checked, depending on the complexity of the record type. It is not necessary to provide values for nondiscriminant fields, but it is safer to do so. The returned value is the minimum number of bits required to hold any possible value of the given fully constrained subtype.

Parameters

Specifies the component to query. All non-nil component values are appropriate and must be of the following type model kind:
Type_Model_Kinds
A_Simple_Static_Model

Specifies the type definition to be queried. The type definition must be of the following kind:
Element_Kinds

A_Type_Definition

For the first form of the function, the type definition must be A_Simple_Static_Model. For the second form of the function, it must be A_Simple_Static_Model or A_Simple_Dynamic_Model.

Specifies the data stream containing at least discriminant values.

Returns the value of the 'Size attribute for the specified
parameters.

Errors

Asis_Inappropriate_Element is raised and Environment.Status is set to Value_Error if a parameter references a library variable that is no longer open or a parameter is specified that is not appropriate for the query.

Examples

Cross-References

Related subprograms:

Related concept:


Function Type_Model_Kind

Expanded Name Asis.Data_Decomposition.Type_Model_Kind

Returns the type model kind for the specified component or type definition.

Description

See the Type_Model_Kinds type for a summary of the models and "Type-Definition Model Kinds" for a detailed description of the type definitions that are represented by each model.

Parameters

Specifies the component to be queried. All component values are appropriate.

Specifies the type definition to be queried. The type definition must be of the following kind:
Element_Kinds

A_Type_Definition

Returns the type model kind for all appropriate parameters, as described above, or Not_A_Type_Model for any unexpected parameters.

Errors

Asis_Inappropriate_Library is raised and Environment.Status is set to Value_Error if a parameter references a library that is no longer open.

Examples

Cross-References

Related type:

Related concept:


Type Type_Model_Kinds

Expanded Name Asis.Data_Decomposition.Type_Model_Kinds

Defines the kinds of type-definition models recognized by ASIS.

Description

The type-definition model kinds are not intrinsic to Ada. They are defined by ASIS to categorize and simplify reference to the kinds of type definitions that packages Data_Decomposition and Portable_Transfer can process.

The type-definition model kinds range from simple and static to complex and dynamic, based on whether the definition includes discriminants and variant parts or not and how the values for those discriminants are specified.

See "Type-Definition Model Kinds" for a detailed description of the type definitions that are represented by each model.

Parameters

Indicates that the component or type contains no variants and has a single fixed 'Size attribute value that and all components and attributes are themselves static and/or fully constrained.

Indicates that the component or type contains one or more components or attributes whose size, position, or value depends on the value of one or more discriminants computed during execution.

The size, positions, or number of components cannot be determined without reference to actual discriminant values.

Indicates that the component or type contains one or more components or attributes whose size, position, or value depends on one or more nonstatic values that are not stored within instances of the type.

The size, positions, or number of components cannot be determined without reference to these nonstatic values, whose runtime values are not known to the ASIS library and cannot be recorded automatically by the Portable_Transfer generics.

Indicates that the specified array or record component is nil or that the specified element is not a type definition.

Cross-References

Related subprogram:

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