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:

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

See Also

ASCII_TEMPLATE, READ_ASCII, READ_CSV, QUERY_CSV