|
|
|
Remote access using Fortran95 | Doc home | Madrigal home |
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:
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
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
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
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
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
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 ,
!
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
!
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
!
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
!
! 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 - 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 - 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 - 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 - 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 - 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
|
|
|
Remote access using Fortran95 | Doc home | Madrigal home |