![]() Previous |
![]() Next |
You can use the IMPORT (from EIF) command to copy data and definitions into your Oracle OLAP analytic workspace from an EIF file. IMPORT also copies any dimensions of the imported data that do not already exist in your workspace, even when you do not specify them in the command.
Tip: Several options that determine how EIF files are imported and exported. These options are listed in "EIF Options". |
IMPORT (from EIF) is commonly used with EXPORT (EIF) to copy parts of one Oracle OLAP analytic workspace to another; you export objects from the source workspace to an EIF file and then import the objects from the EIF file into the target workspace. The source and target workspaces can reside on the same platform or on different platforms. When you transfer an EIF file between computers, you use a binary transfer to overcome file-format incompatibilities between platforms. The EIF file must have been created with the EIFVERSION set to a version that is less than or equal to the version number of the target workspace. Use EVERSION to verify the target version number.
You can also use IMPORT to store information in the EIFNAMES and EIFTYPES options.
Syntax
IMPORT import_item FROM EIF FILE file-id [INTO workspace] -
[MATCH [STATUS]|APPEND|REPLACE [DELETE]] [LIST [ONLY]] [DATA] -
[DFNS] [UPDATE] [NOPROP] [NASKIP] [NLS_CHARSET charset-exp] -
[API | NOAPI]
where import_item is one of the following:
Parameters
The name of an analytic workspace object to be imported from an EIF file to an attached workspace. You cannot specify a qualified object name for the object, because the object is not yet in any workspace. You can list multiple names at a time. See the INTO workspace argument for information about where the object is imported.
AS newname can be used to rename any type of object being imported except dimensions.
When you have exported a multidimensional object as separate variables, list all the variable names. (See the SCATTER AS keyword in the EXPORT (EIF).)
(Default) Indicates that you want to import all the objects contained in the EIF file. See the INTO workspace argument for information about where the objects is imported.
an analytic workspace name that identifies the attached workspace into which objects is imported. When the objects exist in the specified workspace, then their data is overwritten by the imported data. When the objects do not already exist, IMPORT creates them it in the specified workspace. IMPORT ignores identically named objects when they exist in other attached workspaces.
When you do not specify this argument, then Oracle OLAP does the following:
When you have not previously defined the objects being imported in an attached workspace, then IMPORT defines them automatically in the current workspace.
When the objects already exist in any attached workspace, then IMPORT overwrites the data they contain with the imported data.
Identifies the file you want to import. File-id is a text expression that represents the name of the file. The name must be in a standard format for a file identifier.
Indicates that the IMPORT command should bring in only the data associated with dimension values that match those already in the target workspace. For dimensions other than time dimensions, ensure that corresponding dimension values are spelled and capitalized identically in the EIF file and your target workspace when you want them to match; for example, Tents
does not match TENTS
. For time dimensions, Oracle OLAP identifies dimension values by the dates they represent rather than by the way they are displayed. Therefore, time dimension values in the EIF file automatically matches time dimension values in your workspace when they represent the same time periods. When you specify MATCH STATUS, IMPORT only imports data associated with the values included in the current status of that dimension. When the dimension is limited in the target workspace, Oracle OLAP ignores any data in the EIF file associated with the values excluded from the status.
(Default) Indicates that the IMPORT command should bring in all the dimension values, along with associated data, regardless of whether or not the dimension values match those already present in the target workspace. APPEND adds those that do not match to those already present; it adds new values to the end of the list of dimension values. For time dimensions, APPEND also adds dimension values to fill in any gaps between the dimension values in your target workspace and the new ones.
Indicates that, for objects already defined in the workspace, IMPORT should keep the existing dimension values that match the dimension values in the EIF file. IMPORT deletes dimension values (and their data) that do not match dimension values in the EIF file. IMPORT replaces the associated data for the dimension values kept as part of the new dimension when the associated data variables are included in the EIF file. For text dimensions, the order of the dimension values in the EIF file is also adapted.
When you specify REPLACE DELETE, no matching takes place. Before importing a dimension, Oracle OLAP performs a MAINTAIN DELETE ALL, which discards all data associated with the existing dimension and the dimension values.
Important: Be careful when using the REPLACE keyword. When you replace the values of a dimension, all variables and relations in the target workspace dimensioned by it are affected. When a variable or relation is not being imported at the same time, replacing the values of one of its dimensions could result in the loss of its data. |
Produces a list of the definitions. For dimensions, the output lists the number of values in each dimension, as they are imported into the target workspace. For composites, the output lists the number of dimension value combinations. IMPORT also indicates the number of bytes read and the elapsed time every two minutes or, in any case, after the import procedure.
When you define a conjoint or composite that uses an index type other than the default, the IMPORT LIST command displays the index type. When you use the default index type (HASH for conjoints, BTREE for composites), that information is not displayed.
EXPORT (EIF) sends the list to the current outfile. When you specify LIST ONLY, you get only the listing without actually importing anything.
Causes Oracle OLAP to place the correct values in the EIFNAMES and EIFTYPES options without actually importing them. However, Oracle OLAP does not produce a full listing of the object definitions. To produce the list, specify the LIST keyword before the ONLY keyword.
Indicates that, for objects that already exist in the target workspace, IMPORT should update only the data associated with those objects. For formulas that already exist, IMPORT updates their EQ expressions. Objects that IMPORT creates in the target workspace are created with their full definitions and any associated data. You can specify both DATA and DFNS, but when neither is specified, the default is DATA.
Indicates that, for objects that already exist in the target workspace, IMPORT should just update definitions and leave data unchanged. The components of the definition affected by IMPORT DFNS are: LD Command, VNF, and PROPERTY. Objects that IMPORT creates in the target workspace still get their data. You can specify both DATA and DFNS, but when neither is specified, the default is DATA.
Indicates that IMPORT should execute an UPDATE statement after importing each object which can be useful when importing large EIF files that would otherwise cause Oracle OLAP to run out of memory. To control the frequency of updates, use the EIFUPDBYTES option.
Prevents any properties that you have assigned to each object from being read from the EIF file.
Specifies that composite tuples (indexes) that contain only NA
data should not be imported into the target workspace. This argument has no effect on tuples that already exist in the workspace.
Specifies the character set that Oracle OLAP uses when importing text data from the file specified by file-id. Normally, an EIF file contains its own specification of its character set, so that this argument is not needed. However, when the EIF file specifies the character set incorrectly or is missing the character set specification, then you must use this argument to specify the character set correctly.
For information about the character sets that you can specify, see Oracle Database Globalization Support Guide.
This argument must be the last one specified. When this argument is omitted, and Oracle OLAP cannot determine the character set from the EIF file itself, then Oracle OLAP imports the data using the database character set, which is recorded in the NLS_LANG option.
(Default) When the EIF file was created using an EXPORT (EIF) command with the API keyword, import any cube metadata defined for the specified items.
Note: Oracle OLAP automatically executes an UPDATE and a COMMIT after executing this type of import. |
Even if the EIF file was created using an EXPORT (EIF) command with the API keyword, do not import any cube metadata defined for the specified items. When you specify this keyword, Oracle OLAP does not automatically execute an UPDATE and a COMMIT after executing the IMPORT command.
Usage Notes
Separate IMPORT Statements
The MATCH, APPEND, REPLACE, DATA, and DFNS arguments you specify affect all the objects you name to be imported. When you want to treat different objects in different ways, use separate IMPORT statements.
Importing and Exporting Hidden Programs
Importing Relations
When you are importing a relation, IMPORT also brings in the definition and values for the related dimension as well.
Importing Concat Dimensions
When you import a concat dimension into an analytic workspace and the concat dimension and none of its component dimensions already exist in the analytic workspace, then Oracle OLAP imports the concat dimension, its component dimensions, and the definitions of all of the dimensions.
When you import a concat dimension that does not already exist but one or more of its component dimensions already exist in the analytic workspace, then Oracle OLAP imports the concat dimension and any new component dimensions and their definitions. For the component dimensions that already exist in the analytic workspace, Oracle OLAP imports the component dimensions as it does other dimensions, obeying any MATCH, APPEND, REPLACE specifications in the IMPORT statement.
When you import a concat dimension with a name and a definition of a concat dimension that already exists in the analytic workspace, then Oracle OLAP imports the concat dimension as it does other dimension.
When you import a concat dimension with the same name as one that already exists in the analytic workspace but the definition of the imported concat dimension is different than the definition of the existing concat dimension, then the definition of the existing concat dimension does not change and the definitions of the component dimensions of the existing concat dimension do not change. Only the component dimensions of the imported concat dimension that are also component dimensions of the existing concat dimension are imported. When the imported concat dimension does not share any component dimensions with the existing concat dimension, an error condition occurs. When you are importing any objects that are dimensioned by the concat dimension, then Oracle OLAP imports only the values of the object that correspond to the values of the imported dimensions.
Importing and Exporting Dimension Surrogates
You can import or export a dimension surrogate to or from an Express Interchange File (EIF). In those operations, a dimension surrogate behaves like a variable that is dimensioned by the dimension of the surrogate. In an EXPORT operation, the dimension for which the surrogate is defined is also exported. In an IMPORT operation, the dimension for which the surrogate is defined is imported but you can use the MATCH, STATUS, DATA, DFNS, APPEND, and REPLACE keywords to affect which values are imported.
Importing a dimension surrogates also imports the definition and values for the dimension for which it is a surrogate. When a dimension with the same definition already exists in the current analytic workspace, then the effects of the IMPORT keywords such as MATCH, APPEND, REPLACE, DATA, and DFNS are the same for the surrogate as they would be for a variable dimensioned by the dimension. When the name and definition of the imported surrogate is the same as a dimension surrogate that already exists in the current analytic workspace and when the imported surrogate has a value that is identical to a value in the existing surrogate, an error condition occurs.
You can import an INTEGER dimension surrogate when no object of the same name exists in the current analytic workspace or when you use the DFNS keyword. Importing an INTEGER dimension surrogate affects existing INTEGER dimension surrogates when the implicit importing of the dimension of the imported surrogate changes the values of the existing dimension.
APPEND Versus REPLACE
When you are importing an INTEGER dimension that already exists in your target workspace, the following considerations apply.
When the imported INTEGER dimension is larger than the existing one, APPEND and REPLACE have the same effect. The dimension ends up with the number of values in the larger, imported dimension.
When the imported INTEGER dimension is smaller, REPLACE drops the appropriate dimension values from the end of the dimension, along with any associated data, while APPEND leaves the existing dimension values alone.
INTEGER and SHORTINTEGER Data Types
The IMPORT command translates between the INTEGER and SHORTINTEGER data types. When you are importing a variable with one of these data types from an EIF file and it already exists in your workspace as the other type, Oracle OLAP converts the data automatically. The maximum SHORTINTEGER value is 32,767
and the minimum is -32,767
. When you import an INTEGER value that exceeds these limits into a SHORTINTEGER variable, the result is NA
.
TEXT and ID Data Types
When the EIF file you are importing contains ID data that you want to import into TEXT dimensions, variables, relations, or valuesets, Oracle OLAP automatically converts the ID data to text during the import process.
Existing Programs and Models
When you are importing a program or model that already exists in your workspace, you must specify DFNS. A program or a model is a definition only; it does not have any data. The default option DATA does not import the source code when it already exists.
When you define a program, you may specify a data type or a dimension name, which is used when the program is called as a function. When you specify a data type, it determines the data type of the return value. When you specify a dimension name, the return value is a single value of that dimension. When you import an existing program, the data type or the dimension in the imported program definition and the existing program definition must match. Otherwise, Oracle OLAP produces an error message.
PERMIT Statements
The PERMIT statements associated with an object are imported with the object definition. You can see them when you describe the object. However, permission conditions are not evaluated when the object is imported.
When an object with the same name already exists in the target workspace and you specify the DFNS keyword, the PERMIT statements for the object are updated. However, you must execute a PERMITRESET to put the new permission into effect. When an object with the same name already exists in the target workspace and you do not specify the DFNS keyword, the PERMIT statements for the object are not updated. When there is no pre-existing object in the target workspace, and you import with or without the DFNS keyword, the PERMIT statements for the object are updated, but you must execute a PERMITRESET to put the new permission into effect. (See the PERMIT command.)
When you export and import an entire workspace, then update, detach, and reattach the workspace, Oracle OLAP ensures that all the permissions that were in effect before exporting are in place in the target workspace.
Reducing Workspace Size
You can use IMPORT with an EXPORT statement to compact an entire workspace at once. To do this, first export the workspace and then import it under a different name. You can then delete the old workspace and rename the new one with the original name.
Preserving Conjoint Type
When you export a HASH, BTREE, or NOHASH conjoint dimension to an EIF file, the conjoint type is exported along with the definition in the EIF file. When you then import the conjoint dimension into an analytic workspace, Oracle OLAP preserves the conjoint type when you import into a new dimension or a dimension already using that conjoint type. When you import the dimension into an existing dimension that does not use the same conjoint type, Oracle OLAP does not preserve the original conjoint type that was saved in the EIF file.
EIFBYTES, EIFNAMES, and EIFTYPES
You can use the EIFBYTES option to learn the number of bytes read or written by the most recent IMPORT (EIF File) statement. You can use the EIFNAMES option to get a list of the names of all the objects imported by the most recent IMPORT statement and use the EIFTYPES option to learn the types of objects in that list.
The following format causes IMPORT to store information about the specified objects into the EIFNAMES and EIFTYPES options without actually importing the objects. IMPORT places a list of the object names specified by the IMPORT command in the EIFNAMES option. IMPORT also places a list of the type of each object listed in EIFNAMES into the EIFTYPES option. You may use the LIST keyword to send to the current outfile a full listing of the object definitions.
IMPORT name FROM EIF FILE file-id [LIST] ONLY
For more information, see the entries for EIFBYTES, EIFNAMES, and EIFTYPES options.
Importing Unnamed Composites
When you define variables or other objects with the SPARSE keyword in the dimension list, Oracle OLAP creates an unnamed composite that corresponds to the SPARSE dimension list. When you export or import an object with the unnamed composite in its definition, the composite is automatically exported or imported with the object. Since the unnamed composite is not a regular workspace object, you cannot import or export it independently.
Variable Segments Specified with SEGWIDTH
When you use a CHGDFN statement with the SEGWIDTH keyword to specify the length of variable segments, segment information cannot be exported and imported automatically. You can save your SEGWIDTH settings by exporting the entire workspace, creating a new workspace, importing only the workspace objects into the new workspace, specifying segmentation, and then importing the variable data into the new workspace.
Importing TEXT and NTEXT Values
You can export and import TEXT and NTEXT values. Both data types can be exported to a single EIF file.
Exported TEXT values are stored in the EIF file using the character set specified for the file in the EXPORT (EIF).
Exported NTEXT values are stored in the EIF file as NTEXT (UTF8 Unicode).
NTEXT values imported into TEXT objects are converted into the database character set which can result in data loss when the NTEXT values cannot be represented in the database character set.
TEXT values imported into NTEXT objects are converted into the NTEXT (UTF8 Unicode) character set.
Examples
Importing Dimensions from an EIF File
This example shows how to import the contents and dimensions of two variables into the current Oracle OLAP workspace from a disk file called finance.eif
in the current directory object.
IMPORT actual budget FROM EIF FILE 'finance.eif'
IIMPORTING a Concat Dimension
This example shows the result of importing a concat dimension that has a definition that is different than a concat dimension that already exists in the current analytic workspace. Suppose that a DESCRIBE statement returns the following definitions for dimensions and variables in the current analytic workspace.
DEFINE city TEXT DIMENSION DEFINE state TEXT DIMENSION DEFINE country TEXT DIMENSION DEFINE locality DIMENSION CONCAT (city, state) DEFINE geog DIMENSION CONCAT (locality, country) DEFINE sales INTEGER VARIABLE <geog>
The following statement reports the sales
data.
REPORT sales
The preceding statement produces the following results.
GEOG SALES ------------------- ----- <city: Boston> 1000 <city: Springfield> 2000 <state: Ma> 3000 <country: Usa> 4000
A DESCRIBE statement returns the following definitions for dimensions and variables in the diffconcat.eif
file.
DEFINE CITY TEXT DIMENSION DEFINE REGION TEXT DIMENSION DEFINE COUNTRY TEXT DIMENSION DEFINE GEOG DIMENSION CONCAT (CITY, REGION, COUNTRY) DEFINE SALES INTEGER VARIABLE <GEOG>
The following statement reports the sales
data for the dimension values in the analytic workspace from which you exported the concat dimension that is in the diffconcat.eif
file.
REPORT sales
The preceding statement produces the following results.
GEOG SALES ------------------ ----- <city: Boston> 1111 <city: Worcester> 2222 <region: East> 3333 <country: Usa> 4444
The following statement imports the sales
variable from the diffconcat.eif
file and implicitly imports the concat dimension geog
. The APPEND keyword causes Oracle OLAP to add the value Worcester
to the city
dimension. After that, it imports new values for sales
that correspond to <city: Boston>
, <city: Worcester>
, and <country: Usa>
.
IMPORT sales FROM EIF FILE diffconcat.eif APPEND
After the import operation, reporting the SALES values produces the following results.
GEOG SALES ------------------- ----- <city: Boston> 1111 <city: Springfield> 2000 <city: Worcester> 2222 <state: Ma> 3000 <country: Usa> 4444