Transform()

Convert any value into a formatted character string.

Syntax

Transform(<exp>, <cSayPicture>) --> cFormatString

Arguments

<exp> --> is the value to format. This expression can be any valid CBS data type except array or a Nil value.

<cSayPicture> --> is a string of picture and template characters that describes the format of the returned character string.

Returns

Transform() converts <exp> to a formatted character string as defined by <cSayPicture>.

Description

Transform() is a conversion function that formats character, date, logical, and numeric values according to a specified picture string that includes a combination of picture function and template strings.

Function string: A picture function string specifies formatting rules that apply to the Transform() return value as a whole, rather than to particular character positions within <exp>. The function string consists of the @ character, followed by one or more additional characters, each of which has a particular meaning (see below). If a function string is present, the @ character must be the leftmost character of the picture string, and the function string must not contain spaces. A function string may be specified alone or with a template string. If both are present, the function string must precede the template string, and the two must be separated by a single space.

Transform() Functions

Function	Action
B	Displays numbers left-justified.
C	Displays CR after positive numbers.
R	Nontemplate characters are inserted.
X	Displays DB after negative numbers.
Z	Displays zeros as blanks.
(	Encloses negative numbers in parentheses.
!	Converts alphabetic characters to uppercase.

Template string: A picture template string specifies formatting rules on a character by character basis. The template string consists of a series of characters, some of which have special meanings (see below). Each position in the template string corresponds to a position in the value of the <exp> argument. Because Transform() uses a template, it can insert formatting characters such commas, dollar signs, and parentheses.

Characters in the template string that have no assigned meanings are copied literally into the return value. If the @R picture function is used, these characters are inserted between characters of the return value; otherwise, they overwrite the corresponding characters of the return value. A template string may be specified alone or with a function string. If both are present, the function string must precede the template string, and the two must be separated by a single space.

Transform() Templates

Template	Action
A,N,X,9,#	Displays digits for any data type.
L	Displays logicals as "T" or "F".
Y	Displays logicals as "Y" or "N".
!	Converts an alphabetic character to uppercase.
$	Displays a dollar sign in place of a leading space in
	a numeric.
*	Displays an asterisk in place of a leading space in a
	numeric.
.	Specifies a decimal point position.
,	Specifies a comma position.

Examples

This expression formats a number as a currency:

Transform('1000', '$999,999.99')

* Result: '$1,000.00'

____________________________