Objectivity/DB Administration : Tools for Placement-Related Tasks
Tools for Placement-Related Tasks
This chapter describes Objectivity/DB tools for performing placement-related administrative tasks. See also Tools for Administration Tasks for descriptions of the general administration tools.
AddIndex
Use: Tool Runner Syntax
Creates one or more indexes in the specified federated database.
objy AddIndex
(-name
name -class className {-attribute fieldName} [-isUnique] )
| (-indexSpecification indexSpec )
[-objectPlacer placerName]
[-level indexLevel]
[-noTitle]
[-quiet]
[-help]
-bootFile bootFilePath
Options 
-name name
Unique name for the index.
This name must be different from any other index created in the same federated database, or from any index specification or key specification that may already exist in the federated database’s placement model. (Use the ListIndexes tool to see the names that are already in use.)
This option is part of the single-step technique for creating indexes, and must be used with the -class and -attribute options.
-class className
Name of the class of the objects to be indexed. If the class is in a namespace, you must specify either namespaceName.className or namespaceName::className.
This option is part of the single-step technique for creating indexes, and must be used with the -name and -attribute options.
-attribute fieldName
Name of the attribute to be used as a key field for sorting indexed objects.
If the attribute has string values, up to 24 characters of each value are stored in the index. You can change the maximum stored string length in the form fieldName:maxStringLen. For example, name:20
If the attribute is inherited from a superclass and the name is ambiguous, you can qualify it in the form superclassName::fieldName. For example, Shape::numberOfEdges
If the attribute is a member of an embedded object, you can specify it in the form embeddedAttribute.fieldName. For example, Address.city
You can specify this option multiple times to add a combination of key fields. The left-to-right order of the options is significant, with the leftmost designating the primary sort key.
This option is part of the single-step technique for creating indexes, and must be used with the -name and -class options.
-isUnique
Requires the new index to have unique keys. That is, every indexed object must have a unique combination of values in its key fields. If omitted, duplicate key values are allowed.
This option is part of the single-step technique for creating indexes, and may be used with the -name, -class, and -attribute options.
-indexSpecification indexSpec
Name of the index specification on which to base the added index(es).
This option is part of the multi-step technique for creating indexes, and is used as an alternative to specifying the -name, -class, and -attribute options.
-objectPlacer placerName
Object placer that placed the persistent objects to be indexed. If omitted, all objects of the class are indexed, regardless of the object-placer scope to which they belong.
-level indexLevel
Level of the index(es) to be created. If omitted, container-level indexes are added.
This option does not affect the total number of objects to be indexed, but rather determines the level of granularity of the indexes themselves:
indexLevel
Description
container
(Default) Adds a set of container-level indexes, so that a separate index structure is created in each container containing objects to be indexed.
group
Supported in a future release. Adds a set of group-level indexes, so that a separate index structure is created per container group containing objects to be indexed.
partition
Supported in a future release. Adds a set of partition-level indexes, so that a separate index structure is created per partition containing objects to be indexed.
scope
Supported in a future release. Adds a set of scope-level indexes, so that a separate index structure is created for each object-placer scope that contains objects to be indexed.
-noTitle
Suppresses just the copyright notice and program title banner, but no other program output. Useful when invoking the tool from a script or application.
-quiet
Suppresses all program output, including the copyright notice and program title banner.
-help
Prints the tool syntax and definition to the screen.
-bootfile bootFilePath
Path (including the filename) to the boot file of the federated database to which to add indexes.
Discussion 
For your convenience, you can use either of two techniques to add indexes:
The single-step technique enables you to quickly create indexes when the underlying index specifications and key specifications do not already exist. This technique creates the underlying specifications and adds the indexes in a single operation.
To perform the single-step technique, run the AddIndex tool with the -name, -class, -attribute, and (optionally) -isUnique options.
The multi-step technique enables you to create indexes based on index specifications and key specifications that already exist.
To perform the multi-step technique, run AddKeySpecification to create the key specification; run AddIndexSpecification to create the index specification; then run AddIndex with the -indexSpecification option.
The two techniques give you the flexibility of either streamlining the addition of an index, or setting up underlying specifications that can be reused for many different indexes. Both techniques cause key specifications and index specifications to be added to the federated database’s placement model; these are displayed by ListIndexes.
By default, this tool adds an index to every container that contains persistent objects of the indexed class. You can limit indexing to a subset of such objects by specifying the -objectPlacer option. Doing so indexes just the persistent objects of the class that reside in the specified object placer’s scope.
Note:This tool reports an error and quits if you attempt to add a unique index when two or more existing persistent objects of the indexed class have the same combination of values in their key fields.

