The Spectre command line dive sub-command runs a Dive on a data set. It has the following syntax:
spectre dive <filename> [options]
The <filename> points to an existing Dive file to run an existing Dive, or to a cBase or cPlan file to perform an ad hoc dive. The <filename> can take various forms:
- If you set DI_PROJECT or pass --project as an argument, you can use a project path such as /cplans/sales.dive. This format always uses forward slashes regardless of the operating system.
- If you do not set DI_PROJECT and do not pass --project as an argument, you can use a file system path. For example, use C:\di\project\sales\cplans\sales.dive, or use sales.dive if the current working directory is C:\di\project\sales\cplans.
For example:
spectre dive /cplans/sales.dive
Enter spectre dive -h to display the syntax and options as shown in the following table.
Spectre dive Sub-command Options
| Option | Description |
|---|---|
| --dataroot arg |
Set the path to the DiveLine server dataroot. For example: spectre dive /cplans/sales.dive --dataroot c:\di\solution\dl-dataroot Instead of using this option, you can set the DI_HOME environment variable. See Setting Environment Variables. |
| --project arg |
Set the project name. For example: spectre dive /cplans/sales.dive --project sales Instead of using this option, you can set the DI_PROJECT environment variable. See Setting Environment Variables. |
| -u [ --username ] arg |
Run as the specified user. For example: spectre dive /cplans/sales.dive --username jsmith |
| -l [ --limit-rows ] arg |
Limit the number of output rows. For example: spectre dive /cplans/sales.dive --limit-rows 100 |
| --cbase-output arg |
Output directly to a cBase. For example: spectre dive /cplans/sales.dive --cbase-output /cbases/sales-dive.cbase |
| --properties |
Print property values. For example: spectre dive /cplans/sales.dive --properties |
| -p [ --param ] name value |
Set a value for a parameter. For example: spectre dive /cplans/sales.dive --param month 12 --param year 2015 |
| --timing |
Print timing information. For example: spectre dive /cplans/sales.dive --timing |
| -q [ --quiet ] |
Print only warnings and errors to the console. For example: spectre dive /cplans/sales.dive --quiet |
| --human-readable |
Align columns in table output in space-padded fixed-width columns. This option is the default unless writing to a file. For example: spectre dive /cplans/sales.dive --human-readable --properties > c:\temp\sales_dive_prop.txt NOTES: This option is intended for looking at small result sets—it is costly because of the layout required. If used in a Dive redirecting output to a file, the data output is formatted as defined by the format= property. Formatting is always applied when output goes to the terminal. |
| --delimiter |
Indicate an alternative delimiter value to the default tab. The delimiter can be set to "comma", "tab", or a single-character string, for example "|". If set: * Columns will no longer be aligned in the output * Cell values containing the delimiter, a newline, or a double-quote character, will be quoted The new quoting behavior also applies when Spectre dive output is piped to a file or to another process, as long as --human-readable is not used. Available starting with Spectre 7.1(21). |
| With a cPlan or cBase when building a dive explicitly: | |
| -f [ --filter ] arg |
Filter the input using this expression. For example: spectre dive /cplans/sales.cplan --dimension salesperson --filter "value(\"Customer\") = \"5 CLUB [00004]\"" |
| -d [ --dimension ] arg |
Add a dimension to the window. For example: spectre dive /cbases/sales.cbase --dimension salesperson |
| -c [ --column ] arg |
Add a column to the window. For example: spectre dive /cplans/sales.cplan --dimension salesperson --column sales |
| -t [ --totals ] |
Include a totals row. For example: spectre dive /cbases/sales.cbase --dimension salesperson --column sales --totals |
Examples
The following command assumes that the environment variable PATH includes the location of the Spectre executable file.
spectre dive --dataroot C:\di\solution\dl-dataroot
--project PRs /programs/test.dive --timing
This command returns rows for the dimensions specified in the window block in the test.dive. Timing information includes loading the cPlan and cBase, loading string tables, and summarizing the output.
The following three command assumes that the appropriate environment variables are set.
spectre dive measure-dimensions-info.cbase -d Measure
--filter "value(\"Measure\") = \"AMI 30D Pop\""
This command returns the Measure dimension filtered on the specified string value.
spectre dive myextract.dive --human-readable > myextract_result.txt
This command turns the output from a tab-delimited file to fixed-width columns padded with spaces and includes any formatting specified in the Dive script.
spectre dive my.cbase -c "Test Value"
This command totals the Test Value column over all records.