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 might come from elsewhere.
Syntax
FormatValue(<value_format>, <value> [, <style> [, <width> [, <locale>]]])
Parameters
<value_format>
Type: None
A variable that provides the metadata to be used for formatting.
<value>
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
<value> formatted as a text string.
Notes
<value> is formatted according to
<style> (see
Style code syntax). For those formatting codes that can use metadata information, such as Name, Label, and ValueNative (a, b, and V),
<value> is formatted using the metadata information provided by
<value_format>. That is,
<value> is formatted as if it were the current value of the
<value_format> 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