5.2.4.19. query

Used with these options, query returns specific information about a stream. Except for HANDLE and SEEK/POSITION, the stream returns the query information even if the stream is not open. A null string is returned for nonexistent streams.

DATETIME

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

Example 5.153. Stream object — QUERY method

stream~query("datetime")

A sample output might be:

11-12-15 03:29:12

EXISTS

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

Example 5.154. Stream object — QUERY method

stream~query("exists")

A sample output might be:

c:\data\file.txt

HANDLE

returns the handle associated with the open stream.

Example 5.155. Stream object — QUERY method

stream~query("handle")

A sample output might be:

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, this returns the read position by default. Otherwise, this returns the specified position.

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. This is because the language processor starts tracking the current line number if not already doing so, and, thus, might require a scan of the stream from the top to count the line-end characters. See Section 14.1.5, “Line versus Character Positioning” for a detailed discussion of this issue.

Example 5.156. Stream object — QUERY method

stream~query("position write")

A sample output might be:

SYS

returns the operating system stream position in terms of characters.

SIZE

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

Example 5.157. Stream object — QUERY method

stream~query("size")

A sample output might be:

STREAMTYPE

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

TIMESTAMP

returns the date and time stamps of a persistent 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 5.158. Stream object — QUERY method

stream~query("timestamp")

A sample output might be:

2015-11-12 03:29:12