===================
Verifying HSF files
===================

Licensees of HOOPS/Stream who chose to use *.hsf* as their file name extension are contractually required to write compliant HSF files.

Therefore, it is highly recommended that you take steps to verify the correctness of HSF files that you export using the base classes, since there is the potential of incorrectly **formatting** the data (especially user-data) or incorrectly **organizing** the scene graph. For example, every ``#TKE_Open_Segment`` opcode must be matched by ``#TKE_Close_Segment`` opcode. Testing can be performed in two phases:


Basic testing
-------------

In Windows distributions, the SDK includes a reference application called the Hoops3DPartViewer. It is located in the *bin* directory. After creating an HSF file, read it into the reference application. If there is an error with the **formatting** of the HSF data, the app will generate a corresponding message box and **Advanced Testing** should be performed (discussed below). If no message is generated, then the formatting of the data in the HSF file is valid. 

Correct formatting of the data is not to be confused with the validity of the scene-graph represented in the HSF file. If there is a problem with how the scene-graph is organized, the reference application will generate a HOOPS/3dGS-specific error. This error should be used to try and locate the problem with how the scene-graph was organized. Additionally, after a problematic file has finished loading, it can be useful to export it to an 'HMF' file from the application. This is a readable, ASCII representation of the scene-graph. Inspection of this file may provide clues to the problem with scene-graph organization. 


Advanced testing
----------------

If the reference application reports that there was an error with reading the file, then further steps must be taken to determine the problem. If user data is being written out (via the ``#TKE_Start_User_Data`` opcode, which can be manually exported or exported using the ``TK_User_Data`` opcode handler) confirm that the data is being properly formatted per the notes in the :doc:`customizing HSFs section </prog_guide/base_stream/04_01_base_customize_hsf>`. This type of error could also be due to a bug in the writing or reading logic of the toolkit itself. 

The toolkit provides logfile capabilities to help track down such problems. To use these capabilities, perform the following steps: 

#. Call ``BStreamFileToolkit::SetLogging`` passing true. 
#. Re-export the HSF file; the toolkit will create a file called *hsf_export_log.txt* which contains a byte representing each opcode that was exported. 
#. Read the HSF file using the ``TK_Read_Stream_File`` function as reviewed in the section on :doc:`controlling reading </prog_guide/base_stream/02_03_base_controlling_read_write>` (ensure that any custom opcode handlers that you've created are registered with the ``BStreamFileToolkit`` object passed into ``TK_Read_Stream_File``). The toolkit will create a file called hsf_import_log.txt which contains a byte representing each opcode that was imported.
#. Compare the opcodes in the two log files and look for the first opcode where they differ (if any). It is likely that the first pair of matching opcodes has a problem with data formatting (or the toolkit has a bug). If you cannot find any problem with how you've formatted or exported the data and have a support contract, you should submit the problematic HSF file and the log files to technical support.
