:Revision=3
:html
<<
128.174
HexFile-Object|HexFile
$NoSort
--
The IP-Object <!RW>HexFile enables the access to files in the Intel-Hex or Motorola-S-Record Format. 

Of course, these files could be processed via file access with the IP-Object <!RW>FILE. However, <!RW>HexFile simplifies the access, because the decoding is done automatically and the data and addresses can be accessed directly.

If necessary, an extension to other Hex-Formats is possible.

Hex-Files are read all at once and if this is done successfully the individual records can be accessed one after the other separately.
>>

<<
128.174.1
Functions of the HexFile-Object|Functions
--
>>
<<
128.174.1.1
HexFile.EOF|EOF
--
<!DEF>
function <!TW>HexFile.EOF : real;
<!TXT>
Returns <!RW>TRUE, if the end of the Hex-File has been reached, so, when the last record was accessed.
>>
<<
128.174.1.2
HexFile.Error|Error
!128.174.3 - Error codes
!128.174.1.5 - Line
--
<!DEF>
function <!TW>HexFile.Error : real;
<!TXT>
Returns the result of the last <!RW>HexFile.Open-Action.
>>
<<
128.174.1.3
HexFile.Data|Data
--
<!DEF>
function <!TW>HexFile.Data : vector;
<!TXT>
Returns the current record as vector. If the EOF is reached, then the vector is empty.

The address, where the first byte of the vector belongs to can be accessed with the <!RW>HexFile.Address.
>>
<<
128.174.1.4
HexFile.Address|Address
--
<!DEF>
function <!TW>HexFile.Address : real;
<!TXT>
Returns the address of the first byte of the current record. When the EOF is reached the result is always 0.

The record whose first byte belongs to this address can be accessed with <!RW>HexFile.Data.
>>
<<
128.174.1.5
HexFile.Line|Line
!128.174.3 - Error codes
!128.174.2 - Error
--
<!DEF>
function <!TW>HexFile.Line : real;
<!TXT>
Returns the number of the record in which an error occured during <!RW>Hexfile.Open().

Special cases:
<!STBL>
<!>-1<!>no error<!>
<!>0<!>file empty /not found<!>
<!ETBL>
>>
<<
128.174.1.6
HexFile.Get|Get
--
<!DEF>
function <!TW>HexFile.Get (rAddress : real) : real;
<!TXT>
Returns the value of the byte at the address <!PW>rAddress. If no Hexfile has been read in, or there is no byte at the respective address, then -1 is returned.
>>

<<
128.174.2
Procedures of the HexFile-Object|Procedures
--
>>
<<
128.174.2.1
HexFile.Open|Open
!128.174.1.2
--
<!DEF>
procedure <!TW>HexFile.Open (sHexFileName : string[; rFormat : real[; rAdrFormat : real]]);
<!TXT>
Opens the file <!PW>sHexFileName and reads in its content. <!PW>rFormat determines the format of the Hex-file. The following formats are defined:
<!STBL>
<!>0<!>Autodetect (Default)<!>
<!>1<!>Intel-Hex<!>
<!>2<!>Motorola S-Record<!>
<!ETBL>
In case of Autodetect, the first character of the first record which is not empty will be analyzed. If this charcater is 'S', then the Motorola-S-Record format is presumed, otherwise Intel-Hex.

The success of this action can be enquired over <!RW>HexFile.Error.
In case of an error, the EOF becomes immediately <!RW>TRUE. If the action is successful, <!RW>HexFile.First is executed automatically.

<!PW>rAdrFormat set the address format. The values 0 and 1 are possible. 0 is the default value and stands for addresses up to 24 bit for downward compatibility. With 1 all addresses up to 32 bit are possible.
>>
<<
128.174.2.2
HexFile.First|First
--
<!DEF>
procedure <!TW>HexFile.First;
<!TXT>
Makes the first record the current record. 

It can be used to start the programming again from the beginning, without reading in the file again.
>>
<<
128.174.2.3
HexFile.Next|Next
--
<!DEF>
procedure <!TW>HexFile.Next;
<!TXT>
Makes the next record the current record. 

If there is a reading attempt over the last record, then EOF becomes <!RW>TRUE.
>>
<<
128.174.2.4
HexFile.Clear|Clear
--
<!DEF>
procedure <!TW>HexFile.Clear;
<!TXT>
Removes the data of the Hex-File from the memory.
>>
<<
128.174.2.5
HexFile.Set|Set
--
<!DEF>
procedure <!TW>HexFile.Set (rAddress, rByte : real);
<!TXT>
Sets the byte at address <!PW>rAddress to the value <!PW>rByte. 

If no hexfile has been read in, or if there is no byte at the respective address, then nothing happens.
>>
<<
128.174.2.6
HexFile.Save|Save
--
<!DEF>
procedure <!TW>HexFile.Set (sFileName : string; rFormat : real; sFormatInfo : string);
<!TXT>
Saves the Hexfile under the name <!PW>sFileName. With this procedure, a Hexfile can be read in, modified and saved again (even changed into a different format).

rFormat specifies the wanted file format:
<!STBL>
<!>1<!>Intel-Hex<!>
<!>2<!>Motorola S-Record<!>
<!ETBL>
0 for Autodetect is not possible here.

 <!PW>sFormatInfo contains additional information regarding the wanted format in the form:
