Example: A Workbench NetCDF Reader

This section walks you through the process of creating a new file reader routine and registering it with the IDL Workbench.

Warning
While the file reader described here — a routine to read variable and attribute data from NetCDF files — is included in the IDL distribution, it is provided as an example and is not intended as a robust solution for reading generic NetCDF files.

To add the NetCDF file reader, we will do the following:

Create the read_ncdf_doc Routine

Create the query_ncdf_doc Routine

Note that the code for the two routines described here is included in the IDL distribution in the examples/doc/utilities directory. You do not need to re-create the routines in order to use the example; you are, however, free to modify the example code to create a reader that is better suited to your own data.

Create the read_ncdf_doc Routine

This example describes a routine that will open a Network Common Data Format (NetCDF) file and read the variables, their attributes, and any global attributes contained in the file.

Example Code
The code for this example file reader is included in the file read_ncdf_doc.pro in the examples/doc/utilities subdirectory of the IDL distribution. View the file in an IDL Editor window by entering .EDIT read_ncdf_doc.pro.

It is beyond the scope of this section to discuss the process of reading NetCDF data in detail. For more on NetCDF, see Network Common Data Format in the Scientific Data Formats manual. In outline, the file reader does the following:

Checks the input argument to ensure that a file is specified and that it is a NetCDF file.

Retrieves variable and attribute information from the NetCDF file.

Loops through the variables contained in the NetCDF file, reading each and creating an IDL variable to contain the data. All of the individual IDL variables are placed in an anonymous structure variable.

Loops through the attributes of the variables contained in the NetCDF file, reading each and creating an IDL variable to contain the data. All of the individual IDL variables are placed in the previously-created structure variable.

Loops through the global attributes contained in the NetCDF file, reading each and creating an IDL variable to contain the data. All of the individual IDL variables are placed in the previously-created structure variable.

Closes the NetCDF file and returns the anonymous structure variable containing the file's data.

The function looks like this:

FUNCTION read_ncdf_doc, infile 
 
   ; Ensure that a file is specified. 
   IF N_PARAMS() LT 1 THEN $ 
      MESSAGE, 'Incorrect number of arguments.' 
 
   ; Open the NetCDF file for reading. 
   ncid = NCDF_OPEN(infile) 
   IF (ncid EQ -1) THEN $ 
      MESSAGE, 'Error opening file: ' + infile 
 
   ; Retrieve general information about this netcdf file. 
   ncidinfo = NCDF_INQUIRE(ncid) 
 
   ; Place the variables in local arrays. 
   FOR i=0, ncidinfo.nvars-1 DO BEGIN 
      vardata = NCDF_VARINQ(ncid, i) 
      valid_varname = IDL_VALIDNAME(vardata.name, /CONVERT_ALL) 
      varname = valid_varname 
      NCDF_VARGET, ncid, i, varname 
      data = (i eq 0) ? CREATE_STRUCT(valid_varname, varname) : $ 
         CREATE_STRUCT(data, valid_varname, varname) 
      ; Read in attribute data 
      FOR j=0, vardata.natts-1 DO BEGIN 
         att = NCDF_ATTNAME(ncid, i, j) 
         attname = IDL_VALIDNAME(valid_varname + '_' + att) 
         NCDF_ATTGET, ncid, i, att, value 
         attinfo = NCDF_ATTINQ(ncid, i, att) 
         if (attinfo.datatype eq 'CHAR') then value=STRING(value) 
         data = CREATE_STRUCT(data, attname, value) 
      ENDFOR 
   ENDFOR 
 
   ; Read in global attribute data 
   FOR i=0, ncidinfo.ngatts-1 DO BEGIN 
      att = NCDF_ATTNAME(ncid, /global, i) 
      attname = IDL_VALIDNAME(att, /CONVERT_ALL) 
      NCDF_ATTGET, ncid, /global, att, value 
      attinfo = NCDF_ATTINQ(ncid, att, /global) 
      if (attinfo.datatype eq 'CHAR') then value = STRING(value) 
      data = CREATE_STRUCT(data, attname, value) 
   ENDFOR 
 
   ; Close the NetCDF file 
   NCDF_CLOSE, ncid 
 
   ; Return the data structure 
   RETURN, data 
 
END

If you are trying this example on a NetCDF file of your own, note that the above code is already in IDL's path. If you are creating your own file reader routine, be sure to place it in a directory that is included in IDL's path.

Create the query_ncdf_doc Routine

Although it is not strictly necessary, we can easily create a query routine to match the NetCDF file reader routine.

Example Code
The code for this example query routine is included in the file query_ncdf_doc.pro in the examples/doc/utilities subdirectory of the IDL distribution. View the file in an IDL Editor window by entering .EDIT query_ncdf_doc.pro.

Our query routine relies on the fact that the NCDF_OPEN routine returns -1 if it is unable to open the specified file.

FUNCTION query_ncdf_doc, infile 
 
   ; Ensure that a file is specified. 
   IF N_PARAMS() LT 1 THEN $ 
      MESSAGE, 'Incorrect number of arguments.' 
 
   ; Open the NetCDF file for reading. 
   ncid = NCDF_OPEN(infile) 
   success = (ncid EQ -1) ? 0 : 1 
   IF success THEN NCDF_CLOSE, ncid 
 
   RETURN, success 
 
END

If you are trying this example on a NetCDF file of your own, note that the above code is already in IDL's path. If you are creating your own query routine, be sure to place it in a directory that is included in IDL's path.

Register the NetCDF Reader

To register the NetCDF file reader, add the following <reader> element to the idlextensions.xml file:

<reader name='NetCDF File Reader'> 
   <read_routine>read_ncdf_doc</read_routine> 
   <query_routine>query_ncdf_doc</query_routine> 
   <extension>.nc</extension> 
   <extension>.ncd</extension> 
   <extension>.ncdf</extension> 
</reader>

Note that we specify three different extensions for NetCDF files: .nc, .ncd, and .ncdf. If your NetCDF data files used a different extension, you could supply different strings in the <extension> elements.

The <reader> element shown above will work unmodified because the read_ncdf_doc and query_ncdf_doc routines are included in the examples/doc/utilities subdirectory of the IDL distribution, which is included on IDL's path by default. If you create your own file reader and query routines, be sure to save the files in a directory that is on IDL's path.

Test the New File Reader

After saving the modified idlextensions.xml file and restarting the IDL Workbench, you should be able to use the File → Open menu item to open and read NetCDF files. Use the file sample.nc, located in the examples/data subdirectory of the IDL installation, or choose a NetCDF file of your own.