Channels Package

(Channels screenshot)

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:


File channels

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.

Examples

OPEN #4, "o>test.txt"
Creates a file named "test.txt" on the default drive for output through stream 4.
OPEN #5, "i>a:test2.txt"
Opens a file named "test2.txt" on drive A: for input through stream 5.
OPEN #6, "u>c:/data/list.txt"
Opens a file named "list.txt" in the "data" directory of drive C: for update through stream 6.

Variable channels

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.

Example

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)

Memory channels

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 #).

Example

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

Window channels

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:

+3e-compatible windows
These windows are the default type, and provide the same facilities as those provided by the ZX Spectrum +3e (except that, under ResiDOS, input is also supported). These windows support Spectrum-style control codes, so that you can use normal PRINT items such as INK, PAPER and AT (amongst others) in your PRINT # commands, they also support Spectrum tokens and graphics characters (so that you can use LIST # directly, for example).
VT52-compatible windows
These windows are created when you specify a character set address of zero (see below for details). These windows broadly emulate a subset of the VT52 terminal, and so use completely different control codes to the +3e-compatible windows. They are intended for applications such as CP/M and internet application console windows. They support only the standard ASCII character set, not Spectrum tokens or graphics characters. Additionally, they do not support line input; only (non-echoed) character input is provided.

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.

+3e-compatible windows

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).

0
Turn justification off
1
Turn justification on
2
Save current window contents
3
Restore saved window contents
4
Home cursor to top left
5
Home cursor to bottom left
(j) 6
Tab to left or centre of window (PRINT comma)
7
Scroll window
(j) 8
Move cursor left
(j) 9
Move cursor right
10
Move cursor down
11
Move cursor up
(j) 12
Delete character to left of cursor
13
Start new line (PRINT apostrophe)
14
Clear window to current attributes
15
Wash window with current attributes
(e) 16, n
Set INK n (0-7)
(e) 17, n
Set PAPER n (0-7)
(e) 18, n
Set FLASH n (0-1)
(e) 19, n
Set BRIGHT n (0-1)
(e) 20, n
Set INVERSE n (0-1)
(e) 21, n
Set OVER n (0-1)
(j) 22, y, x
Set cursor to pixel line y, character size column x
(j) 23, n
TAB to character size column n
(e) 24, n
Set attributes n (0-255)
(j) 25, n
If n=1, then characters 165-255 will be printed as UDGs, with data located at the end of the standard UDGs. If n=0, then characters 165-255 will be printed as BASIC keyword tokens (the default).
(e) 26, n
Fill window with byte n. Attributes are affected, but not cursor position.
(e) 27, n
Fill window with character n. Attributes and cursor position are affected.
(j) 28, n
Set double width (n=1) or normal width (n=0).
(e) 29, n
Set height n (0=normal, 1=double, 2=reduced, 3=double reduced)
30, n
Set justification mode (0=left, 1=centred, 2=full)
(j) 31, n
Allow embedded codes in justified mode if n=1.

VT52-compatible windows

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):

7 (BEL)
Sounds a beep.
8 (BS)
Moves the cursor 1 character to the left and replaces the character under the cursor with a space. If wrapping is enabled and the cursor is already at the left, it moves to the rightmost position of the previous line (unless it is already on the top line).
10 (LF)
Moves the cursor down 1 line, scrolling the window up if necessary.
13 (CR)
Moves the cursor to the leftmost column of the current line.
27 (ESC)
Introduces an escape sequence or a literal character.

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.

ESC A
Moves the cursor up. If the cursor is already on the top row, it has no effect.
ESC B
Moves the cursor down. If the cursor is already on the bottom row, it has no effect.
ESC C
Moves the cursor right. If the cursor is already in the rightmost column, it has no effect.
ESC D
Moves the cursor left. If the cursor is already in the leftmost column, it has no effect.
ESC E
Clears the window. The cursor position is not affected.
ESC H
Homes the cursor (ie moves the cursor to row 0, column 0).
ESC I
(Reverse index). Moves the cursor up 1 line, scrolling the window down if necessary.
ESC J
Erases all characters from the cursor (including the character under the cursor) to the end of the window. The cursor position is not affected.
ESC K
Erases all characters from the cursor (including the character under the cursor) to the end of the line. The cursor position is not affected.
ESC L
Inserts a line. The row with the cursor on it and all rows below are scrolled down 1 line. The cursor row is cleared. The cursor position is not affected.
ESC M
Deletes the row with the cursor on it. All rows below are scrolled up 1 line. The bottom row is cleared. The cursor position is not affected.
ESC N
Deletes the character under the cursor. All characters to the right of the cursor are moved 1 column to the left. The character at the end of the row is cleared. The cursor position is not affected.
ESC Y r c
Moves the cursor to the given position. r is the row number plus 32, and c is the column number plus 32. If the position is beyond the edge of the window, the cursor is moved to the edge of the window.
ESC b c
Sets the foreground (ink) colour. c can be either a Spectrum colour (0 to 7) or a colour value compatible with Locomotive's +3 CP/M implementation, as follows:
ESC c c
Sets the background (paper) colour. c can be either a Spectrum colour (0 to 7) or a colour value compatible with Locomotive's +3 CP/M implementation, as follows:
ESC d
Erases all characters from the start of the window up to the cursor (including the character under the cursor). The cursor position is not affected.
ESC e
Enables the cursor blob.
ESC f
Disables the cursor blob.
ESC j
Saves the cursor position.
ESC k
Restores the cursor position (as saved by ESC j).
ESC l
Erases all characters on the current line. The cursor position is not affected.
ESC o
Erases all characters from the start of the line up to the cursor (including the character under the cursor). The cursor position is not affected.
ESC p
Enables reverse video mode.
ESC q
Disables reverse video mode.
ESC r
Enables underline mode.
ESC u
Disables underline mode.
ESC v
Enables wrapping at the end of a line.
ESC w
Disables wrapping at the end of a line.

Null channels

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 #).

Example

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

Back to the ResiDOS homepage