<tt>
 [Name=Value [; Name=Value [; Name=Value ...]] 
</tt>
Depending on the format, there are different additional information types:

<h4>Intel-Hex:</h4>
<!STBL>
<tr bgcolor=f0f0f0><td colspan=2><b>AddressMode=</b><!>
<!>64K<br><!REM>(Default)<!TXT><!>pure 16 Bit Model, no extra Address Record is written. Highest address $FFFF.<!>
<!>LINEAR<!>32 Bit Model, an Extra Linear Address Record is written. Highest address $FFFFFFFF.<!>
<!>SEGMENTED<!>20 Bit Model, an Extra Segmented Address Record is written. Highest address $000FFFFF.<!>
<!ETBL>
<ul indent=13>
<li>No Header-Record is written.</li>
<li>An End-Record with the address 0000 is written.</li>
</ul>

<h4>Motorola S-Record:</h4>
<!STBL>
<tr bgcolor=f0f0f0><td colspan=2><b>AddressMode=</b><!>
<!>S1 <font size=-2>or</font> 16<!>Every data is written in S1 records with 16 bit addresses. Highest address $FFFF. In the end, an S9 Record is written.<!>
<!>S2 <font size=-2>or</font> 24<!>Every data is written in S2 records with 24 bit addresses. Highest address $FFFFFF. In the end, an S8 Record is written.<!>
<!>S3 <font size=-2>or</font> 32<!>Every data is written in S2 records with 24 bit addresses. Highest address $FFFFFFFF. In the end, an S7 Record is written.<!>
<!>S* <font size=-2>or</font> Best<!>Depending on the address, the shortest possible record is written. Highest address $FFFFFFFF. In the end, an S9 Record is written.<!>
<!ETBL>
<ul indent=13>
<li>No S5 Records are written.</li>
<li>The address in the End-Record is always 0.</li>
</ul>
>>

<<
128.174.3
Error codes of the HexFile-Object|Error codes
--
<!STBL>
<!+>Code<!+>Meaning<!>
<!c>0<!>everything okay<!>
<!c>1<!>file not found<!>
<!c>2<!>error during the file loading<!>
<!c>3<!>no data in the file<!>
<!c>4<!>file format error<!>
<!c>5<!>incorrect check sum <!>
<!c>6<!>parameter incorrect<!>
<!c>7<!>can't write to file<!>
<!ETBL>
>>

<<
128.174.4
Example
--
<!CODE>
Parameter
  psHexFile : (12, string, 'HexFileName', '');

var
  vHexData : vector;
  rHexAddr : real;

step
  HexFile.Open (psHexFile);          // read in file
  if HexFile.Error =0 then begin
    while not HexFile.EOF do begin   // until file-end
      vHexData:=HexFile.Data;        // get data
      rHexAddr:=HexFile.Address;     // get address
 
      ????  ?????                    // Programming with the
      ???????                        // data from the rHexAddr and
      ??? ????                       // carry out vHexData

      HexFile.Next;                  // next record
    end;
    SetValue (0);                    // OK!
  end
  else begin
    SetValue (HexFile.Error);
  end;
end.
<!TXT>
>>
<<
128.174.5
Supported Hex-File-Formats|File-Formate
--
>>
<<
128.174.5.1
Intel HEX Format (.HEX)|Intel-Hex
--
This format consists of an 8-bit HEX-File. Each record starts with an ':' (1), followed by the heading, the data field and the check sum. Each byte is specified with two ASCII-characters as Hexadecimalnumber in the range 00 to FF. (High-Nibble first).

A record has the following setup: 

<!CODE>
:BBAAAATTHHHH....HHHCC
<!TXT>

where: 

<!CODE>
BB   indicates the number of bytes in the data field (0..255)
AAAA indicates the address offset for the data field 
TT   determines the type of records:
     00 - Data record
     01 - End of file record (2)
     02 - Extended segment address record 
     03 - Start segment address record   (3)
     04 - Extended linear address record 
     05 - Start linear address record    (3)
HH   Bytes of the data range, number as specified by BB
CC   Check sum 
<!TXT>

<ol indent=20>
<li>Records which do not start with ':' are ignored!</li>
<li>Records which are after the End of the file record are ignored!</li>
<li>neither of the two Start...records are supported and generate errors!</li>
</ol>
>>
<<
128.174.5.2
Motorola S-Record-Format|S-Record
--
The Motorola S-Record Format consists of records with the following setup:

<!CODE><b>
S<font color=maroon>T</font><font color=green>LL</font><font color=navy>AA..AA</font><font color=purple>DDDD..DDDD<font color=teal>CC</font>
</b><!TXT>

where:

<ul indent=13>
<li>The first character is always an 'S' -> S-Record</li>

<li>T : Type indicates the type of the record. It is an individual number.</li>

<li>LL : Length consists of two Hex-numbers and indicates the number of the subsequent bytes (not letters!) in the record. The length of the address, the data and the check sum are counted.</li>

<li>AA..AA : The address consists of 4, 6 or 8 Hex-numbers (2, 3 or 4 Byte and / or 16-, 24- or 32 bit address).</li>

<li>DD..DD : The data is represented by data bytes, made up of two Hex-numbers each.</li>

<li>CC : The check sum is an ones complement of the lowest byte of the sum of the previous bytes (incl. length, address and data). In other words, if all the data bytes are added up (length, address, data and check sum) then the modulo 256 result must be always 255.</li>
</ul>

Record types and their processing
<!STBL>
<!c>S0<!>Start record, is ignored<!>
<!c>S1<!>Data record with 16 bit address<!>
<!c>S2<!>Data record with 24 bit address<!>
<!c>S3<!>Data record with 32 bit address<!>
<!c>S5<!>Counter record, is ignored<!>
<!c>S7<!>Block end record for data records with 32 bit address<!>
<!c>S8<!>Block end record for data records with 24 bit address<!>
<!c>S9<!>Block end record for data records with 16 bit address<!>
<!ETBL>

Records S4 and S6 are not allowed. Records S7, S8, S9 may follow only after the data-records that match in each case (e.g. S9 after S1).
>>