TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Package Ids

Package Ids provides resources that support persistent and unique names for elements.These are called element-ids and are represented by the Id type.

An element-id identifies a particular element, from a particular physical compilation unit, from a particular library, at a particular time.

Package Ids provides subprograms that derive element-ids from elements and elements from element-ids. Resources also exist that allow element-ids to be written to and read from files.

Package Ids also supports the related types Id_Segment and Id_Segment_List. Element-ids and elements can be converted to Id_Segment_Lists, and the lists can later be converted back to element-ids and elements. A generic package is provided to support reading and writing of Id_Segment_Lists to files or user- defined structures.

For more information, click on a topic:


Resources in Package Ids

The resources (excluding types) in package Ids fall into several functional groups, as shown below.

To see detailed referenced information, click on the name of a resource:
Element-id properties and operations:
Create_Element Is_Equal Is_Nil
Create_Id Is_Identical
Reading and writing element-ids:
Id_Io

Element-id segment operations:
Create_Element Create_Id_Segments
Create_Id
Reading and writing element-id segment lists:
Id_Segment_Io


Key Concepts for Package Ids

The properties of element-ids and the resources provided for their manipulation are described in the following categories. To see more information, click on a topic:

Properties of Element-Ids

ASIS defines a number of properties for element-ids and permissible levels of conformance for each property. Rational ASIS provides maximal conformance for each property as described below:

Element-Id Properties and Operations

Element-ids are a private type. They can be assigned and used to construct assignable structures. Lists of element-ids can be created and maintained.

ASIS defines the Id_List type as an array of element-ids. A set of concatenation operators for element-ids and Id_Lists is also provided.

An element-id that has not yet been assigned a value tests as Is_Nil and is equal to (=) Asis.Nil_Id. If two element-ids represent the same physical element, they test as Is_Equal. For element-ids, the Is_Identical function is equivalent to Is_Equal.

You create the element-id corresponding to an element with the Create_Id function. Although the element-id encapsulates the physical compilation unit from which the element was obtained, the physical compilation unit is not a parameter to the function. Instead, the Create_Id function identifies the physical compilation unit with other ASIS functions.

The element-id is converted back to the corresponding element with the Create_Element function. In this case, you must specify a library. The returned element will be from the specified library if the appropriate physical compilation unit is part of the library.

Reading and Writing Element-Ids

Package Id_Io supports reading and writing of element-ids. It presents an interface that is functionally equivalent to generic package Direct_Io. All resources that exist in Direct_Io also exist in Id_Io.

Procedures in Id_Io have been defined for reading and writing of element-ids and elements. However, elements are not actually written to or read from the file. Instead, the procedures perform the conversions between elements and element-ids as a convenience.

When a request is made to write an element, the element is converted to an element-id and that element-id is written.

When a request is made to read an element, an element-id is read from the file and then that value is converted to the corresponding element. To perform the conversion, the Read procedure requires that a library be specified. The element-id read from the file is converted to the corresponding element from the specified library.

Element-ids can occupy more than a single index position in a file. Thus, the number of an element-id within a file might not correspond to its index position. Therefore, you should call the Set_Index procedure only with values obtained from the Index or Size functions. Setting the index to an arbitrary location and then reading or writing will probably produce erroneous results.

Element-Id Segment Operations

The amount of data, and the data format required to represent an element-id, is vendor-defined. Because of this, reading and writing of element-ids can take place only through the predefined package Id_Io. This in turn limits reading and writing to files accessible through that interface.

ASIS provides Id_Segments and generic package Id_Segment_Io to provide more general input and output capabilities than are possible with element-ids and package Id_Io.

An Id_Segment type is fixed in length and can be manipulated more freely than an element-id. For example, you can instantiate Direct_Io for an Id_Segment and have it behave as any other instantiation of Direct_Io.

Whether an element-id can be represented by a single Id_Segment is vendor-defined. Typically, an element-id is represented by multiple Id_Segments contained within an Id_Segment_List.

The Id_Segment_List corresponding to either an element-id or an element can be obtained by calling the overloaded Create-_Id_Segments function. Subsequently, you can call the Create_Id and Create_Element functions to obtain the element-id or element corresponding to the Id_Segment_List.

Reading and Writing Element-Id Segment Lists

ASIS provides generic package Id_Segment_Io to assist in the reading and writing of Id_Segments. As with package Id_Io, procedures are available to read and write element-ids and elements. Unlike Id_Io, the operations need not take place to or from a file, and, rather than element-ids, the Id_Segment_Lists corresponding to the elements and element-ids are read or written.

