9.115 HEXTOBIN

Note: Built-In Function Rules Usage Options

Converts the alphanumeric source string to its binary format. Each pair of characters in the source will be converted into its binary equivalent.

The source string should contain only characters 0-9, A-F. Any invalid characters will be treated as zero and an error status returned. The source string must be a multiple of two in length.

For example, source contains alphanumeric string C1C2 (IBM i) 4142 (Windows), Return is AB

Arguments

No

Type

Req/ Opt

Description

Min Len

Max Len

Min Dec

Max Dec

1

A

Req

Source:
Must contain only characters 0-9, A-F
Must be a multiple of 2 in length.

2

Unlimited

2

A

Opt

Y = Return true binary value.

N = (Default) Return "string like" binary value. The first NULL byte in the return will be the terminator of the string.

1

Return Values

No	Type	Req/ Opt	Description	Min Len	Max Len	Min Dec	Max Dec
1	w	Req	Returned binary value	1	Unlimited
2	A	Opt	Return code. OK = action completed. ER = An error occurred.	2	2

Technical Note

If 'Y' is specified for the second argument, use a Binary ( or Alpha ) field to get the returned value. Any other field type may cause the returned value to be truncated or unusable.

Example:

     FUNCTION OPTIONS(*DIRECT)
     DEFINE FIELD(#MYHEX) TYPE(*CHAR) LENGTH(100)
     DEFINE FIELD(#MYHEX2) TYPE(*CHAR) LENGTH(100)
     DEFINE FIELD(#MYRET) TYPE(*CHAR) LENGTH(2)
     DEFINE FIELD(#MYLEN) TYPE(*DEC) LENGTH(3) DECIMALS(0)
     CHANGE FIELD(#MYHEX) TO('''414D5120414D5359443337202020002044B826A420C12563''')
     USE BUILTIN(HEXTOBIN) WITH_ARGS(#MYHEX 'Y') TO_GET(#MYBIN #MYRET)       (1)
     CHANGE FIELD(#MYLEN) TO('24')                                           (3)
     USE BUILTIN(BINTOHEX) WITH_ARGS(#MYBIN #MYLEN) TO_GET(#MYHEX2 #MYRET)   (2)
     RETURN

If #MYBIN is a Binary (or Alpha) field and is equal to or greater than 24 bytes, the BINTOHEX in (2) will return #MYHEX2 with same value as #MYHEX has. The value in #MYRET is 'OK'

If #MYBIN is a String, the BINTOHEX in (2) will return nothing to #MYHEX2 and the value in #MYRET will be 'ER'.

Reason: Although the HEXTOBIN in (1) is instructed to return true binary value, the String nature of #MYBIN in this case will prevent it holding the full result. In fact #MYBIN will only get the binary form of '414D5120414D5359443337202020' as the next '00' is considered as a string terminator. So for the BINTOHEX in (2) #MYBIN has only 14 bytes, which is shorter than the 24 bytes expected.