$ZCONVERT() converts integers between decimal and hexadecimal

Final Release Note

For fast numeric conversion between decimal and hexadecimal, the second and third parameters of $ZCONVERT() can be case-insensitive string values "HEX" or "DEC", the second parameter being the base of the string or number to be converted and the third the base of the output.

  • Unsigned numbers in the range 0 through 0xFFFFFFFFFFFFFFFF can be converted. Decimal return values greater than 999999999999999999 (YottaDB's maximum numeric size) are returned as strings.
  • Hexadecimal numbers are always converted to positive decimal numbers.
  • As conversion from hexadecimal numbers preceded by "-" to decimal is not considered meaningful, if the number to be converted is a “negative” hexadecimal number (e.g., "-F"), the result is 0.
  • Conversion from negative decimal numbers to hexadecimal returns the hexadecimal value of the 2's complement of the number, e.g., the value of $ZCONVERT(-23,"DEC","HEX") is "E9".

The ^%DH() and ^%HD() utility programs use fast $ZCONVERT() conversion when the values supplied are in the range that $ZCONVERT() supports; they otherwise revert to existing conversion logic.

$ZCONVERT() raises the INVCONVERT error for unsupported conversions (e.g., a Unicode conversion in M mode, or converting from DEC to DEC or HEX to HEX) and the INVVALUE error when the input number is outside the supported range. [#485 (closed)]

Description

GTM-5574 addressed range inadequacies in numeric base conversion percent utilities. However, this has slowed down performance such that some users are using the old utility programs, which continue to work with newer versions of software. The utilities should be updated to restore performance. One way to do that is to add support for functions like sprintf() and scanf() to the POSIX plugin, and to have the percent utilities check whether for availability of the required level of the POSIX plugin, and to call the plugin functions if that is the case; falling back to the M code if unavailable.

Draft Release Note

To speed up numeric base conversions between the two most common bases (10 and 16), we add additional options to the $ZCONVERT() utility which can do conversions from decimal to hexadecimal or vice versa of values that would fit in a 64 bit unsigned integer. Note this size exceeds the maximum value that YottaDB can maintain without dropping any bits (YottaDB supports 18 digits of precision while 2^64-1 is 20 digits) but YottaDB, using this $ZCONVERT facility can do this conversion without dropping bits. So if one does $ZCONVERT("FFFFFFFFFFFFFFFF","HEX","DEC"), the returned string (not numeric) will be full precision but if it is used numerically, some precision loss will result.

The extended specification is as follows: $ZCONVERT(value, from, to) where 'from' can be "HEX" or "DEC" and 'to' would be the other (no conversions between hex and hex or between dec and dec). Note that hexadecimal values are ALWAYS converted to positive values. Negative numeric values are supported and convert to the expected hexadecimal values. Note: negative numbers here are represented in 2's complement hex form. In which case, '8'-'F' in the highest order digit represents a negative hex value, so, we decided to not have an additional 'F' prefixing the value to inform its negativity. Where as for the values in the range 1-7 a prefix of 'F' is used to denote the negative value.

The ^%DH() and ^%HD() utilities are modified to take advantage of these faster $ZCONVERT() methods of conversion when the values supplied are in the range that $ZCONVERT() uses. Otherwise the conversions are handled by M code as they were previously.

Errors generated are INVVALUE and INVZCONVERT. INVALUE is raised when input value is out of range, error message conveys information about the input value which caused the error and the range of values supported for conversions between DEC and HEX categories. INVZCONVERT is raised for all unsupported conversions in 3 argument form of $ZCONVERT() (e.g., a Unicode conversion in M mode, or converting from DEC to DEC or HEX to HEX, or converting from UTF-8 to HEX) and error message conveys information about the from and to categories which are allowed.[#485 (closed)]

Edited by Ganesh Mahesh