Big Decimal (BigDecimal) Support for Real Numbers
The translator allows you to use either Java™ double primitive or Big Decimal data types for real numbers. Big Decimal can be used regardless of the standard you are using, but if you are using a financial standard (for example, SWIFT, ACH, OAGi, Target2, IFX, ISO 20022, FpML, FIXML, TWIST, and OFX) we highly recommend that you use Big Decimal.
Big Decimal mode was implemented to allow users to have control over rounding in math operations. When Big Decimal is used, the translator also allows you to control the rounding behavior for mathematical operations. We recommend that you use Big Decimal when you have an application that requires exact precision for mathematical operations. The Java double primitive type has inherent rounding errors and may therefore produce inexact results (for example, 80000.01 multiplied by 100 will yield 8000000.999999999, using the Java double primitive type). These rounding and precision errors occur because Java double primitive types are represented as binary fractions, per the IEEE standard 754, and therefore the Java double primitive type cannot accurately represent decimal fractions. For example, 0.1 is a repeating decimal number in binary (that is, base 2—not base 10). The use of java double primitives can also introduce rounding errors when the translator converts these values to and from strings.
Using Big Decimal mode tells the translator to use “BigDecimal” java instances instead of java “double” primitives. Use of the java double primitives has been retained by default, since that is the legacy behavior of the translator.
If you do not experience issues related to rounding errors, you will likely not want to use Big Decimal mode. However, as a general rule, financial standards should use BigDecimal mode by default (for example, SWIFT). Maps that use Real values for math operations in extended rules and data type conversion, particularly for scientific applications that require precise math operations, should also use Big Decimal mode.
Maps can be assigned Big Decimal mode from the Sterling B2B Integrator Map Editor (hence the compiled txo). You can set Big Decimal for a map by selecting Use BigDecimal Mode on the Map Detail dialog box.
Each rounding mode indicates how the least significant returned digit of a rounded result should be calculated. The Big Decimal rounding modes are described in the following table:
| Big Decimal Rounding Mode |
Description |
|---|---|
| CEILING | Rounding mode is to round towards positive infinity. |
| DOWN | Rounding mode is to round towards zero. |
| FLOOR | Rounding mode is to round towards negative infinity. |
| HALF_DOWN | Rounding mode is to round toward the nearest neighbor unless both neighbors are equidistant (n this case, round down). |
| HALF_EVEN | Rounding mode is to round toward the nearest neighbor unless both neighbors are equidistant, (and in this case, round toward the even neighbor). |
| HALF_UP | Rounding mode is to round toward the nearest neighbor, unless both neighbors are equidistant (and in this case, round up). This is the default. |
| UNNECESSARY | Rounding mode is to assert that the requested operation has an exact result, and therefore no rounding is necessary. |
| UP | Rounding mode is to round away from zero. |
The following table exemplifies how different two-digit decimal values would round to a one digit decimal value, using the Big Decimal rounding mode specified.
| Input Number | UP | DOWN | CEILING | FLOOR | HALF_UP | HALF_DOWN | HALF_EVEN | UNNECESSARY |
|---|---|---|---|---|---|---|---|---|
| 5.5 | 6 | 5 | 6 | 5 | 6 | 5 | 6 | throw ArithmeticException |
| 2.5 | 3 | 2 | 3 | 2 | 3 | 2 | 2 | throw ArithmeticException |
| 1.6 | 2 | 1 | 2 | 1 | 2 | 2 | 2 | throw ArithmeticException |
| 1.1 | 2 | 1 | 2 | 1 | 1 | 1 | 1 | throw ArithmeticException |
| 1.0 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 |
| -1.0 | -1 | -1 | -1 | -1 | -1 | -1 | -1 | -1 |
| -1.1 | -2 | -1 | -1 | -2 | -1 | -1 | -1 | throw ArithmeticException |
| -1.6 | -2 | -1 | -1 | -2 | -2 | -2 | -2 | throw ArithmeticException |
| -2.5 | -3 | -2 | -2 | -3 | -3 | -2 | -2 | throw ArithmeticException |
| -5.5 | -6 | -5 | -5 | -6 | -6 | -5 | -6 | throw ArithmeticException |
The properties in the customer_overrides.properties file that govern rounding behavior are as follows:
- The extendedRules.useRoundingModeForDoubles property
allows you to maintain backward compatibility for maps created prior
to the initiation of Big Decimal support. When you enable Big Decimal
mode (using the storage.useBigDecimal property), you must set
this parameter to false.
extendedRules.useRoundingModeForDouble=falseIf you are not using Big Decimal, leave this property set to true.
extendedRules.useRoundingModeForDoubles=true - The storage.bigDecimalRoundingMode property
sets the rounding mode when Big Decimal is used. The default is HALF_UP,
meaning that the rounding mode is to round toward the nearest neighbor
unless both neighbors are equidistant, (and in this case, round toward
the even neighbor). This property allows you great control over rounding
behavior because it enables you to invoke rounding modes equivalent
to the Big Decimal rounding modes (listed below).
storage.bigDecimalRoundingMode=HALF_UPThis property can be set to the following values (Big Decimal rounding modes):
- CEILING
- FLOOR
- UP
- DOWN
- HALF_DOWN
- HALF_EVEN
- HALF_UP
- UNNECESSARY.
- The storage.bigDecimalMaximumDefaultScale property
sets the default maximum scale for when Big Decimal is used and an
explicit scale is not defined based on the field limits (such as,
accumulator operations). The default for this property is 10.
storage.bigDecimalMaximumDefaultScale=10