Transformer supports the following Windows and UNIX/Linux command line options. Detailed explanations are provided in the subsections that follow.
Command line options are case-insensitive.
| Option | Meaning |
Runs AutoDesign then creates a cube, opens PowerPlay (Windows), and displays the report. cogtr -a data_source Restriction: Use on Windows only, with -d, -f, -r, and -nologo options. | |
Generates categories and creates cubes. -c -pfilename.py?|-mfilename.mdl Restriction: Use with -i, -m, or -p. On Windows, use with -n. | |
Overrides the specified user preference setting. -dpreference_var=setting -pfilename.py?|-mfilename.mdl | |
Updates the model structure but not the data. -e -pfilename.py?|-mfilename.mdl Restriction: Cannot be used with -c. On Windows, use with -n. On Windows, Unix, and Linux, use with -o. | |
Specifies the user-defined preference file. Can be used to publish PowerCubes in batch mode and include prompts in an XML command file using the XML schema for preference files. -fpreference_file -pfilename.py?|-mfilename.mdl | |
Copies new versions of cubes to deployment locations and activates the newer versions. -g[powercube_name]|[powercube_group_name/child_cube_name] -pfilename.py?|-mfilename.mdl | |
Opens the specified .py? model and restarts a failed process from the beginning. -i -pfilename.py? Restriction: On Windows, use with -n. On UNIX and Linux, cannot be used with -s. | |
Displays help for the command line. cogtr -h | |
Specifies database signon information for IBM Cognos Series 7. -ksignon=userid/password -pfilename.py?|-mfilename.mdl | |
| -l | Specifies user authentication information for IBM Cognos 8. -lsignon=userid/password -pfilename.py?|-mfilename.mdl |
Opens the specified .mdl file or accepts Model Definition Language (MDL) statements. -mfilename.mdl | |
Runs cogtr in interactive or batch mode. -ndisplay_state -pfilename.py?|-mfilename.mdl Restriction: Use on Windows only. | |
Omits splash screen display when opening Transformer. -nologo -pfilename.py?|-mfilename.mdl Restriction: Use on Windows only. | |
Turns off various model and cube creation actions. -o -pfilename.py?|-mfilename.mdl | |
Disables category creation and cube rebuild. -ox -pfilename.py?|-mfilename.mdl Restriction: Use on Windows only. | |
Opens the specified binary model file, .py?, where the question mark (?) is replaced by the character that is used in your version of Transformer -pfilename.py? Restriction: Not valid with an MDL file. | |
Specifies the level of detail for error-logging reports. -rlog_level -pfilename.py?|-mfilename.mdl Restriction: Valid levels are 0, 1, 2, 3, and 4. | |
Saves the model. -s -pfilename.py?|-mfilename.mdl Restriction: On Windows, use with -n; cannot be used with -i or -p. | |
Sets the current period. -tcategory_code -pfilename.py?|-mfilename.mdl Restriction: On Windows, use with -n. | |
Gets the partition status for previously generated cubes. -u[powercube_name]|[powercube_group_name/child_cube_name] -pfilename.py?|-mfilename.mdl Restriction: Cannot use this option with secured cubes. On Windows, use with -n. | |
Specifies the number of records for the test cube. -vdata_subset_number Restriction: Use with -c, -m, or -p. On Windows, use with -n. | |
Updates the column and measure scales based on the data source. -x -mfilename.mdl | |
Specifies how IBM Cognos Series 7 user-class security conversion is performed.
|
This Windows-only option runs the AutoDesign utility, builds a model based on the specified data source, and creates the PowerCube.
Use this option with the -d, -f, -r, and -nologo options. Leave a space between the -a and the data source file name.
The syntax for using the -a option is as follows:
cogtr -a data_source
The following Windows example opens the Sales data source and uses AutoDesign to place dates in the time dimension, columns with numeric values in the Measures list, and all remaining columns in the dimension map, using a best-fit approach.
It then creates the Sales cube and if PowerPlay (Windows) is installed on the same computer, displays the Sales report in the reporting application.
cogtr -a Sales_datasource
This option loads a model file, interprets MDL statements, generates categories, and creates cubes.
Use this option with the applicable file-opening option: either -p, -m, or -i. On Windows, use this option with -n.
The syntax for using the -c option is as follows:
cogtr -c -pfilename.py?|-m filename.mdl
The following UNIX/Linux example uses -c and -p options together to open the binary model file go_sales.pyj and process it as described.
cogtr -c -pgo_sales.pyj
The following UNIX/Linux example uses the -c and -m options together to open the equivalent full model definition (the .mdl text file for go_sales), and process it as described.
cogtr -c -mgo_sales.mdl
This option sets a new value for a Transformer user preference. The value overrides settings from the Preferences property sheet for this instance only.
No space may appear between the -d option and its argument. The argument is case-sensitive and must match the value specified in the cogtr.xml file.
For example, use -dLogFileName not -dlogfilename. The syntax for using the -d option is as follows:
cogtr -dpreference_var= setting -pfilename.py?|-m filename.mdl
If you specify the -d option after the -f option, the -d setting overrides the setting for -f. The reverse is also true; the last-appearing option overrides the options that precede it.
You can set preferences in the command line, environment variables, and cogtr.xml. The priority of settings is that the setting in the command line takes precedence over the setting in the environment variable, and the setting in the environment variable takes precedence over the setting in cogtr.xml. If you set a preference more than once in a command line, the last setting overwrites all previous settings.
You can use most settings in the cogtr.xml file as arguments for preference_var.
Although you can specify several -d arguments on the same command line, for Windows production jobs, we recommend that you create your own preference file based on the settings in the cogtr.xml file. You can then reference this file, using the -f option, to run batch Transformer jobs. Similarly, on UNIX and Linux, you can set global preferences using environment variables.
There is a sample preferences file, cogtr.xml.sample in the installation_location/configuration directory. The actual preferences file, cogtr.xml, is not installed by default. It is created and saved to the installation_location/configuration directory the first time you save changes to the Preferences property sheet in Windows. For more information, see cogtr.xml File Settings.
The following example overrides the preference file setting for the DataSourceDirectory, changing it to C:\Newdata. On Windows, it opens the Transact.mdl model and creates the cubes defined there, in batch mode.
cogtr -dDataSourceDirectory=C:\Newdata -nTransact.mdl
The following example overrides the default value at which a warning is issued, for a parent category having too many descendants. The new preference setting (threshold) is 25 children.
cogtr -dChildRatioThreshold=25 -nTransact.mdl
Note: If you change a preference using the -d option, you cannot use the Preferences property sheet in Windows to edit the preference that you changed. The Windows control for the preference that you changed using the -d option is inactive.
You can also use environment variables to set preferences. Transformer version 8.x recognizes the following preference settings or environment variables. For more information, see Controlling Processing with Preference Settings or Environment Variables.
| Preference or Environment Variable | Settings |
| CenturyBreak | Default: 20 |
| ChildRatioThreshold | Default: 35 Minimum: 1 Maximum: 4294967295 |
| CubeSaveDirectory | Default: 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. |
| DataSourceDirectory | Default: the data subdirectory in the installation_location/c8 directory |
| DataWorkDirectory | Default: the temp subdirectory in the installation_location/c8 directory |
| DecimalPoint | Default: a period (.) |
| DefaultSeparator | Default: a comma (,) |
| FilenameVariables | Default: FALSE |
| IncUpdateWarning | Default: TRUE |
| LogDetailLevel | Default: 4 Minimum: 0 Maximum: 4 |
| LogFileAppend | Default: FALSE |
| LogFileDirectory | Default: On Windows, the default is the \Transformer\logs subdirectory under your home directory. On UNIX and Linux, the default is the logs subdirectory in the installation_location/c8 directory. If the logs subdirectory does not exist, then the default is the current working directory. |
| LogFileName | Default: "" |
| LoggingFrequency | Default: -1 |
| LunarFiscalLabeling | Default: TRUE |
| MaxTransactionNum | Default: 50000 |
| ModelSaveDirectory | Default: 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. |
| ModelWorkDirectory | Default: the temp subdirectory in the installation_location/c8 directory |
| MultiFileCubeThreshold | Default: 0 (disabled) Minimum: 0 Maximum: 4294967295 |
| OrderByCategoryLabeling | Default: 0 (disabled) |
| PPDS_READ_MEMORY | Default: 8000000 Minimum: 1000000 |
| PPDS_WRITE_MEMORY | Default: 4000000 Minimum: 1000000 |
| ThousandSeparator | Default: a comma (,) |
| WorkFileMaxSize | Default: 1500000000 Minimum: 100000000 Maximum: 1500000000 |
This option updates and saves all the cube metadata that is defined in the model, but does not update the data. The cube metadata consists of object names, labels, short names, descriptions, drill-through reports, and security information.
You cannot use this option with -c, and you should always use it in combination with the -n and -o options, to run in Windows batch mode and suppress cube creation. Otherwise, you defeat the purpose of this command.
The syntax for using the -e option is as follows:
cogtr -e -pfilename.py?|-m filename.mdl
The following Windows example opens the New.pyj model file and updates the defined cubes without regenerating existing categories or creating new ones. It then saves the model file along with its updated cube metadata: that is, the object names, labels, descriptions, drill-through reports, and security information.
cogtr -e -n -o -pNew.pyj
This option specifies the user-defined preference file or files to use. If you do not include the full directory path with the file name, Transformer searches the executable directory of your most recently installed rendition of the product for the required .xml file.
This option is also used to publish PowerCubes in batch mode and include prompts in an XML command file using the XML schema for preference files.
If you are performing batch tasks that require the use of multiple preference files, Transformer combines the settings in each file successively; later settings override previously defined ones.
Similarly, if you specify the -f option after the -d option, the -f setting overrides the setting for -d. The reverse is also true; the last-appearing option overrides the options that precede it.
No space may appear between the -f option and its argument, preference_file.
Tip: You can base your preference file entries on the settings the cogtr.xml file, and then run batch jobs by referencing the appropriate file using the -f option. Set your environment variables globally or use the -d option for specific command sequences.
The syntax for using the -f option is as follows:
cogtr -fpreference_file -p filename.py?|-mfilename.mdl
The following example sets the preference file to C:\Monthly.xml, opens the model file Transact.mdl, then runs the process in batch to create all of the cubes defined in the model:
cogtr -n -fc:\Monthly.xml -mTransact.mdl
The following UNIX/Linux example parses the go_sales.mdl file using mypref.prf as the specified preference file:
cogtr -fmypref.prf -mgo_sales.mdl
Note: If you change a preference using the -f option, you cannot use the Preferences property sheet in Windows to edit the preference that you changed. The Windows control for the preference that you changed using the -f option is inactive.
The XML file format supports multi-value commands and user-defined preference files. Commands in XML files are executed sequentially unless specific rules are defined.
The XML schema can have multiple sections and multiple commands. Commands can contain multiple parameters and parameters can have multiple values.
The cogtr.xml file conforms to the XML schema. The cogtr.xml file contains two major predefined groups of xml elements:
a section which contains a list of preferences, for example:
<Sections>
<Section Name="Transformer">
<Preference Name="DataWorkDirectory" Value="..\temp"/>
<Preference Name="AutoEdit"Value="0"/>
<Preference Name="ChildRatioThreshold" Value="35"/>
<Preference Name="CubeSaveDirectory" Value="..\temp"/>
<Preference Name="DataSourceDirectory" Value="..\temp"/>
</Section><Section Name="RecentFileList">
<Preference Name="File1" Value="NationalOriginal.mdl"/>
<Preference Name="File2" Value="Cubexx.mdl"/>
<Preference Name="File3" Value="GreatOutdoorsCompany_Slow_v1.mdl"/>
<Preference Name="File4" Value="testcube.mdl"/>
</Section>
</Sections>
a Commands section, which will be empty in most cases. The Commands section passes commands to Transformer when it is used in batch mode.
The following diagram shows the XML schema.
The following example shows multiple preferences and commands being passed to Transformer.
<?xml version="1.0" encoding="UTF-8"?> <!--Sample XML file generated by XMLSpy v2007 sp2 (http://www.altova.com)--> <Settings xsi:noNamespaceSchemaLocation="cogtr_format_v2.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Sections> <Section Name="Transformer"> <Preference Name="DataWorkDirectory" Value="..\temp"/> <Preference Name="AutoEdit" Value="0"/> <Preference Name="ChildRatioThreshold" Value="35"/> <Preference Name="CubeSaveDirectory" Value="..\temp"/> <Preference Name="DataSourceDirectory" Value="..\temp"/> </Section> <Section Name="RecentPackageList"> <Preference Name="mru_entry_0" Value="/content/package[@name='EquifaxCube']"/> </Section> <Section Name="RecentFileList"> <Preference Name="File1" Value="c:\NationalOriginal.mdl"/> <Preference Name="File2" Value="c:\Modified Cubexx.mdl"/> <Preference Name="File3" Value="c:\GreatOutdoorsCompany_Slow_v1.mdl"/> <Preference Name="File4" Value="c:\testcube.mdl"/> </Section> </Sections> <Commands> <Command Name="Publish"> <Parameters> <Parameter Name="CubeName" Value="test"/> <Parameter Name="CognosConnectionDataSourceName" Value="test"/> <Parameter Name="DataSourceWindowsLocation" Value="c:\test1.mdc"/> <Parameter Name="DataSourceUnixLinuxLocation" Value=""/> <Parameter Name="DataSourceNameSpace" Value=""/> <Parameter Name="ReadCacheSize" Value="0"/> <Parameter Name="DataSourceSignon" Value="FALSE"/> <Parameter Name="DataSourceDescription" Value=""/> <Parameter Name="DataSourceToolTip" Value=""/> <Parameter Name="DataSourceUpdate" Value="FALSE"/> <Parameter Name="PackageName" Value="tpc"/> <Parameter Name="Packagelocation" Value="/content"/> <Parameter Name="PackageDescription" Value=""/> <Parameter Name="PackageToolTip" Value=""/> <Parameter Name="PackageUpdate" Value="FALSE"/> <Parameter Name="PackageAllowNullSuppression" Value="TRUE"/> <Parameter Name="PackageAllowMultiEdgeSuppression" Value="TRUE"/> <Parameter Name="PackageAllowAccessToSuppressionOptions" Value="TRUE"/> </Parameters> </Command> <Command Name="n"/> <Command Name="d" Value="DataSourceDirectory=C:\Newdata"/> <Command Name="prompts" Value="MyQuery1"> <Parameters> <Parameter Name="Prompt1" Value="TestCube"/> <Parameter Name="Prompt2"> <Values> <Value>c:\test\cube.mdc</Value> <Value>c:\test\cube1.mdc</Value> <Value>c:\test\cube2.mdc</Value> </Values> </Parameter> <Parameter Name="Prompt3" Value="TestPackage"/> </Parameters> </Command> <Command Name="prompts" Value="MyQuery2"> <Parameters> <Parameter Name="Prompt4"> <Values> <Value>1</Value> <Value>4</Value> <Value>8</Value> </Values> </Parameter> </Parameters> </Command> </Commands> </Settings>
This command allows users to publish PowerCubes in batch mode.
The syntax is
cogtr -fcommand file name -p filename.py?|-mfilename.mdl
where command file name is the name of the file containing the Publish command specification.
The following table describes the command parameters.
| Parameter name | Description |
| CubeName | The name of the PowerCube in the model. This is a mandatory value. |
| CognosConnectionDataSourceName | The name of the Content Management data source. This
is a mandatory value. The set will fail if it is not defined. Default: The name in the model |
| DataSourceWindowsLocation | The Windows location of the data source. Default: The current cube location on Windows |
| DataSourceUnixLinuxLocation | The UNIX/Linux location of the data source. Default: Empty |
| ReadCacheSize | The read cache size for PPDS. Default: 0 |
| DataSourceNameSpace | The authentication namespace for the Content Management data source. Default: Empty |
| DataSourceSignon | The command used to create the Content Management
data source signon, if needed. Default: False |
| DataSourceDescription | The description of the Content Management data source. Default: Empty |
| DataSourceToolTip | The tool tip for the Content Management data source. Default: Empty |
| DataSourceUpdate | The command used to update a data source. Default: FALSE |
| PackageName | The name of the Content Management package. This
is a mandatory value. The set will fail if it is not defined. Default: The name in the model |
| Packagelocation | The location of the Content Management package. Default: Public Folders |
| PackageDescription | The description of the Content Management package. Default: Empty |
| PackageToolTip | The tool tip for the Content Management package. Default: Empty |
| PackageUpdate | The command used to update the existing package when
its settings change. Default: FALSE |
| PackageAllowNullSuppression | The command used to specify whether suppression is
available to IBM Cognos 8 studio users when working with
this package. Default: TRUE |
| PackageAllowMultiEdgeSuppression | The command used to specify whether IBM Cognos 8
studio users can suppress both rows and columns. If this option
is set to FALSE, users can suppress rows only or columns only. If this parameter is set to TRUE, the PackageAllowNullSuppression parameter must also be set to TRUE. Default: TRUE |
| PackageAllowAccessToSuppressionOptions | The command used to specify whether IBM Cognos 8
studio users can control the types of empty values that will be
suppressed, such as zero or missing values. Types of empty values
that users can choose to suppress depend on the IBM Cognos 8
studio. If this parameter is set to TRUE, the PackageAllowNullSuppression parameter must also be set to TRUE. Default: TRUE |
The following example shows the xml code for publishing a cube.
<Command Name="Publish"> <Parameter Name="CubeName" Value="NATIONAL"/> <Parameter Name="CognosConnectionDataSourceName" Value="NATIONAL"/> <Parameter Name="DataSourceWindowsLocation" Value="c:\test\cube.mdc"/> <Parameter Name="DataSourceUnixLinuxLocation" Value=""/> <Parameter Name="DataSourceNameSpace" Value=""/> <Parameter Name="ReadCacheSize" Value="0"/> <Parameter Name="DataSourceSignon" Value="FALSE"/> <Parameter Name="DataSourceDescription" Value=""/> <Parameter Name="DataSourceToolTip" Value=""/> <Parameter Name="DataSourceUpdate" Value="FALSE"/> <Parameter Name="PackageName" Value="NATIONAL"/> <Parameter Name="Packagelocation" Value=""/> <Parameter Name="PackageDescription" Value=""/> <Parameter Name="PackageToolTip" Value=""/> <Parameter Name="PackageUpdate Value="FALSE"/> <Parameter Name="PackageAllowNullSuppression" Value="TRUE"/> <Parameter Name="PackageAllowMultiEdgeSuppression" Value="TRUE"/> <Parameter Name="PackageAllowAccessToSuppressionOptions" Value="TRUE"/> </Command>
You can include prompts in an XML command file. You must use the following command line in order for Transformer to read the file:
cogtr -fcommand file name
where command file name contains a sequence of statements that define prompt values.
The command file can contain one or more commands for prompts. The command name is prompt. The value attribute of the command specifies the prompt name. Each prompt command contains one or more Parameter elements that specify a query name, prompt attributes and values. The Query Parameter element specifies the query to which the prompt belongs. The other Parameter elements define the prompt type and values.
There are several different types of prompts: simple, multi-valued, range, and MUN.
The following example shows single value, multi-value and range prompts.
Prompts can be included in an XML command file. You must use the following command line in order for Transformer to read the file:
cogtr -fcommand file name
where command file name contains a sequence of statements that define prompt values.
The Command File can contain one or more commands for prompts. The command name is prompt. The value attribute of the command specifies the prompt name. Each prompt command contains one or more Parameter elements that specify a query name, prompt attributes and values. The Query Parameter element specifies which query the prompt belongs to. The other Parameter elements define the prompt type and values.
There are several different types of prompts: simple, multi-valued, range, and MUN.
The following example shows single value, multi-value and range prompts.
<?xml version="1.0" encoding="UTF-8"?> <Settings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Commands> <!-- SINGLE_VALUE PROMPT --> <!-- Prompt name --> <Command Name="prompt" Value="MyPrompt1"> <Parameters> <!-- A query this prompt belongs to --> <Parameter Name="Query" Value="Promptmany~1"/> <!-- SingleValue, MultiValue, Range --> <Parameter Name="PromptType" Value="SingleValue"/> <!-- Any type that understood by RS. Optional. Not in use --> <Parameter Name="PromptValueType" Value ="Integer"/> <!-- Value --> <Parameter Name="PromptValue" Value="12345"/> </Parameters> </Command> <!-- MULTI_VALUE PROMPT --> <!-- Prompt name --> <Command Name="prompt" Value="MyPrompt2"> <Parameters> <!-- A query this prompt belongs to --> <Parameter Name="Query" Value="Promptmany~1"/> <!-- SingleValue, MultiValue, Range --> <Paramete Name="PromptType" Value="MultiValue"/> <!-- Any type that understood by RS. Optional. Not in use --> <Parameter Name="PromptValueType" Value ="String"/> <Parameter Name="Values"> <Values> <Value>abc</Value> <Value>bcd</Value> <Value>cdf</Value> <Value>dfe</Value> </Values> </Parameter> </Parameters> </Command> <!-- RANGE --> <!-- Promptname --> <Command Name="prompt" Value="RangePrompt"> <Parameters> <!-- A query this prompt belongs to --> <Parameter Name="Query" Value="Promptmany~1"/> <!-- SingleValue, MultiValue, Range --> <Parameter Name="PromptType" Value="Range"/> <!-- Any type that understood by RS. Optional. Not in use --> <Parameter Name="PromptValueType" Value ="String"/> <Parameter Name="Values"> <Values> <Value>Range - form</Value> <Value>Range - to</Value> </Values> </Parameter> </Parameters> </Command> </Commands> </Settings>
A simple prompt is a variable that has a single value. For example
<Parameter Name="SimplePrompt" Value="Single Value"/>
A multi-valued prompt is a variable that has a number of different values. For example
<Parameter Name="Multi-valued-variable"> <Values> <Value>Value1</Value> <Value>Value2</Value> <Value>Value3</Value> </Values> </Parameter>
A range prompt is a type of multi-valued prompt. It contains a Range-from and a Range-to value. For example
<Parameter Name="Range-variable"> <Values> <Value>Range-from</Value> <Value>Range-to</Value> </Values> </Parameter>
A range prompt does not need to contain both Range-from and Range-to values, but it must have one or the other, as shown below.
<Parameter Name="Range-variable"> <Values> <Value/> <Value>Range-to</Value> </Values> </Parameter>
A MUN prompt is a type of single-value prompt. It must refer to a Member Unique Name, for example
<Parameter Name="[ASPV]" Value="[AMERICA].[WORLD]"/>
This option copies newer versions of cubes to deployment locations and activates the newer versions.
If you want to create the newer version of the cube and then copy and activate it, use this -g option with the -c option.
The syntax for using the -g option is as follows:
cogtr -g[powercube_name]|[ powercube_group_name/child_cube_name] -p filename.py?|-mfilename.mdl
The powercube_name parameter represents the name of the cube in the Transformer model. If powercube_name specifies a cube group that is not a time-based partitioned cube, all child cubes of the cube group are copied to the deployment location and activated. If powercube_name specifies a time-based partitioned cube, it is processed as a single cube; member cubes are not deployed individually.
If a name conflict exists with a child cube of a cube group that has the same name as another cube in the model, use the powercube_group_name/child_cube_name parameters.
When you use the -g option without specifying a cube name, all cubes in the model that have deployment locations defined and enabled, and proper status, are copied and activated.
The following example copies and activates all cubes in Sales.pyj.
cogtr -g -pSales.pyj
The following example copies and activates the child cube named "France" in a cube group named "Europe".
cogtr -gEurope/France -pSales.pyj
This option is displays help for the command line.
On UNIX and Linux, help is also displayed if you do not provide any command options.
The syntax for using the -h option is as follows:
cogtr -h
This option opens a saved model, regardless of the existence of a checkpoint file. On UNIX and Linux, you cannot use the -i option with the -s option.
A checkpoint file is automatically created when a model is suspended due to a general system failure, such as that caused by a power outage. The next time the model is opened in interactive mode, users can open either the checkpoint file or the last-saved version of the model file. In batch mode, you can use the -i option to bypass the prompt and force Transformer to open the original model file instead of the checkpoint file.
The syntax for using the -i option is as follows:
cogtr -i filename.py?
Note: Checkpoint files have a .qy? extension. As with .py? files, the ? (question mark) in the extension is replaced by the character that is used in your release of Transformer, such as .qyj.
The following Windows example opens the model file, Sales.py?, discarding any existing checkpoint file, then runs the process in batch mode to create all defined cubes:
cogtr -n -i Sales.py?
This option supplies the signon information needed to establish one or more database connections during batch processing. It provides an alternative to storing the information in the Signons list or retrieving user IDs and passwords from the configured authentication source. This is especially useful when used with .mdl files which, by default, do not use verb MDL and so do not store signon passwords.
For databases referenced in an Impromptu Query Definition (IQD) file, the signon is the logical database name that appears in the related Transformer .xml file. Multiple IQD data sources can use the same signon object.
Note: You can view these signons on the Transformer (Windows) interface, but you cannot change them.
The syntax for using the -k option is as follows:
cogtr -ksignon= userid/password -p filename.py?|-mfilename.mdl
No spaces may appear between -k and its argument, and the signon name cannot be empty. Also, the signon name cannot contain the ASCII equals (=) character, and the user ID cannot contain a forward slash (/), because both characters are reserved for the parameter syntax.
The following Windows example opens the Field3.mdl file and grants access to the required database using the signon named field, user ID CarlosR, and password pw462. Assuming that the signon matches that defined in the model, the process runs in batch mode, creating the cubes as defined in the model.
cogtr -n -kfield=CarlosR/pw462 Field3.mdl
The following UNIX example reads the data source for model Xyzsales.mdl from an Oracle database using an IQD file, confirms the security information, and processes the model in batch mode. The signon sal_log includes the Oracle user ID corpadm and the password my_pass. The command to process the .mdl file for model Xyzsales.mdl is as follows:
cogtr -c -s -mXyzsales.mdl -ksal_log=corpadm/my_pass
When you use this command, the User ID and password appear in plain text. See the following topic for information about how to avoid plain text passwords.
If you use the -k option to pass user IDs and passwords to the Transformer command line, you must take precautions to avoid a plain text password.
Breaches can occur if unauthorized users are able to invoke the ps command or can gain access to the detailed processing information in the log file.
To avoid plain text passwords, we recommend that you adopt one of the following strategies:
Create a text file containing the -k option and one or more user IDs and passwords. Store the file in a secure directory, and ensure that your command line script can easily invoke it.
For example, you can create the Sal_iqd.txt file to contain two user IDs and passwords:
-ksal_log=corpadm/my_pass -ksal_cube=corpis/bld_cube
You can then call this secured file from the command line. The following is a UNIX example:
cogtr -c -s -mXyzsales.mdl ‘cat Sal_id.txt‘
Add MDL statements to the end of the .mdl model file that embed the user ID and password information and update the signon information needed to log on to the database. Then, run cogtr on UNIX using the -m option, specifying your modified .mdl file.
For example, embed the authentication information using the following MDL statements:
SignonUpdate "sal_cube" PromptForPassword False UserID "corpis" Password "bld_cube"
Create a secured but temporary MDL script on the server to update the model signon. Then, run cogtr on UNIX using the -m option, specifying your modified .mdl file.
For example, create the following MDL script, for batch processing using the -m option:
OpenPY "Xyzsales.pyj"SignonUpdate "sal_cube" PromptForPassword False Password "bld_cube"SavePY "Xyzsales.pyj"
For more information about security, see the IBM Cognos 8 Administration and Security Guide.
This option specifies the user authentication information for IBM Cognos 8. It supplies the signon information needed to authenticate users in one or more security namespaces. The -l option provides an alternative to storing the information in the Signons list.
The syntax for using the -l option is as follows:
cogtr -lsignon=userid/ password -pfilename.py?|-m filename.mdl
The following example opens the Field3.mdl file and grants access to the required namespace using the signon named field, user ID CarlosR, and password pw462. Assuming that the signon matches what is defined in the model, the process runs in batch mode, creating the cubes as defined in the model.
cogtr -n -lfield=CarlosR/pw462 -mField3.mdl
IBM Cognos 8 can be configured to use authentication to an external namespace, where users are prompted for credentials as part of the IBM Cognos 8 logon process.
You can create Cognos 8 signons to build cubes in batch mode in this environment. This signon maintains the user ID, password, and associated namespace. You create as many Cognos 8 signons as the number of IBM Cognos 8 namespaces your users need to log on to. To enable Transformer to use the Cognos 8 signon automatically, enable the Set As Auto Logon property.
To expand on that, if a user has created many Transformer Cognos 8 signons with Set As Auto Logon property checked, and then saved the model, then when using the command line, by default Transformer will authenticate against all those Transformer Cognos 8 signons, without the need to specify the –l option at all.
This option specifies the .mdl-format model or script file to be processed.
If you use multiple occurrences of -m, files are processed in the order of their occurrence.
The syntax for using the -m option is as follows:
cogtr -mfilename.mdl
The following example lists the steps for processing a sample model using the -m option:
Create a separate file, Savemdl.mdl, that contains the line SaveMDL "Xyznew.mdl".
For the file Xyzsales.mdl, use the following command:
cogtr -mXyzsales.mdl -mSavemdl.mdl
For the file Xyzsales.pyj, use the following command:
cogtr -pXyzsales.pyj -mSavemdl.mdl
This Windows-only option opens Transformer in interactive or batch mode.
–n opens Transformer and runs it interactively.
–n1 opens Transformer in batch mode with the Transformer application window minimized. There is no space between -n and the display_state argument, 1.
–n2 opens Transformer in batch mode with the Transformer application window hidden. There is no space between -n and the display_state argument, 2.
In interactive mode, the Transformer application window opens and the user is prompted for information, such as logon credentials, in the same way that they are prompted when Transformer is opened directly. In batch mode, the user is not prompted for information when Transformer runs, even when the information is required. This is expected behavior.
The syntax for using the -n option is as follows:
cogtr -ndisplay_state -p filename.py?|-mfilename.mdl
The following example opens the model file, Roofing.mdl, without displaying an application window, creates its defined cubes, and then saves the model file.
cogtr -n2 -mRoofing.mdl
The following example opens the model file, Roofing.mdl, and creates its defined cubes:
cogtr -n -sRoofing.mdl
This Windows-only option prevents the display of the Transformer splash screen.
The syntax for using the -nologo option is as follows:
cogtr -nologo -pfilename.py?|-m filename.mdl
The following example opens the model Roofing.mdl without first showing the splash screen:
cogtr -nologo -mRoofing.mdl
On Windows, this option regenerates the categories after a model load, but disables cube creation. On UNIX and Linux, it loads the model file, but turns off population of the model with data and cube creation.
On Windows, use this option in combination with -n to open Transformer, perform the specified action in batch mode, and then close Transformer.
The syntax for using the -o option is as follows:
cogtr -o -pfilename.py?|-m filename.mdl
The following example opens the model file, Roofing.mdl, saves any changes to the structure, such as new categories, then closes Transformer without creating any cubes defined in the model.
cogtr -s -n -o -mRoofing.mdl
The following UNIX/Linux example loads the file, go_sales.mdl, but disables both population of the model and creation of cubes:
cogtr -o -mgo_sales.mdl
This Windows-only option is not a combination of -o with -x, but is similar to the functionality of the basic -o option on UNIX and Linux, disabling both category creation and the cube rebuild.
The syntax for using the -ox option is as follows:
cogtr -ox -pfilename.py?|-m filename.mdl
The following example loads the file, go_sales.mdl, but disables both population of the model and creation of cubes:
cogtr -ox -mgo_sales.mdl
This option opens the checkpoint file (.qy? on Windows) or loads a binary model file and processes it, beginning from the last checkpoint saved in the checkpoint file if this exists, or beginning from the start of the .py? file. All changes are saved on termination.
This option is not valid with an .mdl file.
Note: A checkpoint file exists if model processing was suspended. The file has a .qy? extension, where the question mark (?) is replaced by the character that is used in your version of Transformer.
The syntax for using the -p option is as follows:
cogtr -pfilename.py?
The following Windows example opens the checkpoint file associated with model file, Sales.pyj, then continues to process the model in batch mode, creating all defined cubes:
cogtr -n -pSales.pyj
The following UNIX example starts Transformer, process the MDL verb commands in the file monthly_update.mdl, obtains preference settings from the file, trnsfrm_prd.prf, and saves the model:
cogtr -pgo_sales_jan.pyj -mmonthly_update.mdl -ftrnsfrm_prd.prf
This option sets the degree of detail for messages written to the log file.
Each level includes the errors and messages for the higher levels. No spaces may appear between -r and its log_level argument, which is assigned a value from 0 to 4, as follows:
0 - the Enable Message Logging box is cleared; logging is suppressed
1 - includes only severe errors
2 - includes error messages and level 1 messages
3 - includes warning messages, and level 1 and 2 messages
4 - includes all message levels, from informational to severe; the default setting
The syntax for using the -r option is as follows:
cogtr -rlog_level -p filename.py?|-mfilename.mdl
The following example opens the model file Roofing.mdl, sets the degree of detail for messages to 2, then runs the process in batch mode to create all defined cubes. The messages are written to F:\Test\Roof.log.
cogtr -n -r2 -dLogFileName=Roof.log -dLogFileDirectory=F:\Test Roofing
This option, after successful creation of a cube, saves the model with any new categories added during the category generation process, then closes Transformer.
Do not use this option with -i or -p. On Windows, you must use this option in combination with -n.
The syntax for using the -s option is as follows:
cogtr -mfilename.mdl -s filename.py?|filename.mdl
where parameters for -s are optional.
The following Windows example opens the model file Roofing.mdl, creates its defined cubes, saves the model file, and closes Transformer.
cogtr -n -s -mRoofing.mdl
The following UNIX example starts Transformer, parses a text model file (.mdl), and saves the changes in a binary model file (.py?).
cogtr -mgo_sales.mdl -sgo_sales.pyj
This option sets the current period for the purpose of calibrating relative time calculations. It is equivalent to manually defining a current period on the Windows interface, after clearing the Automatically Set Current Time Period box on the Time tab of the Dimension property sheet.
On Windows, you must use this option in combination with -n.
No spaces may appear between -t and its argument, and if the category contains hyphens or space characters (as in the sample date range below), you must enclose it in double quotation marks. Also, the category_code portion of the command is case-sensitive. This identifier must exactly match the category code in the model.
The syntax for using the -t option is as follows:
cogtr -tcategory_code -p filename.py?|-mfilename.mdl
The following example opens the model Year3.mdl, sets the current period to the category which has a category code of 20061201-20061231, then runs the process in batch mode to create all defined cubes.
cogtr -n -t"20061201-20061231" -sYear3.mdl
This option writes the partition information for a specified cube to the log file, using the following format:
datetime Cube [powercube_name]|[powercube_group_name/ child_cube_name] partition report Partition# Category Code Category Name Partition Size
You must generate cubes before their partition status can be reported. If the command line includes options to generate categories and create cubes, those options are processed before the partition information is obtained.
Partition information cannot be provided for cubes and cube groups to which security has been applied. To obtain the partition information of cubes in a cube group, you must specify the individual cube names, not the cube group name.
The cube name is case-sensitive; for example, you must type uNorth not unorth, for the example below to be valid. No spaces can appear between the option and its argument.
The syntax for using the -u option is as follows:
cogtr -u[powercube_name]|[ powercube_group_name/child_cube_name] -p filename.py?|-mfilename.mdl
The powercube_name parameter represents the name of the cube in the Transformer model. If powercube_name specifies a cube group that is not a time-based partitioned cube, all child cubes of the cube group are copied to the deployment location and activated. If powercube_name specifies a time-based partitioned cube, it is processed as a single cube; member cubes are not deployed individually.
If a name conflict exists with a child cube of a cube group that has the same name as another cube in the model, use the powercube_group_name/child_cube_name parameters.
This Windows example opens the model file Roofing.mdl, discarding a checkpoint file if one exists. It then creates all defined cubes and writes the partition information of cubes North and East to the log file F:\Roof.log.
cogtr -i -n -uNorth -uEast -dLogFileName=F:Roof.log -mRoofing.mdl
This option specifies how many data source records to use to create a test cube. If you have a large data source file, this option enables you to do a test run on a limited number of records before processing the entire file.
If the number of records you specify for the test is greater than the total number of records in the source file, the process runs normally, using the entire file.
Because the option syntax does not reference a model file, -v is used in combination with -c, -m, or -p, each of which does reference a model file.
The syntax for using the -v option is as follows:
cogtr -vdata_subset_number
The following example processes a subset of the records in the binary model file Xyzsales.pyj (525 records), generating categories, and creating the test cube.
cogtr -c -pXyzsales.pyj -v525
This option updates the column and measure scales of the MDL model, provided the data source can handle queries about scale. Therefore the option is supported for relational data sources, but not ASCII or other flat-file data sources.
All column scales are first checked to confirm that they match those in the source. Then, the associated measures are checked and their output scales are updated, as required.
The syntax for using the -x option is as follows:
cogtr -x -mfilename.mdl
The following Windows example opens the Field3.mdl file and grants access to the required database using the signon named field, user ID CarlosR, and password pw462. Assuming that the signon matches what is defined in the model, the process runs in batch mode, updates scales of columns defined in the model, and saves it back to the model.
cogtr -n -x -o -s -kfield=CarlosR/pw462 -mField3.mdl
This option specifies how IBM Cognos Series 7 user-class security conversion is performed.
You can use the -y options alone to save changes to the model file, or you can use it in combination with other options.
The -y options correspond to the three security import options in the Import model with IBM Cognos Series 7 user class view dialog box. For more information, see Upgrade an IBM Cognos Series 7 Secured PowerCube.
Choose this option when you want to maintain the view operations applied in the user class views and use the IBM Cognos Series 7 user classes.
During the transition from an IBM Cognos Series 7 namespace to an alternate security provider, you can use the PowerCube property All applicable namespaces to associate all applicable namespaces during migration testing. When you associate all the applicable namespaces to the cube, you can ensure that the group, role, or user dimensional filtering is consistent with that which had been applied for the IBM Cognos Series 7 user class. This option is supported only for migration testing, and cannot be used to deploy cubes in production environments.
The -y1 option requires that you configure the IBM Cognos Series 7 security on which the upgraded model was designed as an available namespace in IBM Cognos 8. The unique identifier that locates the user class in Access Manager is converted to a IBM Cognos 8 identifier, and this process will fail if you use this option with a different IBM Cognos Series 7 namespace.
The following example
runs cogtr.exe in batch mode, does not generate cubes or update categories
saves the .mdl file
preserves the IBM Cognos Series 7 user class views and user classes associated with the IBM Cognos Series 7 model
logs onto the GO namespace with the Administrator user name and no password
cogtr.exe -n2 -ox -s -y1GOnamespace=Administrator/ -mNationalV7.mdl
This option imports only the IBM Cognos Series 7 user class views associated with the upgraded model.
Choose this option when you want to import the IBM Cognos Series 7 user class views associated with the model, but not the user classes.
This option allows you to maintain the view operations applied in the IBM Cognos Series 7 user class views but not use a IBM Cognos Series 7 namespace with the custom views, or if you do not intend to expose IBM Cognos Series 7 as an a available namespace configured in IBM Cognos 8.
The following example
runs cogtr.exe in batch mode
does not generate cubes or update categories
saves the .mdl file
preserves the IBM Cognos Series 7 user class views associated with the IBM Cognos Series 7 model
cogtr.exe -n2 -ox -s -y2 -mNationalV7.mdl
This option discards the IBM Cognos Series 7 user class views and user classes associated with the upgraded model.
Choose this option when you plan to create new custom views and use only the security objects currently configured in the IBM Cognos 8 namespace.
The following example
runs cogtr.exe in batch mode
does not generate cubes or update categories
saves the .mdl file
discards the IBM Cognos Series 7 user class views and user classes associated with the upgraded IBM Cognos Series 7 model
cogtr.exe -n2 -ox -s -y3 -mNationalV7.mdl
