FORMAT

The FORMAT script function lets you format numbers by adding or removing leading zeros. You can specify the number of leading zeros to add or remove, and you can specify the number of decimal places in floating-point numbers.

Syntax

FORMAT (number [,format])

Parameters

• FORMAT
  Formats numbers

• number
  Number that you want to format
  Format: script literal or script variable

• format
  Zeros that serve as placeholder for the number of leading zeros
  floating-point numbers only: specify a delimiter as the decimal point and number of positions after the decimal point
  Format: script literal or script variable
  Default: 0

Return code: Number with or without leading zeros, depending on what you specify

Notes:

• The number of zeros that you enter in the Format parameter serve as a placeholder for the total number of digits. If the number has fewer digits, the value remains unchanged. Leading zeros are removed if you use this parameter.
• If you include the plus sign (+) as the first character in the Format parameter, then the plus sign is also displayed in positive numbers ("+1.00"). In this case, the target variable that you assign the return code of the FORMAT function to must have data type string. If the result is zero because all decimal places have been removed, then the algebraic sign is removed. For more information, see Script Variable Data Types.
• In floating-point numbers, you can specify the number of decimal places. Define a decimal point as a delimiter in the Format parameter. Enter as many zeros after the delimiter as you want decimal places in your number. Numbers that have more decimal places are truncated without rounding. If you do not specify a decimal point, all decimal places are removed. If the number has fewer decimal places than you specify in the Format parameter, the remaining places are filled with trailing zeros.
• A formatted float variable value must be assigned to a variable of type string.

Examples

The following example removes leading zeros from the 16-digit return code of the SYS_BUSY_60 script function, and prints the result in the activation report:

:SET &SRV#=SYS_BUSY_60()
:SET &RET#=FORMAT(&SRV#)
:PRINT &RET#

The following example adds leading zeros to reach the specified length of 5 digits, and prints the result (00125) in the activation report:

:SET &RET#=FORMAT("125","00000")
:PRINT &RET#

The following example removes leading zeros, and prints the result (333) in the activation report:

:SET &RET#=FORMAT("0000333","00")
:PRINT &RET#

In the following example, the number does not change because there are no leading zeros, so the number fits the specified format as is:

:SET &RET#=FORMAT("555","00")
:PRINT &RET#

The following example formats a floating-point number so that it has only one decimal place, and prints the result (-0.7) in the activation report: 

:DEFINE &NUM#,float
:DEFINE &RET#,string
:SET &NUM#=-0.75
:SET &RET#=FORMAT(&NUM#,"00.0")
:PRINT &RET#

The following example removes all decimal places, and prints the result (0000) to the activation report:

:DEFINE &NUM#,float
:DEFINE &RET#,string
:SET &NUM#=0.65
:SET &RET#=FORMAT(&NUM#,"0000")
:PRINT &RET#

See also: