5.2.4.8.1. Command Strings

The argument stream_command can be any expression that evaluates to one of the following command strings:

OPTIONS:

OPEN

Opens the stream object and returns READY:. (If unsuccessful, the previous information about return codes applies.) The default for OPEN is to open the stream for both reading and writing data, for example: 'OPEN BOTH'. To specify that the stream be only opened for input or output, add READ or WRITE, to the command string.

The following is a description of the options for OPEN:

READ: Opens the stream only for reading.
WRITE: Opens the stream only for writing.
BOTH: Opens the stream for both reading and writing. (This is the default.) The stream maintains separate read and write pointers.
APPEND: Positions the write pointer at the end of the stream. (This is the default.) The write pointer cannot be moved anywhere within the extent of the file as it existed when the file was opened.
REPLACE: Sets the write pointer to the beginning of the stream and truncates the file. In other words, this option deletes all data that was in the stream when opened.
SHARED: Enables another process to work with the stream in a shared mode. This mode must be compatible with the shared mode (SHARED, SHAREREAD, or SHAREWRITE) used by the process that opened the stream.
SHAREREAD: Enables another process to read the stream in a shared mode.
SHAREWRITE: Enables another process to write the stream in a shared mode.
NOBUFFER: Turns off buffering of the stream. All data written to the stream is flushed immediately to the operating system for writing. This option can have a severe impact on output performance. Use it only when data integrity is a concern, or to force interleaved output to a stream to appear in the exact order in which it was written.
BINARY: Opens the stream in binary mode. This means that line-end characters are ignored; they are treated like any other byte of data. This is intended to process binary data using the line operations.
Note
Specifying the BINARY option for a stream that does not exist but is opened for writing also requires the RECLENGTH option to be specified. Omitting the RECLENGTH option in this case raises an error condition.
RECLENGTH length: Allows the specification of an exact length for each line in a stream. This allows line operations on binary-mode streams to operate on individual fixed-length records. Without this option, line operations on binary-mode files operate on the entire file (for example, as if you specified the RECLENGTH option with a length equal to that of the file). The length must be 1 or greater.

Example 5.144. Stream command — OPEN option

stream~command("open")
stream~command("open write")
stream~command("open read")
stream~command("open read shared")

CLOSE

closes the stream object. The command method with the CLOSE option returns READY: if the stream is successfully closed or an appropriate error message otherwise. If an attempt to close an unopened file occurs, then the command method with the CLOSE option returns a null string ("").

FLUSH

forces any data currently buffered for writing to be written to this stream.

SEEK offset

sets the read or write position to a given number (offset) within a persistent stream. If the stream is open for both reading and writing and you do not specify READ or WRITE, both the read and write positions are set.

Note

See Chapter 14, Input and Output Streams for a discussion of read and write positions in a persistent stream.

To use this command, you must first open the stream (with the OPEN stream command described previously or implicitly with an input or output operation). One of the following characters can precede the offset number.

=: explicitly specifies the offset from the beginning of the stream. This is the default if you supply no prefix. For example, an offset of 1 with the LINE option means the beginning of the stream.
<: specifies offset from the end of the stream.
+: specifies offset forward from the current read or write position.
-: specifies offset backward from the current read or write position.

The command method with the SEEK option returns the new position in the stream if the read or write position is successfully located, or an appropriate error message.

The following is a description of the options for SEEK:

READ: specifies that this command sets the read position.
WRITE: specifies that this command sets the write position.
CHAR: specifies the positioning in terms of characters. This is the default.
LINE: specifies the positioning in terms of lines. For non-binary streams, this is potentially an operation that can take a long time to complete because, in most cases, the file must be scanned from the top to count the line-end characters. However, for binary streams with a specified record length, the new resulting line number is simply multiplied by the record length before character positioning. See Section 14.1.5, “Line versus Character Positioning” for a detailed discussion of this issue.
Note
If you do line positioning in a file open only for writing, you receive an error message.

Example 5.145. Stream command — SEEK option

stream~command("seek =2 read")
stream~command("seek +15 read")
stream~command("seek -7 write line")
fromend  = 125
stream~command("seek <"fromend "read")

POSITION

is a synonym for SEEK.

QUERY

Used with these QUERY stream_commands, the command method returns specific information about a stream. Except for QUERY HANDLE and QUERY SEEK/POSITION, the stream returns the query information even if the stream is not open. The stream returns the null string for nonexistent streams.

QUERY DATETIME

Returns the date and time stamps of a stream in US format. For example:

Example 5.146. Stream command — QUERY DATETIME option

stream~command("query datetime")

A sample output might be:

11-12-15 03:29:12

QUERY EXISTS

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

Example 5.147. Stream command — QUERY EXISTS option

stream~command("query exists")

A sample output might be:

c:\data\file.txt

QUERY HANDLE

Returns the handle associated with the open stream.

Example 5.148. Stream command — QUERY HANDLE option

stream~command("query handle")

A sample output might be: 3

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, this returns the read position by default. Otherwise, this 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. 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.149. Stream command — QUERY POSITION WRITE option

stream~command("query position write")

A sample output might be:

SYS

Returns the operating system stream position in terms of characters.

QUERY SEEK

Is a synonym for QUERY POSITION.

QUERY SIZE

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

Example 5.150. Stream command — QUERY SIZE option

stream~command("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 persistent stream in an international format. This is the preferred method of getting date and time because it provides the full 4-digit year

Example 5.151. Stream command — QUERY TIMESTAMP option

stream~command("query timestamp")

A sample output might be:

2015-11-12 03:29:12