Developing Longview DataSpecs

Creating DataSpec documents

A DataSpec document consists of functions and comments. There are several Longview Application Framework functions used in DataSpecs as well as other documents, and a few functions specific to DataSpec documents.

Using DataSpec functions

The following lists the functions that are used exclusively used in a DataSpec document. Click the links to view detailed usage and syntax information:

• AdjustedDetail
• AttributeFilter
• Dimension
• Rule
• Schedule
• Sym
• TempSym

The following lists functions that are used in a DataSpec document when used in conjunction with the GET DATAAUDITTRAIL command. Click the links to view detailed usage and syntax information:

• BatchID
• DataChangedThreshold
• DateFilter
• Dimension
• Schedule
• UserFilter

For a list of other commands and functions available for use in DataSpec documents, see Using commands and functions that reference DataSpec documents.

AdjustedDetail

Use this function to indicate whether to download adjusted or unadjusted data.

The AdjustedDetail function in a DataSpec document has the following syntax:

Syntax:

AdjustedDetail value

where:

• value is one of the following:

  Value	Description
  UNADJUSTED	To download unadjusted values only to your DataArea.
  ADJUSTED	To download adjusted values to your DataArea.

Note: If the AdjustedDetail function is not specified in a DataSpec, only adjusted values are downloaded to the DataArea.

AdjustedDetail syntax example

AttributeFilter

Use this function to limit the effect of a calculation to symbols that meet the filter condition. This function could also be used when the dimension is restricted in the CalculationBlock which would have the effect of further restricting the symbols for the dimension based on an attribute filter. For information on using AttributeFilter within a CalculationBlock, see AttributeFilter (CalculationBlock).

Syntax:

ATTRIBUTEFILTER DimName, FilterType, AttrName,Operation, "Expression"

where:

• DimName is the dimension in which calculations will occur.
• FilterType specifies the method to use to search the hierarchy for symbols matching the filter criteria. Select one of the following:

  Value	Description
  ALL	To find only the symbols whose attributes match the filter criteria, with no descendents.
  PARENT	Starting from the top of the hierarchy, to find the symbols whose attributes match the filter criteria, including all descendents. This only checks symbols that are parents to other symbols.
  LEAF	Starting from the bottom of the hierarchy, to find the symbols whose attributes match the filter criteria, including all ancestors. This only checks symbols that are leaf symbols; that is, that have no descendents.
  ROOT	Searching only the top of the hierarchy to find root symbols whose attributes match the filter criteria, including all descendents.

• AttrName is the name of an attribute.
• Operation can be EQ for exactly equal to or NE for not equal to.
• "Expression" is a character string enclosed within double quotation marks. If no expression is provided, the current symbol being calculated in the calculation block will be used. If the expression is a list, separate multiple items with a pipe ( | ).

The filter works in the following manner:

• Non-List Attributes:

  Parameter	Behavior
  Attribute EQ “expression”	Matches only if attribute is an exact match of the “expression”
  Attribute NE “expression”	Matches if attribute is not an exact match of the “expression”

• List Attributes

  Parameter	Behavior
  Attribute EQ “expression”	Matches if attribute is an exact match of the “expression”, or is a list of values, any one of which exactly matches the “expression”
  Attribute NE “expression”	Matches if attribute is Empty, or A list of values, none of which exactly matches the “expression”

Syntax example:

ATTRIBUTEFILTER Accounts, ALL, ZGPNativeCurrency, EQ, "CUSD"

BatchID

Use this function to indicate whether to download audit trail information associated with a particular batch or range of batches. This function only applies to DataSpec documents when used in conjunction with the GET DATAAUDITTRAIL command.

The BatchID function in a DataSpec document has the following syntax:

Syntax:

BatchID value1, TO, value2

where:

• value1 indicates the lower range limit of batch IDs to retrieve.
• value2 indicates the upper range limit of batch IDs to retrieved.

Note: To specify a specific BatchID, use the same value for the parameters value1 and value2.

Syntax example:

DataChangedThreshold

Use this function to indicate whether to download audit trail information associated with a particular threshold. This function only applies to DataSpec documents when used in conjunction with the GET DATAAUDITTRAIL command.

The DataChangedThreshold function in a DataSpec document has the following syntax:

Syntax:

DataChangedThreshold operation, value1[, value2]

where:

• operation is one of the following:

  Value	Description
  BETWEEN	is between
  EQ	Is exactly equal to
  GT	Is greater than
  LT	Is less than

• value1 is the value to specify. If only value1 is specified, then this indicates a specific value. If both value1 and value2 are specified, then value1 indicates the lower range threshold for the BETWEEN operation.
• value2 is indicates the upper range threshold when the BETWEEN parameter is specified. This parameter only applies when the operation specified is BETWEEN and must be used in this case

Syntax example:

DateFilter

Use this function to indicate whether to download audit trail information associated with a particular date or range of dates. This function only applies to DataSpec documents when used in conjunction with the GET DATAAUDITTRAIL command.

The DateFilter function in a DataSpec document has the following syntax:

Syntax:

DateFilter startRange, TO, endRange

where:

• startRange is the starting range for the date in YYYY-MM-DD format.
• endRange is the ending range for the date in YYYY-MM-DD format.

Note: To specify a specific Date, use the same value for the parameters startRange and endRange.

Syntax example:

Dimension

Use this function to specify a dimension, its root symbol, and the number of levels in a DataSpec. You can specify more than one symbol for the same dimension.

Syntax:

DIMENSION SymName[NumLevels][, SymName[NumLevels]]

where:

