Binary Export Results

Data Types

Values written out fall into the following five types:

• Long integer (4 bytes)
• Floating point value in IEEE format (4 bytes) – usually referred to as a ‘Float’ or a ‘Single’ depending on the language in which you are writing your program to read the file in.
• Floating point value in IEEE format (8 bytes) – usually referred to as a ‘Double’. These are only used in the summary results files.
• Timestep – 8 bytes – see below.
• String – variable length – see below.

Dates

Dates are written as 8 byte doubles.

Absolute values represent 'real' times, typically from data from real rainfall events. Relative values represent times typically from synthetic rainfall events.

If the value of the double is less than or equal to zero, then it represents a relative time in seconds. The number should be negated and then treated as a number of seconds.

If the value of the double is positive, then it represents an absolute time in Microsoft's 'OLEDateTime' format. In this format, dates are represented as a number of days since midnight December 30, 1899.

For example, the value -120 means a relative time of 120 seconds, whereas the value 40909.625 means 15:00 on 1 March 2012.

Strings

The purpose of the padding is to help in cases where it is advantageous for a program reading the data to have the data values on 4 byte boundaries within the file i.e. to have every floating point number start at an offset of a multiple of 4 bytes from the beginning of the file.

For example, the string OUTFALL would be represented as follows:

Whereas the string OUTFALLS would be represented as follows:

File Contents - Full time varying results export

Each file contains the following:

1. A format indicator, currently a long containing the value 20110922 (4 bytes).
2. A long integer containing the number of (4 bytes), then for each timestep:
   1. Normal simulations - the timestep as a double in the OLE date format (8 bytes).
3. A long integer containing the number of tables exported (4 bytes).
4. A long integer containing the number of words in block 5 [see below] (4 bytes) i.e. the value has always been the number of words in block 5.
5. For each table with results to export:
   1. A long integer containing the number of objects exported for that table (4 bytes).
   2. A long integer containing the number of non-blob attributes exported for that table (4 bytes) – these are attributes where there is one value for each object.
   3. A long integer containing the number of blob attributes exported for that table (4 bytes) – these are attributes where there can be more than one value for each object.
   4. A string containing the table name.
   5. A string containing the table description.
   6. This is then followed by a block containing strings with information for the attributes and objects of that table as follows:
      1. For each non-blob attribute:
         1. A string containing its internal name.
         2. A string containing its description.
         3. A string containing the units for that attributes (if any).
         4. A long integer containing the precision for the field (4 bytes).
      2. For each blob attribute, the same strings as for the non-blob attributes.
      3. For each object in the table:
         1. A string containing its ID.
         2. For each blob attribute for this table, a long integer (4 bytes) indicating the number of values there are for this object for that attribute. This is necessary because in some cases the number of values varies by blob attribute as well as by object.
6. This is then followed by the results data. This is best explained by means of some pseudo-code:

For all timesteps in order
	For all tables with results to export (in the same order as the header described above)
		For all objects in that table (in the same order as the header described above)
			For all non-blob attributes (in the same order as the header)
				export value (float)
			End
			For all blob attributes (in the same order as the header)
				For I = 1 To the number of values for this attribute for this object
					Export value (float)
				Next I
			End
		End
	End
End

The value described in 4 above, the number of 4 byte words in blocks 5 and 6 may be used to skip past those blocks if, for example, you believe you know what is in them already. It is a number of 'words' i.e. the number of bytes in blocks 5 and 6 divided by 4.

The results begin at offset 4 + (2 * number of timesteps) + 'number of words in block 5' 4 byte words from the start of the file.

The results for each timestep take up the same amount of space in the file, and each results attribute for each object (or attributes in the case of blobs) can be found at the same position in the results for each timestep relative to the start of that timestep. That amount of space and those offsets can be calculated when reading the header of the file.

File Contents - Summary results export

Each file contains the following:

1. A format indicator, currently a long value containing 20151009 (4 bytes).
2. A long integer containing the number of tables exported (4 bytes).
3. A long integer containing the number of words in block J [see below] (4 bytes).
4. Then for each table with results to export:
   1. A long integer containing the number of objects exported for that table (4 bytes).
   2. A long integer containing the number of non-blob attributes exported for that table (4 bytes) – these are attributes where there is one value for each object.
   3. A long integer containing the number of 4 byte floating point number (sometimes termed ‘single’) blob attributes exported for that table (4 bytes) – these are attributes where there can be more than one value for each object.
   4. A long integer containing the number of 8 byte floating point number (sometimes termed ‘double’) blob attributes exported for that table (8 bytes) – these are attributes where there can be more than one value for each object.
   5. A string containing the table name
   6. A string containing the table description.
   7. This is then followed by a block containing strings with information for the attributes and objects of that table as follows:
      1. For each non-blob attribute:
         1. A string containing its internal name.
         2. A string containing its description.
         3. A string containing the units for that attributes (if any).
         4. A long integer containing the precision for the field (4 bytes).
      2. For each 4 byte blob attribute, the same strings as for the non-blob attributes.
      3. For each 8 byte blob attribute, the same strings as for the non-blob attributes.
      4. For each object in the table
         1. A string containing its ID.
         2. For each blob attribute for this table, a long integer (4 bytes) indicating the number of values there are for this object for that attribute. This is necessary because in some cases the number of values varies by blob attribute as well as by object.
5. There then follows the results data. This is best explained by means of some pseudo-code:

   For all tables with results to export (in the same order as the header described above)
   	For all objects in that table (in the same order as the header described above)
   		For all non-blob attributes (in the same order as the header)
   			export value (float)
   		End
   		For all 4 byte blob attributes (in the same order as the header)
   			For I = 1 To the number of values for this attribute for this object
   				Export value (float)
   			Next I
   		End
   		For all 8byte blob attributes (in the same order as the header)
   			For I = 1 To the number of values for this attribute for this object
   				Export value (double)
   			Next I
   		End
   	End
   End
   

For the summary results, an extra table is exported with the name 'scalars'. This always has exactly one object called 'Scalars'. Its attributes are the single values reported for the whole simulation e.g. total lost, total outflow from outfalls, total rainfall. Because this 'Scalars' object is not a real network object, and therefore does not appear in any selection list, the table will not be exported if the export is done for a selection list.

The format indicators are the same for all three types of object and the normal sim.

Differences between the summary and full time varying results files

The differences between the two formats are the following:

• A different header value to distinguish the two files.
• The summary file does not have the number of timesteps or the values specifying the timesteps, instead there is just one set of summary values (primarily maximum and minimum)
• Each table has an additional single value for it in the header – the number of double precision floating point values i.e. the section for each table begins with 4 long values rather than 3.
• The full time varying results do not contain any double values – the full time varying results can be considered as always having zero 8 byte blob attributes for each object type.