Routines (alphabetical) > Routines: Q > QUERY_ASCII

# 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

## See Also

ASCII_TEMPLATE, READ_ASCII, READ_CSV, QUERY_CSV