Developing Longview DataSpecs

This chapter contains information on these main topics:

• "Creating DataSpec documents"
• "Using DataSpec functions"
• "Using commands and functions that reference DataSpec documents"
• "Sample DataSpec document"

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:

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.

ACCOUNTS STAT_ACCOUNTS#99
TIMEPER A1006YTD
ENTITIES LEGAL_ENTITY#99
DETAILS LEDGER#99
CURRENCY Dim4Set
SEGMENTS DIVISIONS#99
ELEMENTS SUMMELE
CONTROLS Dim7Set
ADJUSTEDDETAIL UNADJUSTED            

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)”.

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”

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:

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.

BATCHID 6, TO, 9
BATCHID 123, TO,123                

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:

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

DATACHANGEDTHRESHOLD BETWEEN, 100, 335.5                
DATACHANGEDTHRESHOLD GT, 100
DATACHANGEDTHRESHOLD LT, 100
DATACHANGEDTHRESHOLD EQ, 100

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:

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.

DATEFILTER 2018-09-05, TO, 2018-09-30
DATEFILTER 2018-09-05, TO, 2018-09-05            

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.

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.

RULE ID        

where:

• ID is the rule ID to specify.

RULE 100                

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:

SCHEDULE SchedName
DIMENSION SymName[NumLevels][, SymName[NumLevels]]        

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.

Accounts Accounts_Default                                    
TimePeriods PYr_Total#99
Entities E10000#99
Currencies CAD
Versions Versions_Working
  
Schedule ICStandard
CONTRAS Total#99                        

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.

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

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

TempSym

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

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.

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.

UserFilter userID            

where:

• userID is the user to specify.

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:

CREATE DATAAREA FORDATA USING Forcast.lvdsp                
CREATE LOCK USER USING Forcast.lvdsp "ForData"
DOWNLOAD FORDATA

// DataSpec sample document comment
ATTRIBUTEFILTER TIMEPER,ALL,AZSSIND,EQ, "FALSE"
SCHEDULE SRG08
TempSym TIMEPER, CTEMP, STANDARD, "Temp Time Period Symbol Parent"
TempSym TIMEPER, CTEMP1, STANDARD, "Temp Time Period Symbol #1", CTEMP, +
ACCOUNTS BALSHEET #99
TIMEPER AYR07#99
ENTITIES W11110#99, W1110#45
DETAILS P1000#99
CURRENCY CCAD
SCHEDDIM1 TOTAL#99
CONTROLS DIM5SET

The following commands are executed in a Procedure document:

RUN MODEL FORCPY.lvmod ON FORDATA
UPLOAD FORDATA
DELETE LOCK USER USING Forcast.lvdsp MATCH