This package of IDL functions facilitates reading data and metadata from Common Data Format (CDF) files. While CDF provides all the benefits of a portable, self-documenting scientific data format, reading them is not always a simple matter. To make it simple, I have created this IDL package so that all of the data and metadata from multiple variables can be read from multiple CDF files ... in one single, simple command. The function is called 'spdf_read_mycdf' and it returns an anonymous structure of the form: structure_name.variable_name.attribute_name.attribute_value From this structure, all data and metadata for the requested variables is easily accessed. AUTHOR: Richard Burley, NASA/GSFC/Code 632.0, Feb 13, 1996 burley@nssdca.gsfc.nasa.gov (301)286-2864 NOTES: Three additional 'attributes' will be included in the sub-structure for each variable. The first is the 'VARNAME' field. Because IDL structure tags are always uppercase, and because CDF variable names are case sen- sitive, a case sensitive copy of the variable name is created. The second 'attribute' to be added is the 'CDFTYPE' field. This field will hold a string value holding the cdf data type. The last 'attribute' to be artificially added will be either the 'DAT' field or, if the keyword NODATASTRUCT is set, the 'HANDLE' field. The 'DAT' field will contain the actual data values read from the CDF's for the variable. The 'HANDLE' field will hold a handle_id where the data will reside. This package will look for and utilize certain special attributes required by the International Solar Terrestrial Physics Key Parameters Generation Software Standards and Guidelines. The existance of these attributes is not required for the operation of this software, but will enhance its usefullness, primarily by reading variables that will be needed for proper utilization of the data, even though you may not have asked for them explicitly. This package was tested under IDL version 4.0.1b. This package was tested on CDF's up to version 2.5 and on both r-variables and z-variables. CDF variables defined as unsigned integers are, unfortunately, currently returned by the IDL CDF_VARGET procedure as signed integers. This can cause sign flips. This software detects and corrects for this defect for data values. However, it cannot detect and correct for this defect for attribute values because the IDL procedure CDF_ATTINQ does not return the CDF data type of the attribute. These problems have been reported to RSI. Modifications: As of October 2, 2000, this software can run on all of the following IDL versions, 5.1, 5.2 and 5.3 (testing for 5.4 will commence soon). Some fairly major changes were necessary in order for spdf_read_mycdf to work under 5.3. IDL 5.3 enforces the variable naming rules for structure tag names. This change affects this s/w because we basically had never checked our tag names, e.g. we used the CDF variable names and label attribute values directly. So in spdf_read_mycdf the general concept to fixing this problem was to set up a table (which is shared in a common block - not my favorite way to go, but definitely the easiest), where there are two tags, equiv and varname. varname contains the real CDF variable name, equiv contains the "cleaned up, IDL acceptable" variable name that can be used as a structure tag name... TJK 04/02/2000 1996, NASA/Goddard Space Flight Center This software may be used, copied, or redistributed as long as it is not sold and this copyright notice is reproduced on each copy made. This routine is provided as is without any express or implied warranties whatsoever.

Search the tnames array for the instring, returning the index in tnames if it is present, or -1 if it is not. TJK this function is in a separate file called spdf_tagindex.pro since its called from many different routines in this system. FUNCTION spdf_tagindex, instring, tnames instring = STRUPCASE(instring) ; tagnames are always uppercase a = where(tnames eq instring,count) if count eq 0 then return, -1 $ else return, a(0) end

NAME: READ_MYMETADATA PURPOSE: To read all of the attribute values for the requested variable, and to return this information as an anonymous structure. CALLING SEQUENCE: metadata = read_mymetadata(vname,CDFid) INPUTS: vname = string, name of variable whose metadata is being read CDFid = integer, id of already opened CDF file KEYWORD PARAMETERS: OUTPUTS: metadata = anonymous structure whose tags are the attribute names and whose fields are the corresponding attribute values. AUTHOR: Richard Burley, NASA/GSFC/Code 632.0, Feb 13, 1996 burley@nssdca.gsfc.nasa.gov (301)286-2864 MODIFICATION HISTORY:

RCJ 03/30/2012 Commented out this function. It was called once and that call is commented out too. ;check the variables_comp array for existence of the variable name, for ;the current cdf. function check_varcompare, variables_comp, cdf_index, variable_name ;print,'**** ' & help,variables_comp ;print, variable_name, cdf_index, variables_comp ;stop; x = where(variable_name eq variables_comp(cdf_index,*), xcnt) if (xcnt gt 0)then print, variable_name, ' found 1' else print, variable_name, ' not found 0' if (xcnt gt 0)then return, 1 else return, 0 end +------------------------------------------------------------------------ NAME: spdf_read_mycdf PURPOSE: Read all data and metadata for given variables, from given CDF files, and return all information in a single anonymous structure of the form: structure_name.variable_name.attribute_name.attribute_value CALLING SEQUENCE: out = spdf_read_mycdf(vnames,cnames) INPUTS: vnames = string, array of variable names or a single string of names separated by a comma. (ex. 'Epoch,Magfld,Bmax') cnames = string, array of CDF filenames or a single string of names separated by a comma. KEYWORD PARAMETERS: ALL = 0: get data and metadata for requested variable(s) only. 1: get data and metadata for ALL variables in the CDFs. 2: get data and metadata for all var_type='data' variables. NODATASTRUCT = If set, instead of returning the data for each variable in the 'DAT' attribute field, create a 'HANDLE' field and set it to the handle id of a data handle which holds the data for each variable. NOQUIET = If set, do NOT set the !QUIET system variable before reading the cdf file(s). DEBUG = If set, print out some progress information during reading. TSTART = epoch starting value - YYYYMMDD etc. string. TSTOP = epoch ending value - YYYYMMDD etc. string. OUTPUTS: out = anonymous structure holding all data and metadata for the requested variables. If an error occurs, that we know how to deal w/, an alternate structure is returned, its structure is as follows: ('DATASET',d_set,'ERROR',v_err,'STATUS',v_stat) AUTHOR: Richard Burley, NASA/GSFC/Code 632.0, Feb 13, 1996 burley@nssdca.gsfc.nasa.gov (301)286-2864 MODIFICATION HISTORY: Tami Kovalick, HSTX, 12/16/96 modified to verify whether variables requested in vnames array are actually in the "data" cdfs prior to requesting the data from these variables. If variables aren't valid then they are removed from the vnames array and the code continues on to create a valid structure. Tami Kovalick, HSTX, 12/20/96 modified to allow the use of TSTART and TSTOP keywords (see above). Use of these keywords will force the code to only read the necessary records in the CDF, otherwise the code will read the entire CDF. Could enhance the code to deal w/ one or the other keyword - right now they are only used if both are set. Tami Kovalick, RSTX, 02/13/98, Carrie Gallap started modifications to spdf_read_mycdf to accommodate "virtual variables" (VV) . Tami finished up the code and made corrections to several sections. One new routine was written add_myCOMPONENTS, this routine is called when a valid virtual variable is found in order to add any additional variables needed for actually generating the data for the VV. The routine looks for variable attributes w/ the naming convention COMPONENT_n where n is a digit. The basic methodology to the changes is to determine whether any of the variables selected are virtual variables, if so then the variable name and the source (where the VV was defined - master or data cdfs) are stored in a structure called vir_vars, then add the component variables to the vnames array. Do the usual checking to see if the variables requested in vnames actually exist. Then continue on w/ getting the metadata for all variables (including VV), and continue on w/ the getting the data from the CDFs for all variables except the VV. Population of the VV's data field in the "burley" structure are handled at the very end in a case statement which looks for each VV's variable attribute FUNCTION to determine which actual "IDL function" to call, ie. conv_pos.