To instantiate the generic, you must provide a Positive_Count type, File_Type type, and one set of Read and Write procedures for both sequential and directed operation.

The parameters required by the generic, and the required operation of the formal procedures, are such that resources from an instantiation of Direct_Io for the Id_Segment type can be used to instantiate Id_Segment_Io.

Alternatively, you can provide your own implementation for each of the formal parameters. For example, you could use an array for File_Type, the index type for the array would be Positive_Count, and the read and write routines would deposit or return data from the appropriate position in the array.

When you call one of the Write procedures to write an element-id or element, the generic first converts the value to an Id_Segment_List. Then the appropriate (sequential or directed) actual- parameter Write procedure is called for each element in the list. In the case of a directed Write, the To parameter is increased incrementally by the generic after each element is written.

When you call one of the Read procedures to read an element-id or element, the generic first reads an Id_Segment_List by calling the appropriate (sequential or directed) actual-parameter Read procedure. In the case of a directed Read, the From parameter is increased incrementally by the generic after each element is read. Then the list is converted to the associated element-id or element, utilizing the provided library. This value is then returned by the generic.


Function Create_Element

Expanded Name Asis.Ids.Create_Element

Returns the element corresponding to the specified element-id or list from the specified library.

Description

The element-id or list must correspond to an element available from a physical compilation unit in the specified library.

Parameters

Specifies the element-id for which the corresponding element is desired.

Specifies the list for which the corresponding element is desired.

Specifies the library containing the desired element.

Returns the element corresponding to the specified element-id or list.

Erros

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

Asis_Inappropriate_Element is raised and Environment.Status is set to Value_Error if the element corresponding to the specified element-id is not available in the specified library. The Environment.Diagnosis value will attempt to indicate the reason for the failure. Failures typically are caused by missing or obsolete library units.

Asis_Inappropriate_Element is raised and Environment.Status is set to Value_Error if the specified list cannot be converted to an element-id. The list may be too long or too short, or it may contain invalid values.

Examples

Cross-References

Related subprograms:

Related concepts:


Function Create_Id

Expanded Name Asis.Ids.Create_Id

Returns the element-id corresponding to the specified element or list.

Description

If Asis.Nil_Element is specified, Asis.Nil_Id is returned.

The returned element-id is based on the element and the enclosing physical compilation unit of the element. A conversion from an element-id back to an element requires that the physical compilation unit be available.

Two element-ids are Is_Equal only if their elements are Elements.Is_Equal.

The relational operators equals (=), less than (<), and greater than (>) are defined for element-ids. These operators are available in the nested package Operations.

Parameters

Specifies the element for which the corresponding element-id is desired.

Specifies the list for which the corresponding element-id is desired.

Returns the element-id corresponding to the specified element or list.

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.

Asis_Inappropriate_Element is raised and Environment.Status is set to Value_Error if the element corresponding to the specified element-id is not available in the specified library. The Environment.Diagnosis value will attempt to indicate the reason for the failure. Failures typically are caused by missing or obsolete library units.

Asis_Inappropriate_Element is raised and Environment.Status is set to Value_Error if the specified list cannot be converted to an element-id. The list may be too long or too short, or it may contain invalid values.

Examples

Cross-References

Related subprograms:

Related concepts:


Function Create_Id_Segments

Expanded Name Asis.Ids.Create_Id_Segments

Returns the segment list corresponding to the specified element or element-id.

Description

The length of an Id_Segment_List for an element or an element-id is vendor-defined. You should not assume that all Id_Segment_Lists will be identical in size. Specifying Asis.Nil_Element or Asis.Nil_Id may not result in an Id_Segment_List with a 'Length attribute of 0.

The meaning of the equality operator (=) between Id_Segment_Lists is implementation-defined and not portable. You should not compare Id_Segment_Lists.

Parameters

Specifies the element for which the corresponding segment list is desired.

Specifies the element-id for which the corresponding segment list is desired.

Returns the segment list corresponding to the specified element-id or element.

Errors

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.

Cross-References

Related subprograms:

Related concepts:


Function Debug_Image

Expanded Name Asis.Ids.Debug_Image

Returns implementation-defined debug information for the specified element-id or segment.

Description

The return value uses Text.Image_Delimiter to separate the lines of multiline results. The return value does not end with Text.Image_Delimiter.

The content and format of the returned information is not currently available.