Similarly, after you add a unique index, an exception occurs if you attempt to add a persistent object with duplicate key values, or assign duplicate values to the key fields of an existing persistent object.
Example 
Single-step technique. The following command adds container-level indexes to the federated database designated by myFD.boot. The index within a given container sorts persistent objects of class Person (and its subclasses) by the values of their name and age attributes, where name is the primary sort key. Only the first 20 characters of the name values are stored and used by the index, which allows duplicate key values.
objy AddIndex -name PersonIndex -class Person -attribute name:20 -attribute age -bootFile myFD.boot
Example 
Final step of multi-step technique. The following command adds container-level indexes to the federated database designated by myFD.boot. The indexes are based on an existing index specification called PersonIndex created using AddIndexSpecification. These indexes include all persistent Person objects in the federated database.
objy AddIndex -indexSpecification PersonIndex -bootFile myFD.boot
Example 
Final step of multi-step technique. The following command adds container-level indexes to the federated database designated by myFD.boot. The indexes are based on an existing index specification called PersonIndex created using AddIndexSpecification. These indexes include all persistent Person objects in the scope of the NorthAmerica object placer.
objy AddIndex -indexSpecification PersonIndex -objectPlacer NorthAmerica -bootFile myFD.boot
See also 
DropIndex
ListIndexes
AddIndexSpecification
Use: Tool Runner Syntax
Adds an index specification to the specified federated database's placement model.
objy AddIndexSpecificaton
-name name
-keySpecification keySpec
[-class className]
[-isUnique]
[-noTitle]
[-quiet]
[-help]
-bootFile bootFilePath
Options 
-name name
Name of the index specification; must be unique within the federated database's placement model.
-keySpecification keySpec
Name of the key specification identifying the class and key field(s) of the objects to be indexed.
-class className
Name of the class of the objects to be indexed; must be the class on which keySpec is based, or a subclass of that class. If the class is in a namespace, you must specify either namespaceName.className or namespaceName::className.
You can omit this option to use the class on which keySpec is based.
-isUnique
Requires indexes based on the specification to have unique keys. That is, every indexed object must have a unique combination of values in its key fields. If omitted, duplicate key values are allowed.
-noTitle
Suppresses just the copyright notice and program title banner, but no other program output. Useful when invoking the tool from a script or application.
-quiet
Suppresses all program output, including the copyright notice and program title banner.
-help
Prints the tool syntax and definition to the screen.
-bootfile bootFilePath
Path (including the filename) to the boot file of the federated database to which to add the index specification.
Discussion 
An index specification describes the properties of a particular set of indexes that can be added to the federated database.
Note:You do not need to run this tool if you plan to add an index by running AddIndex using the single-step technique.
Example 
The following command adds an index specification to the placement model of the federated database designated by myFD.boot. The index specification is based on a key specification called PersonKey. Indexes created from the new index specification will include persistent Person objects, as well as objects of any subclasses of Person. Furthermore, such indexes will use a traditional structure, and will allow duplicate key values.
objy AddIndexSpecification -name PersonIndex -keyspecification PersonKey -bootFile myFD.boot
Example 
Assume that Child is a subclass of Person. The following command adds an index specification that is based on a key specification called PersonKey. Indexes created from the new index specification will include just persistent Child objects, as well s objects of any subclasses of Child.
objy AddIndexSpecification -name ChildIndex -keySpecification PersonKey -class Child -bootFile myFD.boot
See also 
AddIndex
AddKeySpecification
AddKeySpecification
Use: Tool Runner Syntax
Adds a key specification to the specified federated database's placement model.
objy AddKeySpecification
-name name
-class className
{-attribute fieldName}
[-noTitle]
[-quiet]
[-help]
-bootFile bootFilePath
Options 
-name name
Name of the key specification; must be unique within the federated database's placement model.
-class className
Name of the class of the persistent objects to be indexed. If the class is in a namespace, you must specify either namespaceName.className or namespaceName::className.
-attribute fieldName
Name of the attribute to be used as a key field for sorting indexed objects.
If the attribute has string values, up to 24 characters of each value are stored in the index. You can change the maximum stored string length in the form fieldName:maxStringLen. For example, name:20
If the attribute is inherited from a superclass and the name is ambiguous, you can qualify it in the form superclassName::fieldName. For example, Shape::numberOfEdges
If the attribute is a member of an embedded object, you can specify it in the form embeddedAttribute.fieldName. For example, Address.city
You can specify this option multiple times to add a combination of key fields. The left-to-right order of the options is significant, with the leftmost designating the primary sort key.
-noTitle
Suppresses just the copyright notice and program title banner, but no other program output. Useful when invoking the tool from a script or application.
-quiet
Suppresses all program output, including the copyright notice and program title banner.
-help
Prints the tool syntax and definition to the screen.
-bootfile bootFilePath
Path (including the filename) to the boot file of the federated database to which to add the key specification.
Discussion 
A key specification can be used by one or more index specification(s) to specify the type of persistent objects to index, and the key field(s) by which to sort them.
Note:You do not need to run this tool if you plan to add an index by running AddIndex using the single-step technique.
Example 
The following command adds a key specification called PersonKey to the placement model of the federated database designated by myFD.boot. When used in an index specification, the key specification instructs the index to sort persistent objects of class Person (and its subclasses) by the values of their name and age attributes, where name is the primary sort key. Only the first 20 characters of the name values are stored and used by the index.
objy AddKeySpecification -name PersonKey -class Person -attribute name:20 -attribute age -bootFile myFD.boot
See also 
AddIndexSpecification
AddStorageLocation
Use: Tool Runner Syntax
Registers file-storage locations with the specified federated database's main storage group (MSG), and manages their membership in storage zones or database-placer groups.
objy AddStorageLocation
[{-name name}]
[-description description]
[{-storageLocation location}]
[{-zone zoneName}]
[{-dbPlacerGroup groupDesignation}]
[-noTitle]
[-quiet]
[-help]
-bootFile bootFilePath
Options 
-name name
Name of a storage location in the MSG.
Use -name with -storageLocation to specify a name for a new storage location being registered in the MSG or to rename a registered storage location. A warning is reported and no action is taken if name is already used in the MSG.
Use -name without -storageLocation to specify a registered named storage location that is to be added to the storage zones or database-placer groups specified by -zone or -dbPlacerGroup options. You can specify multiple -name options to add multiple named storage locations to each specified zone or group. An error occurs and no action is taken if the MSG has no registered location called name.
When multiple -name options are specified, the left-to-right order is significant, with the leftmost being added first among the locations being specified.
-description description
Description of an added location for your own record keeping.
-storageLocation location
File-storage location in the format host::path. Omitting host causes the local host to be used, or the host implied by an NFS mount name.
Use -storageLocation with -name to register location as a new, named storage location in the MSG. An error occurs if you specify multiple -storageLocation options with -name.
Use -storageLocation without -name to register location as a new, unnamed storage location in the MSG. You can specify multiple -storageLocation options to register multiple unnamed storage locations. The left-to-right order is significant, with the leftmost being added first among the locations being specified.
If you specify a location that is already registered in the MSG, the tool prints a warning,
-zone zoneName
Storage zone to which to add the specified storage location(s). If the MSG does not already have a zone with the specified name, the zone is created.
You can specify this option multiple times to add the specified storage location(s) to multiple zones.
-dbPlacerGroup groupDesignation
Database-placer group to which to add the specified storage location(s). A definition for the database placer must already exist in the federated database's placement model.
You can specify this option multiple times to add the specified storage location(s) to multiple groups.
If you are designating a group in the scope of a database placer called dbPlacerName, use one of the following formats:
 
