Objectivity/DB Administration : Administration Tasks : Specifying File Storage
4 
Specifying File Storage
This chapter shows you how to specify storage locations for files of persistent data created by an application.
This chapter describes:
General information about file storage for persistent data.
How to register and manage the storage locations and zones to be used for a federated database’s data files.
How to set the selection policy for choosing from among the registered storage locations.
How to distribute files according to the application that creates them.
How to set storage-acquisition policies for responding when storage locations are unavailable.
Understanding File Storage for Persistent Data
Every file that contains persistent data is stored in a storage location, which consists of a host computer and the path to a particular directory or folder on that computer. The format is host::path—for example:
myhost::C:\myData\placementTutorial\storageTasks
myhost::\myData\placementTutorial\storageTasks
Windows drive
Windows UNC name
myhost::/usr/myData/placementTutorial/storageTasks
Linux
File Storage and the Placement System
The creation and placement of new database files is managed by a federated database’s placement system. The specific mechanism that is responsible for selecting a new database’s storage location is a database placer.
Database placers are defined as part of the federated database’s placement model. The model’s built-in default database placer selects storage locations for database files regardless of the type of data they contain. You can optionally override the default database placer by defining specialized database placers that place data files according to the type of data they contain.
Note:The tasks in this chapter apply to the default database placer. For more specialized placement, such as distributing files based on their content, see the topic on specifying file storage in Getting Started With Managed Object Placement.
Main Storage Group
Every federated database maintains a main storage group (MSG), which is a set of storage locations that are available for placing new files. Whereas the federated database’s global catalog lists the storage locations of database files that have already been created, the MSG is, in effect, an inventory of all the potential locations in which the federation’s database files could be created—by any application and for any kind of data.
When a federated database is created, its MSG is empty. You use an administration tool to register any number of storage locations by adding those locations to the MSG. You typically register multiple storage locations to support redundancy (extra locations when preferred locations fill up or are otherwise unavailable) and file distribution (to achieve load balancing or proximity goals).
You can register a new storage location at any time, at which point it becomes available for subsequently created database files. If, for any reason, you want to prevent further use of a registered storage location, you can use an administration tool to remove it from the MSG.
Note:If you never register any storage locations in the MSG, the default behavior is to place new files in the same directory as the federated database’s system database file. You can change this behavior; see If the MSG is Empty.
Selection From the Main Storage Group
Whenever a new database is created to accommodate a new container, the operation creating the database uses a database placer to obtain a storage location for the new database’s file. The database placer does so by selecting a particular storage location from among those registered in the MSG.
Unless otherwise configured, the database placer chooses the first storage location listed in the MSG, and continues to use that same location for each subsequent database to be placed. If that location becomes full or is otherwise unavailable, the database placer selects the next location listed in the MSG, and so on, until all registered locations have been considered. Finally, the directory containing the federated database’s system database file is used.
You can configure the selection process to support:
Distribution of new files according to application-specific location preferences. See Application-Specific Location Preferences.
Alternative policies for selecting locations from the MSG, such as round-robin and random. See Selection Policies.
Distribution of files according to the data they contain. See the topic on distributing files according to their content in Getting Started With Managed Object Placement.
You can also configure how the selection process is to respond if it encounters one or more inaccessible storage locations; see How Unavailable Storage Locations Are Handled.
Application-Specific Location Preferences
Applications are more efficient when they access and write data to nearby storage locations. Consequently, if all of the applications accessing a particular federated database are running on hosts that are near each other on the network, those applications can usually share the same set of storage locations for the data they create.
If, however, you plan to run multiple applications on widely separated network nodes, you typically need to arrange for each application to use different storage locations for its new database files. You do this by setting up application-specific location preferences, which enable a database placer to select different storage locations for different applications. For specific steps, see Specifying Application-Specific Location Preferences.
Example Figure 4‑1 shows two geographically remote applications that will create data in a single federated database whose database files are to be distributed over four locations. All four locations in the example must be registered in the MSG so that they are available for use.
Figure 4‑1 Location Preferences for Distributed Objectivity/DB Applications
You can set up location preferences so that:
Any files created by App1 will be stored in just the three locations closest to it (LocationA, LocationC, and LocationD).
Any files created by App2 will be stored in just the two locations closest to it (LocationB and LocationC).
 
