Administration Tools - ooimport

Printer-friendly version
Interprets the specified XML document and populates an existing federated database accordingly.
-infile fileName
[-nullifyexternals | -norefcheck]
[[-tmpdirhost hostName] -tmpdirpath dirPath]
[-schemalock lockVal]
-infile fileName
Base name of the file or files containing the XML document to be imported. You may optionally include a path to the directory containing the files; if you do not include a path, the files must reside in the directory in which you run ooimport.
The specified fileName should not include a file extension or suffix. Rather, fileName is sufficient to designate an XML document contained in one or more files, where the first or only file is called filename.xml, and any subsequent files are numbered sequentially, starting with filename_2.xml. Furthermore, when catalog information is being imported, fileName also designates an install file called filenameInstall.xml (if there is one) in the same directory as the XML-document files.
The input files for ooimport are typically the output of an Objectivity/DB export tool (ooexportfd, ooexportdata, ooexportschema, or ooexportcatalog); however, you can specify any XML document that conforms to the XML Schema for Objectivity/DB data. This XML Schema is located in a subdirectory of your Objectivity/DB installation directory (installDir):
On Windows
installDir \etc\objy.xsd
installDir / arch /etc/objy.xsd, where arch is the subdirectory for your UNIX architecture
Permits the import operation to add new class descriptions to the schema of a destination federated database. This option is required only if the destination schema already contains application-defined classes; the purpose of this option is to confirm that additions to the schema are intentional.
When you omit this option, the import operation proceeds only if the imported schema is identical to (or a subset of) the schema in the destination federated database or if the destination federated database is newly created (so its schema contains only Objectivity/DB internal classes). Otherwise, ooimport reports an error and terminates.
You normally use this option to import a schema containing new class descriptions that will be needed by imported persistent objects. A new class description is not added if its class name or type number matches any existing class in the destination schema. An error is reported if an imported class has the same name as existing class, but a different type number; or if an imported class has the same type number as an existing class, but a different name.
Preserves the source identifier of each database, container, and basic object created by ooimport in a destination federated database. (Identifiers of autonomous partitions are not preserved.)
If you are importing catalog information, databases with the original identifiers are created as part of the import operation. If you are importing data without catalog information, you must first ensure that databases with the required identifiers and system names already exist in the destination federated database; if necessary, you must create or attach such databases. Within these databases, ooimport will automatically create any new containers, pages, or slots with the required identifiers as necessary.
When you omit this option, the import operation preserves the clustering of basic objects among containers, but without requiring the identifiers of the destination storage locations to match the identifiers of the corresponding source storage locations. (Corresponding source and destination system names must match, however.) This allows basic objects to be “repacked” within their containers. Repacking basic objects normally changes the page and slot components of OIDs.
When -preserveoids is specified, ooimport reports an error and quits if any of the following is true:
A database with a required identifier does not already exist in the destination federated database (and the imported XML document does not contain a catalog representation for such a database).
An OID conflict is detected—that is, the destination federated database already contains an object that has the same OID as an object being imported.
A slot with the required identifier cannot be created on a page—for example, because the page size of the destination database is too small.
Note: When -preserveoids is specified, you must ensure that the storage-page sizes of the destination databases are large enough to enable each storage page to accommodate the imported basic objects that need to be created on it. The storage-page size of a destination database must be larger than that of the corresponding source database in the following cases:
If the client-host architecture running ooimport uses the 64-bit addressing mode, and the original source objects were stored on pages owned by a 32-bit architecture. Each new imported basic object will require additional storage space when it is created on a page owned by the 64-bit architecture. The amount of additional space required depends on the data itself.
If any original source object was redirected after schema evolution in the source federated database. Redirection occurs when a basic object of an evolved class no longer fits in its original storage location due to an increase in the class’s size. Such an object is moved to a page with more space, and a link to its new location is maintained by a redirection stub left in the original location. The import operation eliminates all redirection stubs, creating each new imported object on the page indicated by its object identifier. Such pages in the destination database may become overcrowded if they are the same size as pages in the source database.
Sets any reference attributes and relationships (associations) that link imported persistent objects to each other, but sets all external references to null. An external reference is a reference attribute or relationship that would link an imported object to one or more objects that are not being imported. A warning is reported for each nullified attribute or relationship.
Omitting this option causes ooimport to try to set all reference attributes and relationships, including external references. However, an external reference is set only if it is valid—that is, if the referenced or related object exists in the destination federated database and is of the correct type. If an invalid reference is encountered, ooimport reports an error and terminates.
Specifying this option makes the import operation faster by limiting it to reconstructing just the reference attributes and relationships that are easily validated—specifically, those that create links among the set of objects being imported. External references are set to null, even those that might be valid.
Sets the reference attributes of imported persistent objects without checking for referential integrity—that is, without checking for the existence of the objects being referenced.
Omitting this option causes ooimport to check for referential integrity, so a reference attribute is set only if the referenced object exists and is of the correct type; otherwise, ooimport reports an error and terminates.
Note: This option suppresses checking only for reference attributes. Relationships (associations) are always checked for referential integrity before being set, whether not you specify this option.
Checking for referential integrity is especially important when you are importing persistent objects with external reference attributes (where the referenced objects are not among the objects you are importing). Thus, omitting this option ensures that all external references point to existing objects within the destination federated database. However, if you are importing objects with a large number of external references, and you know that these references will be valid in the destination federated database, you can consider using this option to make the import operation faster.
Warning: Do not use the -norefcheck option unless you can guarantee that all external references are valid. Otherwise, specifying this option could result in a loss of referential integrity in your data.
Specifying this option has no significant effect when you are importing persistent objects that reference other imported persistent objects.
(HA) Ignores any autonomous partitions represented in the imported XML document. All imported databases are placed under the control of the destination federated database or autonomous partition specified by bootFilePath. If multiple images of a replicated database are represented in the imported XML document, the import operation uses the first such image encountered in the XML document.
You can omit this option to reconstruct autonomous partitions according to the install file corresponding to the specified XML document.
Note: Specifying -collapsepartitions causes ooimport to bypass any information about partitions in the install file corresponding to the specified XML document.
-tmpdirhost hostName
Host on which to create a temporary file. If you omit this option, the default host is:
The host on which you are running this tool, if -tmpdirpath specifies a local path.
The host implied by -tmpdirpath, if an NFS mount name is specified.
If -tmpdirpath specifies a Windows UNC share name, hostName is set to the literal string oo_local_host; any value you specify is ignored.
-tmpdirpath dirPath
Path to the directory on the designated host in which to create a temporary file. If the -tmpdirhost option specifies a remote system, dirPath must be full, not relative. If you omit both the -tmpdirhost and -tmpdirpath options, the temporary file is created in the directory containing the system-database file of the federated database or autonomous partition specified by bootFilePath.
-schemalock lockVal
64-bit unsigned integer key for unlocking the schema for this import operation. You can normally omit this option because, by default, the schema is not locked. This option is required only if you have explicitly locked the schema of a federated database using Objectivity/DB Active Schema.
Nonconcurrent mode. Use this option if no lock server is running or to bypass a running lock server.
Warning: Corruption can occur if concurrent access to the federated database is attempted while any process is using this mode.
Suppresses the copyright notice and program title banner. Useful when invoking the tool from another tool or product.
Suppresses all normal program output.
Prints the tool syntax and definition to the screen.
Path to the boot file of the destination federated database. You can omit this argument if you set the OO_FD_BOOT environment variable to the correct path. (HA) You can specify the boot file of any autonomous partition.
This tool interprets the specified Extensible Markup Language (XML) document and populates the destination federated database accordingly. For example, if you specify an XML document produced by ooexportfd, the destination federated database is populated with the persistent objects, schema, and global catalog of the source federated database.
You can use ooimport to fully populate an empty federated database or to add to an existing populated federated database. Depending on the XML elements present in the specified XML document, ooimport may create:
Persistent objects.
Schema descriptions of new classes.
Global-catalog entries for new databases or (HA) autonomous partitions, along with the corresponding files. Note: Because all containers are currently exported as embedded containers, ooimport does not create any container files.
Warning: Always make a backup of your federated database before you perform an import operation.
An import operation may add new items (or new versions of existing items) to a federated database, and never deletes or overwrites existing items. However, an import operation is performed in multiple transactions. Therefore, if ooimport quits with an error, the partial import may leave your federated database in an inconsistent state. In most cases, you can simply correct the error and then run ooimport again; the import operation will pick up where it left off. A backup is essential because you cannot roll back any portion of the import that has already been committed.
When ooimport creates new databases or (HA) autonomous partitions from an imported global catalog, their filenames are generated and their file locations are determined by the install file generated for the specified XML document. Before running ooimport, you can edit the install file to specify the desired host and directory for each file to be created, in addition to changing other catalog information. If you do not edit the install file (or if the install file is moved or deleted), the default import operation creates all files in the same directory as the system-database file of the specified federated database or boot partition.
Note: ooimport currently creates all containers as embedded containers, including those originally exported from external containers in separate container files.
When importing only data (without catalog or schema information), you must first ensure that the destination federated database has:
A schema that is identical to (or a superset of) that of the source federated database from which the data was exported.
An existing database corresponding to each source database from which data was exported; the corresponding pairs of source and destination databases must have matching system names (and identifiers, if the -preserveoids option is specified).
You can prepare an empty federated database by importing schema and catalog information that were previously exported from the source federated database. ooimport accepts XML documents representing data from all databases or from an individual database (but not just data from a single container or a single basic object).
By default, ooimport preserves the relative clustering of basic objects within containers, but does not preserve the original object identifiers (OIDs). Instead, basic objects are “repacked” (written to consecutive slots on consecutive logical pages within their containers). Reference attributes and relationships (associations) that create links among imported objects are automatically adjusted to reflect the new OIDs. You can specify the -preserveoids option to guarantee that all imported objects keep their original OIDs.
Note: Although ooimport always adjusts the OIDs that link a persistent collection to its elements, the sort order of the collection is not adjusted, even if the sort order is based on the elements’ OIDs. You should consider specifying -preserveoids if you are importing data that includes persistent collections.
By default, ooimport creates a new basic object in the destination federated database for every basic object represented in the imported XML document; if an imported object originally had the same OID as an existing object in the destination federated database, the imported object is simply assigned a different OID. If -preserveoids is specified and an OID conflict is detected, ooimport quits with an error.
By default, an imported database is merged with an existing database if their system names match; the identifiers of the merged databases need not match. An imported container is merged with an existing container if they are both named and their system names match, or if they are both unnamed and their identifiers match. If -preserveoids is specified, identifiers are considered along with system names.
By default, external references (attributes and relationships that reference objects not in the XML document) are set to their exported values if referential integrity can be maintained; otherwise, ooimport reports an error and terminates. You can request different treatment of external references by using either the -nullifyexternals or -norefcheck option.
By default, an entire schema is imported only into a newly created destination federated database (where the schema contains no application-defined classes). You must specify the -addnewclasses option to enable ooimport to add new classes into a populated destination schema.
ooimport reports an error and terminates if the imported schema contains any descriptions that would change an existing class in the destination schema. Use ooschemadump and ooschemaupgrade for schema-evolution operations.
For schema consistency, ooimport allows you to import either an entire schema or the entire set of application-defined classes in a schema. ooimport reports an error and terminates if the specified XML document represents just a single class (the output of ooexportschema -class).
An XML document exported from a pre-Release 9.0 federated database can be imported into a Release 9.0 (or later) federated database. Any databases created by ooimport will have the new Release 9.0 (or later) internal database format. 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

Tuesday, October 30, 2012