Product SiteDocumentation Site

5.2.4.20. query


>>-query(--+-DATETIME--------------------------+--)------------><
           +-EXISTS----------------------------+
           +-HANDLE----------------------------+
           |                       +-CHAR-+    |
           +-+-SEEK-----+--+-READ--+------+--+-+
           | +-POSITION-+  |       +-LINE-+  | |
           |               |        +-CHAR-+ | |
           |               +-WRITE--+------+-+ |
           |               |        +-LINE-+ | |
           |               +-SYS-------------+ |
           +-SIZE------------------------------+
           +-STREAMTYPE------------------------+
           +-TIMESTAMP-------------------------+
Used with these options, the query method returns specific information about a stream. Except for query HANDLE and query 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.120. Stream object - QUERY method

stream_name~query("datetime")

A sample output might be: 
11-12-98 03:29:12
EXISTS
returns the full path specification of the stream, if it exists, or a null string. For example:

Example 5.121. Stream object - QUERY method

stream_name~query("exists")

A sample output might be: 
c:\data\file.txt
HANDLE
returns the handle associated with the open stream.

Example 5.122. Stream object - QUERY method

stream_name~query("handle")

A sample output might be: 
3
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.123. Stream object - QUERY method

stream_name~query("position write")

A sample output might be: 
247
SYS
returns the operating system stream position in terms of characters.
SIZE
returns the size, in bytes, of a persistent stream.

Example 5.124. Stream object - QUERY method

stream_name~query("size")

A sample output might be: 
1305
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.125. Stream object - QUERY method

stream_name~query("timestamp")

A sample output might be: 
1998-11-12 03:29:12