Additional options

If any of these parameters is changed, all the decNumber source files being used must be recompiled to ensure correct operation.

Each parameter is set to a default value in one of the header files, as noted below. The parameters are only set if undefined, so the defaults can be overridden by compiler command-line definitions (e.g., with the option -DDECUSE64=0).

Customization parameters

The first parameter controls the layout of the compressed decimal formats. The storage of a number in these formats must follow the byte ordering (‘endianness’) of the computing platform; this parameter determines how the formats are loaded and stored. The parameter is set in the decNumberLocal.h file, and is:

DECLITEND

This must be either 1 or 0. If 1, the target platform is assumed to be little-endian (for example, AMD and Intel x86 architecture machines are little-endian, where the byte containing the sign bit of the format is at the highest memory address). If 0, the target platform is assumed to be big-endian (for example, for IBM System z machines are big-endian, where the byte containing the sign bit of the format is at the lowest memory address).

Many compilers provide a compile-time definition for determining the endianness of the target platform, and DECLITEND can in that case be defined to use the provided definition.

The decContextTestEndian function can be called to check that the DECLITEND parameter is set correctly.

A second customization parameter allows the use of 64-bit integers to improve the performance of certain operations (notably multiplication and the mathematical functions), even when DECDPUN is less than 5. (64-bit integers are required for the decNumber module when DECDPUN is 5 or more.) The parameter is set in the decNumberLocal.h file, and is:

DECUSE64

This must be either 1 or 0. If 1, which is recommended, 64-bit integers will be used for most multiplications and mathematical functions when DECDPUN<=4, and for most operations when DECDPUN>4. If set to 0, 64-bit integer support is not used when DECDPUN<=4, and the maximum value for DECDPUN is then 4. Full 64-bit support is not assumed; only 32×32 to 64 and the inverse (divide) are used; most 32-bit compilers will be able to handle these efficiently without requiring 64-bit hardware.

Another customization parameter controls whether the status flags returned by decNumber are restricted to the five IEEE flags or comprise an extended set which gives more detail about invalid operations along with some extra flags (this does not affect performance). The parameter is set in the decContext.h file, and is:

DECEXTFLAG

This must be either 1 or 0. If 1, the extended set of flags is used. If 0, only 5 bits are used, corresponding to the IEEE 754 flags.

The fourth customization parameter enables the inclusion of extra code which implements and enforces the subset arithmetic defined by ANSI X3.274. This option should be disabled, for best performance, unless the subset arithmetic is required.

The parameter is set in the decContext.h file, and is:

DECSUBSET

This must be either 1 or 0. If 1, subset arithmetic is enabled. This setting includes the extended flag in the decContext structure and all code which depends on that flag. Setting DECSUBSET to 0 improves the performance of many operations by 10%–20%.

Tuning parameters

DECDPUN

This parameter is set in the decNumber.h file, and must be an integer in the range 1 through 9. It sets the number of digits held in one unit, which in turn alters the performance and other characteristics of the library. In particular:

• If DECDPUN is 1, conversions are fast, but arithmetic operations are at their slowest. In general, as the value of DECDPUN increases, arithmetic speed improves and conversion speed gets worse.
• Conversions between the decNumber internal format and the decimal64 and other compressed formats are fastest – sometimes by as much as a factor of 4 or 5 – when DECDPUN is 3 (because Densely Packed Decimal encodes digits in groups of three).
• If DECDPUN is not 1, 3, or a power of two, calculations converting digits to units and vice versa are slow; this may slow some operations by up to 20%.
• If DECDPUN is greater than 4, either non-ANSI-C-89 integers or library calls have to be used for 64-bit intermediate calculations.^[1] 

The suggested value for DECDPUN is 3, which gives good performance for working with the compressed decimal formats. If the compressed formats are not being used, or 64-bit integers are unavailable (see DECUSE64, below), then measuring the effect of changing DECDPUN to 4 is suggested. If the library is to be used for high precision calculations (many tens of digits) then it is recommended that measurements be made to evaluate whether to set DECDPUN to 8 (or possibly to 9, though this will often be slower).

DECBUFFER

This parameter is set in the decNumberLocal.h file, and must be a non-negative integer. It sets the precision, in digits, which the operator functions will handle without allocating dynamic storage.^[2] 

One or more buffers of at least DECBUFFER bytes will be allocated on the stack, depending on the function. It is recommended that DECBUFFER be a multiple of DECDPUN and also a multiple of 4, and large enough to hold common numbers in your application.

Print and testing parameters

DECPRINT

This must be either 1 or 0. If 1, calls to printf are permitted; if 0, they will not. In the latter case, the decContextTestEndian will not display a warning message (even if its argument is 0), and also the functions decSingleShow, decDoubleShow, and decQuadShow will be excluded from compilation.

The decNumber package also incorporates three compile-time parameters which control the inclusion of extra code which provides for extra checking of input arguments, etc., run-time internal tracing control, and storage allocation auditing. These options are usually disabled, for best performance, but are useful for testing and when introducing new conversion routines, etc. It is recommended that DECCHECK be set to 1 while developing an application that uses decNumber.

These test settings may all report errors using the printf function, so DECPRINT must be set to 1 if any of them are used. The parameters are all set in the decNumberLocal.h file, and are:

DECCHECK

This must be either 1 or 0. If 1, extra checking code, including input structure reference checks, will be included in the module. The latter checks that the structure references are not NULL, and that they refer to valid (internally consistent in the current context) structures. If an invalid reference is detected, the DEC_Invalid_operation status bit is set (which may cause a trap), a message may be displayed using printf, and any result will be a valid number of undefined value. This option is especially useful when testing programs that construct decNumber structures explicitly.

Some operations take more than twice as long with this checking enabled, so it is normally assumed that all decNumbers are valid and DECCHECK is set to 0.

DECALLOC

This must be either 1 or 0. If 1, all dynamic storage usage is audited and extra space is allocated to enable buffer overflow corruption checks. The cost of these checks is fairly small, but the setting should normally be left as 0 unless changes are being made to the decNumber.c source file.

DECTRACE

This must be either 1 or 0. If 1, certain critical values are traced (using printf) as operations take place. This is intended for decNumber development use only, so again should normally be left as 0.