Besides restricting the selection of storage locations to an application-specific subset, location preferences also enable you prioritize, or rank, the locations within that subset. For example, you could set up App1’s location preferences so its data is stored in LocationC and LocationD first, before any of its data is stored in LocationA.
Although location preferences typically reflect geographic relevance, you can use them for any reason. For example, App1 might need storage on very fast servers, while App2 should use slower but larger storage devices.
Preferred Storage Zones
If you are planning to distribute the database files of a federated database over a large number of storage locations, you may find it convenient to combine the locations into one or more storage zones. A storage zone is a named set of registered storage locations that are of interest to particular applications.
When you define a storage zone, you can specify it in an application’s location preferences, instead of listing every location of interest individually. For example, in Figure 4‑1, you could combine LocationB and LocationC into a single zone called MountainCentral, and then list MountainCentral in App2’s location preferences.
You can add or remove storage locations from a zone at any time. If the zone is preferred for an application, the change takes effect immediately. Existing data in a removed location is still available to applications.
Selection Policies
Selection policies enable a database placer to select storage locations in a way that can help balance processing loads and reduce concentrations of network traffic. For example, you could use a selection policy to produce a balanced distribution of database files among equivalent storage resources in a data center.
The selection policy for the default database placer guides the selection from among the locations in the MSG; see Setting the MSG’s Selection Policy.
 
Selection Policy
Description
Any
Select the first storage location listed in the group, and use it for successive requests until it is full or otherwise unavailable. Then select the next location in the list and fill it, and so on.
RoundRobin
Select a storage location from the group at random for the first request, then select locations in a round-robin manner for successive requests.
Random
Select each storage location from the group at random.
Example Assume you registered the storage locations LocationA, LocationB, LocationC, and LocationD in the MSG, and each location can hold at most four databases. Figure 4‑2 shows how the different selection policies would cause 10 database files to be distributed, if all locations are available.
Figure 4‑2 Policies for Selecting Storage Locations From the MSG
The distribution patterns shown in Figure 4‑2 assume that every registered storage location is available at the time it is selected; see How Unavailable Storage Locations Are Handled.
 
