User guide

The working environment
Programs and files
Connecting to peripherals
Changing the interface
- Codepages
  - Bidirectional text
  - Combining characters
- Fonts

The working environment

The first thing you'll see when starting SE Basic IV is the working environment. Like Microsoft BASIC, but unlike practically all modern compilers and interpreters, SE Basic IV's working environment serves both as a development environment and as a canvas on which to execute BASIC commands directly. With a few exceptions, practically all commands that can be run in the working environment can be used in a program, and vice versa.

The default SE Basic IV screen has 24 rows and 80 columns. In some video modes, there are only 40 or fewer columns. Editing takes place on the lowest row.

Logical lines exceed the width of the physical row: if you keep typing beyond the screen width, the text will wrap to the next line but SE Basic IV will still consider it part of the same line. A logical line can be as long as you want providing the memory required to store it is available.

If you press Return, SE Basic IV will attempt to execute the logical line on which the cursor is placed as a command. When the command is executed correctly, SE Basic IV will display the prompt Ok. If there is an error, it will display an error message. If the line starts with a number, it will be stored as a program line. No prompt is displayed.

Special keys

Key	Description
`↑`	Move the cursor up.
`↓`	Move the cursor down.
`←`	Move the cursor left. The left edge of the screen wraps around except at the top row.
`→`	Move the cursor right. The right edge of the screen wraps around except at the bottom row.
`Tab`	Move the cursor to the next tab stop. Tab stops are 8 columns wide.
`Backspace`	Delete the character left of the cursor, shift all further characters on the logical line one position to the left.
`Del`	Delete the character at the cursor and shift all further characters one position to the left.
`Clr`	Delete the current logical line.
`Enter`	Execute or store the current logical line. A line starting with a number is stored as a program line.
`End`	Move the cursor to the first position after the end of the logical line.
`Home`	Move the cursor to the top left of the edit line.
`Page Up`	Move backward through the automatic listing.
`Page Down`	Move forward through the automatic listing.
`Control`	Sets bit `7` and clears bits `6` and `5` on the next character entered. Enables entering characters `128` to `159`.
`Alternate`	Sets bit `7` on next character entered. Enables entering characters `160` to `255`.
`Help`	Opens the on-line help. The program is restored on exit.
`Ins`	Inserts the last line entered into the edit line.
`Compose`	Merges two character glyphs.

When a program is started, the commands in the program are followed until the program quits and returns to direct mode or until user input is required. When a program is running, a few keys have immediate effect:

Key	Description
`Esc`	Stop execution and return to direct mode. A Break message is printed.
`F0`	Generate non-maskable interrupt (NMI). As with `Esc` but also works from machine code.

If user input is required by the INPUT statement, most keys have the same effect as in direct mode. The following keys have a different effect:

Key	Description
`Esc`	Equivalent of pressing `Space`.
`Return`	Finish input and return to the previous mode.

Keyboard shortcuts

The function keys can be used as keyboard shortcuts for some keywords. The default values for the function keys are:

Function key	Command
`F0`	`NMI`
`F1`	`LIST`
`F2`	`RUN` `Return`
`F3`	`LOAD ".BAS"`
`F4`	`SAVE ".BAS"`
`F5`	`CONT` `Return`
`F6`	`TRACE`
`F7`	`BLOAD "",`
`F8`	`BSAVE "",,`
`F9`	`KEY`
`F10`	`SCREEN`
`F11`	`FILES` `Return`
`F12`	`CHDIR ""`
`F13`	`FILES "/PROGRAMS"` `Return`
`F14`	`COLOR 7,1` `Return`
`F15`	`KEY LIST` `Return`

The function key shortcuts can be redefined with the KEY statement.

Keyword abbreviations

Note: These are subject to change as new tokens are added.

Many keywords can be abbreviated with a period (.) omitting the remaining characters. Other keywords have alternative shortcuts, shown in parentheses. These are the shortest abbrevations for each keyword.

