formatNumber()

The strLib.formatNumber() system function returns a number as a formatted string.

For more information on how to construct a format string, see Numeric formatting symbols .

Syntax

  strLib.formatNumber(
    value SMALLINT? | INT? | BIGINT? | DECIMAL? |
              MONEY? | SMALLFLOAT? | FLOAT? in
     [ , numericFormat STRING? in] )
  returns (result STRING?)

value

The numeric value to be formatted, which is assignment compatible with one of the types shown.

numericFormat

A string that defines how the number is formatted. If numericFormat is null, empty, or not specified, the following rules apply:

For MONEY type numbers, EGL uses the strLib.defaultMoneyFormat variable to format the value.
For all other types except floating point types, EGL uses the strLib.defaultNumericFormat variable to format the value.
If the default format string is empty or the number is a floating point type, EGL formats it as a string of unpunctuated digits, with these exceptions:
- Negative numbers have a leading sign.
- Numbers with digits after the decimal point include the value of the decimalSymbol build descriptor option.
- MONEY type numbers include the value of the currencySymbol build descriptor option, in the position that is specified by the currencyLocation build descriptor option.
- Floating-point numbers can be written in exponential notation.
If EGL finds a format string, but cannot use it to process the given number, the result is a string of asterisks.

For more information on the default format variables, see defaultMoneyFormat (EGL system variable) and defaultNumericFormat (EGL system variable). For more information on the build descriptor options, see the following topics:

result

A STRING value. If value is null, the function returns a null value.

Example

The following example shows a DECIMAL number formatted to print on a paycheck.

  myNum DECIMAL(9,2) = -27459.01;
  myFormat STRING = "(*,***,###.##)";
  result STRING;
  
  result = strLib.formatNumber(myNum,myFormat);
  // result is (***27,459.01)

Compatibility

Table 1. Compatibility considerations for formatNumber()
Platform	Issue
COBOL generation	When you format floating point numbers, you cannot specify a format. If you call the function with a second parameter, you receive a validation error.
JavaScript generation	The function strLib.formatNumber() is not supported