FORMAT

Returns a specified string formatted as a currency amount.

Syntax

FORMAT(string,[width,digits,implied,format, position,symbol,separator,decimal])

Arguments

Argument Description Default
string An input string that contains a numeric value to format. string must not contain more than 16 significant digits, and must be in the format:

[spaces][sign][value][.decimalvalue]

Therefore, valid string values would include:

' +21'

' 21.235 '

' -2.3456'

Invalid string values would include:

' Answer: 21.25'

' - 21.25'

' 21,231'

Unexpected results occur if string contains null characters.

EngageOne™ Enrichment ignores information that follows the amount in string. For example, the string values ' 21.235' and '21 POUNDS' both return '21'.

 None.
[width] The total width for the return, including negative signs, separators, and digits. For all position values except C (compact), EngageOne™ Enrichment provides space for negative symbols even if the amount is not negative. This allows for proper decimal alignment.

If you set width too narrow, EngageOne™ Enrichment writes the return in its entirety anyway and sets %%RC to 20.

 10
[digits] The number of digits after the decimal to include in the return. 2
[implied] One of the following:
Y (yes) digits are implied.
N (no) digits are not implied.
For example, the implied parameter would have the following effects:
  • string=2100 and digits=2

    implied=Y—210.00

    implied=N—2100.00

  • string=210.00 and digits=2

    implied=Y—2.10

    implied=N—210.00

  • string=210.1 and digits=3

    implied=Y—0.210

    implied=N—210.100

Typically, you should set implied to N if string contains a decimal character.
[format] One of the following to indicate the currency format to use: 0
0 ($xxx,xxx.xx)
1 $(xxx,xxx.xx)
2 -$xxx,xxx.xx
3 $-xxx,xxx.xx
4 $ xxx,xxx.xx-
5 xxx,xxx.xx (no negatives)
6 ( xxx,xxx.xx) (no currency symbol)
7 xxx,xxx.xx (no currency symbol)
8 xxx,xxx.xx- (no currency symbol)
9 xxx,xxx.xx (no negatives or currency symbol)
10 $ xxx,xxx.xx DR
11 xxx,xxx.xx CR
[position] One of the following: R
L Left-justify currency and negative symbols to the left of the return. For example:

'$( 21.45)'

'$ 21.45 '
R Right-justify currency and negative symbols to the left of the return. For example:

' $(21.45)'

' $21.45'
C Compact currency and negative symbols to the left of the return. For example:

'$(21.45)'

'$21.45'
[symbol] One character that identifies the currency symbol, if any, to search for. Two single quotation marks with no intervening space indicates a null symbol value. $
[separator] One character that identifies the thousands separator, if any, used in the value. Two single quotation marks with no intervening space indicates a null separator value. , (comma)
[decimal] One character that identifies the decimal character, if any, used in the value. Two single quotation marks with no intervening space indicates a null decimal value. . (period)

Results

Result Description
Return string reformatted as a currency amount.
%%RC One of the following:
-1 width is less than 1 or greater than 50
0 No error.
1 string is more than 100 characters in length. EngageOne™ Enrichment uses only the first 100 characters.
2 string was 0 characters in length.
11 A negative value is present for a non-negative format. EngageOne™ Enrichment returns the positive result.
20 The returned value exceeds width. EngageOne™ Enrichment returns the complete formatted value anyway.
%%RM A null string ('').
%%RV The number of characters in the return.

Examples

Function Call Return %%RC %%RV
FORMAT('123456',8, 2, Y, 1, R,$,',','.') '$ 1,234.56' 20 11
FORMAT('-123456',15,2,Y,1,R,$,',','.') ' $(1,234.56)' 0 15
FORMAT('123456',8,2,N,11,C,$,',','.') '123,456.00 CR' 20 13
FORMAT(' -1234567890 is alot',8,2,N,11,C,$,',','.') '1,234,567,890.00 DR' 20 19