AquariusPlus User Guide: Using the System

Command Line

The Aquarius⁺ has a handful of methods by which a user can interact with it. There is the keyboard, the mouse, SD card reader, game controllers... even the built-in Wi-Fi connector can be used to interact with the system. But let's focus on the keyboard, the most common method used in controlling plusBASIC.

When the Aquarius⁺ starts up, the text below appears on a flashing background:

         BASIC

Press RETURN key to start

This is an invitation from the system letting you know it's waiting for you to begin. Very polite, right? So let's do what it's asking and press the RETURN key.

Note: This startup screen may have been turned off in the Settings app, and your machine may go straight to the copyright screen shown below. Additionally, there may be a file named autoexec in the root of your SD card that takes you to a program set to automatically run at boot up. If this is the case, you can remove the SD card before you turn the system on to get to the copyright screen.

Now, the keyboard that you're using with the Aquarius⁺ probably doesn't have a RETURN key, but it probably does have an ENTER key. For inclusivity, we'll refer to it as the ENTER/RETURN from now on. After you press the ENTER/RETURN key, the screen changes to a light blue/cyan, and displays the message below... or something very similar, depending on the version you're using or how your system is configured...

Copyright © 1982 by Microsoft inc. S3
Aquarius+ System V0.33
plusBASIC v0.23x

Ok

You can now begin typing on your keyboard. As you do, letters and symbols will appear beneath the Ok. The Aquarius⁺ is giving you the opportunity to give it instructions or commands, entered as a line of text, hence the term command line. A line is terminated by pressing the ENTER/RETURN key. If you give the Aquarius⁺ an instruction it understands, it will perform or execute it for you, and then display Ok, letting you know it's complete. But until we are familiar with some of the commands the system understands, we'll likely confuse it.

For example, if you type Hello and ENTER/RETURN, the Aquarius⁺ responds with a BEEP sound and displays the error message Syntax error, followed by Ok:

Hello
Syntax error
Ok

There's no harm in this. Errors are common and usually quite frustrating. Rest assured you won't damage or break the system. But to perform useful tasks on the Aquarius⁺, you'll need to understand plusBASIC and the different modes of operation it uses.

Immediate Mode

When interacting with a Command Line-based system like the Aquarius⁺, there are common tasks that need to be completed quickly, without writing an entire program to execute them. This is known as Immediate Mode, where commands are entered in a single line with no line numbers preceding them.

To begin we'll perform two tasks:

• The first is the FRE(0) command, which returns the amount of FREe RAM available for a BASIC program. It is a numeric value, so by itself, the system doesn't know what to do with it... there is a noun but no verb in the request... so to tell the Aquarius⁺ to display it, type the PRINT command (and a SPACE) followed by the FRE(0) command, and then hit the ENTER/RETURN key.
• Next is the command to list the contents of the current DIRrectory on the SD card, DIR. It's job is to display the contents of a directory (sometimes called a folder) to the screen. The VERB PRINT is already implied, so we don't have to add it in front of DIR... in fact, the Aquarius⁺ will complain if we do! Type DIR and hit the ENTER/RETURN key.

So, here are our two commands, each typed in on a line of its own, followed by an ENTER/RETURN:

Single Line Command Example

PRINT FRE(0)
-32280
Ok
DIR
23-08-09 14:44 <DIR> demos
23-08-09 14:44 <DIR> games
23-08-09 14:44 <DIR> music
23-08-09 14:44 <DIR> roms
Ok

Notice that because we have used the ENTER/RETURN key twice, there are two Ok acknowledgements from the computer, letting us know each has been completed. Commands issued in immediate mode DO modify variables, objects, and memory locations, but they are not SAVED as part of a program.

And here are the two commands typed on the same line, separated using the : character, and followed again by ENTER/RETURN...

Compound Command Example

PRINT FRE(0):DIR
-32274
23-08-09 14:44 <DIR> demos
23-08-09 14:44 <DIR> games
23-08-09 14:44 <DIR> music
23-08-09 14:44 <DIR> roms
Ok

Notice here that because ENTER/RETURN was only used once, only a single Ok acknowledgement is shown AFTER both commands have been completed.

Compound commands allow a small amount of sequential processing to be done in a single Immediate Mode command line. Using Immediate Mode commands from the command line will become second nature to you, the more you interact with the Aquarius⁺. We'll cover many more of these commands, but for now you have a simple, direct way of interacting with the system.

Let's make a program!

Programming Mode

Sometimes more logic or user interaction is needed, so a series of commands need to be chained together to complete the task along with looping, branching, or user input. This is known as Programming Mode. In Programming Mode commands are entered as a series of lines, each preceded by a line number.

Like many other early implementations of BASIC, plusBASIC organizes its code (instructions for the computer to perform) using line numbers. These are just numbers (positive integers between 1 and 65529) added to the beginning of each line of code that allow the Aquarius⁺ to sort and execute the instructions in the order intended by the programmer. In more modern programming languages (including newer versions of BASIC), line numbers are no longer used, rather, sections of code are organized in paragraph blocks that are prioritized, interpreted, and executed using combinations of indented text, parenthesis, brackets, and special punctuation.

