Dive Tags

A Spectre Dive script is defined using a dive tag with optional tags between open and close { } braces. 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.
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

(7.0(35) and later)

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.

default-calendar

(7.0(35) and later)

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

dive {

cplan "/cplans/basic.cplan"

window {

dimension "Color"

column "Value"

column "Weight"

}

}

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.

  • 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.
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"

Controls presentation of the data for a dimension or column.

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