Registering Custom File Readers

For a file reader routine to be available to the IOPEN procedure and the File → Open menu item in the IDL Workbench, it must be registered by placing an entry in the idlextensions.xml file.

Note
The file readers listed as registered in Default File Readers are registered automatically; there is no need to register them yourself unless you have removed the <IDL_DEFAULT /> token from the idlextensions.xml file.

To register a custom file reader, you must manually edit the idlextensions.xml file, which is located in the application user directory for the current version of IDL. The application user directory is created by IDL automatically, following the rules outlined in the description of the APP_USER_DIR function. To find the directory where the idlextensions.xml file is located, execute the following command at the IDL command line:

PRINT, APP_USER_DIR_QUERY('itt', 'pref', $
   /RESTRICT_IDL_RELEASE, /RESTRICT_FAMILY)

By default (before you have added any custom file readers), the idlextensions.xml file looks like this: 

<idlextensions version='7.1'> 
  <readers> 
    <IDL_DEFAULT /> 
  </readers> 
</idlextensions>

In this default version, the XML element <IDL_DEFAULT /> tells IDL to register all of IDL's default file readers. If you add your own custom file readers, be sure to preserve the <IDL_DEFAULT /> element; if it is missing from your idlextensions.xml file, IDL's default readers will not be available to the IOPEN procedure and the File → Open menu item in the IDL Workbench.

Adding a Custom File Reader

To register a custom file reader, add a new <reader> element between the <readers> and </readers> tags in the idlextensions.xml file. The <reader> element looks like this: 

<reader name='human readable name'> 
   <read_routine>routine</read_routine> 
   <query_routine>routine</query_routine> 
   <icon>path-relative-to-read_routine</icon> 
   <extension>file-extension-with-dot</extension> 
</reader>

where:

name attribute

The name attribute of the <reader> element specifies a human-readable name for the file reader. This attribute value is used in the File Type dropdown list (along with the file extension) in the file selection dialog used to select a file to read.

The name attribute is optional. If the name is not present, the file extension is displayed in the file selection dialog.

read_routine

The read_routine element specifies the name of the routine that will read the file data. See Creating a Registered File Reader Routine for details on creating the read routine. Note that this element contains the name of the routine to call, not the full name of the .pro file that defines the routine.

The read_routine element must be present.

query_routine

The query_routine element specifies the name of the routine that will attempt to determine whether a file is of the type understood by the file reader. See Creating a Registered Query Routine for details on creating the query routine. Note that this element contains the name of the routine to call, not the name of the .pro file that defines the routine.

The query_routine element is optional. See File Reader Search Algorithm for details.

icon

The icon element specifies the path to a 16 x 16 pixel image file that will be used to identify files of the specified type in the IDL Workbench Project Explorer view. The icon must be a BMP, GIF, PNG, or JPEG file, and the path specified should be specified relative to the location of the file reader routine.

The icon element is optional. If no icon is specified, a default icon is used in the Project Explorer.

extension

The extension element specifies the filename extension used by files of the specified type. Extensions are not case-sensitive, but the '.' should be included: for example, the extension for a GIF file reader could be .gif or .GIF.

The extension element is optional. If multiple extensions correspond to the same file type, include multiple extension elements, each specifying a single extension.

File Reader Search Algorithm

When you use the IOPEN procedure or the File → Open menu item in the IDL Workbench to open a file, IDL performs the following tests to find the file reader associated with the selected file:

reader_flow.gif

Note that if there is more than one entry in the idlextensions.xml file for a particular extension, the first reader listed in the idlextensions.xml file will be used. Default file readers included via the <IDL_DEFAULT /> token are found after any custom readers registered in the idlextensions.xml file.