PSPDec Internal Value

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

PSPDec Internal Value

The internal value of a PSPDec depends upon:

1) its size - the specified number of digits either side of the decimal place
2) the format of the value - either zoned decimal or packed decimal.

The value is always stored exactly in an array of bytes with an implicit decimal position i.e. the decimal position is not stored in the value itself but is inherent in the DigitsAfterDP property.

In the table below, example internal values are given in hexadecimal format e.g. 'F0' represents one byte with the hexadecimal value 'F0' (binary 11110000). Each nibble (half-byte) of the hexadecimal value means something different.

DigitsBeforeDP	DigitsAfterDP	Value	Zoned Value	Packed Value	Comment
1	0	0	F0	0F	Non-negative (zero or positive) values have hex 'F' in the low-order byte.
3	0	123	F1F2F3	123F	Zoned values also have hex 'F' in high-order nibbles of other bytes.
3	0	-123	F1F2D3	123D	Negative values have hex 'D' in the low-order byte.
7	0	123	F0F0F0F0F1F2D3	0000123D	High order bytes have zero value if unused.
5	2	1.23	F0F0F0F0F1F2F3	0000123F	Decimal place is implicit.
5	2	-4.56	F0F0F0F0F4F5D6	0000456D	Decimal place is implicit.
6	2	123456.78	F1F2F3F4F5F6F7F8	012345678F	Packed values with even number of total digits have unused high-order nibble (always zero).

From the above table, you can see that zoned decimal format requires one byte per digit. Packed decimal format is more efficient - it requires (digits/2)+1 bytes to store the value. So packed values take less storage, but are (very slightly) slower for some PSPDec operations. However this is not a big deal, so you can safely accept the default (packed) format for all new PSPDec's if you want to. That is, simply use PSPDec constructors without the format parameter. You can even change the default format for new PSPDec's using the setFormatDefault(char) method.

Whatever the internal format, you can always extract the value either way using the getZonedValue() and getPackedValue() methods. Equivalent setZonedValue(byte[]) and setPackedValue(byte[]) methods allow you to assign values in byte arrays directly to the PSPDec. Naturally the byte arrays you assign must respect the rules above for zoned/packed decimal values.

PSPDec Value as plain String

For each PSPDec, the real decimal numeric value can be extracted and assigned as a string as follows:

// Construct PSPDec
PSPDec Dec1 = new PSPDec(3,2,"123.45");
// Extract value to string
String Dec1Value1 = Dec1.toString();
// Set value from string
Dec1.assign("-123.45");

In the string returned from toString():

there may be a leading minus sign (positive values are unsigned)
the decimal place (if any) is determined by the getDecimalPlace() method
the only other characters are numeric digits 0-9

In the string parameter to assign() and other PSPDec functions taking string numbers:

there may be a positive or negative sign at either the start or end of the string
the decimal place (if any) is also determined by the getDecimalPlace() method
the other characters can only be numeric digits 0-9
an invalid string throws a PSPException exception for which the getErrNum() method returns PSPException.BadStringNumber.

You can control which character in the string represents the decimal place using the setDecimalPlace(char) and setDecimalPlaceDefault(char) methods.

PSPDec value as formatted String

The plain strings above holding numeric values can have no non-numeric character other than a sign (+/-) and whatever character you specify for the decimal place.

You may want to format numeric string values with other characters such as a separator for thousand digits or CR instead of a minus sign. This is possible using a mask object. For any PSPDec, you can use this mask to get a formatted string using the toString(PSPDecMask) method. You can also deformat a formatted string using the checkStringNumber(String,PSPDecMask,StringBuffer) method.