Previous: Remote access with IDL   Up: Remote data access programming reference - toc   Next: Administration guide

Remote access reference using Fortran 95

Unlike the Matlab, IDL, or python API, the Fortran 95 Madrigal APIis built on a low level language, and so there are only lower-level commands available. This API could be used to build similar functionality to global isprint or global download methods of the higher-level languages if third party Fortran libraries for such things as date manipulation were added to it.

Use of this API requires that wget be installed on your machine (freely available on the web).

The following are the methods for accessing Madrigal data remotely via Fortran 95:

These methods return the following Fortran types:

Madrigal Fortran95 API methods

get_connection

          function get_connection(madrigal_url, user_fullname, &
          user_email, user_affiliation)
          ! get_connection returns the connection type needed by all other methods
          ! always the first method called for each session
          ! arguments:
          !  madrigal_url - url of particular Madrigal site's home page
          !  user_fullname - your full name
          !  user_email - your email
          !  user_affiliation - your affiliation. Use 'None' if none
          ! returns a connection structure which is the first argument of all other calls

get_instruments

          subroutine get_instruments(conn, inst_arr, inst_count)
          ! get_instruments allocates an array of instrument structures
          ! describing all available Madrigal instruments
          !
          ! arguments:
          !  conn - the connection structure created by get_connection call
          !  inst_arr - a pointer to an instrument array to be allocated and populated.
          !     user is responsible for calling deallocate and nullify when done
          !  inst_count - set to the number of instruments in inst_arr

get_sites

          subroutine get_sites(conn, site_arr, site_count)
          ! get_sites allocates an array of site structures
          ! describing all available Madrigal sites
          !
          ! arguments:
          !  conn - the connection structure created by get_connection call
          !  site_arr - a pointer to a site array to be allocated and populated.
          !     user is responsible for calling deallocate and nullify when done
          !  site_count - set to the number of sites in site_arr

get_experiments

          subroutine get_experiments(conn, kinst, syear, smonth, sday, shour, sminute, ssecond,  &
               eyear, emonth, eday, ehour, eminute, esecond, local_only, exp_arr, exp_count)
          ! get_experiments allocates an array of exteriment structures
          ! describing all available Madrigal experiments with the given kinst and time range
          !
          ! arguments:
          !  conn - the connection structure created by get_connection call
          !  syear, smonth, sday, shour, sminute, ssecond - exclude exps before this time
          !  eyear, emonth, eday, ehour, eminute, esecond - exclude exps after this time
          !  local_only - if True, only return experiments local to this server.
          !               if False, return local and remote experiments
          !  exp_arr - a pointer to an experiment array to be allocated and populated.
          !     user is responsible for calling deallocate and nullify when done
          !  exp_count - set to the number of experiments in exp_arr

get_experiment_files

          subroutine get_experiment_files(conn, exp_id, file_arr, file_count)
          ! get_experiment_files allocates an array of experiment_file structures
          ! describing all available Madrigal files for the given experiment id
          !
          ! arguments:
          !  conn - the connection structure created by get_connection call
          !  exp_id - experiment id as returned by get_experiments
          !  file_arr - a pointer to ae experiment_file array to be allocated and populated.
          !     user is responsible for calling deallocate and nullify when done
          !  file_count - set to the number of file in file_arr

get_cedar_parameters

          subroutine get_cedar_parameters(conn, fullname, parm_arr, parm_count)
          ! get_cedar_parameters allocates an array of cedar_parameter structures
          ! describing all available Madrigal parameters for the given fullname of file
          ! as returned by get_experiment_files
          !
          ! arguments:
          !  conn - the connection structure created by get_connection call
          !  fullname - fullname of madrigal file as returned by get_experiment_files
          !  parm_arr - a pointer to an cedar_parameter array to be allocated and populated.
          !     user is responsible for calling deallocate and nullify when done
          !  parm_count - set to the number of cedar_parameters in parm_arr
          !
          ! delimiter is \, not ,
          !