Use This Format
When the Database Placer’s Scope Consists of
dbPlacerName
A single storage group. For example:
-dbPlacerGroup accounts
specifies the sole storage group in the accounts placer’s scope.
dbPlacerName::groupNum
Multiple storage groups (one per data file). For example:
-dbPlacerGroup accounts::2
specifies the second storage group in the accounts placer’s scope.
dbPlacerName::partitionNum
Multiple partitions, where each partition consists of a single storage group. For example:
-dbPlacerGroup observations::2
specifies the sole storage group in the second partition of the observations placer’s scope.
dbPlacerName::partitionNum::groupNum
Multiple partitions, where each partition consists of multiple storage groups (one per data file). For example:
-dbPlacerGroup observations::2::2
specifies the second storage group in the second partition of the observations placer’s scope.
-noTitle
Suppresses just the copyright notice and program title banner, but no other program output. Useful when invoking the tool from a script or application.
-quiet
Suppresses all program output, including the copyright notice and program title banner.
-help
Prints the tool syntax and definition to the screen.
-bootfile bootFilePath
Path (including the filename) to the boot file of the federated database to which to add the storage location.
Discussion 
You use the AddStorageLocation tool to:
Register one or more new named or unnamed storage locations.
Rename a registered storage location.
Manage the membership of storage locations in storage zones.
Manage the membership of storage locations in database-placer groups.
Note:If you never register any storage locations for a federated database, the default policy is to place new data files in the directory containing the federated database’s system-database file. (You can optionally configure the placement model so that requesting a new data file while the MSG is empty causes the application to throw an exception.)
Registering new storage locations
Registering a storage location adds it to a federated database’s MSG, making the location eligible for storing the data files of new databases and external containers. The newly registered storage location is added after any that already exist in the MSG.
A new 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 in a configuration file that expresses storage-location preferences.
To register a new named storage location in the MSG, run the tool with the -storageLocation and -name options.
When you register a new storage location, you can optionally add it to one or more storage zones and/or database-placer groups.
Renaming a registered storage location
To change the name of an existing (registered) storage location, run the tool with the -storageLocation to specify the location to be renamed, and the -name option to specify the new name.
Managing membership in storage zones
A storage location can belong to a storage zone, which is a convenient way of designating multiple registered storage locations that are somehow related—for example, by geographic region, by the type of storage medium, and so on.
You can use the AddStorageLocation tool at any time to add a storage location to one or more storage zones. As a convenience, you can add a location to a zone in the same command invocation that registers the location.
To populate a storage zone (creating the zone if necessary), run the tool with the -zone option.
Managing membership in database-placer groups
A storage location can be assigned to a storage group that is maintained by a particular database placer. A database placer prioritizes the locations in its storage group(s) over any other locations in the MSG; depending on how the database placer is configured, it may be restricted to use just the locations in its storage group(s).
You can use the AddStorageLocation tool at any time to assign a storage location to one or more database-placer groups. As a convenience, you can assign a location to a group in the same command invocation that registers the location.
To assign to a storage group belonging to the scope of a particular database placer, run the tool with the -dbPlacerGroup option.
When populating a storage group in a database placer’s scope, the tool reports an error and quits if the group does not yet exist. Consequently, you may need to initialize the scope before running this tool. More specifically:
If the database placer is configured so that its scope will have just a single storage group, that group is created automatically, so you can run the tool at any time.
If, however, the database placer is configured so that scope will have multiple storage groups or partitions, you must run this tool after you run an application that creates data files in the scope of the database placer of interest; the application should create enough files to set up the database placer’s scope with the storage groups to be populated. You can then run this tool once per storage group to populate each group with additional storage locations.
Example 
The following command registers the directory d:\Data on the host machine1 as a storage location named Loc1 in the MSG of the federated database designated by myFD.boot.
objy AddStorageLocation -name Loc1 -storageLocation machine1::D:\Data -bootFile myFD.boot
Example 
The following command registers two unnamed storage locations in the federated database’s MSG. Because of the order of the -storageLocation options, the location on machine1 will be listed in the MSG before the location on hal. (By default, this means the location on machine1 will be used before the location on hal.)
objy AddStorageLocation -storageLocation machine1::D:\Data -storageLocation hal::F:\myProjects\Data -bootFile myFD.boot
Example 
The following command registers a storage location under the name Loc2 and adds it to a zone.
objy AddStorageLocation -name Loc2 -storageLocation machine1::D:\MyData -zone EastCoast -bootFile myFD.boot
Example 
The first of the following commands registers a storage location under the name Loc3. The second command adds the (now) registered Loc3 to a zone.
objy AddStorageLocation -name Loc3 -storageLocation machine1::D:\MoreData -bootFile myFD.boot
 