But we're doing this old school, so line numbers are going to become our best friend.

A plusBASIC program can be written and reviewed on both Aquarius⁺ hardware and emulators on the command line by typing in the instructions character-by-character (using BACKSPACE to fix mistakes) via the keyboard, starting with a line number and a SPACE, continuing with one or more plusBASIC instructions (each "phrase" separated by a COLON), and completed by pressing the RETURN/ENTER key. Since the line of text started with a line number, it is considered to be part of a program, and the computer saves it to memory, sorting it among the other lines by the line number:

Programming Mode Example

10 print fre(0)
20 dir
run
-32291
23-08-09 14:44 <DIR> demos
23-08-09 14:44 <DIR> games
23-08-09 14:44 <DIR> music
23-08-09 14:44 <DIR> roms
Ok

The above program does the same thing as the earlier, compound immediate mode example, but it does so in a single program that is easy to execute. Notice that the command RUN is used to execute the program. If we wanted to see the list of program commands, we would use the command LIST. If we wanted to change any of the lines, we could retype or edit them within a program, but that is covered a bit later. We could save this program for later use by entering the command SAVE "FRE-DIR.BAQ", which saves the program to the current directory as a BASIC program file named "FRE-DIR.BAQ". We could then use the command LOAD "FRE-DIR.BAQ" to put the program into memory, and then again use the command RUN to execute it, or we could combine the two commands into RUN "FRE-DIR.BAQ" to load and run the program in one step.

Note also that we changed things up a little bit: when we typed PRINT FRE(0) in the immediate mode examples, earlier, we typed it in UPPER CASE, but in this program mode example, we typed print fre(0) in lower case. Why? Is this something special we have to do in program mode?

No. The truth is that plusBASIC doesn't care whether commands are typed in UPPER CASE, lower case, or MiXeD CaSe. The only time letter case matters is when it's used as part of a string of characters contained within quotation marks "...

print fre(0)
-32291
Ok

PRINT FrE(0)
-32291
Ok

PRINT "JOE"
JOE
Ok

PRINT "Joe"
Joe
Ok

Organizing a plusBASIC Program