Parameters

Specifies the element-id for which the debug information is desried.

Specifies the segment for which the debug information is desired.

Returns implementation-defined debug information for the specified element-id or segment.

Errors

None.

Examples

Cross-References

Related subprograms:

Related concepts:


Function Is_Equal

Expanded Name Asis.Ids.Is_Equal

Returns a Boolean value indicating whether the specified element-ids represent the same element from the same physical compilation unit.

Description

Returns True if:

Otherwise, this function returns False.

If the parameters were converted to elements using the same library, the elements would test as Elements.Is_Equal.

Parameters

Specifies the first element-id.

Specifies the second element-id.

Returns True if the specified element-ids represent the same element from the same physical compilation unit.

Errors

None.

Examples

Cross-References

Related subprograms:

Related concept:


Function Rename Is_Identical

Expanded Name Asis.Ids.Is_Identical

Returns a Boolean value indicating whether the specified element-ids represent the same element from the same physical compilation unit.

Description

This function performs the same operation as Is_Equal. The name is provided as a convenience.

If the parameters were converted to elements using the same library, the elements would test as Elements.Is_Equal.

Parameters

Specifies the first element-id.

Specifies the second element-id.

Returns True if the specified element-ids represent the same element from the same physical compilation unit.

Errors

None.

xamples

Cross-References

Related subprograms:

Related concept:


Function Is_Nil

Expanded Name Asis.Ids.Is_Nil

Returns a Boolean value indicating whether the specified element-id is Asis.Nil_Id or the specified element-id list has a 'Length attribute value of 0.

Description

An element-id is nil if its value is Asis.Nil_Id. An uninitialized element-id has a value of Asis.Nil_Id.

An element-id list is nil if the value of its 'Length attribute is 0.

Parameters

Specifies the element-id to query.

Specifies the element-id list to query.

Returns True if the specified element-id is Asis.Nil_Id or the specified element-id list has a 'Length attribute of 0.

Errors

None.

Examples

Cross-References

Related subprograms:

Related concept:


Package Id_Io

Expanded Name Asis.Ids.Id_Io

This package supports the reading and writing of element-ids.

Description

This package presents an interface that is functionally equivalent to generic package Direct_Io. All resources that exist in Direct_Io also exist in Id_Io.

Procedures in Id_Io have been defined for reading and writing element-ids and elements. However, elements are not actually written to or read from the file. Instead, the procedures perform the conversions between elements and element-ids as a convenience.

When a request is made to write an element, the element is converted to an element-id and that element-id is written.

When a request is made to read an element, an element-id is read and then the value is converted to the corresponding element. To perform the conversion, the Read procedure requires that a library be specified. The element-id read from the file is converted to the corresponding element from the specified library.

Element-ids can occupy more than a single index position in a file. Thus, the number of an element-id within a file might not correspond to its index position. Therefore, you should call the Set_Index procedure only with values obtained from the Index or Size functions. Setting the index to an arbitrary location and then reading or writing will probably produce erroneous results.

The 'Last of Direct_Io.Count is typically the maximum number of objects of a particular type that can be written to an external file. The 'Last of Id_Io.Count also gives the maximum number of element-ids that can be written. However, because the 'Size of element-ids can differ, the typical number may be somewhat less.

In the first form, the procedure sets the index of the given file to the index value given by the From parameter. Then it returns, in the Item parameter, the value of the element-id in the given file at the current index of the file; finally, it increases the current index by the file storage size of the element-id.

In the first form, the procedure sets the index of the given file to the index value given by the From parameter. Then it returns, in the Item parameter, the value of the element that corresponds to the element-id in the given file at the current index of the file; finally, it increases the current index by the file storage size of the element-id. The element-id read from the file must correspond to an element in a compilation unit in the specified library.

In the first form, the procedure sets the index of the given file to the index value given by the To parameter. Then it gives the value of the Item parameter to the element in the given file at the current index of the file; finally, increases the current index by the file storage size of the element-id.

In the first form, the procedure sets the index of the given file to the index value given by the To parameter. Then it converts the Item parameter to its corresponding element-id and gives this value to the element in the given file at the current index of the file; finally, it increases the current index by the file storage size of the element-id.

Sets the current index of the given file to the given index value. You should not set the index to any value other than those obtained from the Index or Size function.

Errors

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

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.

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

Examples

Cross-References

Related package:

Related concepts:


Generic Package Id_Segment_Io

