The ASCII_TEMPLATE function presents a graphical user interface (GUI) which generates a template defining an ASCII file format. Templates are IDL structure variables that may be used when reading ASCII files with the READ_ASCII routine. See READ_ASCII for details on reading ASCII files.
This routine is written in the IDL language. Its source code can be found in the file ascii_template.pro in the lib subdirectory of the IDL distribution.
Result = ASCII_TEMPLATE( [Filename] [, BROWSE_LINES=lines] [, CANCEL=variable] [, GROUP=widget_id] )
Returns a template defining an ASCII file format.
A string containing the name of a file to base the template on. If Filename is not specified, a dialog allows you to choose a file.
Set this keyword equal to the number of lines that will be read in at a time when the “Browse” button is selected. The default is 50 lines.
Set this keyword to a named variable that will contain the byte value 1 if the user clicked the “Cancel” button, or 0 otherwise.
The widget ID of an existing widget that serves as “group leader” for the ASCII_TEMPLATE graphical user interface. When a group leader is killed, for any reason, all widgets in the group are also destroyed.
Use the following command to generate a template structure from the file “myFile”:
myTemplate = ASCII_TEMPLATE(myFile)
If filename is not supplied in the call to the ASCII_TEMPLATE function, a file selection dialog is displayed prior to the first ASCII_TEMPLATE screen.
Using the ASCII Template Dialog
The ASCII_TEMPLATE function lets you describe the data organization of an ASCII file and generates a template that describes how to correctly import the ASCII data. The READ_ASCII function accesses the data in an ASCII file, using the template to determine how to import the data correctly. (You only have to explicitly call READ_ASCII when you call ASCII_TEMPLATE from the command line. When you start the ASCII Template dialog from an iTool or the workbench, the READ_ASCII routine is called for you.) The template is an IDL variable that you can use to read other files with the same organization.
After starting the ASCII Template dialog, complete the following steps to create the template:
Select the ASCII file. In the Select File to Open dialog, select sine_waves.txt from the examples\data subdirectory of your IDL distribution. The ASCII Template window is displayed.
Define ASCII data type and range.
For this data set, make sure the following options are selected:
Click Next. The second ASCII_TEMPLATE dialog screen appears:
Define ASCII data field characteristics. For this data set, select the following options:
Click Next. The third ASCII_TEMPLATE dialog screen appears:
Specify field characteristics. For this data set, define the following:
Create the template. Click Finish.
The result of these actions depends on the location from which you launched the ASCII Template dialog. The READ_ASCII function, which reads data from a file according to the template specification, is automatically called when you access the ASCII Template dialog from iTools. From the command line, you must explicitly read the ASCII data with the template specification. After defining the structure of your ASCII data using the ASCII Template dialog, refer to the appropriate section:
- iTools ASCII data access: The ASCII data is read and placed in the Data Manager. You can display single or multiple fields of the data using the Insert Visualization dialog.
- IOPEN ASCII data access: When you call IOPEN with an ASCII data file, the ASCII Template dialog is invoked. After you have defined the ASCII data file structure through the dialog, the IOPEN procedure opens the file, reads the ASCII data from it, and adds one or more variables containing the data to IDL's current scope.
- Command line ASCII data access: The template is a structure defining the format of the ASCII data. Access the data using READ_ASCII, and specify the template (or other characteristics) as parameters of the data access operation. See Working with a READ_ASCII Data Structure for details.
Example: Create a SAVE File of a Custom ASCII Template
When importing an ASCII data file into IDL, you must first describe the format of the data using the interactive ASCII_TEMPLATE function. If you have a number of ASCII files that have the same format, you can create and save a customized ASCII template using the SAVE procedure. After creating a SAVE file of your custom template, you can avoid having to repeatedly define the same fields and records when reading in ASCII files that have the same structure.
At the IDL command line, enter the following to create the variable plotTemplate, which will contain your custom ASCII template:
plotTemplate = ASCII_TEMPLATE( )
A dialog box appears, prompting you to select a file.
- Select the plot.txt file in the examples/data subdirectory of the IDL distribution.
- After selecting the file, the Define Data Type/Range dialog appears. First, choose the field type. Since the data file is delimited by tabs (or whitespace) select the Delimited button. In the Data Starts at Line field, specify to begin reading the data at line 3, not line 1, since there are two comment lines at the beginning of the file. Click Next to continue.
- In the Define Delimiter/Fields dialog box, select Tab as the delimiter between data elements since it is known that tabs were used in the original file. Click Next.
In the Field Specification dialog box, name each field as follows:
- Click on the first row (row 1). In the Name field, enter time.
- Select the second row and enter temperature1.
- Select the third row and enter temperature2.
- Click Finish.
Type the following line at the IDL command line to read in the plot.txt file using the custom template, plotTemplate:
PLOT_ASCII = READ_ASCII(FILEPATH('plot.txt', SUBDIRECTORY = $
['examples', 'data']), TEMPLATE = plotTemplate)
Enter the following line to print the plot.txt file data:
The file contents are printed in the IDL console. Your output will resemble the following PLOT_ASCII Printout display.
Create a SAVE file of your custom template by entering the following:
SAVE, plotTemplate, FILENAME='myPlotTemplate.sav'
To restore the template so that you can read another ASCII file, enter:
This file contains your custom ASCII template information stored in the structure variable, plotTemplate.
Note: If you are attempting to restore a file that is not in your current working directory, you will need to specify a path to the file.
After restoring your custom template, you can read another ASCII file that is delimited in the same way as the original file by using the READ_ASCII function and specifying plotTemplate for the TEMPLATE:
PLOT_ASCII = READ_ASCII(FILEPATH('plot.txt', $
SUBDIRECTORY = ['examples', 'data']), $
TEMPLATE = plotTemplate)
Enter the following to display the contents of the file using the customized ASCII template structure previously defined using the dialog.
Added the Help button.
QUERY_ASCII, READ_ASCII, BINARY_TEMPLATE