objy AddStorageLocation -name Loc3 -zone EastCoast -bootFile myFD.boot
See also 
Registering Storage Locations
RemoveStorageLocation
ListStorage
CreateContainers
Use: Tool Runner Syntax
Creates and adds containers to the scope of the specified object placer, possibly to particular container groups.
objy CreateContainers
-count count
-scope placerName | -group groupDesignation
[{-storageLocation location}]
[{-zone zoneName}]
[-noTitle]
[-quiet]
[-help]
-bootFile bootFilePath
Options 
-count count
Number of containers to create.
-scope placerName
Adds the created containers to the scope of the specified object placer. The object placer must be defined in the federated database's placement model.
This option associates a pool of pre-created containers with the entire scope. When the object placer needs to add a container to a group in its scope, it can obtain a container from the pool and assign it to that group. The container remains in that group for its lifetime; containers are never returned to the pool.
-group groupDesignation
Adds the created containers to a particular container group in an object placer’s scope. The object placer must be defined in the federated database's placement model.
This option associates the pre-created containers with just the designated container group. Containers associated with one group are not available to any other group.
This option is useful if the object placer is configured to perform random or round-robin distribution of persistent objects among its containers.
To designate a container group in the scope of an object placer called objPlacerName, use one of the following formats:
 
Use This Format
When the Object Placer’s Scope Consists of
objPlacerName
A single container group. For example:
-group accounts
specifies the sole container group in the accounts placer’s scope.
objPlacerName::groupNum
Multiple container groups (one per placed object).
For example:
-group accounts::2
specifies the second container group in the accounts placer’s scope.
objPlacerName::partitionNum
Multiple partitions, where each partition consists of a single container group. For example:
-group observations::2
specifies the sole container group in the second partition of the observations placer’s scope.
objPlacerName::partitionNum::groupNum
Multiple partitions, where each partition consists of multiple container groups (one per placed object).
For example:
-group observations::2::2
specifies the second container group in the second partition of the observations placer’s scope.
-storageLocation location
Storage location in which to create the new containers and any necessary databases. location must be registered in the federated database’s main storage group (MSG). Specifying this option prioritizes location ahead of the other storage locations listed in the MSG; you can use this option to express a site-specific preference for a particular location. Omitting this option causes the location to be selected from the MSG according to the placement model.
The format of location is host::path. Omitting host causes the local host to be used, or the host implied by an NFS mount name.
You can specify this option multiple times to specify multiple preferred storage locations. The specified locations are equal in preference rank.
-zone zoneName
Name of a storage zone in which to create the new containers. The zone must be registered in the federated database’s main storage group (MSG). Specifying this option prioritizes the storage locations in zoneName ahead of the other storage locations listed in the MSG; you can use this option to express a site-specific preference for a particular zone.
You can specify this option multiple times to specify multiple preferred storage zones. The specified zones are equal in preference rank.
-noTitle
Suppresses just the copyright notice and program title banner, but no other program output. Useful when invoking the tool from a script or application.
-quiet
Suppresses all program output, including the copyright notice and program title banner.
-help
Prints the tool syntax and definition to the screen.
-bootfile bootFilePath
Path (including the filename) to the boot file of the federated database to which to add containers.
Discussion 
You use this tool to provision the container groups belonging to a particular object placer’s scope. Provisioning a container group populates it with pre-created containers. Doing so can improve the performance of your application, which would otherwise create each container implicitly as needed to place new objects. You may also need to initialize a container group with a particular number of containers if the object placer is configured to perform random or round-robin distribution of persistent objects among its containers.
 
