Allowed uses: By Go/Commit, SQL
When you have conditions in your logic that are not dependant on the records being scanned, you might only want to test those conditions once. For example, you might want to test that there is a specific keyword or that a certain cell of the application has a specific value in the selected set of members for a given dimension. Rather than applying the condition to the entire set of records to scan, the condition can be evaluated before the WHEN / ENDWHEN loop, with the following instruction:
*TEST_WHEN( {condition} )
The {condition} is a string that the logic engine passes to a Visual Basic script for evaluation. If the returned value is TRUE, the subsequent WHEN / ENDWHEN loop is processed. Otherwise the entire loop is skipped.
Example
// skip the loop if Budget is not among the passed categories
*TEST_WHEN(instr("%CATEGORY_SET%","BUDGET")>0)
*WHEN *
//….. *ENDWHEN
*GO
// skip the loop if account FLAG is zero for a certain time,intco combination
*TEST_WHEN(GET(ACCOUNT="FLAG",INTCO="NON_INTERCO",TIME="2004.JAN")<>0)
*WHEN *
//….. *ENDWHEN
As shown in the above example, the instruction supports the use of the %{dim}_SET% keyword. It also supports the GET instruction, to retrieve a value from the recordset. When one or more GET instructions are used in the evaluation of the condition, you must remember to specify all required dimensions. The nonspecified dimensions default to the values they have in the first record of the source record set. In other words, you can only omit dimensions that do not vary in the recordset being scanned.
Another syntax supported anywhere in this instruction is the FLD( ) keyword. Here is a valid example:
Example
*CALC_EACH_PERIOD // handle periods one by one
*XDIM_MEMBERSET TIME=PRIOR, %TIME_SET% // include prior period to selected dates
// This tests that the evaluated period is not the prior period
*TEST_WHEN(instr("%TIME_SET%","FLD(TIME.ID)")>0)
*WHEN….
The TEST_WHEN instruction is specific to the current GO section. If the script does not contain a GO section, it is specific to the current COMMIT section.
POS() keyword
The POS() keyword can be used in a WHEN / ENDWHEN structure when you need to compare the position of the current time period relative to a different one. This situation may arise when a logic must change behavior when passing beyond a certain date. For example, the first three months of a year may contain actual data, where some accounts are input, and the other months contain budget data, where the same accounts are calculated.
The new keyword comes in two formats:
POS(TIME) // to use in a *WHEN instruction
And
POS({time}) // to use in a *IS instruction
The correct structure is:
*WHEN POS(TIME)
*IS <>= POS({time})
//….. …
where {time}
must be an explicit date. For example:
Example
*WHEN POS(TIME)
*IS <>=POS(“2005.MAR”)
//……
To make the date more dynamic, you can use the *FLAG_PERIOD instruction. See *FLAG_PERIOD