The STATVAL function returns the dimension value that corresponds to a specified position in the current status list of a dimension or a dimension surrogate, or in a valueset.
The data type returned by STATVAL is either the data type of the dimension or dimension surrogate value or an INTEGER that indicates its position in the default status list of the dimension. The dimension value that STATVAL returns is converted to a number or a text value, as appropriate to the context. To ensure that STATVAL returns an INTEGER value, specify the INTEGER keyword. See Example 8-120, "Ensuring that STATVAL Returns an INTEGER".
A text expression whose value is the name of a dimension, a dimension surrogate, or a valueset.
An INTEGER expression that specifies the position in the current status list of a dimension or a valueset. When you specify a position that has no values, STATVAL returns NA.
Specifies that STATVAL must return an INTEGER that represents the position of the dimension value in the default status list.
In a FOR loop over a dimension, the status is limited to a single dimension value for each iteration of the loop. Therefore, STATVAL has a value only for position 1. For other positions, STATVAL returns NA.
Example 8-119 STAVAL with Qualified Data References
Suppose you want to know the sales figures for the month ranked fifth among the 10 months with the highest total sales. After limiting month to the TOP 10, use STATVAL in a qualified data reference to produce sales figures for the month ranked fifth.
LIMIT month TO TOP 10 BASEDON TOTAL(sales, month) REPORT month
These statements produce the following report.
MONTH -------------- Jul96 Jun96 Jul95 Aug96 Jun95 Sep96 May96 Aug95 Sep95 MAY95
Using STATVAL in the following REPORT statement produces a different report.
REPORT W 8 DOWN district HEADING -
JOINCHARS('Sales: 5th of Top Ten - ' STATVAL(month 5)) -
sales(month STATVAL(month 5))
This is the report produced by the preceding statement.
------------Sales: 5th of Top Ten - Jun95-------------
-----------------------PRODUCT------------------------
DISTRICT Tents Canoes Racquets Sportswear Footwear
-------- ---------- ---------- ---------- ---------- ----------
Boston 88,996.35 147,412.44 90,840.60 75,206.30 144,162.66
Atlanta 110,765.24 106,327.17 109,695.31 155,652.78 146,364.99
Chicago 70,908.96 108,039.05 100,030.29 104,900.66 148,386.81
Dallas 128,692.56 71,899.23 176,452.58 164,823.10 32,421.25
Denver 91,717.46 99,099.20 140,961.37 99,951.60 70,149.77
Seattle 113,806.48 143,037.62 54,926.87 57,739.03 75,457.04
Notice that the qualified data reference in the following statement means "sales for the fifth month in the default status of month."
sales(month 5)
While the qualified data reference in the following statement means "sales for the fifth month in the current status of month."
sales(month STATVAL(month 5))
The following statements show the different values that are returned for a qualified data reference of month and for STATVAL with month as an argument.
SHOW month(month 5) SHOW STATVAL(month 5)
The preceding statements produce the following output.
May95 Jun95
Example 8-120 Ensuring that STATVAL Returns an INTEGER
Depending on the context, STATVAL may return an INTEGER value without your specifying the INTEGER keyword.
The following statements
LIMIT month TO 'Jun95' TO 'Dec95' SHOW STATVAL(month 3)
produce this output.
Aug95
With the INTEGER keyword,
SHOW STATVAL(month 3 INTEGER)
the following output is produced.
8