; ; NOSA HEADER START ; ; The contents of this file are subject to the terms of the NASA Open ; Source Agreement (NOSA), Version 1.3 only (the "Agreement"). You may ; not use this file except in compliance with the Agreement. ; ; You can obtain a copy of the agreement at ; docs/NASA_Open_Source_Agreement_1.3.txt ; or ; http://cdaweb.gsfc.nasa.gov/WebServices/NASA_Open_Source_Agreement_1.3.txt. ; ; See the Agreement for the specific language governing permissions ; and limitations under the Agreement. ; ; When distributing Covered Code, include this NOSA HEADER in each ; file and include the Agreement file at ; docs/NASA_Open_Source_Agreement_1.3.txt. If applicable, add the ; following below this NOSA HEADER, with the fields enclosed by ; brackets "[]" replaced with your own identifying information: ; Portions Copyright [yyyy] [name of copyright owner] ; ; NOSA HEADER END ; ; Copyright (c) 2010-2014 United States Government as represented by the ; National Aeronautics and Space Administration. No copyright is claimed ; in the United States under Title 17, U.S.Code. All Other Rights Reserved. ; ; ;+ ; This file contains a procedure-oriented wrapper that integrates ; functionality from the SpdfCdas class (IDL client interface to ; <a href="http://cdaweb.gsfc.nasa.gov/WebServices"> ; Coordinated Data Analysis System Web Services</a> (CDAS WSs)) ; and the ; <a href="http://spdf.gsfc.nasa.gov/CDAWlib.html">CDAWlib</a> ; library. ; ; @copyright Copyright (c) 2010-2014 United States Government as ; represented by the National Aeronautics and Space ; Administration. No copyright is claimed in the United States ; under Title 17, U.S.Code. All Other Rights Reserved. ; ; @author B. Harris ;- ;+ ; This function is an example of a callback_function for the ; spdfGetData function. ; ; @param statusInfo {in} {type=strarr} ; @param progressInfo {in} {type=lon64arr} ; @param callbackData {in} {type=reference} ; @returns a continue flag. A return value of zero indicates that ; the operation should be cancelled. A return value of one ; indicates that the operation should continue. ;- function SpdfGetDataCallback, $ statusInfo, progressInfo, callbackData compile_opt idl2 print, 'spdfGetDataCallback: statusInfo:', statusInfo if progressInfo[0] eq 1 then begin percentComplete = $ double(progressInfo[2]) / progressInfo[1] * 100.0 print, progressinfo[2], progressInfo[1], percentComplete, $ format='(%"spdfGetDataCallback: (%d) bytes of (%d) complete (%f%%)")' endif return, 1 end ;+ ; This function gets data from <a href="http://www.nasa.gov/">NASA</a>'s ; <a href="http://spdf.gsfc.nasa.gov/">Space Physics Data Facility</a> ; <a href="http://cdaweb.gsfc.nasa.gov/">Coordinated Data Analysis ; System</a>. ; ; @param dataset {in} {type=string} ; name of dataset to get data from. ; @param variables {in} {out} {type=strarr} ; On entry, names of variables whose values are to be gotten. ; On exit, names of variables actually read (may be more ; than requested). Note that this parameter is ignored when ; the ALL keyword value is greater than 0. ; @param timeSpan {in} {type=strarr(2)} ; ISO 8601 format strings of the start and stop times of the ; data to get. ; @keyword dataview {in} {optional} {type=string} {default='sp_phys'} ; name of dataview containing the dataset. ; @keyword keepfiles {in} {optional} {type=boolean} {default=false} ; The KEEPFILES keyword causes SpdfGetData to retain the ; downloaded data files. Normally these files are deleted ; after the data is read into the IDL environment. ; @keyword quiet {in} {optional} {type=boolean} {default=false} ; SpdfGetData normally prints an error message if no data is ; found. If QUIET is set, no error messages is printed. ; @keyword verbose {in} {optional} {type=boolean} {default=false} ; The VERBOSE keyword causes SpdfGetData to print additional ; status, debugging, and usage information. ; @keyword callback_function {in} {optional} {type=string} ; this keyword value is the name of the IDL function that ; is to be called during this retrieval operation. The ; callbacks provide feedback to the user about the ongoing ; operation, as well as provide a method to cancel an ; ongoing operation. If this keyword is not set, no ; callback to the caller is made. For information on ; creating a callback function, see "Using Callbacks with ; the IDLnetURL Object" in the IDL documentation. ; @keyword callback_data {in} {optional} {type=reference} ; this keyword value contains data that is passed to the ; caller when a callback is made. The data contained in ; this variable is defined and set by the caller. The ; variable is passed, unmodified, directly to the caller ; as a parameter in the callback function. If this keyword ; is not set, the corresponding callback parameter's value ; is undefined. ; @returns structure containing requested data. ; @examples ; <pre> ; d = spdfgetdata('AC_K2_MFI', ['Magnitude', 'BGSEc'], $ ; ['2013-01-01T00:00:00.000Z', '2013-01-03T00:00:00.000Z'], $ ; /VERBOSE) ; ; The Epoch values are returned in d.epoch.dat ; The Magnitude values are in d.magnitude.dat ; The BGSEc values are in d.bgsec.dat ; ; To see further info. about each variable type ; help, /struct, d."variablename" ; To make a plot with the CDAWlib s/w type ; s = spdf_plotmaster(d, /AUTO, /CDAWEB, /GIF, /SMOOTH, /SLOW) ; </pre> ;- function SpdfGetData, $ dataset, variables, timeSpan, dataview = dataview, $ keepfiles = keepfiles, quiet = quiet, $ verbose = verbose, callback_function = callback_function, $ callback_data = callback_data compile_opt idl2 if ~keyword_set(dataview) then begin dataview = 'sp_phys' end cdas = $ obj_new('SpdfCdas', $ endpoint = 'http://cdaweb.gsfc.nasa.gov/WS/cdasr/1', $ userAgent = 'SpdfGetData/1.0', $ defaultDataview = dataview) timeInterval = $ obj_new('SpdfTimeInterval', timeSpan[0], timeSpan[1]) httpErrorReporter = obj_new('SpdfHttpErrorReporter') dataResults = $ cdas->getCdfData( $ timeInterval, dataset, variables, $ httpErrorReporter = httpErrorReporter) if ~obj_valid(dataResults) then begin obj_destroy, timeInterval obj_destroy, cdas return, obj_new() endif fileDescriptions = dataResults->getFileDescriptions() if n_elements(fileDescriptions) gt 0 then begin cd, current=cwd if ~file_test(cwd, /write) then begin tmpDir = getenv('IDL_TMPDIR') pushd, tmpDir if ~keyword_set(quiet) then begin print, 'Warning: The current working directory (', $ cwd, ') is not writable.' print, 'Temporarily changing working directory to ', $ tmpDir if keyword_set(keepfiles) then begin print, 'Downloaded files will be saved to ', tmpDir endif endif endif localCdfNames = strarr(n_elements(fileDescriptions)) for i = 0, n_elements(fileDescriptions) - 1 do begin if obj_valid(fileDescriptions[i]) then begin if keyword_set(callback_function) then begin statusInfo = strarr(1) statusInfo[0] = $ string(i + 1, n_elements(fileDescriptions), $ fileDescriptions[i]->getName(), $ format='(%"Beginning file retrieval (%d) of (%d) (%s)")') progressInfo = lon64arr(5) progressInfo[0] = 0 continue = call_function(callback_function, $ statusInfo, $ progressInfo, $ callback_data) if ~continue then begin obj_destroy, fileDescriptions obj_destroy, dataResults obj_destroy, timeInterval obj_destroy, cdas if n_elements(tmpDir) ne 0 then popd return, 1 endif endif localCdfNames[i] = $ fileDescriptions[i]->getFile($ callback_function=callback_function, $ callback_data=callback_data) endif else begin if keyword_set(verbose) then dataResults->print obj_destroy, fileDescriptions obj_destroy, dataResults obj_destroy, timeInterval obj_destroy, cdas if n_elements(tmpDir) ne 0 then popd return, 1 endelse endfor localCdfNames2 = localCdfNames allVars = '' ; reads data into handles (memory) should be fastest data = spdf_read_mycdf(allVars, localCdfNames2, all = 1, $ /nodata) ; reads data into .dat structure tags ; data = spdf_read_mycdf(variables, localCdfNames) if n_tags(data) eq 3 && $ array_equal (tag_names(data), $ ['DATASET', 'ERROR', 'STATUS']) then begin if keyword_set(verbose) then begin print, 'Error in spdf_read_mycdf()' print, ' ERROR: ', data.error print, ' STATUS: ', data.status endif obj_destroy, fileDescriptions obj_destroy, dataResults obj_destroy, timeInterval obj_destroy, cdas return, 1 endif newbuf = spdf_hsave_struct(data, /nosave) ; don't use the /nosave if you want it saved ; to a save file, need to specify a file name though. if ~keyword_set(keepfiles) then begin file_delete, localCdfNames endif if keyword_set(verbose) then begin if keyword_set(keepfiles) then begin print, 'Data sub/superset returned in local CDF file: ', $ localCdfNames endif print, ' ' print, 'Data variables returned are:' print, ' ' help, /struct, newbuf print, ' ' endif endif else begin if ~keyword_set(quiet) then begin print, 'No data found' endif endelse obj_destroy, fileDescriptions obj_destroy, dataResults obj_destroy, timeInterval obj_destroy, cdas if keyword_set(verbose) then begin print, 'Data values are returned in the data structure in each variables .dat tag member. ' print, ' ' print, "For example - for the call d = spdfgetdata('AC_K2_MFI', ['Magnitude', 'BGSEc'], ['2013-01-01T00:00:00.000Z', '2013-01-03T00:00:00.000Z'])" print, ' ' print, 'The Epoch values are returned in d.epoch.dat' print, 'the Magnitude values are in d.magnitude.dat' print, 'and the BGSEc values are in d.bgsec.dat' print, ' ' print, 'To see further info. about each variable type help, /struct, d."variablename"' print, 'To make a plot with the CDAWlib s/w type s = spdf_plotmaster(d, /AUTO, /CDAWEB, /GIF, /SMOOTH, /SLOW) endif if n_elements(tmpDir) ne 0 then popd return, newbuf ; data end