FormatValue
Returns a string that is the result of formatting a value according to one or more specified styles. The FormatValue function is identical to the
Format function, except that the metadata to be used for formatting is provided by one variable, while the value to be formatted may come from elsewhere.
Syntax
FormatValue(ValFormat, Val [, Style [, Width [, Locale]]])
Parameters
ValFormat
Type: None
A variable that provides the metadata to be used for formatting.
Val
Type: None
The value to be formatted.
Style
Type: Text
Optional. One or more formatting codes. Multiple codes must be separated by semicolons.
Width
Type: Long
Optional. The minimum width of the formatted string.
Locale
Type: Long
Optional. The output locale to use for regional variations in formatting. If Locale is omitted or is negative, the current output locale is used for formatting.
(return)
Type: Text
Val formatted as a text string.
Remarks
Val is formatted according to Style, as described below. For those formatting codes that can use metadata information, such as Name, Label, and ValueNative (a, b, and V, described in the table below), Val is formatted using the metadata information provided by ValFormat. That is, Val is formatted as if it were the current value of the ValFormat variable.
If Width is supplied and the formatted string is shorter than the absolute value of Width, the string is padded with space characters to make it up to (the absolute value of) Width characters. If Width is negative, spaces are added at the end of the string; otherwise, spaces are added at the start.
Style code syntax
Style consists of one or more formatting codes. For more information, see
Style code syntax.
Example: Using the FormatValue function in an SQL query
This example uses the FormatValue function in an SQL query that can be run against the Museum sample data set provided with the UNICOM Intelligence Developer Documentation Library(DDL). The query lists the categories in the museums variable, and for each category shows the total number of male and female respondents who selected that category:
SELECT FormatValue(museums, GROUPBY.COL[0], 'b') Museum,
SUM(gender = {male}) Male,
SUM(gender = {female}) Female
FROM vdata GROUP BY museums ON DefinedCategories(museums)
In this example, the FormatValue function is effectively used to display the label of each category in the set returned by
DefinedCategories(museums). Because the result of
DefinedCategories(museums) is a set of category values with no connection to the metadata for the museums variable, it is not possible to use the
Format function to return the label of each category in the set. Instead, the FormatValue function is used so that the museums variable can be specified as providing the metadata for the formatting of the category values returned by
DefinedCategories(museums).
For more information on the extended SQL syntax used in this query, see
Advanced SQL queries.
Here is the result set of running the example query:
Museum Male Female
--------------------------------- ---- ------
National Museum of Science 209 124
Museum of Design 49 43
Institute of Textiles and Fashion 31 16
Archeological Museum 18 8
National Art Gallery 7 12
Northern Gallery 11 10
Other 16 21
(null) 0 0
See also