UDF IDL Keyword Definitions

The UDF IDL Interface supports a number of keywords. These serve two basic purposes: to modify how data is grouped in the IDL data structure and to set the units of the returned measurements. Using the keywords, especially to set up unit definitions, often requires a more detailed understanding of both the UDF structure in general and the UDF PIDF file in particular than most users have or need. This can be circumvented by setting the keywords using the Keyword Selection GUI discussed in the next section.

Setting the keywords without going through the Keyword Selection GUI at times requires some knowledge of the PIDF and how it is organized. This can be found in the PIDF Definition Document. The keywords for which this information will be most important are those which are used to define measurement units. These keywords are arrays with a 1-1 correspondence between the array values and the measurement definitions one of the PIDF measurement blocks. Each array value is the offset into one of the defined unit_numbers defined under each measurement definition. The unit numbers themselves are offsets into the unit definitions given under the UNITS block in the PIDF.

A list of the currently supported keywords is given below followed by a more detailed explanation of each.

AUNITS

The AUNITS keyword is used to set the unit definitions for UDF measurements listed under the PIDF Ancillary Data Block. This is an array field with a 1-1 correspondence to PIDF Ancillary Block measurement definitions. Each array value is an index into the measurement unit_number block.

If the number of elements in the AUNITS array is less than the number of ancillary data definitions in the PIDF Ancillary Block then the value of the last element in the array is applied to all remaining Ancillary Block definitions. When the number of elements in the AUNITS array is larger than the number of ancillary data definitions in the PIDF Ancillary Block all extra elements are ignored.

An example in setting an AUNITS element is found below. The asterisk bracketed section of text shows a hypothetical PIDF Ancillary Data definition in which there are three unit definitions specified (three unit_number fields).

$*********************************************************************
    struct CalSet0 {
        string name = "Sample Data";              $$ cal set name
        string short_name = "SData";              $$ cal set name
        int pidf_cal_num = 0;                     $$ pidf cal number
        int vidf_cal_num = 0;                     $$ cal set no.
        int num_units = 3;                        $$ no. of units
        int unit_number = 0;                      $$ unit number
        int unit_number = 3;                      $$ unit number
        int unit_number = 7;                      $$ unit number
        char cal_modify_flag = 'Y';               $$ cal based on sens
        int number_cal_sensors = 1;               $$ how many sensors
        int cal_based_on_sensor = -1;             $$ sensors
    };
$*********************************************************************

AZIMUTH

The AZIMUTH keyword sets the format for the start and stop UDF azimuth data in the IDL UDF data structure. The azimuth data is returned with each UDF_READ call. This keyword is equivalent to the AZIMUTH option in the Keyword Selection GUI.

The AZIMUTH settings are:

BASEUNIT

The BASEUNIT keyword sets the default Unit Number to select when assigning units to returned UDF measurements which have not explicitly had units numbers assigned through other keywords. This keyword is equivalent to the UNITS option in the Keyword Selection GUI.

The BASEUNIT settings are:

DFORMAT

The DFORMAT keyword sets the floating point representation to use when returning measurements found in the Sensor, Ancillary, and Mode Blocks in the PIDF. This keyword is equivalent to the FORMAToption in the Keyword Selection GUI.

The DFORMAT settings are:

INDICES

The INDICES keyword sets the format for the array index data returned in the IDL UDF data structure. UDF array index data is returned with each UDF_READ whenever the UDF sensor measurements form either array or matrix data. This keyword is equivalent to the ARRAY INDICES option in the Keyword Selection GUI.

The INDICES settings are:

IUNITS

The IUNITS keyword is used to set the unit definition for UDF array indices. It is a single value which can be specified as either a scalar or as an array of one element. The value given is the number of one of the PIDF ScanUnit definitions within the first defined PIDF SCAN BLOCK.

An example in setting an IUNITS keyword is found below. The asterisk bracketed section of text shows a hypothetical PIDF SCAN BLOCK which contains three ScanUnit definitions.

