FILEQUERY

The FILEQUERY function returns information about a file. The attribute argument you specify in your FILEQUERY function call determines the type of information that is returned.

Return Value

The data type of the return value depends on the attribute you specify. See Table 13-1, "File Attributes Returned by FILEQUERY" for more information.

Syntax

FILEQUERY(file-id attrib-arg)

Arguments

file-id

A fileunit number or a file name.

• A fileunit number is a number that Oracle OLAP assigned to a file you opened through a previous call to the FILEOPEN function or through the OUTFILE command. You can use the return value of the FILEOPEN function or the value of the OUTFILEUNIT option.

• A file name is a text expression specifying the name of the file you want to move or rename. Unless the file is in the current directory, you must include the name of the directory object in the name of the file.

  
  

  Note: Directory objects are defined in the database, and they control access to directories and file in those directories. You can use the CDA command to identify and specify a current directory object. Contact your Oracle DBA for access rights to a directory object where your database user name can read and write files.

  
  

Some attributes require that you specify a fileunit number; others require the file name. In many cases, you can specify either. Table 13-1, "File Attributes Returned by FILEQUERY" lists the valid keywords for attrib-arg and, for each keyword, provides a description and indicates whether you specify a file-unit-number of a file-name for the file-id argument.

attrib-arg

Specifies the type of information you want to retrieve about the file. The data type of FILEQUERY's return value depends on the attribute you specify. The attribute you specify must be appropriate for the file; otherwise, an error occurs. Table 13-1, "File Attributes Returned by FILEQUERY" lists the valid keywords for attrib-arg and, for each keyword, provides a description and indicates whether you specify a file-unit-number of a file-name for the file-id argument.

Table 13-1 File Attributes Returned by FILEQUERY

Keyword	Return Values	Return Data Type	file-id Argument
APPEND	TRUE when the file is open for writing at the end ( that is, TRUE for APPEND and WRITE); FALSE when it is not.	BOOLEAN	Fileunit number
BMARGIN	The number of blank lines that form the bottom margin.	INTEGER	Fileunit number
CHANGED	TRUE when the file's archive bit is set; FALSE when it is not.	BOOLEAN	Fileunit number or file name
DATE	The date that the file was last modified	DATE	Fileunit number or file name
EOF	TRUE when end-of-file has been reached; FALSE when it is not.	BOOLEAN	Fileunit number
EXISTS	TRUE when the file exists; FALSE when it is not.	BOOLEAN	Fileunit number or file name
FILENAME	The file name associated with the fileunit.	TEXT	Fileunit number
LINENUM	The current line number. Resets after each pagebreak when PAGING is on; keeps incrementing when PAGING is off. When file is currently open in READ mode, returns the current record number.	INTEGER	Fileunit number
LINESLEFT	The number of lines left on the page.	INTEGER	Fileunit number
LSIZE	For a file that is open for writing, the line length for the standard Oracle OLAP page heading. (See the STDHDR program.) For a fileunit that is open for reading, specifies the record length for binary input files.	INTEGER	Fileunit number
NAMELIST	The name of the file (such as demo), without an extension.	TEXT	Fileunit number or file name
NLS_CHARSET	The character set being used for this fileunit. See the FILEOPEN command for more information.	TEXT	Fileunit number
NUMBYTES	The size of the file in bytes.	INTEGER	Fileunit number or file name
ORIGIN	The type of computer on which the file was created.	TEXT	Fileunit number
PAGENUM	The current page number. See "Paging Attributes".	INTEGER	Fileunit number
PAGEPRG	The Oracle OLAP program or statement that produces headings when output is paged. See "Paging Attributes".	TEXT	Fileunit number
PAGESIZE	The number of lines on each page. See "Paging Attributes".	INTEGER	Fileunit number
PAGING	TRUE when the output is formatted in pages; FALSE when it is not. See "Paging Attributes".	BOOLEAN	Fileunit number
PAUSEATPAGEEND	TRUE when Oracle OLAP will pause after each page; FALSE when it will not. See "Paging Attributes".	BOOLEAN	Fileunit number
R[EAD]	TRUE when the file is open for reading; FALSE when it is not.	BOOLEAN	Fileunit number
RO	TRUE when the file's read-only attribute is set; FALSE when it is not.	BOOLEAN	Fileunit number or file name
SPECLIST	The name and extension of the file.	TEXT	Fileunit number or file name
TABEXPAND	TRUE when the tab characters will be expanded when the file is read by FILEGET or FILEREAD; FALSE when they will not. See "Tab Treatment".	BOOLEAN	Fileunit number or file name
TIME	The time that the file was last modified.	DATETIME	Fileunit number or file name
TMARGIN	The number of blank lines that form the top margin.	INTEGER	Fileunit number
UNIT	The file unit for the specified file name.	INTEGER	File name
W[RITE]	TRUE when the file is open for writing; FALSE when it is not.	BOOLEAN	Fileunit number

Notes

Before specifying a fileunit with the FILEQUERY function, use FILEOPEN or OUTFILE to open the file.

The ORIGIN attribute identifies the computer on which a file was originally created. You must use the FILESET command to set ORIGIN when the file originated on another type of computer. This attribute is relevant only for files that are open for reading.

You can use the LISTFILES command to see a list of which open files can be referenced by the FILEQUERY function.

When you want tab characters in the source file to be expanded when read by FILEGET or FILEREAD, you can specify the TABEXPAND attribute with the FILESET command. When TABEXPAND is zero, tab characters will not be expanded. A value greater than 0 indicates the distance, in bytes, between tab stops. The default value of TABEXPAND is 8.

The paging attributes apply only to files that currently, unless otherwise noted, have PAGING set to YES and are open in WRITE mode -- such as files opened with FILEOPEN(...WRITE) or FILEOPEN(...APPEND). You can set any of the paging attributes with the FILESET command.

Use FILEQUERY with the EOF attribute where you used FILESTATUS in previous Oracle OLAP versions.

When specifying a file name, use the file naming conventions for your operating system. For example, it might be necessary to type upper, lower, and mixed case letters to match the name of the file for which you want information.

(Unix only) When querying for Unix file names, wildcard characters (that is, * ?) are allowed when searching with the NAMELIST, SPECLIST, and EXISTS attribute arguments.

Examples

DEFINE fil.unit INTEGER
fil.unit = FILEOPEN('REPORT' WRITE)

FILECLOSE fil.unit