BCD

Synopsis

HELP:   Binary coded decimal (BCD) floating point number
TYPE:   OBJECT
SYNTAX: BCD(SIGNED,TYPE=UNPACKED/PACKED/ZONED,ZONE=SYSTEM/ASCII/EBCDIC,INTDIGITS=num,FRACDIGITS=num,ROUNDING[=AWAYFROMZERO/NEAREST/TOWARDZERO/ERROR],BYTES=num)

Description

Writes a binary-coded decimal (BCD) representation of a real number, taking an FL5-internal neutral real number representation (produced by a reading counterpart) as input.

This converter supports multiple formats of BCD numbers. The parameter TYPE must be set to the correct BCD format of the input number. The following formats are supported:

• UNPACKED: Each decimal digit is stored in one byte. Only the lower nibble (4 bits) are used, the upper nibble is ignored
• PACKED: Each decimal digit is stored in one nibble, so one byte contains two decimal digits.
• ZONED: Each decimal digit is stored in one byte. The upper nibble contains the zone bits. They are usually set to a fixed value so that the byte holds a character value corresponding to the digit.

BCD numbers can be signed or unsigned. If the SIGNED flag is specified, numbers are written with a positive or negative sign. Without the flag, output numbers are unsigned. Unsigned BCD numbers can only have positive values. When attempting to convert a negative number to an unsigned BCD, an error occurs. In the signed case, the sign is part of the BCD number. Its specific representation depends on the BCD type:

• UNPACKED: The sign is stored in the right-most byte
• PACKED: The sign is stored in the right-most nibble
• ZONED: The sign is stored in the upper nibble of the right-most byte, replacing the zone bits with the sign value

BCD representations of real numbers are always fixed-point numbers, with an implied decimal (i.e. not stored) point. Therefore, the number of fractional digits must be specified via the FRACDIGITS parameter. If it is omitted, the resulting BCD number consists of only the integral part of the real number, with no fractional digits (i.e. FRACDIGITS=0). If the real number contains more fractional digits than are representable, remaining fractional digits are cut off by default. For a different rounding method or for gerating an error when truncation would occur, set the ROUNDING parameter accordingly.

If the INTDIGITS parameter is specified, the string will always contain exactly the specified number of digits in the integral portion of the BCD number. The integer portion is padded with leading zero digits as necessary. If the number to convert requires more integral digits to be representable as BCD number, an error occurs. If the INTDIGITS parameter is omitted, the buffer passed to this number converter is always filled completely (which is relevant when using the byte interface).

As an alternative to INTDIGITS, you can specify the BYTES parameter. This may be useful for fixed-length data types. By specifying the BYTES and FRACDIGITS parameters, the number of integer digits that fit into the specified number of bytes is calculated depending on the other BCD parameters. If both, INTDIGITS and BYTES, is specified, the BYTES parameter is ignored.

The hexadecimal value 0xD is used for a negative sign. A positive number uses 0xC for the sign. For type ZONED, these sign values only apply for BCD numbers in EBCDIC zone format, i.e. the upper zone nibble is set to 0xF. If the zone is in ASCII format (0x3), the positive sign value is 0x3, the negative sign value is 0x7. So, the decimal number -123 in zoned BCD with an EBCDIC zone is 0xF1F2D3. With an ASCII zone, the same number is stored as 0x313273.

The parameter ZONE is relevant only if TYPE=ZONED and specifies whether the zone is in ASCII (0x3) or EBCDIC (0xF) format and also specifies the values used for the sign nibble as described in the paragraph above. If not specified, the zone is system-dependent (i.e. EBCDIC on EBCDIC machines, ASCII otherwise).

Arguments

• SWITCH: SIGNED - Enable for signed float [FALSE]
• NUMBER: TYPE=UNPACKED/PACKED/ZONED - BCD type [UNPACKED]
  • UNPACKED - Unpacked BCD number
  • PACKED - Packed BCD number
  • ZONED - Zoned BCD number
• NUMBER: ZONE=SYSTEM/ASCII/EBCDIC - Character set (only for type zoned) [SYSTEM]
  • SYSTEM - System character set (ASCII or EBCDIC)
  • ASCII - ASCII character set (0x30-0x39)
  • EBCDIC - EBCDIC character set (0xF0-0xF9)
• NUMBER: INTDIGITS=num - Number of integral digits (before comma) [variable]
• NUMBER: FRACDIGITS=num - Number of fractional digits (after comma) [0 - only integral part]
• NUMBER: ROUNDING=AWAYFROMZERO/NEAREST/TOWARDZERO/ERROR - Rounding method if fractional digits don't fit [TOWARDZERO(=cut off)]
  • AWAYFROMZERO - Round fractional part away from zero (0.1 => 1; -0.1 => -1)
  • NEAREST - Round fractional part toward nearest integer (0.1=>0; 0.5=>1; -0.5=>-1)
  • TOWARDZERO - Round fractional part toward zero (=cut off) (0.9 => 0; -0.9 => 0)
  • ERROR - Return an error instead of rounding a too long number
• NUMBER: BYTES=num - Calculate integral digits to produce fixed length data type [variable]