| String | Description | |---|---| | "u>*filespec*" | This opens an existing file and opens an input/output-stream to it. | | "m>*address, length*" | This opens an input/output channel to the memory area at *address*, *length*. | | "v>*x$*" | This opens an input/output channel to the variable x$ which must be a character array with a single dimension, large enough to hold everything that will be output to it/input from it. | | "w>*line, col, ht, wid [, csize [, cset]]*" | This opens an input-output channel to a text *window* on the screen, starting at character position (*line*,*col*), with a height of *ht* character rows and a width of *wid* characters. Optionally, a character width of *csize* (3-8px) may be specified. This does not affect the definition details of the window, which are always specified in 8px wide characters. A user-supplied character set may also be specified, located at address *cset*. See the Windows special section for details. | | "d>*driver_name>[driverspec]*" | Opens a channel to *driver_name,* whose data flow direction is dictated by the driver it addresses. *Driverspec* is optional and depends on the driver (if needed or not). | *Table 20 – OPEN # channelspec setup strings* Here are some examples:
OPEN #4,"o>a:test.txt"Creates a file named test.txt on virtual disk drive a: and opens an output-only channel to it, connected to stream 4.
OPEN #5,"stuff"Opens an existing file named stuff on the default drive and opens an input-only channel to it, connected to stream 5.
Once a stream is opened, it can be used with the standard **INPUT #** and **PRINT #** commands, as well as the additional *pointer commands*. Before we get into those, we should just first mention: **CLOSE** *#n* which closes the previously opened stream *#n*. If *n* is a stream between **0** and **3**, then the default channel for that stream (**k**, **s** or **p**) is reattached to it. Note, that attempting to **CLOSE** a stream that hasn't been opened, will not produce an error; instead it will exit gracefully with **OK, 0:1.** For example:
CLOSE #4Closes the channel attached to stream 4.
Streams, and especially those opened to large files, can be very long to navigate in a serial manner: imagine having a file that's 100 Kbytes long, you would have to iterate through 102400 characters to read the very last one byte. For that reason, *NextBASIC* maintains *pointers* to the position you're located within a stream, how long the stream is (in characters / bytes), the ability to move these *pointers* to any location within a stream and finally the ability to read one byte from the current pointer position from that stream. The commands and functions to do that are called *Pointer Commands* and are the following: **POINT #...** and **RETURN #...TO**, **DIM#...** and **DIM #...TO**, **GO TO #** and **NEXT #...TO**. Let's visit their syntax below: **POINT** *#n*\ **RETURN** *#n* **TO** [%]*var* This command returns the current position of stream *n.* It's the same as the **RETURN #...TO** with the exception that no variable assignment is done to the resulting value. If the **RETURN** variant is used, then it also stores it in variable *var*. The variable can be an integer one, which means that it will accept –*safely*– positions of up to **65536** bytes within the stream (or a maximum value of **65535** as position **0** is the very first position within a stream). Do not use integer values if you plan on accessing streams larger than that! If you don't use the **TO** variant however you can use it as part of the regular expression evaluator.