We established previously that line numbers dictate the order in which the program lines are stored and executed (generally), but they are also used as reference points for plusBASIC commands that control the flow of the programs: GOTO, GOSUB, LIST, RUN, and RESTORE. This allows a plusBASIC to jump, loop, and repeat instructions when certain conditions (of the programmer's choosing) are met.

Similarly, line labels are an alternate method of referencing lines. A line label must be placed at the beginning of a line immediately after the line number. It consists of an underscore _ followed by one or more alphanumeric characters (cannot be plusBasic keywords), and is terminated by completing the line with the ENTER/RETURN key. Line labels may be of any length, and unlike variable names, all characters are significant.

Why wouldn't you use line labels all the time?

When the plusBASIC interpreter searches for a line label, it has to start from the very beginning of the program to search for it as a text string, whereas line numbers are stored in order as bytes, so the interpreter can more easily find these values. But line labels are more flexible when writing code, as they don't need to be updated when line numbers have to be refactored. An approach we'll cover later in detail is the concept of a Label Jump Table: a series of lines of code at the very beginning of the program that feature a line label followed by a GOTO statement with a specific line number as its destination. That offers a compromise where the Label Jump Table is the only location a subroutine line number needs to be updated, but all line labels can remain the same.

Another useful command is the REM (REMark) statement. REM allows the programmer to document, disable, and annotate plusBASIC code to make it more readable, useful, and functional. Make liberal use of the REM statement to make your code more readable, particularly when GOSUB or GOTO are used with labels:

Line Label and REM Example

2000 _main
2001 REM Main Body
2100 GOSUB _timer
2099 END
4000 _timer
4001 REM Timer subroutine to count jiffies
4100 REM Do timer stuff here
4199 RETURN

Line numbers are typically assigned by the programmer at intervals of 10, 100, or 1000. This allows extra "room" between lines to add additional code without having to completely refactor (renumber) the program instructions. The programmer is also free to type in lines of code out-of-order, allowing them to add new instructions in earlier sections of the program even after parts closer to the end are finished. The computer will know to sort them by line number even if line 100 is typed into the system AFTER line 500.

When writing plusBASIC code, some programmers find that it's easier to read and write code if line numbers are the same length (four or five digits) so that similar lines of code line up. Another practice is to use consistent ranges of line numbers for standard parts of the program. The following is an example:

• 1000 - 1299 : Program header and Label Jump Table
• 1300 - 1599 : Set system flags and initialize variables
• 1600 - 1999 : Setup routines
• 2000 - 3999 : Main loop
• 4000 - 8999 : Program routines
• 9000 - 9999 : Closeout routines

Program Editors

While editing on the command line is useful for short programs and for troubleshooting or testing, a better practice is to use a text editor to modify and arrange the plusBASIC code. The Aquarius⁺ has an included text editor, AQDS (AQuarius Development System) that allows more effective editing of a program than the Immediate Mode method. Like many text editors and word processors, it uses cursor keys for navigation and allows selection of blocks of text for copying and pasting elsewhere in the document. Line numbers are still needed for each line of instructions with colons separating "phrases", but the programmer must manually sort them by line number, otherwise any line number lower than a previously higher one will discontinue loading of the file. There are Python utilities that can automatically renumber a file, but this can't be done on Aquarius⁺ hardware.

The best approach is to use a Windows, MacOS, or Linux-based text editor to create and modify the files, but the code has to be transferred between the PC and the Aquarius⁺ environment, either via the SD Card or a network connection when using Aquarius⁺ hardware, or most commonly directly editing files in the AquariusPlusDisk directory for the emulator so that edits can be saved and tested quickly.

By default, plusBASIC saves programs in a "tokenized" format when using the SAVE "filename" command. The tokenized format is only partially legible in a text editor, with line numbers and keywords replaced with odd characters (byte values), making the file uneditable. If the SAVE "filename", ASC command is used, plusBASIC saves the program as clear text ASCII, fully editable in a text editor. The default SAVE command can be set to always save in ASCII format if the command SET SAVE ASC ON is executed. This instruction can also be saved into the autoexec file to run at start-up and default the system to perform ASCII saves, even without using the ,ASC parameter. This effect can be reversed with the command SET SAVE ASC OFF. Note that ASCII text files take slightly longer for plusBASIC to execute as they must first be tokenized within memory. The default tokenized format (commonly using the .BAQ extension) is faster, but again is not editable in a text editor.

plusBASIC Shortcuts

Command Shortcuts

We've used the PRINT and REM commands a couple of times so far in our examples, and as your programming skills improve, you'll probably use them more often than any other commands. In fact, they will become a bit tedious to type after a while. The good news is that there are a few command shortcuts that can be used for some plusBASIC commands that will save you a few keystrokes over time. These can be used either in immediate mode or program mode:

• PRINT = ? - The PRINT command can be shortened to a question mark, ?.
• REM = ' - The REM command can be shortened to a apostrophe, '.

Control Key Shortcuts

In addition to command shortcuts the system also has shortcuts that can be typed holding down the CTRL (control) key and typing another character. A complete list of these control shortcuts are listed here, but here are a few examples:

• CTRL+C - causes a running program to end. Works the same as ESC.
• CTRL+G - plays a BEEP sound.
• CTRL+M - same as the ENTER/RETURN key.
• CTRL+N - changes the characters to the extended Latin-1 character set.
• CTRL+O - changes the characters to the original Aquarius character set.

Compose Characters

The Aquarius⁺ can type more characters than are shown on most keyboards. These are typed by holding down the LeftAlt key, then typing two characters to create an extended character. Note that you will have to use the CTRL+N control key shortcut to see these characters! This list of compose keys shows the complete list, but here are a few examples:

• LeftAlt+O+C - Copyright © character
• LeftAlt+Hyphen+L - Pounds sterling £ character

You can use the CTRL+O control key shortcut to switch back to the Aquarius character set when you're done.

The Panic Button(s)

There are some situations where the Aquarius⁺ will either appear to be unresponsive, or will be doing things that make absolutely no sense, and there's no way you can make it come back to reality. Fortunately, there are steps you can take to get back to "normal":

• CTRL+S - Sometimes a command or program is waiting for keyboard input, and it is not clear about it's needs. CTRL+S (STOP/PAUSE) discontinues the current program or command.
• CTRL+C - If you're running a program, and it seems unresponsive to any keystrokes or is just stuck, try this Control Key shortcut. It causes any plusBASIC command or program to stop, and go back to Immediate Mode, often with a printout of what line number in the program it stopped.
• ESC - This key does the same thing as CTRL+C and can be used in the same situations.
• CTRL+O - Sometimes a custom CHRSET (Character Set) is being used, and is displaying garbage on the screen. Using this Control Key shortcut will force the original Aquarius Character Set -- AQUASCII -- to be used instead.
• CTRL+T - In some instances, the system is stuck in an odd SCREEN mode that cannot be seen. This combination switches back to the primary 40 column character mode.
• CLS + ENTER/RETURN - Occasionally, the foreground and background screen color combination can't be read, so characters are "invisible". Typing this, even if the characters can't be seen as they are typed, sets it back to the default black text on cyan background.
• SHIFT+ESC - This forces the Aquarius⁺ to reset. While your plusBASIC program will be lost (ALWAYS SAVE your program before running it!), the other parts of memory (graphics, sounds/songs, character sets, etc.) are usually preserved.
• Power Off & On - This completely resets the Aquarius⁺ and wipes it's memory. The SD Card contents are not usually harmed, but if a file was being written to the SD Card during the power, it could be damaged.

Summary

In this section on Using the System we talked about the Command Line. Then we discussed both Immediate Mode and Programming Mode, where we covered organizing a plusBASIC program and how to use Program Editors. Finally, we offered some plusBASIC Shortcuts to make using the Aquarius⁺ easier.

In the next section, we'll take what we've learned here and we'll start writing a plusBASIC program.

If you want to go to another section, visit the Table of Contents.