ABS AC.OS A.ND (&) ASC AS.IN AT.AN BL.OAD B.SAVE CA.LL C.OPY CH.DIR CHR$ CLE.AR CLO.SE# CLS COL.OR CONT COS DA.TA DEEK DEF. FN# DE.LETE DIM D.OKE ED.IT EL.SE END EO.F# E.RROR EXP FI.LES FIX FN F.OR G.OTO GOS.UB IF INK.EY$ INP I.NPUT INS.TR INT KEY K.ILL LINE L.OCATE LEF.T$ LEN LET LI.ST LOAD LOC# LOF# LOG M.KDIR ME.RGE MI.D$ MOD NA.ME NEXT N.EW NOT (~) OFF OLD ON OP.EN# OR (|) O.UT PA.LLETTE P.RINT (?) PE.EK PI PO.KE RA.NDOMIZE READ R.EM (‘) REN.UM RES.TORE RET.URN RI.GHT$ RM.DIR RUN SA.VE SC.REEN SE.EEK # SGN SIN SO.UND SPC SQR STEP S.TOP STR$ STR.ING$ TAB TAN TH.EN TO T.RACE T.RON USI.NG U.SR VAL V.AL$ WA.IT WE.ND W.HILE X.OR

Matrix keyboards

It is possible to use SE Basic IV with computers that use simple matrix keyboards. These omit the function keys, but all other keys are accessible:

┌────┬────┬────┬────┬────┬────┬────┬────┬────┬────┐
│TAB │CAPS│PGUP│PGDN│←   │↓   │↑   │→   │CTRL│BKSP│
│1  !│2  @│3  #│4  $│5  %│6  &│7  '│8  (│9  )│0  _│
└─┬──┴─┬──┴─┬──┴─┬──┴─┬──┴─┬──┴─┬──┴─┬──┴─┬──┴─┬──┴─┐
  │Q   │W   │E   │R   │T   │Y   │U   │I   │O   │P   │
  │HOME│ DEL│ END│   <│   >│   [│   ]│ INS│   ;│   "│
  └─┬──┴─┬──┴─┬──┴─┬──┴─┬──┴─┬──┴─┬──┴─┬──┴─┬──┴─┬──┴────┐
    │A   │S   │D   │F   │G   │H   │J   │K   │L   │COMPOSE│
    │   ~│   |│   \│   {│   }│   ^│   -│   +│   =│RTN CLR│