To Pre-create Containers for a Scope Consisting of
Use This Option
A single group.
Either the -scope option or the -group option.
Multiple container groups (in one or more partitions), where each container group can have an arbitrary number of containers.
The -scope option.
Multiple container groups (in one or more partitions), where each group should have a particular number of containers.
The -group option. Run the tool once for each group to be provisioned.
When you use the -group option, an error occurs if the specified container group does not yet exist. To ensure that the container groups to be provisioned already exist in the object placer’s scope, you can run an application that creates enough objects to set up the container groups of interest. You then run this tool once per container group to provision each group with additional pre-created containers.
Example 
The following command provisions the sole container group of the accounts object placer with 1000 containers. The new containers are placed in new databases that are created in one of the storage locations in the EastCoast zone.
objy CreateContainers -count 1000 -scope accounts -zone EastCoast -bootFile myFD.boot
CreatePartition
Use: Tool Runner Syntax
Creates a partition and adds containers for it within the scope of the specified object placer.
objy CreatePartition
-partitionObject objectIdentifer
-objectPlacer placerName
-count count
[{-storageLocation location}]
[{-zone zoneName}]
[-noTitle]
[-quiet]
[-help]
-bootFile bootFilePath
Options 
-partitionObject objectIdentifier
Object identifier (OID) of the object that serves as the partitioning key for the partition of interest. Specify the identifier in its D-C-P-S format (for example, 5-3-1-4). The object must be of the type designated by the specified object placer as its related-object class.
-objectPlacer placerName
Adds the created partition to the scope of the specified object placer. The object placer must be defined in the federated database's placement model.
This option associates a pool of pre-created containers with the partition. When the object placer needs to add a container to a group in the partition, the placer obtains a container from the pool and assigns it to that group. The container remains in that group for its lifetime; containers are never returned to the pool.
-count count
Number of containers to create for the new partition.
-storageLocation location
Storage location in which to create the new containers and any necessary databases. location must be registered in the federated database’s main storage group (MSG). Specifying this option prioritizes location ahead of the other storage locations listed in the MSG; you can use this option to express a site-specific preference for a particular location. Omitting this option causes the location to be selected from the MSG according to the placement model.
The format of location is host::path. Omitting host causes the local host to be used, or the host implied by an NFS mount name.
You can specify this option multiple times to specify multiple preferred storage locations. The specified locations are equal in preference rank.
-zone zoneName
Name of a storage zone in which to create the new containers. The zone must be registered in the federated database’s main storage group (MSG). Specifying this option prioritizes the storage locations in zoneName ahead of the other storage locations listed in the MSG; you can use this option to express a site-specific preference for a particular zone.
You can specify this option multiple times to specify multiple preferred storage zones. The specified zones are equal in preference rank.
-noTitle
Suppresses just the copyright notice and program title banner, but no other program output. Useful when invoking the tool from a script or application.
-quiet
Suppresses all program output, including the copyright notice and program title banner.
-help
Prints the tool syntax and definition to the screen.
-bootfile bootFilePath
Path (including the filename) to the boot file of the federated database to which to add containers.
Discussion 
You use this tool to provision the container groups belonging to a particular partition within an object placer’s scope. Provisioning a container group populates it with pre-created containers. Doing so can improve the performance of your application, which would otherwise create each container implicitly as needed to place new objects. You may also need to initialize a container group with a particular number of containers if the object placer is configured to perform random or round-robin distribution of persistent objects among its containers.
This tool is similar in purpose to the CreateContainers tool, which you can use to provision an entire object-placer scope or individual container groups within that scope.
Example 
The following command creates a partition within the accounts object-placer scope. The new partition is reserved for accounts belonging to the bank branch represented by the object whose OID is 5-3-1-4. The command provisions the new partition with 250 containers. If necessary, the new containers are placed in new databases that are created in one of the storage locations in the EastCoast zone.
objy CreatePartition -partitionObject 5-3-1-4 -objectPlacer accounts -count 250 -zone EastCoast -bootFile myFD.boot
DeleteIndexSpecification
Use: Tool Runner Syntax
Deletes an index specification from the specified federated database's placement model.
objy DeleteIndexSpecificaton
([-name name] | [-obsolete])
[-noTitle]
[-quiet]
[-help]
-bootFile bootFilePath
Options 
-name name
Name of the index specification to delete. If you use this option, you cannot use the -obsolete option.
-obsolete
Deletes all obsolete index specifications. An index specification becomes obsolete if the indexed class or any of its indexed attributes no longer exist in the schema model of the federated database. If you use this option, you cannot use the -name option.
-noTitle
Suppresses just the copyright notice and program title banner, but no other program output. Useful when invoking the tool from a script or application.
-quiet
Suppresses all program output, including the copyright notice and program title banner.
Suppresses all normal program output.
-help
Prints the tool syntax and definition to the screen.
-bootfile bootFilePath
Path (including the filename) to the boot file of the federated database from which to delete the index specification.
Discussion 
If you attempt to delete an index specification that is used by an index in the federated database, the tool reports an error and quits. You must first drop any indexes that use the index specification, then you can delete the specification itself.
You can run the ListIndexes tool to see which index specifications are used by indexes in the federated database.
Deleting an index specification does not delete the key specification that it uses. To delete a key specification, use the DeleteKeySpecification tool.
Example 
The following command deletes an index specification from the placement model of the federated database designated by myFD.boot.
objy DeleteIndexSpecification -name PersonIndex -bootFile myFD.boot
See also 
DropIndex
ListIndexes
DeleteKeySpecification
DeleteKeySpecification
Use: Tool Runner Syntax
Deletes a key specification from the specified federated database's placement model.
objy DeleteKeySpecification
([-name name] | [-obsolete])
[-noTitle]
[-quiet]
[-help]
-bootFile bootFilePath
Options 
-name name
Name of the key specification to delete. If you use this option, you cannot use the -obsolete option.
-obsolete
Deletes all obsolete key specifications. A key specification becomes obsolete if the relevant indexed class or attribute no longer exists in the schema model for the federated database. If you use this option, you cannot use the -name option.
-noTitle
Suppresses just the copyright notice and program title banner, but no other program output. Useful when invoking the tool from a script or application.
-quiet
Suppresses all program output, including the copyright notice and program title banner.
-help
Prints the tool syntax and definition to the screen.
-bootfile bootFilePath
Path (including the filename) to the boot file of the federated database from which to delete the key specification.
Discussion 
If you attempt to delete a key specification that is used in an index specification in the federated database’s placement model, the tool reports an error and quits. You must first delete any index specification that uses the key specification, then you can delete the key specification itself.
You can run the ListIndexes tool to see which key specifications are used by index specifications in the placement model of the federated database.
Example 
The following command deletes a key specification called PersonKey from the placement model of the federated database designated by myFD.boot.
objy DeleteKeySpecification -name PersonKey -bootFile myFD.boot
See also 
DropIndex
DeleteIndexSpecification
ListIndexes
DropIndex
Use: Tool Runner Syntax
Drops (removes) the specified indexes and optionally deletes its underlying structures.
objy DropIndex
(-name name | -indexSpecification indexSpec) | -obsolete
[-clean]
[-objectPlacer placerName]
[-level indexLevel]
[-noTitle]
[-quiet]
[-help]
-bootFile bootFilePath
Options 
-name name
Drops any indexes with the name assigned by the -name option of AddIndex.
If you use this option, you cannot also use the -indexSpecification or -obsolete option.
-indexSpecification indexSpec
Drops any indexes based on the index specification named indexSpec.
If you use this option, you cannot use the -name or -obsolete option.
-obsolete
Drops all indexes based on obsolete specifications. An index specification becomes obsolete if the indexed class or any of its indexed attributes no longer exist in the schema model of the federated database.
If you use this option, you cannot use the -name or -indexSpecification option.
-clean
Drops the specified indexes, along with the index specification and key specification on which the indexes are based.
The index specification is not deleted if it is used by some other index. Similarly, the key specification is not deleted if it is used in some other index specification. Failure to delete a specification is reported in the tool output.
-objectPlacer placerName
Drops only the indexes that include objects that were placed by placerName. If omitted, the tool drops all indexes based on indexSpec or name at the specified level.
-level indexLevel
Level (container, group, partition, or scope) that each index spans. The indexLevel does not affect which objects are indexed, but rather determines whether these objects are indexed using a set of container-level indexes, a set of group-level indexes, a set of partition-level indexes, or a single scope-level index.
-noTitle
Suppresses just the copyright notice and program title banner, but no other program output. Useful when invoking the tool from a script or application.
-quiet
Suppresses all program output, including the copyright notice and program title banner.
-help
Prints the tool syntax and definition to the screen.
-bootfile bootFilePath
Path (including the filename) to the boot file of the federated database from which to drop indexes.
Discussion 
You can use this tool to drop indexes that are no longer needed.
The -name and -indexSpecification options are interchangeable alternatives for specifying the indexes to be dropped. The -name option is convenient if you created the indexes using the single-step technique; see AddIndex. The -indexSpecification option fits in with the multi-step technique, in which you create the index specification explicitly with AddIndexSpecification.
By default, dropping indexes does not remove the index specification or key specification(s) on which they are based. If you do not plan to reuse the specifications for further indexes, you can specify the -clean option to delete them when you drop the indexes. Doing so is a convenient alternative to running the DeleteIndexSpecification and DeleteKeySpecification tools. (Note, however, that index specifications are not deleted if they are used by other indexes, and key specifications are not deleted if they are used by other index specifications.)
You can run the ListIndexes tool to list the index specifications on which existing indexes are based.
See also 
DeleteIndexSpecification
ListIndexes
AddIndex
ExportPlacement
Use: Tool Runner Syntax
Creates a placement model document (PMD) describing the placement model that is currently installed in the federated database.
objy ExportPlacement
-outFile fileName
[-allVersions]
[-includeSystemDefined]
[-noTitle]
[-quiet]
[-help]
-bootFile bootFilePath
Options 
-outFile fileName
Name of the file in which to write the exported PMD. You may optionally include a path to an existing directory in which to create the output file; if you do not include a path, the output file is created in the directory in which you ran the tool. The .pmd filename extension is recommended, but is not added automatically.
-allVersions
Includes all versions of the placement model. If omitted, includes only the latest version.
-includeSystemDefined
Includes any internal placement models found in the federated database. If omitted, includes only application-specific placement model or models.
Internal placement models generally exist to support different Objectivity products.
-noTitle
Suppresses just the copyright notice and program title banner, but no other program output. Useful when invoking the tool from a script or application.
-quiet
Suppresses all program output, including the copyright notice and program title banner.
-help
Prints the tool syntax and definition to the screen.
-bootfile bootFilePath
Path (including the filename) to the boot file of the federated database to be exported.
Discussion 
This tool exports the placement model of a federated database by representing them textually in Extensible Markup Language (XML).
You typically export a placement model so you can edit its PMD; importing the edited PMD creates a new version of the placement model.You can see the version history by running ExportPlacement with the -allVersions option.
See also 
ImportPlacement
ImportPlacement
Use: Tool Runner Syntax
Imports the specified placement model document (PMD), and installs the described placement model into the federated database.
objy ImportPlacement
-inFile fileName
[-allVersions]
[-noTitle]
[-quiet]
[-help]
-bootFile bootFilePath
Options 
-inFile fileName
Name of the PMD file to import. You may optionally include a path to the directory containing the file; if you do not include a path, the file must reside in the directory in which you run the tool.
-allVersions
Includes all versions of the placement model. If omitted, includes only the latest version.
-noTitle
Suppresses just the copyright notice and program title banner, but no other program output. Useful when invoking the tool from a script or application.
-quiet
Suppresses all program output, including the copyright notice and program title banner.
-help
Prints the tool syntax and definition to the screen.
-bootfile bootFilePath
Path (including the filename) to the boot file of the federated database.
Discussion 
This tool interprets the specified Extensible Markup Language (XML) document and installs the described placement model into the specified federated database accordingly.
After an imported placement model is installed, it governs the placement of all subsequently created persistent objects; existing objects are not affected.
This tool creates a new version of the installed placement model.
This tool checks to make sure the placement model being installed is valid. If, for example, a placement rule specifies a non-existent class, the tool reports an error and quits, without making any updates to the federated database.
See also 
ExportPlacement
ListIndexes
Use: Tool Runner Syntax
Lists any indexes that have been added to the federated database.
objy ListIndexes
[-outputFormat format]
[-noTitle]
[-quiet]
[-help]
-bootFile bootFilePath
Options 
-outputFormat format
Chooses the format (text or xml) for the list output. If omitted, the default is text.
-noTitle
Suppresses just the copyright notice and program title banner, but no other program output. Useful when invoking the tool from a script or application.
-quiet
Suppresses all program output, including the copyright notice and program title banner.
-help
Prints the tool syntax and definition to the screen.
-bootfile bootFilePath
Path (including the filename) to the boot file of the federated database.
Discussion 
This tool lists the following information for the federated database:
The key specifications that are available.
The index specifications that are available.
The indexes that are in use.
The output also labels any of the above elements that are now obsolete due to changes in the schema model for the federated database. The DropIndex, DeleteIndexSpecification, and DeleteKeySpecification tools have an -obsolete option for removing all obsolete entries.
See also 
AddIndex
DropIndex
DeleteIndexSpecification
DeleteKeySpecification
ListStorage
Use: Tool Runner Syntax
Lists the storage locations and zones that are currently registered in the federated database's main storage group (MSG).
objy ListStorage
[-includeUnavailable]
[-noTitle]
[-quiet]
[-help]
-bootFile bootFilePath
Options 
-includeUnavailable
Includes storage locations that are currently unavailable because they are full.
-noTitle
Suppresses just the copyright notice and program title banner, but no other program output. Useful when invoking the tool from a script or application.
-quiet
Suppresses all program output, including the copyright notice and program title banner.
-help
Prints the tool syntax and definition to the screen.
-bootfile bootFilePath
Path (including the filename) to the boot file of the federated database.
Discussion 
The tool output lists:
The storage locations that have been registered with the federated database.
The assignment of any storage locations to storage zones or database-placer groups.
The existing database-placer groups to which storage locations can potentially be added.
The order in which storage locations are listed is significant. By default, a placement model is configured to use the first location in the list until that location is full, and then use the second location, and so on. (The ordering in the MSG can be overridden by site-specific location preferences, however.)
If no storage locations have been registered for the federated database, the MSG is shown as EMPTY, and the default policy is to place new data files in the directory containing the federated database’s system-database file. (You can optionally configure the placement model so that requesting a new data file while the MSG is empty causes the application to throw an exception.)
See also 
AddStorageLocation
RemoveStorageLocation
Use: Tool Runner Syntax
Removes a storage location from one or more specified zones and database-placer groups, or else from the federated database's main storage group (MSG) and all its zones and groups.
objy RemoveStorageLocation
{-name locationName} | {-storageLocation location}
[{-zone zoneName}]
[{-dbPlacerGroup groupDesignation}]
[-noTitle]
[-quiet]
[-help]
-bootFile bootFilePath
Options 
-name locationName
Name of a storage location to be removed.
You can specify multiple -name options to remove multiple named storage locations.
-storageLocation location
Storage location in the format host::path. Omitting host causes the local host to be used, or the host implied by an NFS mount name.
If location matches an unnamed location, that location is removed; if location matches the host and path of a named location, that named location is removed.
You can specify multiple -storageLocation options to remove multiple storage locations.
-zone zoneName
Storage zone from which to remove the storage location. The storage location remains in the MSG.
You can specify this option multiple times to remove a storage location from multiple zones.
-dbPlacerGroup groupDesignation
Database-placer group from which to remove the storage location. The storage location remains in the MSG.
You can specify this option multiple times to remove a storage location from multiple database-placer groups.
If you are designating a group in the scope of a database placer called dbPlacerName, use one of the following formats:
 