Expanded Name Asis.Ids.Id_Segment_Io

This generic provides support for reading and writing element-ids and elements in terms of their element-id segment values.

Description

This generic is provided as a convenience. The functionality provided can be duplicated in other ways.

To instantiate the generic, you must provide two formal types and four formal procedures:

If you call the sequential read and write procedures, Id_Segment_Io calls only your actual sequential read and write procedures. If you call the directed read and write procedures, Id_Segment_Io initially calls your directed read and write proce-dures. However, ASIS does not define whether subsequent calls are made to the sequential or directed procedures.

If you are creating a portable ASIS application and need to perform directed reads and write, each of the four procedures must be implemented. If you perform only sequential reads and writes, you need not implement the directed procedures. None of the formal parameters have default values, however, so at least a dummy implementation must be provided to instantiate the generic.

The parameters required by the generic, and the required operation of the formal procedures, are such that resources from an instantiation of Direct_Io for the Id_Segment type can be used to instantiate this generic package.

The Write procedures convert the specified element-id or element to an Id_Segment_List and then write the list, one Id_Segment at a time, using the actual procedures provided in the instantiation. Conversely, the Read procedures read an Id_Segment_List, one Id_Segment at a time, using the actual procedures provided in the instantiation and then convert the list to an element-id or element.

Parameters

Specifies a user-defined integer type that typically represents an index into type File_Type.

Specifies a user-defined type that represents the file that the Id_Segment values are to be written to or read from.

Specifies the procedure called by the generic when a directed read of an Id_Segment is required.

The actual procedure should set the current index of the specified file to the value of the From parameter. Then it returns, in the Item parameter, the Id_Segment value at the current index. The current index should then be changed by an amount appropriate for the implementation.

Specifies the procedure called by the generic when a directed write of an Id_Segment is required.

The actual procedure should set the current index of the specified file to the value of the To parameter. Then it gives the value of the Item parameter to the Id_Segment whose position in the file is at current index. The current index then should be changed by an amount appropriate for the implementation.

Specifies the procedure called by the generic when a sequential read of an Id_Segment is required.

The actual procedure should return, in the Item parameter, the Id_Segment value at the current index of the specified file. The current index then should be changed by an amount appropriate for the implementation.

Specifies the procedure called by the generic when a sequential write of an Id_Segment is required.

The actual procedure should give the value of the Item parameter to the Id_Segment whose position in the file is at current index. The current index then should be changed by an amount appropriate for the implementation.

In the first form, the procedure calls the actual procedure corresponding to the formal sequential Read procedure so as to read a complete Id_Segment_List. In the second form, the actual procedure corresponding to the formal directed Read procedure is called and, for each call after the first, the value of the From parameter is increased by 1.

Once the entire Id_Segment_List is read, the value is converted to an element-id that is returned in the Item parameter.

In the first form, the procedure calls the actual procedure corresponding to the formal sequential Read procedure so as to read a complete Id_Segment_List. In the second form, the actual procedure corresponding to the formal directed Read procedure is called and, for each call after the first, the value of the From parameter is increased by 1.

Once the entire Id_Segment_List is read, the value is converted to an element in the specified library. The element is returned in the Item parameter.

The Item parameter is first converted to an Id_Segment_List.

Then, in the first form, the procedure calls the actual procedure corresponding to the formal sequential Write procedure so as to write each element of the Id_Segment_List. In the second form, the actual procedure corresponding to the formal directed Write procedure is called and, for each call after the first, the value of the To parameter is increased by 1.

The Item parameter is first converted to an Id_Segment_List.

Then, in the first form, the procedure calls the actual procedure corresponding to the formal sequential Write procedure so as to write each element of the Id_Segment_List. In the second form, the actual procedure corresponding to the formal directed Write procedure is called and, for each call after the first, the value of the To parameter is increased by 1.

Errors

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

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.

Examples

Cross-References

Related package:

Related concepts:


Package Operations

Expanded Name Asis.Element-ids.Operations

Package Operations provides a simple way to obtain visibility to operators for types used in package Ids. The package typically is referenced in a use clause by an application.

Parameters

Returns a hash value for the specified element-id. This value can be used in symbol tables and related structures where quick access to element-ids is required.

Cross-References

Related subprograms:

Related concepts:

1 Package Id_Io provides resources that are functionally equivalent to those in Direct_Io (Ada83 LRM 14.2.4, Ada95 LRM 14.2.4). Only those resources with different definitions or parameters are shown and described.


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