How Unavailable Storage Locations Are Handled
A storage location is unavailable if any of the following are true:
The location’s host cannot be accessed by the application—for example, because the host or a network link is not operational.
The location’s directory cannot be accessed by the application—for example, because of insufficient access permissions.
The location’s directory is full—for example, because the databases previously created there have grown large, so it has run out of space.
The following subsections describe how unavailable locations are handled.
If an Individual Location is Unavailable
If a database placer attempts to select a storage location that is currently unavailable for any reason, that location is skipped, and the selection process considers the next available location as determined by the database placer’s selection policy.
Special behavior applies when a location is skipped because its host cannot be accessed. A database placer waits up to 25 seconds if it cannot connect to a location’s host right away.
If Preferred Locations are Unavailable
If you set up application-specific location preferences, and all of the top-ranked storage locations are unavailable, the locations at the next lower rank are used, and so on, to the lowest rank.
If all preferred storage locations in all ranks are unavailable, then the database placer is allowed to select from any nonpreferred locations that may be registered in the MSG. You can optionally limit the selection to consider just the preferred locations, causing the application to throw an exception if none are available; see Representing Location Preferences in a Configuration File.
If an Entire Group of Locations is Unavailable
If all the locations you registered in the MSG are unavailable, the default database placer consults the MSG’s storage-unavailable policy. The default is to use the directory containing the federated database’s system-database file. Alternatively, you can limit the selection to just the explicitly registered locations, causing the application to throw an exception if none are available.
For specific steps, see Setting Storage-Unavailable Policies.
If the MSG is Empty
If you never registered any storage locations in a federated database’s MSG, then the empty MSG contains no available locations, so the default database place consults the MSG’s storage-unavailable policy. The default is to use the directory containing the federated database’s system-database file. Alternatively, you can cause the application to throw an exception if no locations are registered.
For specific steps, see Setting Storage-Unavailable Policies.
Registering Storage Locations
Registering Storage Locations
You use the AddStorageLocation administration tool to register storage locations with a federated database’s MSG. You can register any number of individual storage locations, optionally combining them into any number of storage zones. A storage location must exist before you register it.
A storage location can be registered with or without a name. Registering the location under a name is recommended, because doing so makes it easier to refer to the location from a tool or when setting up application-specific preferences.
The order in which you register storage locations is the order in which they are listed in the MSG. That is, whenever you register a new storage location, it is added after any that already exist in the MSG.
You specify remote storage locations using the format shown in Understanding File Storage for Persistent Data. You can use relative pathnames for local locations.
To register a named storage location
Run This Tool
With These Options
-name
-storageLocation
-bootFile
Example Assume LocationA is a subdirectory of the current directory. Register LocationA with the name LocA in the MSG for the RentalCompanyData federated database.
At the storageTasks command prompt, enter:
objy AddStorageLocation 
	-name LocA 
	-storageLocation ./LocationA 
	-bootFile RentalCompanyData.boot
 
To register one or more unnamed storage locations
Run This Tool
With These Options
-storageLocation
-bootFile
Example Assume LocationB, LocationC, and LocationD are subdirectories of the current directory. Register these locations without names in the MSG for the RentalCompanyData federated database.
At the storageTasks command prompt, enter:
objy AddStorageLocation 
	-storageLocation ./LocationB
	-storageLocation ./LocationC 
	-storageLocation ./LocationD 
	-bootFile RentalCompanyData.boot
 
Managing Storage Locations
Displaying the MSG
You use the ListStorage administration tool to list the registered storage locations in a federated database’s MSG. The output shows:
The order of the registered storage locations.
The names (if any) of the registered storage locations.
The storage zones (if any) and the locations in them.
The storage-unavailable policy for the MSG (behavior when the MSG is empty or all registered locations are full).
To list registered storage locations
Run This Tool
With These Options
-bootFile
Example List the storage locations registered in the MSG for the RentalCompanyData federated database in the current directory.
At the command prompt enter:
objy ListStorage -bootFile RentalCompanyData.boot
 
The following output is displayed:
Main Storage Group locations:
 
  Name                 Host and Path
--------------------+--------------------------------------------------
  LocA           myHost::C:\myData\placementTutorial\storageTasks\LocationA
  {NO NAME}      myHost::C:\myData\placementTutorial\storageTasks\LocationB
  {NO NAME}      myHost::C:\myData\placementTutorial\storageTasks\LocationC
  {NO NAME}      myHost::C:\myData\placementTutorial\storageTasks\LocationD
 
  Storage Unavailable Policy: Use Federated Database Location
 
Naming or Renaming a Registered Storage Location
You use the AddStorageLocation administration tool to assign a name to an unnamed storage location or to rename a storage location that has a name.
To name registered storage locations
Run This Tool
With These Options
-name
-storageLocation
-bootFile
Example Assign the name LocB to the registered location that matches ./LocationB.
objy AddStorageLocation 
	-name LocB
	-storageLocation ./LocationB 
	-bootFile RentalCompanyData.boot
 