download_file

          function download_file(conn, fullname, destination, user_fullname, user_email, user_affiliation, file_format)
          ! download_file downloads fullname as returned by get_experiment_files to destination is specified
          !    file_format
          !
          ! arguments:
          !  conn - the connection structure created by get_connection call
          !  fullname - fullname of madrigal file as returned by get_experiment_files
          !  destination - full path to save file as locally
          !  user_fullname, user_email, user_affiliation - three string describing requester
          !  file_format - must be 'ascii', 'hdf5', or 'netCDF4'.  'netCDF4' requires
          !    a madrigal 3.0 site of higher
          !
          ! Returns 0 is success, -1 if not
          !

isprint

          function isprint(conn, fullname, parms, filters, destination, user_fullname, user_email, user_affiliation)
          ! isprint downloads fullname to destination with requested parms and filters applied.  parms
          !     may include both measured and derived parameters.  Format of output file is hdf5, netCDF4, or
          !     ascii as determined by destination extension
          !
          ! arguments:
          !  conn - the connection structure created by get_connection call
          !  fullname - fullname of madrigal file as returned by get_experiment_files
          !  parms - Comma delimited string listing requested parameters (no spaces allowed).
          !  filters - Space delimited string listing filters desired, as in isprint command All filters
          !      begin with ==filter=. Details: --filter=<[mnemonic] or [mnemonic1,[+-*/]mnemonic2]>,<lower limit1>,
          !      <upper limit1>[or<lower limit2>,<upper limit2>...] a filter using any measured or derived Madrigal
          !      parameter, or two Madrigal parameters either added, subtracted, multiplied or divided. Each filter
          !      has one or more allowed ranges. The filter accepts data that is in any allowed range. If the Madrigal
          !      parameter value is missing, the filter will always reject that data. Multiple filter arguments are
          !      allowed. To skip either a lower limit or an upper limit, leave it blank. Examples: (--filter=ti,500,1000
          !      (Accept when 500 <= Ti <= 1000) or --filter=gdalt,-,sdwht,0, (Accept when gdalt > shadowheight - that is,
          !      point in direct sunlight) or --filter=gdalt,200,300or1000,1200
          !      (Accept when 200 <= gdalt <= 300 OR 1000 <= gdalt <= 1200))
          !  destination - full path to save file as locally. If extention is .h5, .hdf, or .hdf5,
          !     will download in Madrigal Hdf5 format. If it has a .nc extension, will
          !     download as netCDF4. Otherwise, it will download as column delimited ascii.
          !     Trying to save as Hdf5 or netCDF4 with a Madrigal 2 site will raise an exception
          !  user_fullname, user_email, user_affiliation - three string describing requester
          !
          ! Returns 0 is success, -1 if not
          !

mad_calculator

          function mad_calculator(conn, parms, destination, year, month, day, hour, minute, second,   &
              start_lat, stop_lat, step_lat, start_lon, stop_lon, step_lon, start_alt, stop_alt, step_alt, &
              one_d_parms, one_d_values)
          ! mad_calculator runs the Madrigal derivation engine to derive the requested parameters for the specified time
          !     and range of geodetic locations. Writes ascii output to destination.  Optional arguments
          !     are one_d_parms and one_d_values, where if given these set additional one d values for the given one d parms.
          !
          ! arguments:
          !  conn - the connection structure created by get_connection call
          !  parms - Comma delimited string listing requested parameters (no spaces allowed).
          !  destination - full path to save ascii file as locally.
          !  year, month, day, hour. minute. second - six integers that set input time
          !  start_lat, stop_lat, step_lat - three real dp that set latitude range and step in degrees (-90 to 90)
          !  start_lon, stop_lon, step_lon - three real dp that set longitude range and step in degrees (-180 to 180)
          !  start_alt, stop_alt, step_alt - three real dp that set altitude range and step in km
          !  one_d_parms - a string with comma separated mnemonics representing the one D parameters to specify (no spaces)
          !     (optional argument). Example: 'azm,elm'
          !  one_d_values - a string with comma separated float strings representing the one D values to specify (no spaces)
          !     (optional argument) Number of values must match number of parms in one_d_parms. Example: '27.5,-165'
          !
          ! Returns 0 is success, -1 if not
          !

Types created by the above methods

