National Oceanic and
Atmospheric Administration
United States Department of Commerce

Create the Ferret Script that makes the product

Last modified: Mon, 04/03/2017 - 17:29
You need some Ferret logic to create the product for your new operation. The main secret is finding the information you need in the Ferret symbols.

You script will receive a slew of symbols which convey to it everything that it needs to know about the product it is supposed to create. For example:

 DEFINE SYMBOL data_0_region "region_0"
 DEFINE SYMBOL data_0_title "AIR TEMPERATURE (DEG C)"
 DEFINE SYMBOL data_0_url "coads_climatology"
 DEFINE SYMBOL data_0_var "airt"
 DEFINE SYMBOL data_1_region "region_0"
 DEFINE SYMBOL data_1_title "SEA SURFACE TEMPERATURE (Deg C)"
 DEFINE SYMBOL data_1_url "coads_climatology"
 DEFINE SYMBOL data_1_var "sst"
 DEFINE SYMBOL ferret_do_contour "default"
 DEFINE SYMBOL ferret_fill_type "default"
 DEFINE SYMBOL ferret_format "shade"
 DEFINE SYMBOL ferret_image_format "default"
 DEFINE SYMBOL ferret_interpolate_data "false"
 DEFINE SYMBOL ferret_land_type_0 "shade"
 DEFINE SYMBOL ferret_land_type_1 "shade"
 DEFINE SYMBOL ferret_land_type "default"
 DEFINE SYMBOL ferret_mark_grid "default"
 DEFINE SYMBOL ferret_palette "default"
 DEFINE SYMBOL ferret_script "plot"
 DEFINE SYMBOL ferret_size "0.5"
 DEFINE SYMBOL ferret_use_graticules "default"
 DEFINE SYMBOL ferret_use_ref_map "default"
 DEFINE SYMBOL region_0_t_hi "15-Feb"
 DEFINE SYMBOL region_0_t_lo "15-Feb"
 DEFINE SYMBOL region_0_x_hi "180.0"
 DEFINE SYMBOL region_0_x_lo "-180.0"
 DEFINE SYMBOL region_0_y_hi "89.0"
 DEFINE SYMBOL region_0_y_lo "-89.0"
 DEFINE SYMBOL result_plot_image_filename "/usr/local/www/html/TOMCAT_DEMO/tomcat/webapps/LPS/output/A11061B5D1328B3C836C192786B784A8.gif"
 DEFINE SYMBOL result_plot_image_ID "image1"
 DEFINE SYMBOL result_plot_image_type "image"
 DEFINE SYMBOL result_debug_filename "/usr/local/www/html/TOMCAT_DEMO/tomcat/webapps/LPS/output/A11061B5D1328B3C836C192786B784A8_debug.txt"
 DEFINE SYMBOL result_debug_ID "debug"
 DEFINE SYMBOL result_debug_type "debug"
 DEFINE SYMBOL result_count "2"

The first block of symbols relate to the data upon which this operation will be performed.

 DEFINE SYMBOL data_0_region "region_0"
 DEFINE SYMBOL data_0_title "AIR TEMPERATURE (DEG C)"
 DEFINE SYMBOL data_0_url "coads_climatology"
 DEFINE SYMBOL data_0_var "airt"
 DEFINE SYMBOL data_1_region "region_0"
 DEFINE SYMBOL data_1_title "SEA SURFACE TEMPERATURE (Deg C)"
 DEFINE SYMBOL data_1_url "coads_climatology"
 DEFINE SYMBOL data_1_var "sst"

In this particular invocation of the operation, two different data variables were selected in the user interface. They are denoted by the prefixes "data_0" and "data_1". The three most imporant symbols are the "data_n_url" which is the actual file or OPeNDAP URL that contains the data for this variable. The "data_n_var" symbol which contains the netCDF variable name that contains the data and finally, the "data_n_region" symbol which is a reference to region information contained elsewhere in this colleciton of symbols.

The referenced region information is just a collection of high and lowpairs, one pair for each axis upon which this variable is defined. Thehigh and low values can be the same (as is shown in the t axis in thiscase).

 DEFINE SYMBOL region_0_t_hi "15-Feb"
 DEFINE SYMBOL region_0_t_lo "15-Feb"
 DEFINE SYMBOL region_0_x_hi "180.0"
 DEFINE SYMBOL region_0_x_lo "-180.0"
 DEFINE SYMBOL region_0_y_hi "89.0"
 DEFINE SYMBOL region_0_y_lo "-89.0"

The "ferret properties" are specific name/value pairs that are passed in to control the behavior of the Ferret script. 

 DEFINE SYMBOL ferret_do_contour "default"
 DEFINE SYMBOL ferret_fill_type "default"
 DEFINE SYMBOL ferret_format "shade"
 DEFINE SYMBOL ferret_image_format "default"
 DEFINE SYMBOL ferret_interpolate_data "false"
 DEFINE SYMBOL ferret_land_type_0 "shade"
 DEFINE SYMBOL ferret_land_type_1 "shade"
 DEFINE SYMBOL ferret_land_type "default"
 DEFINE SYMBOL ferret_mark_grid "default"
 DEFINE SYMBOL ferret_palette "default"
 DEFINE SYMBOL ferret_script "plot"
 DEFINE SYMBOL ferret_size "0.5"
 DEFINE SYMBOL ferret_use_graticules "default"
 DEFINE SYMBOL ferret_use_ref_map "default"

Typically, these are names and values that are derived from the "options" that are applied to this particular operation. We defined the options for your operation in the previous step. These properties can also be given values or new ones can be created by defining XML like this: <properties><ferret><my_property>my property value</my_property></ferret></properties> anywhere in the <datasets> or <variables> definitions in the configuration file.

The final collection of symbols relates to the output you script is expected to provide.

 DEFINE SYMBOL result_plot_image_filename "/usr/local/www/html/TOMCAT_DEMO/tomcat/webapps/LPS/output/A11061B5D1328B3C836C192786B784A8.gif"
 DEFINE SYMBOL result_plot_image_ID "image"
 DEFINE SYMBOL result_plot_image_type "image"
 DEFINE SYMBOL result_debug_filename "/usr/local/www/html/TOMCAT_DEMO/tomcat/webapps/LPS/output/A11061B5D1328B3C836C192786B784A8_debug.txt"
 DEFINE SYMBOL result_debug_ID "debug"
 DEFINE SYMBOL result_debug_type "debug"
 DEFINE SYMBOL result_count "2"

These symbols are a direct translation of the information in the response section of the XML you used to define the operation.

 <operation name="Test Fancy New Operation" ID="Test" template="test_output" script="Plot_2D">
 <service>ferret</service>
 <response ID="PlotResp" type="HTML" index="1">
 <result type="image" ID="plot_image"/>
 <result type="debug" ID="debug"/>
 <result type="cancel" ID="cancel"/>
 </response>
 </operation>

The one your likely to want to pay attention to is the one tagged with the ID "plot_image" since that's where you want to put the plot image you've created for this operation. E.g. FRAME/FORMAT=gif/FILE="($result_plot_image_filename)"