Skip to main content

$ZHEX (ObjectScript)

Converts a hexadecimal string to a decimal number and vice versa.




Argument Description
num An expression that evaluates to a numeric value be converted, either a quoted string or an integer (signed or unsigned).


$ZHEX converts a hexadecimal string to a decimal integer, or a decimal integer to a hexadecimal string.

If num is a string value, $ZHEX interprets it as the hexadecimal representation of a number, and returns that number in decimal. Be sure to place the string value within quotation marks.

If num is a numeric value, $ZHEX converts it to a string representation of the number in hexadecimal format. If either the initial or the final numeric value cannot be represented as an 8-byte signed integer, $ZHEX issues a <FUNCTION> error.

You can perform the same hexadecimal/decimal conversions using the HexToDecimal()Opens in a new tab and DecimalToHex()Opens in a new tab methods of the %SYSTEM.UtilOpens in a new tab class:

  WRITE $SYSTEM.Util.DecimalToHex("27")
  WRITE $SYSTEM.Util.HexToDecimal("27"),!
  WRITE $SYSTEM.Util.HexToDecimal("1B")

$ZHEX can be used with $CHAR to specify a Unicode character using its hexadecimal character code: $CHAR($ZHEX("hexnum")).

Forcing a Hexadecimal Interpretation

To force an integer value to be interpreted as hexadecimal, concatenate any non-hexadecimal character to the end of your num argument. For example:

   WRITE $ZHEX(16_"H")

returns 22.



A string value or a numeric value, a variable that contains a string value or a numeric value, or an expression that evaluates to a string value or a numeric value.

A string value is read as a hexadecimal number and converted to a positive decimal integer. $ZHEX recognizes both uppercase and lowercase letters “A” through “F” as hexadecimal digits. It truncates leading zeros. It does not recognize plus and minus signs or decimal points. It stops evaluation of a string when it encounters a non-hexadecimal character. Therefore, the strings “F”, “f”, “00000F”, “F.7”, and “FRED” all evaluate to decimal 15. If the first character encountered in a string is not a hexadecimal character, $ZHEX evaluates the string as zero. Therefore, the strings “0”, “0.9”, “+F”, “-F”, and “H” all evaluate to zero. The null string ("") is an invalid value and issues a <FUNCTION> error.

An integer value is read as a decimal number and converted to hexadecimal. An integer can be positive or negative. $ZHEX recognizes leading plus and minus signs. It truncates leading zeros. It evaluates nested arithmetic operations. However, it does not recognize decimal points. It issues a <FUNCTION> error if it encounters a decimal point character. Therefore, the integers 217, 0000217, +217, -+-217 all evaluate to hexadecimal D9. -217, -0000217, and -+217 all evaluate to FFFFFFFFFFFFFF27 (the twos complement). Other values, such as floating point numbers, trailing signs, and nonnumeric characters result in a <FUNCTION> or <SYNTAX> error.



returns 15.

   WRITE $ZHEX(15)

returns F.

   WRITE $ZHEX("1AB8")

returns 6840.

   WRITE $ZHEX(6840)

returns 1AB8.


returns 0.

   WRITE $ZHEX(-1)


   WRITE $ZHEX((3+(107*2)))

returns D9.

See Also

FeedbackOpens in a new tab