Administration Tools - ooattachdb

Printer-friendly version
Attaches the specified database to a federated database.
ooattachdb
([-host hostName] -filepath path -db dbSysName [-id dbId])
| (-dbmap mapFile [-catalogonly])
[-nullifyexternals]
[-readonly]
[-tidy]
[-standalone]
[-notitle]
[-quiet]
[-help]
[bootFilePath]
Options
-host hostName
Data-server host of the database file to be attached. If you omit this option, the default host is:
n
The current host, if -filepath specifies a local path.
n
The host implied by -filepath, if an NFS mount name is specified.
If -filepath specifies a Windows UNC share name, hostName is set to the literal string oo_local_host; any value you specify is ignored.
-filepath path
Path (including the filename) to the database file to be attached. If the -host option specifies a remote system, path must be full, not relative. If path does not identify a valid database file on the specified host, ooattachdb reports an error and terminates.
-db dbSysName
System name with which the database is to be attached. If a database with this system name already exists in the federated database, the ooattachdb tool reports an error and terminates.
-id dbId
Integer identifier with which the database is to be attached (for example, 78). This option also accepts the identifier specified in D-C-P-S format (for example, 78-0-0-0). The maximum database identifier is 65534.
If a database with the specified identifier already exists in the federated database, the ooattachdb tool reports an error and terminates.
If you omit this option, the database is attached with its original identifier (that is, the identifier is obtained from the database file). If a database with this identifier already exists in the federated database, a new identifier is generated for the attached database.
-dbmap mapFile
ASCII text mapping file that specifies a group of databases to be attached. This option replaces the -db , -id , -host , and -filepath options. The mapping file contains one line for each database to be attached. Each line must have the following general format:
destDbID destDbSys hostName filepath
where
destDbID (Optional) Database identifier with which the database is to be attached.
destDbSys System name with which the database is to be attached.
hostName Data-server host of the database file.
filepath Path (including the filename) to the database file.
If you omit the destDbID for a database, the identifier is obtained from the database file; if a database with this identifier already exists in the federated database, a new identifier is generated for the attached database.
If any filepath does not identify a valid database file on the specified host, or if any other error is detected in a mapping-file entry, ooattachdb reports an error and terminates, and none of the databases are attached.
-catalogonly
Updates the federated database’s global catalog with minimal verification. Specifying this option can save time when you are attaching a large number of databases in a single operation.
When you specify this option, ooattachdb verifies that the specified file exists, but does not check whether it is a valid database file. Furthermore:
n
No indexes are updated with objects from the attached databases.
n
No adjustments are made to the contents of the attached files, if any database is attached with a new identifier.
This option applies only when the -dbmap option is specified. You must specify each database’s original identifier explicitly as the destDbID in the mapping file entries.
Warning: Do not use the -catalogonly option if any database is being attached with a new identifier. Doing so will make the objects in the attached database unusable.
-nullifyexternals
Sets all external references to null, even those that might be valid. An external reference is a relationship (association) or reference attribute that would link an object in an attached database to one or more objects in any other database, including other databases being attached with -dbmap.
Omitting this option leaves all external references unchanged. Any such external reference is valid only if the referenced or related object exists and is of the correct type.
This option is ignored if you also specify the -catalogonly option.
-readonly
Attaches the database file as a read-only database. When a database is read-only, all requests for read locks are automatically granted and all requests for update locks are automatically refused, independently of the lock server. You can omit this option to attach the database as a read/write database. After the database is attached, you can change its access status using oochangedb.
-tidy
Consolidates the disk space for each database that is being attached with a new identifier. Changing a database’s identifier increases the size of the database due to adjustments made to object identifiers, references, and so on. This option minimizes the impact of these adjustments.
-standalone
Nonconcurrent mode. Use this option only if the lock server for the specified federated database or autonomous partition is stopped. If the lock server is running, the tool reports an error and terminates.
-notitle
Suppresses the copyright notice and program title banner. Useful when invoking the tool from another tool or product.
-quiet
Suppresses all normal program output.
-help
Prints the tool syntax and definition to the screen.
bootFilePath
Path to the boot file of the federated database to which the database is to be attached. You can omit this argument if you set the OO_FD_BOOT environment variable to the correct path. (HA) Specify the boot file of the autonomous partition that is to control the attached database.
Discussion
Objectivity/DB checks whether a valid database file exists in the specified location(s). It is your responsibility to ensure that the schema of the destination federated database is identical to (or a superset of) the schema of each database being attached. If you are attaching a database that has external containers, the database file and relevant container files must be in the same directory. (Copying the database first accomplishes this.)
By default, ooattachdb leaves external references unchanged, so that objects in a database being attached may have relationships (associations) or reference attributes referring to objects in other databases. Such external references are valid if the referenced or related objects exist either in the destination federated database or in some other database being attached with the -dbmap option. You can avoid invalid external references by specifying the -nullifyexternals option, which causes ooattachdb to set every external reference in the attached database(s) to 0.
A database identifier is a component of the object identifiers (OIDs) of objects in the database. By default, Objectivity/DB automatically adjusts the following items if you attach one or more databases with new database identifiers:
n
The object identifiers of all objects within each attached database
n
Any relationships (associations) or reference attributes that exist among objects within each attached database
n
Any relationships (associations) or reference attributes that exist among objects in different databases attached as a group through the -dbmap option
However, Objectivity/DB does not attempt to find and adjust references that may exist from objects in the destination federated database to objects in the databases being attached.
Warning: Adjustments to object identifiers are not made if you specify the -catalogonly option, which prevents ooattachdb from opening any database files. When specifying -catalogonly, you must ensure that every database is attached with its original identifier; otherwise, Objectivity/DB will not be able to find objects in the attached database.
The adjustments made to accommodate a new identifier increase the database’s size. Use the -tidy option to minimize the impact of these adjustments.
When you attach a database to a federated database that has indexes, and the attached database contains objects of an indexed class, ooattachdb automatically updates all of the relevant indexes. Indexes are not updated when you specify -catalogonly.
If you are maintaining old pre-Release 9.0 federated databases as well as creating new Release 9.0 (or later) federated databases, note that:
n
You can use ooattachdb to mix old and new databases in a new federated database. More specifically, a database that uses the pre-Release 9.0 internal format can be attached to a Release 9.0 (or later) federated database.
n
You cannot use ooattachdb to attach new databases to an old federated database. More specifically, a database that uses the Release 9.0 (or later) internal format cannot be attached to a pre-Release 9.0 federated database.
The internal database format refers to the implementation of catalogs, and may affect the behavior of an application; see the appendix on accessing earlier databases in the documentation for your Objectivity/DB programming interface.
See also

Date: 
Tuesday, October 30, 2012
Product: 
Objectivity/DB
Version: 
10.2.1
10.2
10.1.4
10.1.2
9.4.1