connection

          ! connection - created by get_connection
          ! passed into all other methods
          type :: connection
              character (len=1024) :: main_url
              character (len=1024) :: cgi_url
              character (len=512)  :: user_fullname
              character (len=512)  :: user_email
              character (len=512)  :: user_affiliation
              integer              :: site_id ! site id of site connected to
              character (len=1024) :: version ! version of local Madrigal site in form I.I[.I]
          end type connection

instrument

          ! instrument - created by get_instruments
          type :: instrument
              character (len=1024)  :: name ! instrument name
              integer               :: code ! instrument id code (kinst)
              character (len=12)    :: mnemonic ! 3 letter code
              double precision      :: latitude
              double precision      :: longitude
              double precision      :: altitude ! in km
              character (len=1024)  :: category ! Example: 'Incoherent Scatter Radars'
              character (len=1024)  :: pi ! Instrument PI.  Will be 'Unknown' for Madrigal 2.X sites
              character (len=1024)  :: pi_email ! Instrument PI email.  Will be 'Unknown' for Madrigal 2.X sites
          end type instrument

site

          ! site - created by get_sites
          type :: site
              integer               :: site_id
              character (len=1024)  :: site_name ! site name
              character (len=1024)  :: site_url ! url to site home page
              character (len=1024)  :: contact_name ! site contact name
              character (len=1024)  :: contact_email ! site contact email
          end type site

experiment

          ! experiment - created by get_experiments
          type :: experiment
              integer               :: id ! unique id that identifies experiment
              character (len=1024)  :: url ! Example: 'http://madrigal.haystack.mit.edu/cgi-bin/madtoc/1997/mlh/03dec97'
              character (len=1024)  :: name ! experiment name. Example: 'Wide Latitude Substorm Study'
              integer               :: site_id ! site id of Madrigal site where data located
              character (len=1024)  :: site_name ! site name of site where data is. eg: 'Millstone Hill'
              integer               :: kinst ! id code of instrument
              character (len=1024)  :: inst_name ! Example: 'Millstone Hill Zenith Radar'
              integer               :: syear, smonth, sday, shour, sminute, ssecond ! start time
              integer               :: eyear, emonth, eday, ehour, eminute, esecond ! end time
              logical               :: is_local ! True if local data to this Madrigal site, False if remote data
              character (len=1024)  :: madrigal_url ! url to Madrigal site where data is. If local, same as init
              character (len=1024)  :: pi ! Instrument PI.  Will be 'Unknown' for Madrigal 2.X sites
              character (len=1024)  :: pi_email ! Instrument PI email.  Will be 'Unknown' for Madrigal 2.X sites
              character (len=1024)  :: real_url ! real url to Madrigal experiment. url string is only historical format
              integer               :: uttimestamp ! st_mtime of expDir. -999 if not supported by the Madrigal site
              integer               :: access ! access code of the experiment (0 if public, 2 if public, -999 if n/a).
              character (len=1024)  :: version ! version of Madrigal site where data is in form I.I[.I]
          end type experiment

experiment_file

          ! experiment_file - created by get_experiment_files
          type :: experiment_file
              character (len=1024)  :: fullname ! file fullname
              integer               :: kindat ! kind of data code of this file
              character (len=2048)  :: kindat_desc ! string describing kind of data
              integer               :: category ! (1=default, 2=variant, 3=history, 4=real-time)
              character (len=1024)  :: status ! status description
              integer               :: permission ! 0 for public, 1 for private
              integer               :: exp_id ! experiment id this file belongs to
          end type experiment_file

cedar_parameter

          ! cedar_parameter - created by get_cedar_parameters
          type :: cedar_parameter
              character (len=128)   :: mnemonic ! parameter mnemonic
              character (len=2048)  :: description ! parameter description
              integer               :: is_error ! 1 if error parameter, 0 if not
              character (len=128)   :: units ! units description
              integer               :: is_measured ! 1 if parm in file, 0 if derived
              character (len=1028)  :: category ! parameter category description
          end type cedar_parameter
Previous: Remote access with IDL   Up: Remote data access programming reference - toc   Next: Administration guide