stream

stream open <file> (r|w|a|r+|w+)
stream read (line|list|char) <stream>
stream print <list> <stream>
stream write <string> <stream>
stream rewind <stream>
stream seek (<posn>|+<incr>|-<decr>|end) <stream>
stream state <stream>
stream eof <stream>
stream close <stream>
stream flush <stream>
stream watch <stream> <what> <procName>
stream ignore <stream>

Examples:

"var s [stream open kmap.def w]": Open the file "kmap.def" for writing, creating it if it wasn't there before, and truncating any existing file.
"stream write $line $s": Write the string in $line to the open stream.

This allows you to read, write, create, and otherwise manipulate files on the host machine from Swat.

Subcommands may be abbreviated uniquely.
Streams are a precious resource, so you should be sure to always close them when you are done. This means stream access should usually be performed under the wings of a "protect" command so the stream gets closed even if the user types Ctrl+C.
Swat's current directory changes as you change stack frames, with the directory always being the one that holds the executable file for the patient to which the function in the current frame belongs. If the <file> given to "stream open" isn't absolute, it will be affected by this.
The global variable file-init-dir contains the absolute path of the directory in which Swat was started. It can be quite useful when forming the <file> argument to "stream open".
The second argument to "stream open" is the access mode of the file. The meanings of the 5 possible values are:

r: read-only access. The <file> must already exist.
w: write-only access. If <file> doesn't already exist, it will be created. If it does exist, it will be truncated.
a: append mode. The file is opened for writing only. If <file> doesn't already exist, it will be created. If it does exist, writing will commence at its end.
r+: read/write. The <file> must already exist. A single read/write position is maintained, and it starts out at the start of the file.
w+: read/write. If <file> doesn't already exist, it will be created. If it does exist, it will be truncated. A single read/write position is maintained, and it starts out at the start of the file.

"stream read" can read data from the stream in one of three formats:

line: Returns all the characters from the current position up to the first newline or the end of the file, whichever comes first. The newline, if seen, is placed at the end of the string as \n. Any other non-printable characters or backslashes are similarly escaped.
list: Reads a single list from the stream, following all the usual rules of Tcl list construction. If the character at the current read position is a left brace, this will read to the matching right brace, bringing in newlines and other whitespace. If there is whitespace at the initial read position, it is skipped. Standard Tcl comments before the start of the list are also skipped over (so if the first non-whitespace character encountered is #, the characters up to the following newline or end-of-file will also be skipped).
char: This reads a single character from the stream. If the character isn't printable ASCII, it will be returned as one of the regular Tcl backslash escapes.

If there's nothing left to read, you will get an empty string back.

"stream write" writes the string exactly as given, without interpreting backslash escapes. If you want to include a newline or something of the sort in the string, you'll need to use the "format" command to generate the string, or place the whole thing in braces and have the newlines in there literally.
While the syntax for "stream print" is the same as for "stream write", there is a subtle difference between the two. "stream write" will write the string as it's given, while "stream print" is intended to write out data to be read back in by "stream read list". Thus the command

 stream write {foo biff} $s

would write the string "foo biff" to the stream. In contrast,

 stream print {foo biff} $s

would write "{foo biff}" followed by a newline.

To ensure that all data you have written has made it to disk, use the "stream flush" command. Nothing is returned.
"stream rewind" repositions the read/write position at the start of the stream. "stream seek" gives you finer control over the position. You can set the stream to an absolute position (obtained from a previous call to "stream seek") by passing the byte number as a decimal number. You can also move forward or backward in the file a relative amount by specifying the number of bytes to move, preceded by a "+", for forward, or a "-", for backward. Finally, you can position the pointer at the end of the file by specifying a position of "end".
"stream seek" returns the new read/write position, so a call of "stream seek +0 $s" will get you the current position without changing anything. If the seek couldn't be performed, -1 is returned.
"stream state" returns one of three strings: "error", if there's been some error accessing the file, "eof" if the read/write position is at the end of the file, or "ok" if everything's fine. "stream eof" is a shortcut for figuring if you've reached the end of the file.
"stream close" shuts down the stream. The stream token should never be used again.
"stream watch" and "stream ignore" are valid only on UNIX and only make sense if the stream is open to a device or a socket. "stream watch" causes the procedure <procName> to be called whenever the stream is ready for the access indicated by <what>, which is a list of conditions chosen from the following set:

read: the stream has data that may be read.
write: the stream has room for data to be written to it.

When the stream is ready, the procedure is called:

 <procName> <stream> <what>

where <what> is the list of operations for which the stream is ready.

See Also: protect, source, file.

switch

switch <thread-id>
switch [<patient>] [:<thread-num>]

Examples:

"switch 3730h": Switches swat's current thread to be the one whose handle ID is 3730h.
"switch :1": Switches Swat's current thread to be thread number 1 for the current patient.
"switch parallel:2": Switches Swat's current thread to be thread number 2 for the patient "parallel"
"switch write": Switches Swat's current thread to be thread number 0 (the process thread) for the patient "write"
"switch": Switches Swat's current thread to be the current thread on the PC.

Switches between applications/threads.

Takes a single argument of the form <patient>:<thread-num> or <threadID>. With the first form, :<thread-num> is optional -- if the patient has threads, the first thread is selected. To switch to another thread of the same patient, give just :<thread-num>. You can also switch to a patient/thread by specifying the thread handle ID. NOTE: The switch doesn't happen on the PC--just inside swat.
If you don't give an argument, it switches to the actual current thread in the PC.

GEOS SDK TechDocs |

stdpaths ... | Next:

symbolCompletion ...