Creating a Registered File Reader Routine

For a file reader routine to be available via the IOPEN procedure or the File → Open menu item in the IDL Workbench, it must meet the following criteria:

  1. It must have the routine signature described below.
  2. The reader routine's .pro file must be present in a directory included in IDL's !PATH system variable.
  3. It must be added to the idlextenions.xml file as described in Registering Custom File Readers.

See Example: A Workbench NetCDF Reader for an example of a custom file reader routine.

File Reader Routine Signature

A file reader routine should be an IDL function with the following signature: 

Result = READ_ROUTINE(File [, PALETTE=Palette])

where:

Result

The data read from the file. Result can be any data type.

When a file is selected using the File → Open menu item in the IDL Workbench, IDL will generate a variable name based on the specified file name.

File

A string containing the name of the file to be read.

Palette

A named variable that will contain the palette associated with the file, if a palette is present. The palette should be returned as a [3, 256] element byte array containing the red, green, and blue color vectors. This keyword is optional.

When a file is selected using the File → Open menu item in the IDL Workbench, IDL will generate a variable name based on the specified file name, with the suffix "_pal" appended.

If you create a file reader routine with this signature and register it in the idlextenions.xml file, IDL will use the routine to open files of the corresponding type when selected using the File → Open menu item in the IDL Workbench or the IOPEN procedure.

Additional Keywords

Although a file reader routine must have exactly one argument — a string containing the name of the file to read — it can include other keywords in addition to the (optional) PALETTE keyword. When using the file reader via the IOPEN routine, any additional keywords specified will be passed from IOPEN to the reader routine using the _EXTRA keyword inheritance mechanism. See Keyword Inheritance in Application Programming for details on the inheritance mechanism.

For example, suppose your file reader includes a METADATA keyword but does not include a PALETTE keyword, giving it a signature that looks like 

Result = MY_FILE_READER(File, METADATA=metadata)

If the MY_FILE_READER function is placed in a directory in IDL's path, and an entry in the idlextenions.xml file specifies that it should be used to open files with the extension .xyz, then calling IOPEN as follows 

IOPEN, 'testfile.xyz', testfile_data, METADATA=testfile_metadata

would call MY_FILE_READER, placing the retrieved data in a variable named testfile_data and the value returned by the METADATA keyword in a variable named testfile_metadata.

Note
When a file reader is invoked by selecting the File → Open menu item in the IDL Workbench, only the Filename argument and the PALETTE keyword (if present) are used. Other keywords are ignored.