Skip to content

Read_Hex

See Also: File I/O Commands, Direct_Input, Read, Readln, Read_Block, Write_Hex, Sequential File I/O

Purpose

To read binary data as two-byte hexadecimal numbers.

Syntax

Read_Hex [Channel {channel-num}] {variable} [{length}]

Argument Explanation

  • channel channelNum
    Input channel to read data from. If omitted, the channel will be that specified in the most recently executed Direct_Input, Read, Read_Block, or Readln command in which channel was specified or implied.

  • variable
    Variable is required, may be of any type except Indicator and cannot be a constant. Additional variables may be on the command line, separated by spaces, without limit.

  • length
    Length is the number of hex values to read. If not used, all data in hex format will be read.

What It Does

Read_Hex reads length hexadecimal characters into variable from the file or device named in the most recently executed Direct_Input command. Read_Hex can be used in conjunction with Write_Hex to convert data between binary and text formats.

It will read the number of bytes specified (by the length parameter) or until non-hex data (which includes the end of line) is encountered. The byte encountered is not read and will remain on the input stream. Specifying 0 as the length reads until non-hex data is encountered.

This command works similarly to the Read_Block command. You can use Read_Hex when reading text formatted as hexadecimal digits, and Read_Block for normal text.

Example

String sTextData
Direct_Input "TestHex"
Read_Hex
sTextData 13
Showln sTextData

In the example above, assume the file TESTHEX contains the following characters:

48656C6C6F2C20776F726C6421

Then the following would be displayed:

Hello, world!

Example

String sData1 sData2 sData3
Direct_Input "TestHex"
Read_Hex
sData2 2
Read_Block 1
Read_Hex
sData2 2

In the example above, assume the file TESTHEX contains the following characters:

10,13

So the hexadecimal characters are separated by non-hexadecimal characters. You will need to use Read_Block to read the non-hexadecimal characters, then continue using Read_Hex.

Notes

  • It is highly recommended to always use the channel feature when doing any sequential I/O, thus making your code more reusable and ready for use with multiple I/O channels if the need arises.

  • If the optional length parameter is not used, the command will read as much data as it can; all data that is in hexadecimal format will be read.

  • The input file or device must be opened with the Direct_Input command prior to using Read_Hex.

  • You can use Read_Block to read an entire file into a UChar.