INCBUILDDIM

Build one or more dimensions from a data file, without restructuring the database. This command is designed to be used when building an outline from multiple data sources. You can save time by deferring restructure. Deferred-restructure dimension building is also called incremental dimension building.

Syntax

INCBUILDDIM location rulobjName dataLoc sourceName fileType errorLog appendLog

Parameter	Description
location	Location of the rules file. Values: 1 - Local/client-based rules file 2 - Remote/server rules file 3 - File. Use option 3 if the file is not an Essbase object, or if you want to specify the full path name. Otherwise, Essbase looks in the <APPNAME>/<DBNAME> directory.
rulobjName	Name of the rules file.
dataLoc	Location of the data file. Values: 1 - Local/client data file 2 - Remote/server data file 3 - File. Use option 3 if the file is not an Essbase object, or if you want to specify the full path name. Otherwise, Essbase looks in the <APPNAME>/<DBNAME> directory. 4 - SQL source
sourceName	Source of the data file. Values: If dataLoc is 1 or 2, specify the data file name. If dataLoc is 3, specify the data file name and path. If dataLoc is 4, specify the SQL user name and password.
fileType	Data file type. Values: 1 - Excel file 2 - Lotus .WK1 file (No longer supported) 3 - Lotus .WK3 file (No longer supported) 4 - Text file 5 - Lotus .WK4 file (No longer supported). This parameter is not required if you are using an SQL source.
errorLog	Name of text file to receive error messages and rejected records. Each INCBUILDDIM command in a BEGININCBUILDDIM...ENDINCBUILDDIM block can specify a different error log.
appendLog	Specifies whether to append to the error log file or overwrite it. Values: 1 - Append 2 - Overwrite
verify	Parameter specifying whether to verify the outline resulting from the deferred-restructure dimension build. Values: Y - Yes, verify the outline. This is the default. N - No, do not verify the outline.

Notes

Use a INCDIMBUILD command for each data source and rules file to be included in the dimension build. Use a BEGININCBUILDDIM command at the beginning of a group of INCDIMBUILD comands. Use an ENDINCGULDDIM command at the end of the group of INCBUILDDIM commands.

The INCBUILDDIM command changes dimensions in the .OTN file according to the specified rules file and data file. See BEGININCBUILDDIM for information on the .OTN file.

Each rules file can build one or more dimensions. If a rules files builds multiple dimensions and an error occurs in a record for any dimension, Essbase rejects the entire record. As a result, other dimensions represented in that record might not build correctly. Consider designing dimension builds with multiple rules files using INCBUILDDIM.

An example of this problem relates to the Add as Child build method. Break the rules file into multiple rules files if both of the following circumstances apply:

The rules and data files specify more than one Add as Child member per record.
One of the members being added already exists in the outline as a child of any other parent.

Consider, for example, adding Mbr1 and Mbr2 as children of Par1 and Par2:

Par1    Par2
    Mbr1    Mbr2

If Mbr1 already exists in the outline as the child of some other parent than Par1, you need to break the rules file into two separate builds. Otherwise, when Essbase sees that the member already exists in the outline, it rejects the entire record.

By default, each step of a deferred-restructure dimension build must produce a valid outline. You can use the verify N parameter to create an interim outline that is not valid and then update the outline in a subsequent INCBUILDDIM command to ensure the outline is valid. To verify the outline in a subsequent INCBUILDDIM command, remove the verify parameter or specify a Y. Make sure that the last INCBUILDDIM command verifies the outline.

INCBUILDDIM is identical to BUILDDIM, except for the following:

INCBUILDDIM does not automatically restructure the database after modifying the dimensions. You can have several consecutive INCBUILDDIM commands inside a BEGININCBUILDDIM...ENDINCBUILDDIM block. Essbase restructures when it encounters ENDINCBUILDDIM.
INCBUILDDIM enables you to append to, rather than overwrite, the error log.
BUILDDIM does not enable you to bypass outline verification.

Example

Example 1

The following command builds the dimensions specified in GENREF.RUL and LEVELMUL.RUL, discards all data, and saves the new outline after the dimension builds are complete:

BEGININCBUILDDIM;
    INCBUILDDIM 2 "GENREF.RUL" 2 "GENREF.TXT" 4 "ERR.OUT" 1  "N";
    INCBUILDDIM 2 "LEVELMUL.RUL" 2 "LEVELMUL.TXT" 4 "ERR.OUT" 1 "Y";
    ENDINCBUILDDIM 4;

Note that you can use the same rules file with multiple data files, providing the data files conform to the formatting and rules saved in the rules file. For example:

BEGININCBUILDDIM
    INCBUILDDIM 2 "GENREF.RUL" 2 "GENREF1.TXT" 4 "ERR.OUT" 2 "N";
    INCBUILDDIM 2 "GENREF.RUL" 2 "GENREF2.TXT" 4 "ERR.OUT" 1 "N";
    INCBUILDDIM 2 "GENREF.RUL" 2 "GENREF3.TXT" 4 "ERR.OUT" 1 "Y";
    ENDINCBUILDDIM 4;

Example 2

The following Windows example imports dimensions from a server based text file, using a server based rules file, and specifies an error file.

INCBUILDDIM 2 "Genref.rul" 2 "Genref.txt"  4 "c:\valscrt.ERR" 2;