command
>>-command(stream_command)-------------------------------------><
Returns a string after performing the specified
[stream_command]
. The returned string depends
on the
[stream_command]
performed
and can be the null string. The following
[stream_command]
s:
- Open a stream for reading, writing, or both
- Close a stream at the end of an operation
- Move the line read or write position within a persistent stream
(for example, a file)
- Get information about a stream
If the method is unsuccessful, it returns an error message
string in the same form that the
[description] method uses.
For most error conditions, the additional information is in the form of
a numeric return code. This return code is the value of
ERRNO that
is set whenever one of the file system primitives returns with a
-1 .
Command Strings
The argument
[stream_command]
can be any expression that to one of the following command strings:
+-BOTH--| Write Options |-+
>>-+-OPEN--+-------------------------+--+-------------+-+------><
| +-READ--------------------+ +-| Options |-+ |
| +-WRITE--+---------+------+ |
| +-APPEND--+ |
| +-REPLACE-+ |
+-CLOSE----------------------------------------------+
+-FLUSH----------------------------------------------+
| +- = -+ +-CHAR-+ |
+-+-SEEK-----+--+-----+-offset--+-------+--+------+--+
| +-POSITION-+ +- < -+ +-READ--+ +-LINE-+ |
| +- + -+ +-WRITE-+ |
| +- - -+ |
+-QUERY--+-DATETIME--------------------------+-------+
+-EXISTS----------------------------+
+-HANDLE----------------------------+
| +-CHAR-+ |
+-+-SEEK-----+--+-READ--+------+--+-+
| +-POSITION-+ | +-LINE-+ | |
| | +-CHAR-+ | |
| +-WRITE--+------+-+ |
| | +-LINE-+ | |
| +-SYS-------------+ |
+-SIZE------------------------------+
+-STREAMTYPE------------------------+
+-TIMESTAMP-------------------------+
[Write Options:]
|--+---------+--------------------------------------------------|
+-APPEND--+
+-REPLACE-+
[Options:]
+-----------------------------------+
V |
|--+------------+----+-NOBUFFER----------------------+-+--------|
+-SHARED-----+ +-BINARY--+-------------------+-+
+-SHAREREAD--+ +-RECLENGTH--length-+
+-SHAREWRITE-+
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. 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.
|
Stream command - OPEN option
stream_name~command("open")
stream_name~command("open write")
stream_name~command("open read")
stream_name~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 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
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.
|
Stream command - SEEK option
stream_name~command("seek =2 read")
stream_name~command("seek +15 read")
stream_name~command("seek -7 write line")
fromend = 125
stream_name~command("seek <"fromend read)
|
POSITION |
is a synonym for SEEK.
Used with these
[stream_command]
s, the
COMMAND 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. 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:
Stream command - QUERY DATETIME option
stream_name~command("query datetime")
A sample output might be:
11-12-95 03:29:12
|
QUERY EXISTS |
Returns the full path specification of the stream object,
if it exists, or a null string. For example:
Stream command - QUERY EXISTS option
stream_name~command("query exists")
A sample output might be:
c:\data\file.txt
|
QUERY HANDLE |
Returns the handle associated with the open stream.
Stream command - QUERY HANDLE option
stream_name~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
for a detailed discussion of this issue.
Stream command - QUERY POSITION WRITE option
stream_name~command("query position write")
A sample
output might be:
247
|
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.
Stream command - QUERY SIZE option
stream_name~command("query size")
A sample output might be:
1305
|
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
Stream command - QUERY TIMESTAMP option
stream_name~command("query timestamp")
A sample output might be:
1995-11-12 03:29:12
|
|