QUANTIZE scalar function

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

The number of digits (16 or 34) is the same as the number of digits in numeric-expression.

The schema is SYSIBM.

numeric-expression

An expression that returns a value of any built-in numeric data type. If the argument is not a decimal floating-point value, it is converted to DECFLOAT(34) for processing.

exp-expression

An expression that returns a value of any built-in numeric data type. If the argument is not a decimal floating-point value, it is converted to DECFLOAT(34) for processing. The exp-expression is used as an example pattern for rescaling numeric-expression. The sign and coefficient of exp-expression are ignored.

The coefficient of the result is derived from that of numeric-expression. 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 exp-expression).

The CURRENT DECFLOAT ROUNDING MODE special register determines the rounding mode.

Unlike other arithmetic operations on the decimal floating-point data type, if the length of the coefficient after the quantize operation is greater than the precision specified by exp-expression, the result is NaN and a warning is returned (SQLSTATE 0168D). This ensures that, unless there is a warning condition, the exponent of the result of QUANTIZE is always equal to that of exp-expression.

if either argument is NaN, NaN is returned
if either argument is sNaN, NaN is returned and a warning is returned (SQLSTATE 01565)
if both arguments are infinity (positive or negative), infinity with the same sign as the first argument is returned
if one argument is infinity (positive or negative) and the other argument is not infinity, NaN is returned and a warning is returned (SQLSTATE 0168D)

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. The result can be null; if any argument is null, the result is the null value.

Examples

Example 1: The following examples show the values that are returned by the QUANTIZE function given a variety of input decimal floating-point values and assuming a rounding mode of ROUND_HALF_UP:

QUANTIZE(2.17, DECFLOAT(0.001)) = 2.170 
QUANTIZE(2.17, DECFLOAT(0.01)) = 2.17 
QUANTIZE(2.17, DECFLOAT(0.1)) = 2.2 
QUANTIZE(2.17, DECFLOAT('1E+0')) = 2 
QUANTIZE(2.17, DECFLOAT('1E+1')) = 0E+1 
QUANTIZE(2, DECFLOAT(INFINITY)) = NaN    -- warning 
QUANTIZE(0, DECFLOAT('1E+5')) = 0E+5 
QUANTIZE(217, DECFLOAT('1E-1')) = 217.0 
QUANTIZE(217, DECFLOAT('1E+0')) = 217 
QUANTIZE(217, DECFLOAT('1E+1')) = 2.2E+2 
QUANTIZE(217, DECFLOAT('1E+2')) = 2E+2

Example 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, DECFLOAT(1))) = -0 
```