; IDL-OPENDAP interface. ; Copyright (c) 2006 OPeNDAP, Inc. ; Author: Patrick West UCAR/HAO ; Dan Holloway ; ; Based on IDL-DODS Written by Daniel J. Carr - Research Systems, Inc. ; ; This is free software; you can redistribute it and/or ; modify it under the terms of the GNU Lesser General Public ; License as published by the Free Software Foundation; either ; version 2.1 of the License, or (at your option) any later version. ; ; This library is distributed in the hope that it will be useful, ; but WITHOUT ANY WARRANTY; without even the implied warranty of ; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU ; Lesser General Public License for more details. ; ; You should have received a copy of the GNU Lesser General Public ; License along with this library; if not, write to the Free Software ; Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA ; ; You can contact OPeNDAP, Inc. at PO Box 112, Saunderstown, RI. 02874-0112. ; ; Main interface routine for IDL-OPENDAP link. ; opendap_get sets up the environment, and then calls ; opendap_get_das or opendap_get_data to establish a connection and ; return the appropriate OPeNDAP data. ; ; url - (Input ) ; URL location to connect to. ; ce - (Input ) ; Data constraint expression. ; opendap_data - (Output) ; Returns the requested DODS data as an IDL structure. ; deflate - (Optional input flag) ; ACCEPT_DEFLATE flag (1=yes (default), 0=no). ; mode - (Optional input flag) ; Flag for the type of data to retrieve ; (0 or 'DATA' for the data (default), 1 or 'DAS' for the DAS) ; seq_blocksize - (Optional input flag) ; How many elements should be allocated at once for sequence data ; Default: 4096 ; ; returns - ; Status (1=ok, 0=fail). ; ; The DAP data ("opendap_data" parameter) is returned as an ; IDL structure variable. The IDL structure will have one ; tag for each DAP variable that is returned, and the tag ; name is the same as the DAP name for that variable. ; For simple DAP variables, the value of the corresponding ; IDL structure tag will be an IDL scalar value. Other ; DAP variable types will be returned as nested structures: ; ; DAP data type: Returned IDL structure: ; ; ARRAY {ARRAY:data, ; START_STRIDE_STOP:fltarr(3,N), ; DIMENSION_NAMES:strarr(N)} ; ; GRID {GRID:data, ; dimension_name_0:dimension_data_0, ; ... ; dimension_name_n:dimension_data_n} ; ; NOTE: the grid dimension names are optional - ; not all grids will have them. ; ; STRUCTURE {var_name_0:var_data_0, ; ... ; var_name_n:var_data_n} ; ; SEQUENCE {record_name_0:record_data_0, ; ... ; record_name_n:record_data_n} ; ; NOTE: each record_data field corresponds to a ; sequence "column". ; ; Tag names in capital letters are literal. ; Other tag names are derived from the DODS data. ; ; EXAMPLE: ; ; IDL> url = 'http://test.opendap.org/opendap-3.4/nph-dods/data/nc/fnoc1.nc' ; IDL> stat = OPENDAP_GET(url, data) ; % Compiled module: OPENDAP_GET_DODS. ; % Compiled module: OPENDAP_GET_DODS_DATA. ; % Compiled module: OPENDAP_HANDLE_NODE. ; % Compiled module: OPENDAP_FIX_NAME. ; % Compiled module: OPENDAP_HANDLE_CONTENT. ; % Compiled module: REVERSE. ; % Temporary variables are still checked out - cleaning up... ; IDL> print, stat ; 1 ; IDL> help, /str, data ; ** Structure <824e1a4>, 5 tags, length=23172, data length=23172, refs=1: ; U STRUCT -> Array[1] ; V STRUCT -> Array[1] ; LAT STRUCT -> Array[1] ; LON STRUCT -> Array[1] ; TIME STRUCT -> Array[1] ; IDL> print, TAG_NAMES(data) ; U V LAT LON TIME ; IDL> help, /str, data.u ; ** Structure <8252124>, 2 tags, length=11460, data length=11460, refs=2: ; U INT Array[21, 17, 16] ; DIMENSION_NAMES STRING Array[3] ; IDL> print, data.u.dimension_names ; LON LAT TIME_A ; ; FUNCTION OPENDAP_GET, url, opendap_data, CE=opendap_ce, $ DEFLATE=deflate, MODE=mode, $ SEQ_BLOCKSIZE=seq_blocksize, $ DEBUG=debug ;{ DEFSYSV, '!opendap_null_c', EXISTS=opendap_defined ; If this is the first time run in this IDL session, ; then define system variables and link external routines. IF( opendap_defined EQ 0 ) THEN BEGIN @opendap_setup ENDIF IF( N_ELEMENTS( url ) LE 0ul ) THEN BEGIN ;{ PRINT,'url passed is empty' RETURN, 0ul ENDIF ;} IF( STRCOMPRESS( url ) EQ '' ) THEN BEGIN ;{ PRINT,'url passed is empty' RETURN, 0ul ENDIF ;} IF( N_ELEMENTS( opendap_ce ) LE 0L ) THEN opendap_ce = '' IF( N_ELEMENTS( deflate ) LE 0ul ) THEN deflate = 0ul IF( N_ELEMENTS( debug ) LE 0ul ) THEN debug = 0ul IF( N_ELEMENTS( mode ) LE 0ul ) THEN BEGIN ;{ mode = 0ul ENDIF ELSE BEGIN ;} ;{ IF (STRCMP(mode,'DATA',/FOLD_CASE) EQ 1ul) THEN BEGIN ;{ mode = 0ul ENDIF ELSE BEGIN ;} ;{ IF (STRCMP(mode,'DDS',/FOLD_CASE) EQ 1ul) THEN BEGIN ;{ mode = 1ul ENDIF ELSE BEGIN ;} ;{ IF (STRCMP(mode,'DAS',/FOLD_CASE) EQ 1ul) THEN BEGIN ;{ mode = 2ul ENDIF ELSE BEGIN ;} ;{ IF (STRCMP(mode,'FULLDATA',/FOLD_CASE) EQ 1ul) THEN BEGIN ;{ mode = 3ul ENDIF ELSE BEGIN ;} ;{ IF (STRCMP(mode,'FULLDDS',/FOLD_CASE) EQ 1ul) THEN BEGIN ;{ mode = 4ul ENDIF ELSE BEGIN ;} ;{ IF (STRCMP(mode,'FULLDAS',/FOLD_CASE) EQ 1ul) THEN BEGIN ;{ mode = 5ul ENDIF ELSE BEGIN ;} ;{ PRINT, 'Unrecognized Keyword parameter, MODE=',STRING(mode) PRINT, 'options are: dds, das, data, fulldds, fulldas, fulldata' RETURN, 0ul ENDELSE ;} ENDELSE ;} ENDELSE ;} ENDELSE ;} ENDELSE ;} ENDELSE ;} ENDELSE ;} IF( N_ELEMENTS( seq_blocksize ) LE 0ul ) THEN seq_blocksize = 4096ul stat = 0ul IF( mode EQ 0ul OR mode EQ 1ul OR mode EQ 3ul OR mode EQ 4ul ) THEN BEGIN ;{ stat = OPENDAP_GET_DATA( url, opendap_data, CE=opendap_ce, $ DEFLATE=deflate, $ SEQ_BLOCKSIZE=seq_blocksize, $ MODE=mode, debug ) ENDIF ELSE BEGIN ;} ;{ IF( mode EQ 2ul OR mode EQ 5ul ) THEN BEGIN ;{ stat = OPENDAP_GET_DAS( url, opendap_data, CE=opendap_ce, $ DEFLATE=deflate, MODE=mode, debug ) ENDIF ;} ENDELSE ;} RETURN, stat ;} END