Removing a Storage Location From the MSG
You use the RemoveStorageLocation administration tool to remove a storage location from the MSG. Removing a storage location from the MSG prevents that location from being used for any subsequently created database file; any existing database files in that location are not affected.
To remove a storage location from the MSG
Run This Tool
With These Options
-name or -storageLocation
-bootFile
Example Remove the storage location ./LocationD from the MSG:
objy RemoveStorageLocation 
	-storageLocation ./LocationD 
	-bootFile RentalCompanyData.boot 
 
Managing Storage Zones
Setting Up a Storage Zone
You use the AddStorageLocation administration tool to create and populate a storage zone. A new storage zone is created automatically the first time you add a storage location to it. A zone can contain any number of storage locations. The storage locations in a zone may, but need not, be directories on the same host.
To set up a storage zone
Run This Tool
With These Options
-zone
-name or -storageLocation
-bootFile
Example Create a storage zone called MountainCentral, and populate it with the existing location named LocB:
objy AddStorageLocation 
	-zone MountainCentral
	-name LocB
	-bootFile RentalCompanyData.boot
 
Add two more storage locations to the MountainCentral zone:
objy AddStorageLocation 
	-zone MountainCentral
	-storageLocation ./LocationC 
	-storageLocation ./LocationD 
	-bootFile RentalCompanyData.boot
This command adds the registered location matching ./LocationC, and also re-registers the previously deleted location ./LocationD.
 
Removing a Storage Location From a Storage Zone
You use the RemoveStorageLocation administration tool to remove a storage location from a single storage zone, while leaving it registered in the MSG.
To remove a storage location from a single storage zone
Run This Tool
With These Options
-zone
-name or -storageLocation
-bootFile
Example Remove the storage location ./LocationD from the MountainCentral zone, leaving the location in the MSG:
objy RemoveStorageLocation 
	-zone MountainCentral
	-storageLocation ./LocationD 
	-bootFile RentalCompanyData.boot
 
Setting the MSG’s Selection Policy
You modify a federated database’s placement model to set the selection policy that applies to the MSG; see Selection Policies. The initial selection policy is Any.
To change an MSG’s selection policy
1. Run the ExportPlacement tool to generate a placement-model document (PMD) containing the federated database’s current placement model.
objy ExportPlacement -outFile temp.pmd -bootFile RentalCompanyData.boot
2. Open the PMD for editing.
3. Find the <MainStorageGroup> element and set the value of the selection attribute to one of the values listed in Selection Policies—for example:
 
<MainStorageGroup>
  <StorageGroupConfiguration selection="RoundRobin" />
  ...
</MainStorageGroup>
 
4. Run the ImportPlacement tool to install the placement model defined by the changed PMD.
objy ImportPlacement -inFile temp.pmd -bootFile RentalCompanyData.boot
Specifying Application-Specific Location Preferences
You can arrange for an individual Objectivity/DB application to create new database files in preferred storage locations; see Application-Specific Location Preferences. To do so, you:
Define the application’s location preferences.
Represent the location preferences in an Objectivity configuration file.
Note:Spark driver applications normally use the location preferences described in Using Predefined Location Preferences.
Defining an Application’s Location Preferences
You define an application’s location preferences by identifying the particular locations to be used for new database files, and deciding how these locations are to be used. You typically prioritize locations that are local to the application, but preferences can also be based on other criteria, such as the speed or capacity of network links and hosts.
Note:Location preferences do not restrict which database files an application can access. Rather, preferences apply only when the application produces new database files to accommodate the persistent objects it creates.
To define location preferences for an application
1. Examine the registered storage locations and storage zones in the MSG, and identify the ones that are preferred—the ones you want the application to use.
The preferred locations and zones are typically a subset of the MSG.
2. If appropriate, identify the relative priority among the preferred locations and zones, and assign each one to a preference level, or rank. Note:
You can put multiple locations and zones in the same rank if they are of equal importance.
In many scenarios, only a single rank is useful.
3. Decide whether the nonpreferred (unranked) locations and zones can be used as “overflow” by the application if all the preferred (ranked) locations and zones are unavailable.
4. If you think any of the preferred storage locations will likely need replacing later while the application is running, be sure they are assigned to a preferred storage zone. (The zone’s contents can be changed at any time, and the changes will be detected by the running application.)
Example Assume you are defining preferences for the Objectivity/DB applications shown in Figure 4‑1. The preferences for App1 and App2 might look like this:
 
