Preferences

This section describes the most common preference settings that you can specify for Cognos® Transformer.

Before you start specifying preferences, read the section Controlling Processing with Preference Settings or Environment Variables.

When specifying the preference settings in the installation_location/configuration/cogtr.xml file, use the installation_location/configuration/cogtr.xml.sample file as a reference.

In most cases, preference files that contain invalid options are ignored and an error message is written to the log file. This type of error-handling applies, for example, if the preference file value for the ModelSaveDirectory is incorrect. However, if the value for CubeSaveDirectory is incorrect, the variable is ignored, but no log file entry is added. If the ChildRatioThreshold value is outside its acceptable range, the invalid setting is changed at run time to either its maximum or minimum value, depending on which value is closest to the incorrect setting.

Consider the following when using the command line options to specify preferences:

  • Command line syntax does not allow a space between -d and its preference_var argument.
  • Blank characters, tab characters, and lines beginning with the number sign (#) are ignored.
Tip: For each setting listed below, path refers to the directory and file name. For non-Windows platforms, the default is the temp directory in the installation_location/c10 directory. On Windows platforms different defaults apply, as described below.

General

The following settings specify general Transformer preferences.

  • <Preference Name="AllowDQ" Value="1"/>

    This setting specifies how to process queries for the dynamic query-based packages and reports. If it is set to 1, query routing sends queries for dynamic query-based packages or reports to the dynamic mode query engine. If it is set to 0 or not specified, query routing sends all queries to the compatible mode query engine.

    Important: Queries processed by the compatible mode query engine are executed by Transformer, not by the Cognos Analytics server. Routing queries to the dynamic mode query engine results in additional processing for the Cognos Analytics server.

Directory

The following settings specify directories required by Transfomer.

  • <Preference Name="ModelWorkDirectory" Value="path1;path2;..."/>

    This setting specifies where Cognos 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 if severe errors occur during cube creation. This file has the extension .qy?, where the ? is replaced by the character used in your version of Cognos Transformer.

  • <Preference Name="DataWorkDirectory" Value="path1;path2;..."/>

    This setting specifies where Cognos Transformer creates temporary work files when generating cubes. The default path is the "temp" directory in the installation_location/c10 directory. Cognos Transformer creates multiple files automatically, and concatenates them into one logical file, regardless of which drive they are in.

    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.

  • <Preference Name="DataSourceDirectory" Value="path1;path2;..."/>

    This setting specifies where Cognos Transformer searches for data source files other than .iqd files. The default is the installation_location/c10/data directory.

  • <Preference Name="CubeSaveDirectory" Value="path1;path2;..."/>

    This setting specifies where Cognos 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/c10 directory.

  • <Preference Name="ModelSaveDirectory" Value="path"/>

    This setting specifies where Cognos 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/c10 directory.

File

  • MultiFileCubeThreshold

    This 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.

      The multifile cube contains one file with the .mdc extension, and one or more files with the multidimensional partition (.mdp) extension. This type of cube cannot be compressed.

      The default value is 0, which means that multifile cube generation is disabled.

Log Files

The following settings control where and how Cognos Transformer writes information to an ASCII-text log file.

  • <Preference Name="LogFileDirectory" Value="path"/>

    This setting specifies where Cognos 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/c10 directory. If the logs subdirectory does not exist, then the default is the current working directory.

  • <Preference Name="LogFileName" Value="file_name"/>

    This setting specifies the log file name. You can include the full path with the file name.

    If you do not specify the file name, the output is displayed on the screen, which is the product default.

    On Windows, if the log file name is not specified, a model name or a generated name, such as tfmr0001.log, is used and the .log extension is added.

    On UNIX, if the log file name is not specified or set to stdout, the output is displayed on the screen.

  • <Preference Name="LogFileAppend" Value="FALSE"/>

    This 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="LogDetailLevel" Value="4"/>

    This setting specifies the types of messages that are written to the log file. Choose from the following severity levels:

    • 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 Cognos 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, seeUsing the Log File to Analyze Processing Bottlenecks.

    Tip: You can also use the -r command line option to control the types of messages generated.
  • <Preference Name="LoggingFrequency" Value="-1"/>

    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="MaskCmdLine" Value="0|1|2"/>

    This setting is used to mask or hide command line arguments that might expose user credentials in the log file. The setting is applicable to Transformer on UNIX only. The following values can be specified for this setting:

    • 0 - the entire command line is written to the log file. This is the default value.
    • 1 - all parameters for the -k and -l options are replaced with asterisk (***) symbols in the log file.
    • 2 - the command line is not written to the log file.

Warning

These settings control whether Cognos Transformer issues warnings about potential incremental update problems and ratios between categories and their descendants.

  • <Preference Name="IncUpdateWarnings" Value="TRUE"/>

    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="ChildRatioThreshold" Value="35"/>

    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.

Output

  • <Preference Name="MaxTransactionNum" Value="50000"/>

    This setting specifies how often Cognos 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.

Data Source Attributes

These settings specify various physical attributes of the data source files.

  • <Preference Name="DecimalPoint" Value="."/>

    This setting specifies the character used as a decimal point in a data source. The default is a period (.).

  • <Preference Name="DefaultSeparator" Value=","/>

    This setting specifies the field delimiter in a delimited-text data file. The default is a comma (,).

  • <Preference Name="ThousandSeparator" Value=","/>

    This setting specifies the character used as a thousands separator in a data source. The default is a comma (,).

  • <Preference Name="CenturyBreak" Value="20"/>

    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. Cognos 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.

    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.

Date Format

  • <Preference Name="LunarFiscalLabeling" Value="TRUE"/>

    This setting controls the format in which the date is displayed. It determines whether users can 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.

PowerCube Build Performance

The following preferences have an impact on PowerCube build performance.

  • <Preference Name="MultiProcessing" Value="1"/>

    Use this preference to choose between the type of multiprocessing used in this version of IBM® Cognos Analytics and the type used in version 8.4.

    In this version of the product, flat file, package and report data sources are read using multiple threads. One thread reads data records, and another thread processes them. This improves performance during the data read phase. In addition, multiprocessing is supported for Unicode flat files.

    In version 8.4, flat files use the IBM Cognos Series 7 type of multiprocessing, which is less efficient, while packages and reports have no multiprocessing at all.

    By default, this preference has a value of 1 (enabled), which represents the type of multiprocessing used in this version of IBM Cognos Analytics. Setting this preference to 0 reverts multiprocessing to the type used in version 8.4.

  • <Preference Name="WorkFileCompress" Value="1"/>

    Use this preference to choose whether to compress temporary files generated during PowerCube builds. Compressing temporary files significantly improves input/output performance.

    By default, this preference is enabled (value of 1). You can disable it (value of 0) if you are using a RAM disk or a very fast RAID disk to hold temporary work files.

  • WorkFileMaxSize

    This setting specifies the threshold number of bytes at which Cognos Transformer splits its work files. The minimum is 1000000000 and the maximum is 1500000000. The default value is 1500000000.

  • <Preference Name="WorkFileSortMethod" Value="1"/>

    Use this preference to choose between new sorting methods introduced in this version of Cognos Transformer and the type of sorting used in Cognos Transformer 8.4.

    This version of Cognos Transformer introduces an improved multi-threaded sort and single-threaded sort.

    You can specify the following settings for this preference:

    • 0 - represents Cognos Transformer 8.4-style of sorting
    • 1 - represents multi-threaded sort (default)
    • 2 - represents single-threaded sort
    Note: If this preference is set to 0, temporary files created during sorting are placed in the temp directory defined in IBM Cognos Configuration. In IBM Cognos Series 7, this functionality was controlled by the TEMPFILEDIRsetting.
  • <Preference Name="WorkFileSortThreads" Value="3"/>

    Use this preference when WorkFileSortMethod is set to multi-threaded sort (value of 1) to specify the number of sorting threads.

    Depending on hardware resources, it may be beneficial to set this preference to 2 or 3 (default).

    When WorkFileSortMethod is set to 1 or 2, Cognos Transformer processes the amount of memory specified by the preference WorkFileMaxSize during the sorting. The WorkFileMaxSize default is 1,500,000,000 bytes, which may be too high, depending on the hardware resources and Cognos Transformer model size. The value of WorkFileMaxSize should match the amount of physical memory available to Cognos Transformer during the PowerCube build. Cognos Transformer can avoid memory exhaustion if WorkFileMaxSize is too high; however, if there is not enough physical memory, cube build performance may not be optimal.