Use This Format
When the Database Placer’s Scope Consists of
dbPlacerName
A single storage group. For example:
-dbPlacerGroup accounts
specifies the sole storage group in the accounts placer’s scope.
dbPlacerName::groupNum
Multiple storage groups (one per data file). For example:
-dbPlacerGroup accounts::2
specifies the second storage group in the accounts placer’s scope.
dbPlacerName::partitionNum
Multiple partitions, where each partition consists of a single storage group. For example:
-dbPlacerGroup observations::2
specifies the sole storage group in the second partition of the observations placer’s scope.
dbPlacerName::partitionNum::groupNum
Multiple partitions, where each partition consists of multiple storage groups (one per data file). For example:
-dbPlacerGroup observations::2::2
specifies the second storage group in the second partition of the observations placer’s scope.
-noTitle
Suppresses just the copyright notice and program title banner, but no other program output. Useful when invoking the tool from a script or application.
-quiet
Suppresses all program output, including the copyright notice and program title banner.
-help
Prints the tool syntax and definition to the screen.
-bootfile bootFilePath
Path (including the filename) to the boot file of the federated database from which to remove the storage location.
Discussion 
Removing a storage location from a federated database’s MSG prevents that location from being used for any subsequently created database file or container file.
You remove one or more storage locations from individual zones or groups by running the tool with one or more -zone and/or -dbPlacerGroup options. If you do not include any -zone or -dbPlacerGroup option, the tool removes the storage location(s) from the MSG (and therefore from all zones and groups in the MSG).
You must specify at least one -storageLocation option or -name option; otherwise the tool reports an error and terminates:
Use the -storageLocation option to remove an unnamed or a named storage location.
Use the -name option to specify a named storage location.
Example 
The following command removes the specified named storage location from the MSG and from any storage zone or database-placer group that includes it.
objy RemoveStorageLocation -name Loc1 -bootFile myFD.boot
Example 
The following command removes the specified storage locations from the MSG and from any storage zone or database-placer group that includes them.
objy RemoveStorageLocation -storageLocation machine1::D:\Data -storageLocation hal::F:\myProjects\Data -bootFile myFD.boot
Example 
The following command removes the specified named storage location from the the specified zone, but leaves it in the MSG and any other storage zones or database-placer groups.
objy RemoveStorageLocation -name Loc3 -zone EastCoast -bootFile myFD.boot
See also 
AddStorageLocation