$*********************************************************************
    int num_scan = 1;                            $$ no. of scan blocks
    struct Scan0 {
$----------------------SCAN BLOCK 00----------------------------------
        int scan_block_num = 0;                   $$ scan block number
        int num_units = 3;                        $$ no. scan of units
        struct ScanUnit0 {
            char spacing = 'I';               
            int units_index = 1;             
        };
        struct ScanUnit1 {
            char spacing = 'I';             
            int units_index = 7;           
        };
        struct ScanUnit2 {
            char spacing = 'I';           
            int units_index = 8;         
        };
    };
$*********************************************************************

MUNITS

The MUNITS keyword is used to set the unit definitions for UDF measurements listed under the PIDF Mode Data Block. This is an array field with a 1-1 correspondence to PIDF Mode Block measurement definitions. Each array value is an index into the measurement unit_number block.

If the number of elements in the MUNITS array is less than the number of mode definitions in the PIDF Mode Block then the value of the last element in the array is applied to all remaining Mode Block definitions. When the number of elements in the MUNITS array is larger than the number of mode data definitions in the PIDF Mode Block all extra elements are ignored.

An example in setting an MUNITS element is found below. The asterisk bracketed section of text shows a hypothetical PIDF Mode Data definition definition in which there are two unit definitions specified (two unit_number fields).

$*********************************************************************
    struct Mode0 {
        string name = "Freq Scaling";              $$ mode name
        string short_name = "FqSca";               $$ mode name
        int pidf_mode_num = 0;                     $$ pidf mode number
        int vidf_mode_num = 0;                     $$ mode no.
        int num_units = 2;                         $$ no. of units
        int unit_number = 1;                       $$ unit numbers
        int unit_number = 14;                      $$ unit numbers
    };
$*********************************************************************

SFORMAT

The SFORMAT keyword sets the return format to use for sensor data in the IDL UDF data structure. This keyword is equivalent to the STORAGE option in the Keyword Selection GUI.

The SFORMAT settings are:

SUNITS

The SUNITS keyword is used to set the unit definitions for UDF measurements listed under the PIDF Sensor Data Block which includes those PIDF sensor definitions whose measurement is defined in the VIDF to be ancillary data. This is an array field with a 1-1 correspondence to PIDF Sensor Block measurement definitions. Each array value is an index into the measurement unit_number block.

If the number of elements in the SUNITS array is less than the number of sensor definitions in the PIDF Sensor Block then the value of the last element in the array is applied to all remaining Sensor Block definitions. When the number of elements in the SUNITS array is larger than the number of sensor data definitions in the PIDF Sensor Block all extra elements are ignored.

An example in setting an SUNITS element is found below. The asterisk bracketed section of text shows a hypothetical PIDF Sensor Data definition in which there are five unit definitions specified (five unit_number fields).

$*********************************************************************
    struct Sensor0 {
        string name = "SSD H Elevation 0";        $$ sensor name
        string component = "Elevation 0";         $$ component name
        char source = 'V';                        $$ source (V) (S)
        string scf_filename = "N/A";              $$ not applicable
        char pitch_angle_flag = 'N';              $$ pa calculation
        int pidf_sensor_num = 0;                  $$ pidf sensor num
        int vidf_sensor_num = 0;                  $$ sensor vidf no.
        int group_num = 0;                        $$ sensor group no.
        int scan_block_info = 0;                  $$ scan block info
        int display_flag = 1;                     $$ display bit
        int num_units = 5;                        $$ no. data of units
        int unit_number = 0;                      $$ unit numbers
        int unit_number = 4;                      $$ unit numbers
        int unit_number = 7;                      $$ unit numbers
        int unit_number = 8;                      $$ unit numbers
        int unit_number = 16;                     $$ unit numbers
    };
$*********************************************************************

While it should be obvious, setting the SUNITS keyword definition as SUNITS=[999] is equivalent to setting the selected unit_number definition for each sensor definition in a PIDF Sensor Block to the last defined unit_number. This is identical to setting the keyword BASEUNIT to 1.

THETA

The THETA keyword sets the format for the start and stop UDF elevation data in the IDL UDF data structure. The elevation data is returned with each UDF_READ call. This keyword is equivalent to the ELEVATION option in the Keyword Selection GUI.

The THETA settings are: