Skip to main content

Adding Storage Definitions to a Class

The physical storage used by a persistent or serial class is specified by means of a storage definition. You can use Studio to view and edit such storage definitions.

Note:

Storage definitions are a fairly advanced feature of InterSystems IRIS® objects. In most cases, you do not need to work with storage definitions; the InterSystems IRIS class compiler automatically creates and manages storage definitions for persistent objects.

If you use storage definitions, you typically work with them in the following cases:

  • You need detailed control over the storage used by a persistent object, perhaps for performance tuning.

  • You are mapping an object definition on top of a preexisting data structure.

A class can have any number of storage definitions, though only one can be used at one time. A new class does not have a storage definition until either you save and compile the class or you explicitly add one to the class. You can add a new storage definition to a class using Class > Add > Storage.

Note:

Compiling a class automatically generates its storage definition. Only persistent and serial classes have storage definitions.

Within Studio, you can view and edit the storage definitions for a class in two different ways:

  • Visually using the Storage Inspector in the Class Inspector window: select Storage in the Class Inspector and select the desired storage definition.

  • Textually using the Class Editor; the storage definition is in the body of the class definition.

These techniques are described in the following sections.

Adding Storage Definitions to a Class

You can add a new storage definition to a class definition in two ways:

  • Adding a storage definition to the class definition using the Class Editor and Class > Add > Storage.

  • Using the New Storage wizard.

Using the New Storage Wizard

You can use the New Storage wizard to add a new storage definition to a class definition. You can start the New Storage wizard using Class > Add > Storage. Alternatively, right-click in the Class Inspector and select Add > New Storage . You can also click the New Storage button hierarchical diagram from the toolbar.

The New Storage wizard prompts you for information. Select Finish at any time (in this case, default values are provided for any information you have not specified).

Name, Type, Description Page

The New Storage wizard prompts you for the following information (you can later modify any of these values):

Storage Name

(required) Name of the new storage definition. This name must be a valid class member name and must not conflict with the name of a previously defined storage definition.

See Rules and Guidelines for Identifiers.

Storage Type

(required) Type of storage used by this storage definition. The type specifies which storage class is responsible for implementing the storage interface for this class. The choices are:

  • Storage — this storage definition is based on the %Storage.Persistent class. This is the default storage type used for new persistent classes.

  • SQL Storage — this storage definition is based on the %Storage.SQL class. This storage type uses SQL statements to perform storage operations. This storage type is used for mapping objects to existing data structures or to communicate with remote RDBMS via the InterSystems SQL Gateway.

  • Custom Storage — this storage definition is based on a user-defined storage class.

Description

(optional) Description of the new storage definition.

A description may include HTML formatting tags. See Creating Class Documentation in Defining and Using Classes.

Global Characteristics of a %Storage.Persistent Definition Page

For a %Storage.Persistent storage definition, the New Storage wizard lets you specify some characteristics of the globals (persistent multidimensional arrays) used to store the data and indexes for the persistent class. These characteristics include:

DataLocation

Name of the global as well as any leading subscripts used to store instances of the persistent class. For example, to specify that data should be stored in the global ^data, enter ^data in this field. To specify that data should be stored in the global subnode ^data("main"), enter ^data("main").

IndexLocation

Name of the global as well as any leading subscripts used to store index entries for the persistent class. By default, indexes are stored in the Index Reference global with an additional subscript based on the Index name. You can override this on an index-by-index basis.

IdLocation

Name of the global as well as any leading subscripts used to contain the default object ID counter. The object ID counter is used to maintain the ID number of the next object instance of this type.

Using the Class Inspector with Storage Definitions

You can use the Class Inspector to visually view and edit a class' storage definition. The Class Inspector displays a list of storage definitions in the same way that it displays methods or properties.

To view an existing storage definition in the Class Inspector:

  1. Select the Class Inspector.

  2. Select Storage in the Inspector's Member list pull-down.

  3. Double-click a storage definition.

At this point, the Class Inspector displays storage keywords along with their values.

Data Nodes

Represents the set of data mappings used by the %Storage.Persistent storage class. The Data Nodes editor, which you can invoke by double-clicking on the Data Nodes keyword, allows you to view and edit the set of data node specifications for the storage definition: that is, you can directly specify how your class' properties are stored in global nodes.

SQL Storage Map

Represents the set of data mappings used by the %Storage.SQL storage class. The SQL Storage Map editor, which you can invoke by double-clicking the SQL Storage Map keyword, allows you to view and edit the set of mappings used to map object properties to existing data structures.

Using the Class Editor with Storage Definitions

You can use the Class Editor to view and edit a class' storage definition. You can toggle the display of a class storage definitions using View > Expand Code.

A storage definition is displayed as an in-line XML island in the body of the class definition using the same XML elements that are used in the external, XML-representation of a class definition.

For example, suppose you have a simple persistent MyApp.Person class:

/// A simple persistent class
Class User.Person Extends %Persistent 
{
Property Name As %String;
Property City As %String;
}

After compiling this class (to ensure that the class compiler has created a storage definition for it), display its storage definition using the View > Expand Code (or select plus icon next to the top line of the block). This results in following display in the Class Editor:

/// A simple persistent class

Class User.Person Extends %Persistent
{

Property Name As %String;

Property City As %String;

Storage Default
{
<Data name="PersonDefaultData">
    <Value name="1">
        <Value>%%CLASSNAME</Value>
    </Value>
    <Value name="2">
        <Value>Name</Value>
    </Value>
    <Value name="3">
        <Value>City</Value>
    </Value>
</Data>
<DataLocation>^User.PersonD</DataLocation>
<DefaultData>PersonDefaultData</DefaultData>
<IdLocation>^User.PersonD</IdLocation>
<IndexLocation>^User.PersonI</IndexLocation>
<StreamLocation>^User.PersonS</StreamLocation>
<Type>%Storage.Persistent</Type>
}

}

The XML storage definition includes all the defined storage keywords and their corresponding values represented as XML elements.

You can directly edit this definition in the Class Editor as you would any other part of the class definition. If you enter invalid XML syntax, the editor colors it as an error.

The storage definition can be useful in cases where you need to do simple or repetitive modifications.

For example, suppose you want to change the name of a property City to HomeCity, while preserving the physical storage layout (that is, you want the new property name to access the values stored with the old name). You can do this using the Class Editor as follows:

  1. Load the class definition into a Studio Class Editor window and display its storage.

  2. Use the Editor's Replace command to replace all occurrences of the property City with HomeCity. You must be careful to only change those occurrences of City that represent the property name (such as in the property definition, method code, descriptions, and in the body of the storage definition); do not replace the values of any class definition keywords.

  3. Save and recompile the class definition.

FeedbackOpens in a new tab