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.

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), 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, 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. 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. Enrichment returns the positive result.
20 The returned value exceeds width. 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