The channels package provides a number of new channels for use under ResiDOS. Most of these are compatible with the extended channels of the ZX Spectrum +3e, although there are also several important additions.
After installing the package (available here), in order to make use of the new channels, you will need to read the information on using extended channels in ResiDOS.
The channels provided are:
Streams may be opened to any file in one of three different access modes: input (using the "I>" channel), output (using the "O>" channel) and update (using the "U>" channel).
In input and update modes, the file must already exist, or an error will occur. In output mode, the file is deleted if it already exists, and then a new file is created. Once the file is open, it can be input from (if opened in input or update modes) or output to (if opened in output or update modes). Because of file buffering, it is essential to CLOSE # any file channel before finishing, otherwise data may be lost.
The channel specifier for all file channel types requires the filename of the file to follow the ">" character.
File channels support all the pointer operations (FN ptr#(), FN ext#() and POINT #).
It should be noted that files on IDEDOS disks are always stored as a number of 128-byte "records" and so you may read rubbish at the end of a file if it is not an exact multiple of 128 bytes in length. To avoid this problem, you should write some code or "signature" at the end of your file which you can detect when reading it back. Alternatively, you could write the number of bytes or entries in your file at the start. This problem does not exist for files on FAT disks, but it would be good practice to do this anyway, since it will then allow your program to be used with files on both FAT and IDEDOS disks.
The "V>" channel can be used to direct output to or input from a string variable, which can be easily manipulated within a BASIC program. This would allow you to (for example) examine disk catalogs in your BASIC program, or make an auto-running game demo (by inputting from a string containing set keystrokes).
The channel specifier for the variable channel type requires the name of the string variable to follow the ">" character.
Variable channels support all the pointer operations (FN ptr#(), FN ext#() and POINT #).
The string specified must be a character array with a single dimension, large enough to hold the maximum amount of data you expect to have to deal with.
Here is an example program that outputs a list of installed ROMs to a string.
10 DIM a$(1000)
20 OPEN #8, "V>a$"
30 %roms+ #8
40 LET l=FN ptr#(8)
50 CLOSE #8
60 PRINT "Assignment length is ";l
70 PRINT "List is:"
80 PRINT a$( TO l)
The "M>" channel can be used in a very similar way to the variable channels. However, as it is a fixed memory region, it is more suitable for use by machine-code programs.
The channel specifier for the memory channel type requires the address and length of the memory region (separated by a comma) to follow the ">" character.
Memory channels support all the pointer operations (FN ptr#(), FN ext#() and POINT #).
Here is an example program that outputs a disk catalogue to memory and then runs a machine-code routine to process it:
10 CLEAR 29999
20 OPEN #7, "M>30000,1000"
30 CAT #7
40 LET x=USR myroutine
50 CLOSE #7
The "W>" window channels are the most complex of the extended channels currently available on ResiDOS. Two different types of window, with very different behaviours, are available:
The channel specifier for the window channel type requires the following values (separated by commas) to follow the ">" character: top line (0-23), leftmost column (0-31), height (1-24), width (1-32), and optionally character size (3-8) and character set address. If no character size is specified, the default is 8. If a character set address is given, then this is used instead of the built-in fonts; this allows you to use nice fonts such as those provided with art programs and adventure games. If the character set address is given as zero (0), then a VT52-compatible window is created instead of a +3e-compatible window.
Note that the character size has no bearing on the way the window is defined, but it does affect the number of "actual" columns you have available. For example, the following defines a window the size of the entire screen; but because a character size of 5 is specified, the number of characters that can be printed in the window at any time is 24x51:
OPEN #5,"w>0,0,24,32,5"
Window channels do not support the pointer operations. However, the "set position" operation (POINT #) can be used to change the region of memory to which window output is sent. Normally, this is the standard Spectrum screen address (16384), but it can be set to any 8K boundary. This is mostly useful for machine-code programmers, as it allows them to perform window output directly to the 128K Spectrum's alternate screen at 49152 in page 7, for example.
When PRINTing to +3e-compatible windows, you can use many of the same control functions as you can with the normal screen. For example: ' (apostrophe; start a new line), , (comma; start a new column), TAB, AT, INK , PAPER, FLASH, BRIGHT , INVERSE, OVER. Of these, only AT behaves slightly differently; it takes y to be a pixel line and x to be an actual character column.
When first defined, windows are in non-justified mode, but they can be set to be left-, full- or centre-justified. Note that in justified mode, some features and control codes cannot be accessed, so you may need to switch back to non-justified mode to use them.
Input is supported in +3e-compatible windows. If you use INKEY$ # , then the keyboard is simply scanned and a character returned without anything being output to the window. If you use INPUT #, then a cursor is added to the window at the current position. The user can then input any text desired, using the left and right arrows to move along the text input so far, or the up and down arrows to move to the start or end of the text. The DELETE key deletes the character to the left of the cursor, and the ENTER key completes the input. Depending upon memory available, the entire size of the window can be used in the input, although care is taken to ensure that no input character is ever scrolled off the top of the window. An absolute maximum of 255 characters is allowed in the input line.
A complete list of control codes follows; these codes can be sent to a window by PRINTing them using the CHR$ function. If a code is preceded by (j) then it will be ignored if issued in justified mode (however, their settings will still be taken into account; for example, you can justify double-width text, but you must set it before entering justified mode). If a code is preceded by (e) then it can only be used in justified mode if the "embedded codes" feature has been set (which requires more memory to be allocated for the channel).
VT52-compatible windows behave very differently from +3e-compatible windows, and are most useful for applications such as CP/M and internet console applications. They do not support line input (INKEY$# and INPUT # are allowed, but are implemented as non-echoed character input) or non-ASCII characters (such as the Spectrum tokens and graphics characters). By default, these windows operate in a "non-wrapping" mode (when the end of a line is reached, text does not wrap automatically to the next line unless CR and LF codes are issued) and with a visible cursor, although these modes can be changed. The full list of control codes supported is as follows (other control codes are ignored):
The following escape sequences are interpreted. If an ESC character is followed by any character other than those in this list, then that character is output as a literal (without any further interpretation) directly to the window, and the escape sequence is terminated.
The "Z>" channel simply discards all output that is sent to it. It always returns a CR character (ASCII 13) when it is read from (so the INPUT # command always returns an empty string). This can be handy if you wish to execute a command which produces output that you do not want.
The channel specifier for the null channel type is simply "Z>".
Null channels support all the pointer operations (FN ptr#(), FN ext#() and POINT #).
Here is an example program that does nothing much at all!
10 OPEN #4, "Z>"
30 CAT #4
40 INPUT #4;x$
50 CLOSE #4