ReadVIDF TCL UTILITIES USER MANUAL ReadVIDF
SYNOPSIS
Read a measurement from a UDF file.
PACKAGE
TCLUDF
NAME
ReadVIDF
USAGE
set rV  ReadVIDF  Key Ver Field Block Beg End Ret {AsArray}]
INPUT DEFINITIONS
Key - The data key associated with the with UDF hierarchy of the VIDF opened file. Key should have been obtained from a call to GetDataKey and the VIDF file opened in a call to FileOpen.
Ver - Version number associated this file
Field - The VIDF information field to return. A list of field names is given under the procedure description below.
Block - If the Field being requested is an element in either a table of constant definition block then this field specifies which table or constant definition to obtain the information from. If not then set this variable to 0.
Beg - If the information field contains multiple values this is the index of the first element to return. The first element in the field is element 0.
End - If the information field contains multiple values this is the index of the last element in the to return. If this variable is input as -1 then End is internally set to the last value in the field.
Ret - This is the returned information associated with the VIDF Field. If the field contains multiple values it is returned either as an array or a list of values depending on how AsArray is set.
AsArray - An optional variable which allows the VIDF data to be returned as either an array or a list of values. The default is to return the data as a list. Set the value to 1 to return as an array. This input only has meaning when the VIDF field being returned contains multiple values.
RETURN DEFINITION
Routine returns OK if no errors reported or ERROR: ReadVIDF - VIDF Read Error N if an error is returned. The error iD is returned in N and will be one of those below.
-1 - Invalid Field name
-2 - Total number of elements request is less than 0. (Probably End < Beg)
-3 - Beg exceeds the number of elements in the field.
-4 - End exceeds the number of elements in the field.
DESCRIPTION
ReadVIDF reads from the UDF VIDF data file opened in the call to FileOpen which used the same KeY and Version number passed into the procedure. It returns the informaton associated with the VIDF Field. The valid Field definitions are listed in the table below. The table gives the field name, if the field is part of a table or constant definition block, and a brief description of the field (see the VIDF manual for more complete descriptions).
VIDF FIELD DEFINITIONS
FIELD BLOCK DEFINITION
PROJECT Project lineage designation
MISSION Mission lineage designation
EXPDESC Experiment lineage designation
INSTDESC Instrument lineage designation
CONTACT Contact information
NUMCOMNTS Number of lines of comments
COMMENTS Comment field
DSYEAR Starting year of information
DSDAY Starting day of information
DSMSEC Starting millisecond of information
DSUSEC Starting microsecond of information
DEYEAR Ending year of information
DEDAY Ending day of information
DEMSEC Ending millisecond of information
DEUSEC Ending microsecond of information
SMPID Data storage information
SENMODE Data timing information
NUMQUAL Number of defined quality flags
CALSETS Number of ancillary measurements defined
NUMTBLS Number of defined tables
NUMCONSTS Number of defined constants
STATUS Number of instrument mode flags defined
PADEFINED Pitch Angle information flag
SEN Number of measurement definitions
SWPLEN Array length of measurements
MAXNSS Maximum number of sensor sets in a UDF data record
DATALEN Byte length of a UDF data record
FILLFLAG Data fill value defined flag
FILL Data fill value
DAMETHOD Array timing information
STATUSNAME Instrument mode definitions
STATES Instrument mode ranges
SENNAME Measurement definitions
CALNAMES Ancillary measurement definitions
QUALNAME Quality flag definitions
PAFORMAT Pitch Angle algorithm definition
PAPROJECT Magnetic field data UDF project name
PAMISSION Magnetic field data UDF mission name
PAEXPER Magnetic field data UDF experiment name
PAINST Magnetic field data UDF instrument name
PAVINST Magnetic field data UDF virtual instrument name
PABXBYBZ Magnetic field Bx, By, and Bz sensor numbers
PAAPPS Number of steps in the to-unit algorithm
PATBLS Algorithm table numbers
PAOPS Algorithm operations
DATATYPE Measurement format definitions
TDWLEN Measurement bit lengths
SENSTATUS Measurement status flags
TIMEOFF Measurement timing corrections
CALUSE Ancillary data mapping definitions
CALWLEN Ancillary data bit lengths
CALTARGET Ancillary data targets
TBLSCASZ TABLE Number of elements in table scale array
TBLELESZ TABLE Number of elements in table definition array
TBLTYPE TABLE Table type
TBLDESCLEN TABLE Number of lines in table comment field
TBLDESC TABLE Table comment field
TBLVAR TABLE Number usage definition
TBLEXPAND TABLE Table expansion flag
CRITACTSZ TABLE Number of critical action definitions
CRITSTATUS TABLE Critical instrument mode numbers
CRITOFF TABLE Offsets into the critical action table
CRITACTION TABLE The critical action table elements
TBLFMT TABLE Table format definitions
TBLOFF TABLE Offsets into the table elements data
TBLSCA TABLE The table elements scaling information
TBL TABLE The table elements
CONSTID CONSTANT The constant definition identifier
CONSTDESCLEN CONSTANT Number of lines in constant comment field
CONSTDESC CONSTANT Constant comment field
CONSTSCA CONSTANT The constant elements scaling information
CONST CONSTANT The constant elements
If Field is part of either a Table or Constant definition use Block to specify which Table or Constant definition the field data is to be obtained from. If the field contains multiple values any subset of the values can be returned by specifying a Beg and End index. Both specifications must be within the number of values in the field. Setting Beg to 0 and End to -1 will cause the entire set of values to be returned. Multiple values can be returned either as a list or array of values depending on whether AsArray is set to 0 or 1 respectively.
ERRORS
None Generated
C BACKING
No
EXAMPLE(S) 
# GET the what sensor data are contained in the UDF IMOORBIT definition

