You can invoke Transformer from the command line to populate models, create cubes, and perform other actions. How and where these actions are performed is determined by information that you provide.
You can control specific operating characteristics of Transformer by creating user preference files or by setting up environment variables, or by overriding either of these from the command line.
The settings contain information such as default directories for various classes of files that Transformer uses or creates.
All preference file settings can be used as environment variables, and you can use multiple preference files.
Transformer searches for settings in the following sequence:
cogtr.xml in the IBM Cognos configuration directory
environment variables
the -d or -f command line option
Note: If the command line contains both -d and -f, Transformer uses the one that appears last.
Environment variables override settings in any preference file, and command line options override environment variable settings.
For example, to override the directory where source files are read, you can include the following UNIX environment variable definition in the *.sh file:
DataSourceDirectory=$HOME/data; export $HOME/data
To use the command line to override the setting for the directory where the source files are read, start Transformer using the following command:
cogtr -dDataSourceDirectory=$HOME/data
Consider the following:
Preference file syntax does not allow a space between -d and its preference_var argument.
In preference files, blank characters, tab characters, and lines beginning with the number sign (#) are ignored.
In most cases, preference files that contain invalid options are ignored, and an error message is written to the log file. For example, this error-handling applies if the preference file entry for the ModelSaveDirectory is incorrect. However, if the entry for CubeSaveDirectory is incorrect, the variable is ignored but no log file entry is added; if the ChildRatioThreshold entry is outside its acceptable range, the invalid setting is changed at runtime, to either its maximum or minimum value depending on which value is closest to the incorrect setting.
Each environment variable must be defined before it is used in a command, and must be preceded by a dollar character ($). Optionally, braces ({}) may be used to enclose the environment variable name.
The environment variable must be alphanumeric (ASCII-text format), and may contain an underscore (_).
Special environment variable characters, such as $, {, or }, may appear in a file name or directory string if they are preceded by the escape character (\). This backslash is automatically removed before the string is used. For example, a pair of backslash characters (\\) is replaced by one backslash.
Variable substitution is not performed on the values of environment variables.
The following are preference file entries you can set for Transformer.
Note: In the following lists of preferences, path refers to the directory and file name. For non-Windows platforms, the default is the "temp" directory in the installation_location/c8 directory. On Windows platforms, different defaults apply as described below.
The following setting specifies where Transformer creates the temporary file while you work on your model. The default path is the value of ModelSaveDirectory. The temporary file can be used to recover a suspended model at strategic checkpoints, should a severe error occur during cube creation. This file has the extension .qy?, where the ? is replaced by the character used in your version of Transformer.
<Preference Name="ModelWorkDirectory" Value=" path1;path2;..."/>
The following setting specifies where Transformer creates temporary work files when generating cubes. The default path is the "temp" directory in the installation_location/c8 directory. Transformer creates multiple files automatically, and concatenates them into one logical file, regardless of which drive they are in.
<Preference Name="DataWorkDirectory" Value="path1;path2;..."/>
By distributing the files across multiple drives, you can work around size limitations imposed by your operating system, and reduce disk contention. The location of the files is determined by the list of paths that you specify. The files are created in the order specified in the list of paths.
For data source files other than .iqd-format files, the following setting specifies where Transformer searches for files. The default path is the data subdirectory in the installation_location/c8 directory.
<Preference Name="DataSourceDirectory" Value="path1;path2;..."/>
The following setting specifies where Transformer saves cubes. On Windows, the default is the \Transformer\PowerCubes subdirectory under your home directory. On UNIX and Linux, the default is the temp subdirectory in the installation_location/c8 directory.
<Preference Name="CubeSaveDirectory" Value="path1;path2;..."/>
The following setting specifies where Transformer saves models. On Windows, the default is the \Transformer\Models subdirectory under your home directory. On UNIX and Linux, the default is the temp subdirectory in the installation_location/c8 directory. If you are running Transformer with an .mdl file and you have specified the -s option, a .py? file is created in this directory. (The ? in the extension .py? is replaced by the character used in your version of Transformer, such as .pyj for versions 8.3 and 8.4.)
<Preference Name="ModelSaveDirectory" Value="path"/>
The following setting specifies the threshold number of bytes at which Transformer splits its work files. The minimum is 1000000000 and the maximum is 1500000000. The default value is 1500000000.
WorkFileMaxSize
The following setting specifies a value that determines one of the following options:
the creation of a single cube that is larger than 2 GB
the threshold at which multiple files are created for a very large cube; for example, 30,000,000 if your cube is still less than 2 GB or 1,000,000 to create smaller cubes
MultiFileCubeThreshold
This multiple-file cube has one file with the .mdc extension and one or more files with the .mdp (multi-dimension partition) extension. The cube cannot be compressed. The default MultiFileCubeThreshold value is 0, which signifies that multiple file generation is disabled.
The following settings control where and how Transformer writes information to an ASCII-text log file.
The following setting specifies where Transformer creates the log file. On Windows, the default is the \Transformer\logs subdirectory under your home directory. On UNIX and Linux, the default is the temp subdirectory in the installation_location/c8 directory. If the logs subdirectory does not exist, then the default is the current working directory.
<Preference Name="LogFileDirectory" Value="path"/>
The following setting specifies a file name if you want messages written to a file, rather than displayed on the screen. The file name can include the full path. By default, this file has the same name as the model file, but with a .log extension.
<Preference Name="LogFileName" Value="path"/>
The following setting specifies that the log file is overwritten for each new model or cube. A value of TRUE appends the new log data to the existing log file.
<Preference Name="LogFileAppend" Value="FALSE"/>
The following setting specifies the types of messages that are written to the log file. Choose from the following severity levels:
<Preference Name="LogDetailLevel" Value="4"/>
0 - suppresses logging
1 - includes severe errors only, which must result in corrupted files or inconsistent data
These can arise if limits are exceeded for CPU, disk, file, or transaction resources, or if the model, cubes, or temporary files have been corrupted.
2 - includes severe errors and errors that occur at the transaction level
These cause the cube to be invalid, but leave it in a consistent, possibly incomplete, state.
3 - includes severe errors and warnings indicating a potential problem
Warning messages do not impede processing.
4 - includes severe errors, errors, warnings, and informational messages (default)
You can use the log file to check the status of cube creation. The progress of a cube update is indicated by statements in the file, each containing the following fields:
date and time (24-hour clock) at which the message was issued
the message severity
the message text
The text of each message includes header information, the ID of the object being processed (in hex notation), and messages about Transformer processes and timing.
Messages marked "Timing" are especially useful to analyze as a series of processing events. You can do this by importing the log file into a spreadsheet application as a tab-and-comma-delimited file. For more information, seeRecommendation - Analyze Processing Bottlenecks Using the Log File.
You can also use the -r command line option to control the types of messages generated.
This setting specifies, in elapsed minutes, how often messages are written to the log file. The default is -1. When the setting is -1, messages are not logged. If it is set to 0, messages are written to the log file whenever they are generated:
<Preference Name="LoggingFrequency" Value="-1"/>
These settings control whether Transformer issues warnings about potential incremental update problems and ratios between categories and their descendants.
This setting issues warnings when an event is going to take place that will make an incrementally updated cube invalid; for example, deleting a category. The default value of TRUE means that warnings are issued; FALSE disables warnings.
<Preference Name="IncUpdateWarnings" Value="TRUE"/>
This setting issues a warning if the number of child categories for any parent category exceeds the specified value. Valid values are 1 through 16384. The default is 35.
<Preference Name="ChildRatioThreshold" Value="35"/>
This setting specifies how often Transformer creates checkpoints for recovery from severe errors during cube creation. This is defined as the number of records written to a cube before a new checkpoint is created. If your data sources are constructed from a database, this value shouldn't exceed the size of your database rollback journal. The default is 500000.
<Preference Name="MaxTransactionNum" Value="50000"/>
These settings specify various physical attributes of the data source files.
This setting specifies the character used as a decimal point in a data source. The default is a period (.).
<Preference Name="DecimalPoint" Value="."/>
This setting specifies the field delimiter in a delimited-text data file. The default is a comma (,).
<Preference Name="DefaultSeparator" Value=","/>
This setting specifies the character used as a thousands separator in a data source. The default is a comma (,).
<Preference Name="ThousandSeparator" Value=","/>
This setting specifies the cut-off date that determines whether the two-digit year (YY) in a six-digit date is a 20th or 21st century date. Transformer interprets values below the cut-off as 21st century dates and values at or above the cut-off as 20th century dates. The default is 20.
<Preference Name="CenturyBreak" Value="20"/>
Because 00 to 19 are automatically treated as 21st century dates and 20 to 99 as 20th century dates, you only need to change the default if your data source includes dates from 1900 to 1919. For example, the setting CenturyBreak=18 means that the values 00 to 17 are interpreted as 2000 to 2017 and the values 18 to 99 are interpreted as 1918 to 1999.
This setting controls the format in which the date is displayed:
<Preference Name="LunarFiscalLabeling" Value="TRUE"/>
It determines whether users will be able to view dates in a cube in lunar year format. The value TRUE indicates that the dates will be displayed in this format. A value of FALSE indicates that dates will be displayed in calendar year format.
The following sections describe the environment variables you can set for Transformer on UNIX and Linux. Shared library variables, and related database (RDBMS) variables server communication settings are omitted because client-server synchronization is not supported in IBM Cognos 8.
To run Transformer on UNIX or Linux, the loader requires that the library path variable specify the location of the shared libraries. The library path variable for each supported operating system is as follows.
| Operating System | Environment Variable |
| Sun Solaris | LD_LIBRARY_PATH |
| IBM AIX | LIBPATH |
| HP-UX | SHLIB_PATH |
| Linux | SHLIB_PATH |
If your data sources make use of one or more relational databases, you must install them before using Transformer. For more information, see the Installation Guide for your version of Transformer.