ReadUDF TCL UTILITIES USER MANUAL ReadUDF
SYNOPSIS
Read a measurement from a UDF file.
PACKAGE
TCLUDF
NAME
ReadUDF
USAGE
set rV  ReadUDF  Key Ver N sN cN FwD {FullSwp}]
INPUT DEFINITIONS
Key - The data key associated with the with UDF hierarchy of the opened file. Key should have been obtained from a call to GetDataKey.
Ver - Version number associated this file
N - The iD to use when adding data to the the ExDa global variable. ExDa holds all of the read data as well much ancillary data. The data will be stored as ExDa(N,ITEM) where ITEM is the variable name being held.
sN - The VIDF sensor number of the measurement to be returned.
cN - If the data is stored in matrix format this is the column of matrix data to be returned. Matrix formatted data is returned column by column.
FwD - Indicates when to advance the file descriptor to the next time in the data file. A value of 0 holds the file descriptor at the present time and a value of 1 moves the file descriptor to the next time in the file.
FullSwp - An optional variable which allows scalar data stored as an array of measurements to be read in all at once. Default is set to 0 to read measurement by measurement. Setting the value to 1 will indicate that scalar data stored as arrays should be read all at once. This setting will no affect non-scalar measurements or scalar measurements not stored in an array format.
RETURN DEFINITION
1|ALLOK - ALL_OKAY
0|ReadUDF - NO SENSOR - The requested sensor or matrix column is not returned in this time slot.
-1|EOF - End of file reached
-2|ReadUDF - UNOPENED FILES - The data file has not been opened
DESCRIPTION
ReadUDF reads from a UDF data file and returns the data for the measurement associated with the VIDF sensor number sN. Measurements are scalar, array, or matrix by format. Scalar data values are returned singly unless stored as an array of values in which case the entire array may be returned if FullSwp has been set to 1. It should be noted that FilePos in FINE mode will position the file descriptor within a scalar array at the element whose time is closed to the requested start time. As such the first read of an array of scalar data returns all the data from the file pointer on and may not pick up the entire array. Subsequent reads will return the full array. Array data is always returned array by array and matrix data is returned matrix column by matrix column so that multiple reads are required to obtain the full matrix.
All data obtained in the read is returned in the global ExDa array. This includes the start and stop time tags associated with the returned data, the satellite spin rate, the requested measurement, the corresponding set of array indices if the data is an array data set, all mode data, and any ancillary data which is associated with the measurement. Measurement, mode, ancillary, and array indice data are returned in whatever format they were stored in the UDF data file. Since this is often the native telemetry format the data is generally not in a useable format at this point and is needs to be passed to the ConvertToUnits procedure which converts the data to physical units
. The more commonly used elements in the ExDa are shown in the table below. N in the element name refers to the input value of N in the routine.
COMMONLY USED ExDa ELEMENTS
ELEMENT DESCRIPTION
N,BYR Beginning year of the returned data
N,BDY Beginning day of year of the returned data
N,BMSEC Beginning millisecond of day of the returned data.
N,BNSEC Beginning fractional millisecond of day of the returned data multiplied by 109.
N,EYR Ending year of the returned data
N,EDY Ending day of year of the returned data.
N,EMSEC Ending millisecond of day of the returned data.
N,ENSEC Ending fractional millisecond of day of the returned data multiplied by 109.
N,SPIN The spin period in milliseconds.
N,TOTCOLS Total number of matrix columns in a matrix measurement.
N,NSMP Number of data samples returned in in the read. For array measurements this is the array length and for matrix measurements the matrix column size.
N,QuaL The quality flag associated with the measurement.
In addition to information returned in the ExDa array, the beginning and ending phase angle(s) (one per ExDa(N,NSMP)) are returned in the global array ExPhiN, where again N is the value passed into the routine.
The FwD flag advances the file descriptor to the next set of measurements in the file when set to 1. This occurs after the present read and takes effect at the next invocation of ReadUDF. When accessing multiple measurements from the UDF definition the forward flag should be set to 1 when the last measurement is read.
ERRORS
None Generated
C BACKING
No
EXAMPLE(S) 
# INITIALIZE the UDF common variables

UDFInits

# GET the key for the UDF hierarchy IMAGE IMAGE1 OA ORBIT IMOORBIT

set KeY [GetDataKey IMAGE IMAGE1 OA ORBIT IMOORBIT]

# OPEN the data file containing the time 2001 198 1 0 0

FileOpen $KeY 0 2001 198 1 0 0 2001 198 6 0 0

# POSITION the file pointer to the beginning of the requested time

FilePos $KeY 0 2001 198 1 0 0 

# READ in the first three sensors in the OA UDF file. Get the first 5
#   sets of measurements.  PRINT the times associated with each
#   measurement set.

for { set I 0 } { $I < 5 } { incr I } { 
   set FwD 0
   for { set J 0 } { $J < 3 } { incr J } { 
      if { $J == 2 } { set FwD 1 }
      ReadUDF $KeY 0 OA $J 0 $FwD 
   }
   puts stderr "$ExDa(OA,BYR) $ExDa(OA,BDY) $ExDa(OA,BMSEC) to \
                        $ExDa(OA,EYR) $ExDa(OA,EDY) $ExDa(OA,EMSEC)"
}

> 2001 198 3600000 to  2001 198 3720000
> 2001 198 3720000 to  2001 198 3840000
> 2001 198 3840000 to  2001 198 3960000
> 2001 198 3960000 to  2001 198 4080000
> 2001 198 4080000 to  2001 198 4200000
Nov 17, 2006