BCD

Synopsis

HELP:   Binary coded decimal (BCD) number
TYPE:   OBJECT
SYNTAX: BCD(SIGNED,TYPE=UNPACKED/PACKED/ZONED,ZONE=SYSTEM/ASCII/EBCDIC,DIGITS=num,BYTES=num)

Description

Writes a binary-coded decimal (BCD) representation of an integer number, taking an FL5-internal neutral integer 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

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).

The length of the written BCD number can be specified in three ways:

1. Setting the DIGITS to a value greater than zero causes this writer to always write exactly the specified number of decimal digits. The number is padded with leading zeros if necessary. If the BCD representation is longer than the specified amount of digits, a range error occurs. Please note that the digits count does not include a sign (if present) and that the byte length of the resulting BCD number is roughly half of the digits count when writing packed BCD numbers.
2. No integral digits but setting the BYTES for a fixed length data type will result in a calculated amount of digits to fit within the requested space. This simplifies the type and sign dependent amount of integral digits if the number must fit in a fix structure. The rest works like if this amount of DIGITS is given.
3. By omitting the DIGITS and BYTES parameter, the buffer given to the writer is always filled completely. This allows using one converter handle to convert to BCD numbers of different lengths, when using the byte interface (fcbconv()), by simply passing output buffers of different sizes. Numbers are padded with zero, if necessary. If the output buffer is too short, a range error occurs.

Arguments

• SWITCH: SIGNED - Enable for signed BCD [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: DIGITS=num - Print exactly this amount of digits (excl. sign) [variable]
• NUMBER: BYTES=num - Calculate digits to produce fixed length data type [variable]