INPUT DEFINITIONS

DESCRIPTION read_drec() accesses data from the currently active sensor set within the UDF file identified with Key and Ver and returns the data associated with Sensor. If there are no measurements found associated with this sensor in the sensor set then an error is indicated. Sensor can be set to a negative number in which case it is set internally to the first sensor returned in the sensor set. This is useful when the data of interest is either preface or general ancillary data or mode data since it ensures that the data is returned with each read without worrying if the sensor measurement was present in the data. When data is acquired it is placed within the memory block pointed to by UDF.

UDF measurements fall under three definitions:

Scalar A single point measurement. There may be more than once instance of the scalar measurement within a UDF sensor set. Vector An array of measurements (e.g. counts vs energy; power vs frequency). There is only one instance of a given measurement per sensor set. Matrix A number of vector measurements linked under a common sensor name. Each vector measurement forms a column in the matrix. Matrix sensor columns always run sequentially from 0 to N where N is the number of matrix columns being returned.

The actions of read_drec() vary with the type of data being acquired. When accessing a scalar measurement, MCol is ignored and a single instance of the measurement is retrieved unless FullCol is set in which case all of the measurements in the sensor set beginning at the current measurement are returned. Both MCol and FullCol are ignored when retrieving vector data. The read routine always returns a full array of values at each call. Matrix data is returned one column at a time, the column indicated by MCol and in this case is similar to vector data.

In addition to returning the requested sensor data, read_drec() also returns: full timing information, all mode data for the current sensor set, all ancillary data associated with the sensor, spin angle information, where applicable pitch angle information, the data quality flag and for vector and matrix data the array indices or row numbers respectively.

After a read has been performed the data pointer can either be advanced in time (TimeAdv = 1) or remain at its current position. Advancing in time moves the data pointer to the next instance of the measurement. When retrieving multiple sensors at a given time period, the pointer should be advanced on the request of the last measurement.

Because time advances after a measurement read it is possible for the routine to indicate an end of file status on a successful read. After a call to read_drec() the filled_data field in the UDF structure should be checked. If 1, then data was acquired during the previous read regardless of what the status message may indicate and should be processed before acting on the status message. The structure field is accessed as

#include "util_str.h" struct idf_data *ExDa; ExDa = (struct idf_data *) UDF; if (ExDa->filled_data) Process DATA

Under normal conditions Ext should be set to a NULL string. Setting Ext to a non-NULL string will cause the file_pos routine to attempt to use the appropriate named UDF header and data files but with the string .Ext appended to it. The file must exist in the current working directory.

RETURN VALUE On success, ALL_OKAY is returned, otherwise an error code is returned.

ERRORS DREC_NOT_FILLED No opened file (file_open not called?) DREC_NO_FILES No opened file: file_open not called DREC_NO_SENSOR Sensor requested no found LOS_STATUS No more data in data file NEXT_FILE_STATUS Data is in next data file

APPLICABLE FORMATS UDF V2.2, IDFS V2.1

RESTRICTIONS When a matrix sensor is spread out over multiple sensor sets the read routine will automatically advance to the next sensor set if the requested matrix column is greater than the largest column number in the current sensor set. Under these conditions you cannot go back to retrieve a column in a previous sensor set. Matrix columns should always be retrieved from least to greatest value.

When accessing matrix sensors which span multiple sensor sets, a TimeAdv will bring you to the next full matrix which in the case of multiple sensors may not be an advance in time.

SEE ALSO ret_codes(1H) file_open (1) file_pos (1) read_drec (1)