# 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.  Do
#   this in case there are multiple time dependent VIDF's for this UDF.

FilePos $KeY 0 2001 198 1 0 0

# READ the number of defined sensors

ReadVIDF $KeY 0 SEN 0 0 -1 nS 

# READ the sensor definitions

ReadVIDF $KeY 0 SENNAME 0 0 -1 sNames

# PRINT OUT THE MEASUREMENT DEFINITIONS

puts stderr "IMOORBIT contains the following $nS measurements:"

for { set I 0 } { $I < $nS } { incr I } { 
   puts stderr [format "  Sensor %2d  %s" $I [lindex $sNames $I]]
}

>IMOORBIT contains the following 25 measurements:
>  Sensor  0    Satellite GCI Position: X
>  Sensor  1    Satellite GCI Position: Y
>  Sensor  2    Satellite GCI Position: Z
>  Sensor  3    Satellite GCI Velocity: X
>  Sensor  4    Satellite GCI Velocity: Y
>  Sensor  5    Satellite GCI Velocity: Z
>  Sensor  6    Satellite GSE Position: X
>  Sensor  7    Satellite GSE Position: Y
>  Sensor  8    Satellite GSE Position: Z
>  Sensor  9    Satellite GSE Velocity: X
>  Sensor 10    Satellite GSE Velocity: Y
>  Sensor 11    Satellite GSE Velocity: Z
>  Sensor 12    Satellite GSM Position: X
>  Sensor 13    Satellite GSM Position: Y
>  Sensor 14    Satellite GSM Position: Z
>  Sensor 15    Satellite GSM Velocity: X
>  Sensor 16    Satellite GSM Velocity: Y
>  Sensor 17    Satellite GSM Velocity: Z
>  Sensor 18    Sun GCI Position: X
>  Sensor 19    Sun GCI Position: Y
>  Sensor 20    Sun GCI Position: Z
>  Sensor 21    Moon GCI Position: X
>  Sensor 22    Moon GCI Position: Y
>  Sensor 23    Moon GCI Position: Z
>  Sensor 24    L-Shell
Feb 18, 2007