QUANTIZE

The QUANTIZE function returns a decimal floating-point value that is equal in value (except for any rounding) and sign to expression-1 and which has an exponent set equal to the exponent in expression-2.

expression-1: An expression that returns a value of any built-in numeric, character-string, or graphic-string data type. If the data type of the argument is not a DECFLOAT value, it is converted to DECFLOAT(34) for processing.
expression-2: An expression that returns a value of any built-in numeric, character-string, or graphic-string data type. If the data type of the argument is not a DECFLOAT value, it is converted to DECFLOAT(34) for processing.

If one argument (after conversion) is DECFLOAT(16) and the other is DECFLOAT(34), the DECFLOAT(16) argument is converted to DECFLOAT(34) before the function is processed.

The coefficient of the result is derived from that of expression-1. It is rounded if necessary (if the exponent is being increased), multiplied by a power of ten (if the exponent is being decreased), or remains unchanged (if the exponent is already equal to that of expression-2).

If necessary, the rounding mode is used by the QUANTIZE function. See CURRENT DECFLOAT ROUNDING MODE for more information.

Unlike other arithmetic operations on the DECFLOAT data type, if the length of the coefficient after the quantize operation would be greater than the precision of the resulting DECFLOAT number, an error occurs. This guarantees that unless there is an error, the exponent of the result of a QUANTIZE function is always equal to that of expression-2.

The result of the function is a DECFLOAT(16) value if both arguments are DECFLOAT(16). Otherwise, the result of the function is a DECFLOAT(34) value. If either argument can be null, the result can be null; if either argument is null, the result is the null value

Note

Results involving DECFLOAT special values: Decimal floating-point special values are treated as follows:

If either argument is NaN and the first argument is not -NaN, then NaN is returned.
If either argument is sNaN, then a warning or error occurs. ^¹
If either argument is -NaN and the first argument is not NaN, then -NaN is returned.
If either argument is -sNaN, then a warning or error occurs. ^¹
If both arguments are Infinity (positive or negative), then Infinity (positive or negative) is returned.
If one argument is Infinity (positive or negative) and the other argument is not Infinity (positive or negative), then NaN is returned. ^¹

Examples

The following examples illustrate the value that is returned for the QUANTIZE function given the input DECFLOAT values:

 QUANTIZE(2.17, 0.001)            ==> 2.170
 QUANTIZE(2.17, 0.01)             ==> 2.17
 QUANTIZE(2.17, 0.1)              ==> 2.2
 QUANTIZE(2.17, 1e+0)             ==> 2
 QUANTIZE(2.17, 1e+1)             ==> 0E+1
 QUANTIZE(2, Infinity)            ==> NaN (exception)
 QUANTIZE(0, 1e+5)                ==> 0E+5
 QUANTIZE(217, 1e-1)              ==> 217.0
 QUANTIZE(217, 1e+0)              ==> 217
 QUANTIZE(217, 1e+1)              ==> 2.2E+2
 QUANTIZE(217, 1e+2)              ==> 2E+2

In the following example, the value -0 is returned for the QUANTIZE function. The CHAR function is used to avoid the potential removal of the minus sign by a client program.

 CHAR(QUANTIZE(-0.1, 1))          ==> -0

¹ If *YES is specified for the SQL_DECFLOAT_WARNINGS query option, NaN is returned with a warning.