The UDF Header File

A UDF header file consists of one or more variable length records. Each record in essence is a snapshot of the state of the measurements being returned within the corresponding UDF data file. They are linked to one or more sensor sets within the UDF data file. Information within a header record is used to:

Provides a number of timing variables many of which are used in determining the start and stop time of a measurement.

Provides a list of what measurements are being returned with a sensor set.

Provides quality information for each of the returned measurements.

For array of matrix sensors it provides the array indices of the array or matrix rows being returned.

Holds any instrument status information which may be needed in converting the measurements to physical units (gain, temperature, etc)

As a rule, information within the header file is slowly varying or constant in time. As such it is not unusual for a UDF Header File to consist only a single record. A new header record is written into the Header File file only when any of the fields in the header structure changes.

Record Structure

The structure of a UDF header record is given by the C Structure:

struct HeaderRecord

{

ByTe_2 RecordSize;

ByTe_2 Year;

ByTe_2 Day;

ByTe_1 TimeBase;

u_ByTe_1 NumStatus;

ByTe_4 AccumTm;

ByTe_4 LatencyTm;

ByTe_4 ScanResetTm;

ByTe_4 SSetResetTm;

ByTe_2 NumSensors;

u_ByTe_2 NumSample;

u_ByTe_2 NumColumns;

u_ByTe_2 LeadColumn;

u_ByTe_2 TotColumns;

ByTe_2 ArrayIndex[1 or NumSample];

ByTe_2 SensorIndex[NumSensors];

u_ByTe_1 QualFlags[NumSensors];

u_ByTe_1 StatusData[NumStatus];

};

where the type definitions ByTe_4, ByTe_2, ByTe_1 and u_ByTe_1 represent a 4 byte signed integer, a 2 byte signed integer, an 1 byte signed integer and a 1 byte unsigned integer respectively. All integers should have the endian definition of the local machine. The UDF software will take care of changing this format when when the data is moved to a system which has a different endian definition.

The structure fields have the following definitions. It should be remembered that the field definitions only have meaning for the sensor sets which point to this header record as a source of information.

RecordSize

The length of the header record in bytes. This includes the two bytes of the RecordSize field.

Year

The beginning year of the first measurement in the sensor set. This is specified as a 4 digit quantity (1998, 2004, etc).

Day

The beginning day of year of the first measurement in the sensor set. A year starts at day 1.

TimeBase

The exponent of the scaling factor used to take the value in the AccumTm field to seconds as:

AccumTm(sec) = AccumTm * 10^TimeBase

NumStatus

The number of elements in the header record StatusData field. The value is a constant within any UDF definition and equals the value set in the VIDF Number of Status Bytes field.

AccumTm

An integer specification of the accumulation time of an individual measurement in the sensor set to which this record is associated. Used in conjunction with the TimeBase field, the field gives the measurement accumulation time in seconds.

LatencyTm

The number of microseconds of dead time between successive measurements of the same quantity.

ScanResetTm

The number of microseconds of dead time between successive array measurements. Generally 0 if the measurement does not return an array of data.

SSetResetTm

The the number of microseconds of dead time between the end of the current sensor set and the beginning of the next sensor set.

NumSensors

The number of UDF sensors returned in the sensor set. This value must be less than or equal to the value found in the Number of Sensors VIDF field.

NumSample

The number of measurements returned by under and defined UDF sensor within the sensor set. All sensors returning data within the sensor set must return the same number of values. For sensors associated with array or matrix data this is the array length or matrix column length respectively. For scalar data this is the number of successive scalar measurements returned in the sensor set.

NumColumns

This field is present in the header record only if the UDF sensors are associated with matrix data. The field holds the number of columns of matrix data included in the sensor set for each returned sensor. NOTE: Matrix data may be split across sensor sets and UDF data records.

LeadColumns

This field is present in the header record only if the UDF sensors are associated with matrix data. The field holds the column number of the first column in each matrix being returned in the sensor set. NOTE: Matrix data may be split across sensor sets and UDF data records.

TotColumns

This field is present in the header record only if the UDF sensors are associated with matrix data. The field contains the total number of columns in each matrix being returned in the sensor set. If the matrix is split across multiple sensor sets this is not the same as NumColumns which is the number of columns in the matrix actually contained in the current sensor set. NOTE: Matrix data may be split across sensor sets and UDF data records.

ArrayIndex

An array holding the array indices associated with the measurements being returned under each sensor. Scalar sensors always have an array length of 1 and the array index value should be set to 0. For sensors associated with matrix data this array holds the row numbers of the matrix associated with the returned column of data. If the returned data is either array or matrix data then the length of this field is the value found in the header NumSample field. There is an implicit assumption that the array indices or row numbers are identical for each sensor in the sensor set. sensors have the same set of indices returned.

SensorIndex

An array of length NumSensors which holds the sensor iD for each measurement begin returned in the sensor set. The measurement iDs are offsets into the VIDF field sensor names to the position defining the measurement.

QualFlags

An array of length NumSensors. Each element in the array is a quality indicator for one of the of UDF sensors being returned. The quality indicator(s) are offsets into the VIDF Data Quality Description field.

StatusData

A field of length NumStatus which if zero is not included in the header record. Each element contains data from one of the status definitions given in the VIDF Status Byte Description field. The location of each status data value in the array must match its offset in the Status Byte Description field.