┌───┴─┬──┴─┬──┴─┬──┴─┬──┴─┬──┴─┬──┴─┬──┴─┬──┴─┬──┴───────┤
│SHIFT│Z   │X   │C   │V   │B   │N   │M   │ALT │ESC       │
│  ALT│   :│   `│   ?│   /│   *│   ,│   .│SYMB│SPACE HELP│
└─────┴────┴────┴────┴────┴────┴────┴────┴────┴──────────┘

Programs and files

SE Basic IV can hold one BASIC program at a time in memory. To enter a program line, start with a line number and enter BASIC commands after that. The only limit on the length of a program line is the available memory. However, if you want to retain compatibility with Microsoft BASIC you should limit lines to a maximum of 255 characters, including the line number and any spaces. The program line will not be immediately executed, but stored in the program. Program lines are sorted by line number, so that line 10 is executed before line 20. All program lines must have a line number. Line numbers range from 0 to 16383 inclusive (Microsoft BASIC goes up to 65529). Within one program line, statements are separated by colons (:).

To run the program, type the command RUN. SE Basic IV will now execute all program lines in order inside the working environment. You cannot move the cursor around or enter commands while the program is running. If and when the program finishes, it will return control of the working environment to you. You can interrupt a program at any time by pressing Esc or F0(NMI). The program will stop immediately, print a Break message and return control to you.

A program can be stored on a drive by using the SAVE "MYPROG.BAS" command. The program will be written to the current working directory with the name specified in the command.

You can read a program file into memory with LOAD "MYPROG.BAS". This will erase the program currently in memory and replace it with the one read from the current working directory. To access files in a different directory, specify a path from the current directory. The path specification follows UnoDOS 3 conventions. The only valid path separator is the slash /. For example, LOAD "BASIC/MYPROG.BAS".

The current behaviour of SE Basic IV is as follows:

The .BAS extension is not included automatically if it is ommitted from the filename.
Programs are stored in plain text (non-tokenized) format unless otherwise specified.

When loading a program, syntax checking occurs for each line. If the line fails syntax checking, it is added as plain text for you to correct. However, programs must have a valid line range so you may have to renumber them before using them with SE Basic IV.

There are no plans to support Microsoft tokenized or protected formats. These can be converted with PC-BASIC which can also be used to renumber programs.

You can auto-run a program using LOAD "MYPROG.BAS","R". This differs slightly from the Microsoft BASIC syntax because SE Basic IV would treat r as an undefined variable.

You can load and save programs in tokenized format with {LOAD|SAVE} "MYPROG.BAS","T". Because the tokens are not finalized, you should keep a copy of your program in plain text format.

If you save a program called AUTOEXEC.BAS in tokenized format in the root folder, it will run automatically when you power on or hard reset your computer.

Accessing your drive

SE Basic IV uses UnoDOS 3 conventions for filename and paths.

Compatible BASIC files

When plain text support is added, SE Basic IV should be able to load any .BAS file with a valid line range. However, the more it diverges from the Microsoft BASIC dialect, the more work it will require to get it to run. The aim is to gracefully handle various line endings, as is currently done with the CONFIG.SYS file.

Packages

SE Basic IV can run packaged programs. A package is a folder stored in the PROGRAMS folder. Currently these are limited to machine code programs. However, there are plans to extend the application package format to also support BASIC programs.

Connecting to peripherals

SE Basic IV uses a system of input and output based on channels and streams. The CPU provides a 16-bit port range (0 to 65535). The same commands are used regardless of I/O device. For example PRINT #2 is used to send output to the screen, whereas PRINT #3 might be used to send output to a printer.

Streams and channels intuitively correspond to the software and hardware parts of I/O respectively. That is, a stream should be thought of merely as a collection of data going to or coming from a piece of hardware, and a channel should be associated with a particular piece of hardware such as a printer. In SE Basic IV, streams are numbered from 0 through 15, and their basic operations are reading and writing data.

The BASIC statement INPUT #s; [input-list] reads data from stream number s into the variables specified in the input-list. Conversely, the BASIC statement PRINT #s; [print-list] writes data to stream s. In general both INPUT # and PRINT # can be used in the same way as their ordinary counterparts INPUT and PRINT. In particular all the normal complexity of a PRINT statement can be used equally well in a PRINT # statement. In each case the data sent to the stream is exactly the same as the data which would be sent to the screen by the PRINT statement. The INPUT # statement is slightly more complicated in that is can both read and write data, as in INPUT "What is your name? "; A$. In fact each stream really has two components, an input stream and an output stream. Data written to the stream by either PRINT # or INPUT # goes to the output stream while input comes from the input stream.

It is even possible to change streams part way through a PRINT statement, as in PRINT #3; "hello"; #6; "there". This is obviously fairly confusing though, so should probably be avoided unless there is a good reason for using this construct.

Opening and closing

How do you know which stream numbers are associated with which channel? Before a stream is used it must be opened. Opening a stream serves two purposes. It associates the given stream with a particular piece of hardware (the channel), and actually signals the relevant device that it is going to be used. Stream are opened in SE Basic IV using the syntax OPEN #s, c$ where s is the stream number being opened (0 to 15) and c$ is a string specifying the channel to associate the stream with. Following this command, any data sent to stream s will go to the specified channel. It is possible to open several streams to the same device, but each stream can only be associated with a single channel.

The statement CLOSE #s is used to end the association of stream s with a channel. SE Basic IV supports three default channels:

K: Keyboard
S: Screen
W: Workspace

The W channel is internal, used to send data to the edit buffer. In practice the only channel that has both input and output of these is the keyboard channel. When SE Basic IV starts, the following streams are opened automatically: 0:K, 1:K, 2:S. The W channel cannot be opened from SE Basic IV. It is possible to redefine the standard channels, thus OPEN #2, "K" will cause output normally sent to the screen to be redirected to the keyboard.

For example, OPEN #5, "K" associates stream 5 with the keyboard, and thereafter INPUT #5; A$ would behave in an identical manner to INPUT A$.

Device independence

The most important advantage of using streams is in the writing of device independent programs. Say that you want to give the user the option of having all output go to either the screen or to the printer. Without using streams it is necessary then to have separate output statements for each device, as in;

IF (output = printer) THEN LPRINT "Hello" ELSE PRINT "Hello"

By using streams we can just open a particular stream (say 4) to the desired output device and thereafter use only one output statement;

PRINT #4; "Hello"

Obviously this will result is a much shorter program, particularly, if there are many output statements in the program. Further, it is an easy matter to add even further output devices if they become an option later in the programs development.

You could also hack an existing program by adding somewhere near the start;

IF [printer required] THEN OPEN #2,"P"

which will make all ordinary PRINT instructions go to the printer.

More stream commands

SE Basic IV also allows LIST and INKEY$ to be used with streams. LIST #s will send a copy of the program to stream s. However, currenlty INKEY$ can only be used with the keyboard channel.

Note that INKEY$ is not the same as INKEY$ #1 because the former does a stand-alone key scan whereas the latter attempts to read a key from the K device.

This section is based on an article written by Dr. Sean A. Irvine and Dr. Ian Collier for the comp.sys.sinclair FAQ.

Changing the interface

Codepages

SE Basic IV supports a large number of legacy codepages that were common at the time Microsoft BASIC was popular, excluding double-byte character set codepages used for Chinese, Japanese and Korean. You can select your codepage by using the cp=<option> in the CONFIG.SYS file. Codepages are stored in the /SYSTEM/FONTS folder and loaded when the computer restarts. SE Basic IV will load and save all program files as if encoded in the codepage you select.

Note that SE Basic IV does not implement the following features relevant to some of these codepages:

Bidirectional text

By default, all text is printed left-to-right independent of the codepage selected. In Microsoft BASIC, to write strings in a language that is written right-to-left, the logical character sequence must be inverted so that the order appears correct visually. But in SE Basic IV, you can enter the logical character sequence from left-to-right in a string and then invert reverse the string with PRINT a$*-1. This affects code pages marked with B in the table.

Combining characters

SE Basic IV recognizes single-byte code points (where each glyph shows on a single cell on the screen) and double-byte code points (where a single glyph takes up two cells on the screen). Combining characters (such as the combining diacritics of codepages 874 and 1258) are therefore not shown correctly: instead of being combined with their preceding base character as a single combined glyph, such combinations will be shown as separate glyphs. Where available, alternative codepages with precomposed characters will give better results. This affects code pages marked with C in the table.

Note: Where a bitmap display is in use, it is possible to manually combine characters by over-priting the diacritics.

The following codepages are available. SE Basic IV uses the Microsoft OEM codepage number where this is unambiguous. For unofficial codepages and those with conflicting numbering, codepage names are used instead of numbers.

ID	Codepage	Languages	Notes
0437-IBM	DOS Latin USA	English	IBM default
0932-JAP	Shift-JIS (variant)	Japanese	MSX2+ compatible
1250-EUC	Central European	Central European languages
1251-CYR	Cyrillic	Cyrillic languages
1252-EUW	Western European	Western European languages
1253-GRE	Greek	Greek
1254-TUR	Turkish	Turkish
1255-HEB	Hebrew	Hebrew	B
1256-ARA	Arabic	Arabic script languages	B
1257-BAL	Baltic	Baltic languages
1258-VIE	Vietnamese	Vietnamese	C
KOI8-R	Cyrillic	Russian	for use with JCUKEN keyboard layout
IR-109	ISO-8559-3	Turkish, Maltese and Esperanto	Latin 3 - South European
IR-226	ISO-8559-16	Albanian, Croatian, Hungarian, Polish, Romanian, Serbia and Slovenian	Latin 10 - South-Eastern European

Fonts

In SE Basiv IV, codepages and fonts are equivalent. A font is a 2KB file containing a raster definition for each of the 256 characters. Characters are six pixels wide by eight characters tall. They are encoded in eight bytes using only the middle six bits of each byte. Fonts are stored in the /SYSTEM/FONTS folder.

The following fonts available to display text created on other systems: