Dive Tags

A Spectre Dive script is defined using a dive tag with optional tags between open and close { } braces. This topic describes the tags that can be used within the dive code block. The tags are listed in alphabetical order, after the dive tag, in the following table.

Dive Tags

Tags Examples Notes
dive

dive {

…

}

 Defines the block for the Dive definition. The Dive name is the same as the filename of the Dive script.
add

dive {

cplan"/cplans/sales.cplan"

window {

dimension "Product"

column "Cost"

column "Revenue"

add "Profit" `value("Revenue") - value("Cost")`

}

}

Adds a new column to the window after it is built with arranged dimension values and any summarized values.

NOTES:

  • Unlike column, which creates summary columns at the creation of the window, the add occurs in sequence with other window operations.
  • An add calculation can use information about the window's sort order and filtering, which column calculations cannot do.
  • Add tags can refer to column tags.
all-cbase-columns

dive {

cplan {

cbase-input "basic.cbase"

}

detail-window {

all-cbase-columns

sort {

column "Value" reverse=true

}

}

}

 Includes all columns in the cBase in the detail dive. Use within a detail-window block.
auto-rows

rotate {

rotate-output-names "Head" "Value"

row-out "1" "1"

auto-rows left-inclusive=false

row-out "12" "12"

}

Automates inclusion of rows between an explicit start and end of a rotate. Use within a rotate block.

The optional attributes left-inclusive and right-inclusive can be used to specify an exclusive range.

This example snippet rotates columns 2 through 12 into rows.
aux-table

dive {

cplan "/cplans/sales.cplan"

window {

dimension "Salesperson"

column "Units"

aux-table "Totals"

}

}

 

window {

dimension "Sales Region"

dimension "Salesperson"

column "Units"

aux-table "Totals"

aux-table "Region Subtotals" {

dimension "Sales Region"

}

}

Creates totals or subtotals in the window. The string argument after aux-table becomes the name of the row it generates.

Create subtotals by specifying the dimensions that you want in the aux table block as in the second code snippet.
calc-set

dive {

cplan "calc-set.cplan"

window {

dimension "Color"

column "Weight"

calc-set "Value Set"

}

}

 Refers to multiple calculations defined in the cPlan with the calc-set tag. In the Dive script, the calc-set is referenced by name to add additional columns to the window.

calendar

calendar "modified-standard" type="standard" {

period "year-month" format="YYYY-MMM"

}

calendar "fiscal" type="custom" {

cbase-input "fiscal.cbase"

}

calendar "fiscal" file="fiscal.calendar"

Adds a calendar for the Dive.

The first example declaration reformats the standard display from YYYY/MM to YYYY-MMM.

The second example creates a fiscal calendar from the indicated cBase.

The last example builds the fiscal calendar from the named calendar text file.

See Calendar Declarations.
column

dive {

cplan "/cplans/Orders.cplan"

window {

dimension "Order Number"

dimension "Order item"

column "Size"

column "Weight"

column "Avg DP" `average (value("Discounted Price"))`

column "Turn" `first( value("Ship Date") - value("Order Date") )`

}

}

Refers to a summary column, or calculated column defined in the cPlan or in the window block.

NOTES:

  • The column tag can be followed by an expression, or label and format tags.
  • A column tag makes a summary from detail records.
  • A column tag cannot refer to another column tag or an add tag.

  • Column and dimension tags are always processed (and data generated internally) before all other operations in a window, which are then processed sequentially.
cplan

dive {

cplan "/cplans/basic.cplan"

window {

dimension "Color"

column "Weight"

column "Cumulative Weight" `calc("Weight") + previous(calc("Cumulative Weight"), 0)`

column "Total Remaining" `top(calc("Weight")) - calc("Cumulative Weight")`

}

}

Specifies the cPlan to dive into. See cPlan Tags.

NOTE: Dives always contain a cplan tag, and that tag or cPlan file contains the input, be it text-input, cbase-input, odbc-input, or dive-input.

cross

dive {

cplan "/cplans/sales.cplan"

window {

dimension "salesman"

cross {

dimension "region"

column "raw sales"

}

}

}

Creates a CrossTab by adding a cross dimension and column.

NOTE: When multiple dimensions and columns are listed in the cross block, the result is a MultiCrossTab window.
date-rollup

dive {

cplan {

cbase-input "small-date.cbase"

}

window {

dimension "Year-Quarter" {

date-rollup "source date" calendar="standard" period-type="year-quarter"

}

column "COUNT" `count()`

}

}

 Includes information about a dimension that supports a date rollup. This includes the calendar, period type, the source dimension to be rolled, as well as a name for the new rolled dimension.

default-calendar

default-calendar "offset november"

default-calendar "modified-standard"

 Specifies a default calendar. The default calendar can be set to any declared calendar (including custom calendars), or standard, offset <month>, or iso 8601. The default calendar is standard unless declared otherwise.
detail-window

dive {

cplan {

cbase-input "basic.cbase"

}

detail-window {

all-cbase-columns

}

}

 Sets up a dive with no summarization. This snippet dumps the entire cBase. See Detail Windows.
dimension

dive {

cplan "/cplans/basic.cplan"

window {

dimension "Color"

column "Value"

column "Weight"

}

}

window {

dimension "TX Year-Month" {

date-rollup "tx-date" calendar="standard" period-type="year-month"

}

Specifies what dimensions to display in the window.

NOTES:

  • MultiTabs are specified by supplying more than one dimension for a window.
  • The dimension tag can be used in the aux-table block.
  • The dimension tag can be followed by label and format tags.
  • The dimension tag can be followed by a date-rollup block.

  • Column and dimension tags are always processed (and data generated internally) before all other operations in a window, which are then processed sequentially.

  • Dimensions cannot refer to a column of type double.
dive-input

dive {

cplan {

dive-input "foo.dive"

}

window {

dimension "Sales Region"

column "Plan Units"

}

}

 Performs a dive and uses the result as the input. This is equivalent to the Integrator squash operation, creating a single record for a series of dimensions.
duration

column "Playing Time" type="integer" duration=true

Indicates the numeric value is meant to be displayed as a time duration. The format is h:mm:ss.

Use with add or column tags in the dive.
filter

dive {

cplan "/cpalns/sales.cplan"

window {

dimension "Salesman"

column "Monthly Sales"

filter `value("Monthly Sales") > 100000`

}

}

dive {

take-parameter "X"

cplan {

input "../data/basic/basic.cbase"

}

filter `param_match("X", "Mood")`

window {

dimension "Mood"

}

}

Filters data in the window as the dive is performed. If you need more than one filter, use a compound expression.

NOTE: Filters are row-level expressions. Filters placed outside of a window work on the entire data set and do not know about dimensions.
format

column "profit" format="$#,#;\"$\"(#,#)" label="as dollars"

dimension "Datetime" label="Formatted" format="MMM D, YYYY ii:mm pp"

dimension "Year Month" format="YYYY-MM" {

date-rollup "Date" calendar="standard" period-type="year-month"

}

Controls presentation of the data for a dimension or column.

NOTE: The format tag may be provided on a window dimension even if that window dimension is a rollup. If not provided, the format will be the default format because rollup dimensions do not inherit format.

See Spectre Format Conventions.

TIP: A Dive file's "format=" takes precedence over a cPlan's "format=" property.
group

dive {

cplan {

input "/common/basic.cbase"

dimension "Mood" {

group "Ends with y" `rsubstr(value("Mood"), 1, 1) = "y"`

}

}

window {

dimension "Mood"

column "Value"

group "Mood" "Ends with y"

}

}

 Includes the total for the named group defined in the cPlan. The group tag adds a row to the window.
input

dive {

cplan {

multilevel {

cbase-input "basic.cbase" name="one"

cbase-input "demo_drs.cbase" name="two"

}

}

detail-window input="one" {

all-cbase-columns

}

}

 Use to refer to an input file by name when the cPlan includes multiple files. Must be used with detail-window and name tags.
jump

dive {

cplan "/cplans/basic.cplan"

window {

dimension "Mood"

column "Weight"

sort {

column "Weight" reverse=true

}

filter `row_number() <= 3`

}

jump {

cplan {

input "/cplans/extra.cbase"

}

}

window {

dimension "Genre"

column "Duration"

}

}

Takes the summarized rows of that window, uses them to filter a different cPlan, and then switches the dive over to that cPlan. Any subsequent windows work on the new cPlan.

A parent window, which is any window except the last one, can have a jump tag in it.

In this example, the dive jumps to extra.cbase. The only dimension in this window is "Mood", so this filters extra.cbase to only the "Mood" values present in this window, which are the top 3 by Weight.

After the jump, subsequent windows are based on the filtered extra.cbase data.
label dimension "object" label="Categories" Provides an alternative column header for a dimension or column.
name cbase-input "demo_drs.cbase" name="small" Provides a name for the input. Use when the dive refers to multiple inputs that require identification elsewhere in the script.
remove

dive {

cplan "/common/basic.cplan"

window {

dimension "Mood"

column "Value"

column "Weight"

sort {

column "Weight" reverse=true

}

remove "Weight"

}

}

 Removes data from the window.
rename

dive {

cplan "/common/basic.cplan"

window {

dimension "Mood"

column "Value"

rename "Value" "Worth"

}

}

 Changes the name of the column or dimension in the window. Specify the old name, then the new name.
replace

dive {

cplan"/cplans/sales.cplan"

window {

dimension "YearMo"

column "Units"

replace "Units" `max(0, value("Units"))`

}

}

Changes a column value. The replace tag is similar to the add tag, but the replace tag redefines an existing column. The calculation can refer to the old version of the column.
rotate

dive {

cplan {

text-input "string-data-mths.txt"

rotate {

rotate-output-names "nos" "mths"

row-out "1"

auto-rows

row-out "12"

}

}

window {

dimension "nos"

column "mths"

}

}

Defines a rotation of the data. The rotate tag rotates specified columns into rows.
rotate-output-names rotate-output-names "heading col name" "rotated data 1" "rotated data 2"

Identifies a heading column that indicates which columns are rotated to create a row, and value columns for the rotated column values. This tag names the columns that the respective row-out arguments refer to.

TIP: Elements for the rotate-output-names are labeled Row Name Column and Value Columns in the GUI.
row-out row-out "head" "start col" "end col"

Refines the rotation. The row-out tags specify the data that populates the heading column with the first argument and the columns that are rotated with the remaining arguments.

TIP: Elements for row-out appear in the GUI as Input columns:DimensionValue (first arg) and whatever is specified for Column.
sort

dive {

cplan "/common/basic.cplan"

window {

dimension "Color"

dimension "Mood"

column "Weight"

sort {

column "Color"

column "Weight" reverse=true

}

}

}

Sorts the data in the window by the specified column or columns. The reverse tag reverses the sort order.

If an alternative sort is defined for a named string column when the cBase is built, the alternative sort order is used for the Dive.
take-parameter

cplan {

take-parameter "Mood Filter" selection=true {

default "Happy" "Dopey"

}

take-parameter "Color Filter" selection=true {

default-all-values

}
input "/common/basic.cbase"

calc "Filtered Value" `calc("Value")` filter=`param_match("Mood Filter", "Mood") and param_match("Color Filter", "Color")`

}

Accepts the parameter value from the calling script.
tunnel-input

dive {

cplan "my-cplan.cplan" {

tunnel-input "new.tnl"

}

...

}

Specifies a Tunnel script as the source for the input data. The tunnel script is executed and Spectre treats the resulting table of data as if it were a text file.

As with other data inputs, tunnel-input takes parameter provisions (same as in dive-input blocks), column options (same as in text-input blocks), and the stale-after option (same as in odbc-input blocks).

Available starting with Spectre 7.1(6).
use-script-order

rotate use-script-order=false {

rotate-output-names "Size" "Count"

row-out "Small"

row-out "Medium"

row-out "Large"

}

Refines the rotation by allowing the programmer to avoid using script order for strings in a rotate. If not specified, defaults to true.

With the example in the snippet, the headings column, when sorted, will sort in string-sort order: "Large", "Medium", "Small". If use-script-order were omitted or set to true, then that column would sort in script-order—that is, the order they appear in the script: "Small", "Medium" then "Large". Available starting with Spectre 7.1(19).
window

dive {

cplan "demo_drl.cplan"

window {

dimension "Sales Region"

column "Order Count"

column "Units YTD"

column "Revenue YTD"

}

}

 Indicates what data to return to the display. Dimensions refer to cBase columns, while columns refer to cPlan calculations.
within

window {

dimension "sales region"

dimension "product family"

dimension "product name"

column "Revenue"

within "sales region" "product family" {

sort {

column "Revenue" reverse=true

}

}

}

window {

dimension "State"

dimension "City"

column "Population"

within "State" {

sort {

column "Population"

}

add "Index" `row_number()`

add "Count" `row_count()`

add "First" `row_number() = 1`

add "Last" `row_number() = row_count()`

add "Level" `row_number() != row_count()`

}

}

Specifies the control break for the operation. In this first snippet, a multitab is specified—within indicates the level to perform the sort.

In the second snippet, the within tag creates breaks on the multitab window that can be used similar to Integrator breaks.

See also: