──FORMAT(number─┬───────────────────────────────────────────┬─)──
└─,─┬──────┬─┬─────────────────────────────┬┘
└before┘ └,─┬─────┬─┬─────────────────┬┘
└after┘ └─,─┬────┬─┬─────┬┘
└expp┘ └,expt┘
FORMAT returns number rounded and formatted.
The number is first rounded and formatted to standard REXX rules, just as though the operation number+0 had been carried out. If only number is given, the result is precisely that of this operation. If any other options are specified, the number is formatted as follows.
The before and after options describe how many characters are to be used for the integer part and decimal part of the result respectively. If either or both of these are omitted, the number of characters used for that part is as needed.
If before is not large enough to contain the integer part of the number, an error results. If before is too large, the number is padded on the left with blanks. If after is not the same size as the decimal part of the number, the number will be rounded (or extended with zeros) to fit. Specifying 0 will cause the number to be rounded to an integer.
Here are some examples:
FORMAT('3',4) -> ' 3'
FORMAT('1.73',4,0) -> ' 2'
FORMAT('1.73',4,3) -> ' 1.730'
FORMAT('-.76',4,1) -> ' -0.8'
FORMAT('3.03',4) -> ' 3.03'
FORMAT(' - 12.73',,4) -> '-12.7300'
FORMAT(' - 12.73') -> '-12.73'
FORMAT('0.000') -> '0'
The first three arguments are as previously described. In addition, expp and expt control the exponent part of the result: expp sets the number of places to be used for the exponent part; the default is to use as many as needed. The expt sets the trigger point for use of exponential notation. If the number of places needed for the integer part exceeds expt, exponential notation is used. Likewise, exponential notation is used if the number of places needed for the decimal part exceeds twice expt. The default is the current setting of NUMERIC DIGITS. If 0 is specified for expt, exponential notation is always used unless the exponent would be 0. The expp must be less than 10, but there is no limit on the other arguments. If 0 is specified for the expp field, no exponent is supplied, and the number is expressed in simple form with added zeros as necessary (this overrides a 0 value of expt). Otherwise, if expp is not large enough to contain the exponent, an error results. If the exponent is 0, in this case (a non-zero expp), then expp+2 blanks are supplied for the exponent part of the result.
Here are some examples:
FORMAT('12345.73',,,2,2) -> '1.234573E+04'
FORMAT('12345.73',,3,,0) -> '1.235E+4'
FORMAT('1.234573',,3,,0) -> '1.235'
FORMAT('12345.73',,,3,6) -> '12345.73'
FORMAT('1234567e5',,3,0) -> '123456700000.000'