7.4.61.1.2. QUERY Stream Commands

Used with these stream commands, the STREAM function returns specific information about a stream. Except for QUERY HANDLE and QUERY SEEK/POSITION, the language processor returns the query information even if the stream is not open. The language processor returns UNKNOWN for QUERY STREAMTYPE and the null string for nonexistent streams.

Note that technically although a directory is persistent, it is not a stream. If the directory exists, the date / time queries return the time stamp of the directory, QUERY SIZE returns 0, and QUERY STREAMTYPE returns UNKNOWN. The other commands return the null string.

QUERY DATETIME

returns the date and time stamps of a stream in US format.

Example 7.77. Builtin function STREAM QUERY examples

stream("..\file.txt","c","query datetime")

A sample output might be:

11-12-98 03:29:12

QUERY EXISTS

returns the full path specification of the named stream, if it exists, or a null string.

Example 7.78. Builtin function STREAM QUERY EXISTS examples

stream("..\file.txt","c","query exists")

A sample output might be:

c:\data\file.txt

QUERY HANDLE

returns the handle associated with the open stream.

Example 7.79. Builtin function STREAM QUERY HANDLE examples

stream("..\file.txt","c","query handle")

A sample output might be:

QUERY POSITION

returns the current read or write position for the stream, as qualified by the following options:

READ

returns the current read position.

WRITE

returns the current write position.

Note

If the stream is open for both reading and writing, the default is to return the read position. Otherwise, it returns the appropriate position by default.

CHAR

returns the position in terms of characters. This is the default.

LINE

returns the position in terms of lines. For non-binary streams, this operation can take a long time to complete, because the language processor starts tracking the current line number if not already doing so. Thus, it might require a scan of the stream from the top to count line-end characters. See Section 14.1.5, “Line versus Character Positioning” for a detailed discussion of this issue.

Example 7.80. Builtin function STREAM QUERY POSITION examples

stream("myfile","c","query position write")

A sample output might be:

SYS

returns the operating-system stream position in terms of characters.

QUERY SIZE

returns the size, in bytes, of a persistent stream.

Example 7.81. Builtin function STREAM QUERY SIZE examples

stream("..\file.txt","c","query size")

A sample output might be:

QUERY STREAMTYPE

returns a string indicating whether the stream is PERSISTENT, TRANSIENT, or UNKNOWN.

QUERY TIMESTAMP

returns the date and time stamps of a stream in an international format. This is the preferred method of getting the date and time because it provides the full 4-digit year.

Example 7.82. Builtin function STREAM QUERY TIMESTAMP examples

stream("..\file.txt","c","query timestamp")

A sample output might be:

2016-11-12 03:29:12