PSP Decimal Overflow

Want more information ?. Try the Web Home Page for this document.

PSPDec Overflow

Two PSPDec methods (setOverflow(byte) and setOverflowDefault(byte)) concern numeric values which have more digits before the decimal place than the PSPDec itself e.g. a numeric value of ‘1234.00’ for a number with DigitsBeforeDP set to 3. When such a value is assigned to a PSPDec, ‘overflow’ is said to occur.

Overflow occurs following actions in your program code. For example, the program assigns the value ‘1234.00’ to the PSPDec using the setValue(String) method. How PSPDec responds in this case is determined by the overflow setting which you can determine using the getOverflow() method.

You can set/get the overflow values (Java bytes) as in the following examples:

// Construct PSPDec
PSPDec Dec1 = new PSPDec(11,2,"1234.56");
// Set overflow handling to truncation with a beep
Dec1.setOverflow(PSPDec.OVERFLOW_TRUNCATE_BEEP);
// Reset overflow handling to increment DIGITS_BEFOREDP
Dec1.setOverflow(PSPDec.OVERFLOW_BUMP_BEFOREDP);
// Retrieve current value for overflow
byte curOverflow = Dec1.getOverflow();

PSPDec Overflow Settings

Overflow Setting	What happens when overflow occurs
OVERFLOW_IGNORE	The new value (excess high-order digits and all other digits) is ignored. The value of the PSPDec does not change.
OVERFLOW_IGNORE_BEEP	Same as above. The system also beeps.
OVERFLOW_TRUNCATE	The excess high-order digit(s) are truncated i.e. chopped off. For example, ‘1234.00’ simply becomes ‘234.00’. The new truncated value is assigned to the PSPDec.
OVERFLOW_TRUNCATE_BEEP	Same as above. The system also beeps.
OVERFLOW_BUMP_BEFOREDP	PSPDec automatically increments the `DigitsBeforeDP` property value to accomodate the new numeric value, which is immediately assigned. Any increase to the size of the PSPDec is permanent i.e. `DigitsBeforeDP` is not automatically reduced later if smaller numeric values are assigned to the PSPDec. If the PSPDec.MAX_DIGITS_BEFORE limit is reached, then further overflow is treated the same as OVERFLOW_EXCEPTION below.
OVERFLOW_EXCEPTION	The new value (excess high-order digits and all other digits) is ignored. The value of the number does not change. PSPDec throws a PSPException error for which `getErrNum()` returns `PSPException.NumOverflow`. This error is also thrown if MAX_DIGITS_BEFORE limit is reached when OVERFLOW_BUMP_BEFOREDP is set.

Overflow defaults to OVERFLOW_BUMP_BEFOREDP for a PSPDec when it is first created.

Tips for overflow settings

If you always want to ignore new numeric values that trigger overflow, choose one of the OVERFLOW_IGNORE, OVERFLOW_IGNORE_BEEP or OVERFLOW_EXCEPTION settings.

A truncated numeric value (OVERFLOW_TRUNCATE or OVERFLOW_TRUNCATE_BEEP) may be quite acceptable in certain circumstances. For example, you may deliberately isolate the fractional portion of one PSPDec value by assigning it's value to another number which has DigitsBeforeDP set to zero.

Automatically incrementing DigitsBeforeDP using OVERFLOW_BUMP_BEFOREDP makes sense only if the rest of your application can live with an incremented DigitsBeforeDP.

Using one of the 'beep' values (OVERFLOW_IGNORE_BEEP or OVERFLOW_TRUNCATE_BEEP) may not be a good idea, depending upon your view of user interface design. You may instead choose OVERFLOW_EXCEPTION and present the overflow error in a more user-friendly manner e.g. a dialog box. You also need to exercise judgement as to where the 'beep' is actually triggered - a beep on a server system may be meaningless to a PSPDec user on another far-away system.