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 Caché objects. In most cases, you do not need to work with storage definitions; the Caché 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 first a) save and compile the class, or, b) you explicitly add one. 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 definition(s) 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 window; 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 selecting Add > Storage or select the New Storage icon, generated description: newstorageicon, 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.

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:

  • Caché Storage—this storage definition is based on the %CacheStorageOpens in a new tab class. This is the default storage type used for new persistent classes.

  • Caché SQL Storage—this storage definition is based on the %CacheSQLStorageOpens in a new tab 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 talk to remote RDBMS via the Caché 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 can include HTML formatting tags. For more details, see “Using HTML Markup in Class Documentation” in the chapter “Defining and Compiling Classes” in Using Caché Objects.

Global Characteristics of a %CacheStorage Definition Page

For a %CacheStorageOpens in a new tab storage definition, the New Storage wizard lets you specify some characteristics of the globals (persistent multidimensional arrays) used to store the data and indices 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, indices 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 %CacheStorageOpens in a new tab 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 %CacheSQLStorageOpens in a new tab 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 definition(s) 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 MyApp.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 window:

/// A simple persistent class
Class MyApp.Person Extends %Persistent 
{

Property Name As %String;
Property City As %String;

<Storage name="Default">
    <Data name="PersonDefaultData">
        <Value name="1">
            <Value>City</Value>
        </Value>
        <Value name="2">
            <Value>Name</Value>
        </Value>
    </Data>
    <DataLocation>^MyApp.PersonD</DataLocation>
    <DefaultData>PersonDefaultData</DefaultData>
    <IdLocation>^MyApp.PersonD</IdLocation>
    <IndexLocation>^MyApp.PersonI</IndexLocation>
    <Type>%Library.CacheStorage</Type>
</Storage>
}

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