QUERY_ASCII

The QUERY_ASCII function tests a file for compatibility with READ_ASCII and returns an optional structure containing information about the file.

This routine is written in the IDL language. Its source code can be found in the file query_ascii.pro in the lib subdirectory of the IDL distribution.

Example

Use the following code to retrieve information from a text file:

file = FILEPATH( "irreg_grid1.txt", $
SUBDIRECTORY=['examples','data'] )
result = QUERY_ASCII( file, info )
if (result) then HELP, info, /STRUCTURES $
else PRINT, 'File not found or is not a valid ASCII file.'

Syntax

Result = QUERY_ASCII( Filename [, Info] )

Return Value

This routine returns a long integer with the value of 1 (one) if the query was successful (and the file type was correct) or 0 (zero) on failure. The following criteria are used to decide whether a file is a valid ASCII file:

If 80% of the first 32768 bytes in the file are valid ASCII characters, then the file is considered to be valid
Byte values in the range 7-13 (bell, backspace, horizontal tab, line feed, vertical tab, form feed, carriage return) or in the range 32-127 (standard characters) are considered valid ASCII characters

These criteria provide an efficient and robust method to filter ASCII files from non-ASCII files. The 80% figure lets an ASCII file have a certain number of non-ASCII characters, perhaps in a header portion or for special characters such as fractions or symbols.

Arguments

Filename

A scalar string containing the full pathname of the file to query.

Info

A named variable in which to return an anonymous structure containing information about the file. This structure is valid only when the return value of the function is 1. The structure has the following fields:

Field	IDL Type	Description
NAME	String	File name, including full path
TYPE	String	File format (always `'ASCII'`)
BYTES	Long64	File length in bytes
LINES	Long64	Number of lines
WORDS	Long64	Number of words

For the WORDS field, words are assumed to be separated by whitespace, including carriage returns, line feeds, tabs, and spaces.

Note: IDL uses the file’s first 32768 characters to determine whether it is ASCII or not. If the file is valid, IDL processes the remainder of the file and fills in the Info structure for the complete file. If the file is not valid, IDL does not modify the Info variable.

Tip: If you have a data file that contains only columns of data (without any header lines), the number of words (WORDS) divided by the number of lines (LINES) should give you the number of columns.

Keywords

None

Version History

6.2	Introduced