Sample Location Preferences for App1
Rank 1
LocationC and LocationD
Rank 2
LocationA
Unranked
All others in the MSG. OK to use if ranked locations are unavailable
Sample Location Preferences for App2
Rank 1
MountainCentral zone
Unranked
All others in the MSG. Do not use if ranked locations are unavailable; throw an exception, instead.
 
Representing Location Preferences in a Configuration File
You represent an Objectivity/DB application’s location preferences in an Objectivity configuration file. A Spark driver application always uses the default Objectivity configuration file machine.config; see Default File for Machine-Wide Settings.
To represent location preferences in a configuration file
Note:(Advanced task) For a Spark driver application, you rarely need to represent location preferences other than the predefined ones described in Using Predefined Location Preferences.
1. Open the chosen Objectivity configuration file in an XML editor and insert the following XML elements. These elements represent the entire set of location preferences, including one or more empty ranks.
 
<?xml version="1.0" encoding="UTF-8"?>
<Objectivity>
... 
  <LocationPreferences allowNonPreferredLocations="true">
    <LocationPreferenceRank>       <!-- First or only rank -->
      ...
    </LocationPreferenceRank>
 
    <LocationPreferenceRank>       <!-- Additional rank -->
      ...
    </LocationPreferenceRank>
  </LocationPreferences> 
... 
</Objectivity>
 
2. Within the element representing each rank, insert appropriate XML elements from the following table to represent the locations or zones in the rank.
XML Element Within a <LocationPreferenceRank>
Represents
<StorageLocation value="name"/>
Or
<StorageLocation value="host::path"/>
A registered storage location with the indicated name or host/path combination.
<Zone value="zoneName"/>
A registered storage zone named zoneName.
<LocalHost value="true"/>
All registered storage locations residing on the host on which the application is running.
<Host value="hostName"/>
All registered storage locations residing on the host whose network name is hostName.
3. Adjust the value of the allowNonPreferredLocations attribute as appropriate. (Specify false to limit the selection to just the preferred locations.)
4. Save the configuration file.
Note:Once the configuration file is loaded by an application, any subsequent changes you make to the file are ignored by that application until that application is restarted. However, any changes you make to the contents of a preferred zone are detected by the application immediately, without requiring a restart.
Setting Storage-Unavailable Policies
You modify a federated database’s placement model to set the storage-unavailable policy for a database placer. The policy for the default database placer specifies what happens if all the storage locations in the MSG are unavailable or if the MSG is empty.
The default behavior is to select the directory containing the federated database’s system database file. You set the storage-unavailable policy explicitly if you want to limit the selection to just the locations in the main storage group.
Note:If you are using data-specific database placers, you can set the storage-unavailable policy for each placer individually; see Getting Started With Managed Object Placement.
To set the storage-unavailable policy for a federation’s MSG
1. Run the ExportPlacement tool to generate a placement-model document (PMD) containing the federated database’s current placement model.
2. Open the PMD for editing.
3. Find the <MainStorageGroup> element and set the value of the storageUnavailablePolicy attribute to a value listed in the table below. For example:
 
<MainStorageGroup>
  ...
  <StorageAcquisitionPolicy ... 
    storageUnavailablePolicy="UseDefault" />
</MainStorageGroup>
 
 
StorageUnavailablePolicy
Description
UseDefault
Select the system-database directory, if possible; otherwise raise an exception for the application to handle.
ApplicationException
Raise an exception for the application to handle.
4. Run the ImportPlacement tool to install the placement model defined by the changed PMD.