The decNumber Library, version 3.36
Copyright (c) IBM Corporation, 2006. All rights reserved. ©
6 Jul 2006
[previous | contents | next]

Additional options

This section describes some additional features of the decNumber package, intended to be used when extending the package or tuning its performance. If you are just using the package for applications, using full IEEE arithmetic, you should not need to modify the parameters controlling these features.


Tuning and testing parameters

The decNumber package incorporates a number of compile-time parameters. If any of these parameters is changed, all the decNumber source files being used must be recompiled to ensure correct operation.

Two parameters are used to tune the trade-offs between storage use and speed. The first of these determines the granularity of calculations (the number of digits per unit of storage) and is normally set to three or to a power of two. The second is normally set so that short numbers (tens of digits) require no storage management – working buffers for operations will be stack based, not dynamically allocated.

These are:

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: 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 DECBUFFER-sized buffers will be allocated on the stack, depending on the function; comparison, additions, subtractions, and exponentiation all allocate one, multiplication allocates two, and division allocates three; more complex operations may allocate more. 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.

A third compile-time parameter controls the layout of the compressed decimal formats. The storage of a number in these formats may be chosen to either follow the byte ordering (‘endianness’) of the computing platform or to use fixed ordering. For best performance when using these formats, this parameter should be set to 1. The parameter is set in the decNumberLocal.h file, and is:

DECENDIAN
This must be either 1 or 0. If 1, which is recommended, the formats will be stored following the endianness of the underlying computing platform. For example, for AMD and Intel x86 architecture machines, which are little-endian, the byte containing the sign bit of the format is at the highest memory address; for IBM z-Series machines, which are big-endian, the byte containing the sign bit of the format is at the lowest memory address. This setting means that the decimal formats will be stored using the same ordering as binary integer and floating-point formats on the same machine, and also allows much faster conversions (up to a factor of three) to and from the decNumber internal form.

Setting DECENDIAN to 0 forces the formats to be stored using fixed, big-endian, ordering. This is provided for compatibility with earlier versions of the decNumber package.

A fourth compile-time 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 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.

Three further compile-time parameters control the inclusion of extra code which provides for full checking of input arguments, 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. These parameters are all set in the decNumberLocal.h file, and are:

DECCHECK
This must be either 1 or 0. If 1, code which checks input structure references will be included in the module. This 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), and any result will be a valid number of undefined value. This option is useful for verifying programs which 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 development use only, so again should normally be left as 0.

A final compile-time 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%.

Footnotes:
[1] The decNumber library currently assumes that non-ANSI-89 64-bit integers are available if DECDPUN is greater than 4. See also the DECUSE64 tuning parameter.
[2] Dynamic storage may still be allocated in certain cases, but in general this is rare.

[previous | contents | next]