• DIMENSION is the name of a dimension.
• SymName is the name of a symbol in the dimension.
• NumLevels is optional and is the number of levels down to be included from the symbol.

ACCOUNTS TrialBalance#99

Rule

Use this function to specify the server rule for which to download validation data. Use this function in conjunction with the Validation option of the Download (for DataAreas) command.

Syntax:

RULE ID

where:

• ID is the rule ID to specify.

Syntax example:

RULE ID

See also

• Download (for DataAreas)

Schedule

Use this function to specify the schedule from which you want to download data in a datalink. You then use the DimSpec function to specify schedule dimensions and symbols.

Use this function in DataSpec documents as follows:

Syntax:

where:

• SchedName is a schedule you want to define in the DataSpec.
• DIMENSION is the name of a dimension.
• SymName is the name of a symbol in the dimension.
• NumLevels is the number of levels down to be included from the symbol.

Syntax example:

Sym

Use this function to assign one or more symbols in a dimension to a temporary symbol. This can be useful when you want to create a visual structure that is a combination of real and temporary symbols.

For information on creating a temporary symbol, see TempSym.

Syntax:

SYM DimName, SymName1[,SymName2, ..., SymNameN], TemporaryParent [,WEIGHT, "weightvalue"]

where:

• DimName is the dimension that contains the symbol(s) to assign.
• SymName1[,SymName2, ..., SymNameN] are the symbols to assign to the temporary symbol.

  Note: Symbols appear in the hierarchy in the order in which they were assigned.

• TemporaryParent specifies the temporary symbol to which to assign the symbol(s).
• WEIGHT is optional and specifies that you want to define a weight for the symbol with respect to its parent. If you specify this parameter, you must also specify weightvalue. If you do not specify this parameter, the system assigns a positive weight to the symbol(s).
• weightvalue defines the symbol’s relationship with respect to its parent and can be one of the following:

  Value	Description
  + or 1	To add the symbol’s value to the temporary parent
  - or -1	To subtract the symbol’s value from the temporary parent.
  0	To ensure the symbol has no mathematical effect on the temporary parent.

Note: The weightvalue applies to all symbols assigned using the same SYM statement. If you have symbols that should use different weights, you must write another SYM statement for those symbols

Syntax example:

SYM ENTITIES, Maine, NewHampshire, Vermont, Connecticut, NorthEastGroup, WEIGHT, "+"

TempSym

Use this function to create a temporary symbol in the specified dimension.

Syntax:

TEMPSYM DimName, SymName, SymType [, "SymDesc"] [, TemporaryParent, Weight]

where:

• DimName is the dimension that will contain the new temporary symbol.
• SymName is a name for the new symbol. For guidelines, see Symbol names.
• SymType specifies the way the symbol rolls up to its parent symbol, and can be one of the following:

  Value	Description
  Standard	To add the symbol into the parent (for example, monthly expenses added into annual expenses).
  Carryforward	When the parent value equals the value of the cell immediately preceding it (for example, cash balance as a running year-to-date, where the year-end amount equals the amount for December).
  Static	When the child value has no effect on the parent value — for example, for price symbols. (The parents of such symbols are used only to group symbols, not to aggregate their values.) Static symbols do not roll up in any direction, and override any assigned weights.

• "SymDesc" is a character string to be used as a description of SymName, in English, enclosed in double quotation marks. For guidelines, see Symbol descriptions.
• TemporaryParent is optional and specifies the temporary parent symbol to which to assign SymName. If you do not specify a parent, the is created as a root symbol in the dimension specified for DimName.
• Weight defines the symbol’s relationship with respect to its parent and can be one of the following:

  Value	Description
  + or 1	To add the symbol’s value to its parent
  - or -1	To subtract the symbol’s value from its parent.
  0	To ensure the symbol has no mathematical effect on it’s parent.

Syntax example:

TEMPSYM TIMEPER, CTEMP1, STANDARD, "Temp Time Period Symbol One", CTEMP, 1

UserFilter

Use this function to indicate whether to download audit trail information associated with a particular user. This function only applies to DataSpec documents when used in conjunction with the GET DATAAUDITTRAIL command.

Syntax:

UserFilter userID

where:

• userID is the user to specify.

Syntax example:

USERFILTER user123

Using commands and functions that reference DataSpec documents

In addition to the functions used only with DataSpec documents (see Using DataSpec functions) the following Longview Application Framework commands and functions can reference a DataSpec document:

• Copy Data command
• Create DataArea command
• Delete Lock command
• Get DataAuditTrail command
• Set WorkflowStatus command

For more information on these and other commands and functions, see Developing Longview Procedures and Developing Longview Models.

Sample DataSpec document

The following example illustrates a DataSpec document named Forcast.lvdsp, establishes a DataArea called Fordata, and downloads dimensions, symbols, structures, data, etc., to the local memory of the user’s computer. The DataArea can consist of multi-level symbol Structures for all dimensions. It is not limited to three active dimensions.

Note: To add a comment to syntax, insert two forward slashes ( // ) at the beginning of the comment.

The following rules apply to the use of DataAreas within a DataSpec created by another script:

• If a DataArea is created in the parent script, it can be used in a child script (i.e., a child script inherits all the DataAreas created in its parent scripts).
• If a DataArea is created in the child script, it is visible in that script and all of its child scripts only.
• If an inherited DataArea is deleted in the child script, the data will not be cleared from the memory and it is still accessible from the parent script. However, the child script will lose its reference to that DataArea.
• Downloading or Uploading an inherited DataArea in a child script has the same effect as doing so in the main script.

The following commands are executed in a Procedure document:

Syntax example:

The following commands are executed in a Procedure document: