Appendix B – Reference

The following sections provide a handy reference of Error Codes and their equivalent Reports, NextBASIC keywords and functions as well as other information discussed so far in a consice form

Reports and Error Codes

These appear at the bottom of the screen whenever the computer stops executing some function, and explain why it stopped, whether for a natural reason, or because an error occurred.

The report has a brief message explaining what happened and the bank number (not present unless the error occurred in a banked section of program), the line number and statement number within the line where it stopped (A command is shown as line 0. Within a line, statement 1 is at the beginning, statement 2 comes after the first colon or THEN, and so on). Some of the codes will have a code number or letter so that you can refer to the tables below. There are two types of error reports: General and Storage System related.

General Errors

The behaviour of CONTINUE depends very much on the reports. Normally, CONTINUE goes to the line and statement specified in the last report, but there are exceptions with reports 0, 9 and D.

Below, there is a table showing all the reports together with the circumstances they can occur.

¹ STOP cannot normally be entered in NextBASIC as a token; this is retained for compatibility and does work when you switch to 48K mode

Storage Device Related Errors

The following are reports generated by NextZXOS for storage device errors. Those marked in the left-hand column with RIC may be followed by the options Retry, Ignore or Cancel?

Some reports may occur with the code(s) shown or without them.

NextBASIC Keywords and Functions

The following is a list of all NextBASIC keywords in alphabetical order with a short description regarding their function.

The following is a list of all NextBASIC functions in alphabetical order with a short description regarding their purpose:

The Decimal System

Most European languages count using a more or less regular pattern of tens – in English, for example, although it starts off a bit erratically, it soon settles down into regular groups:

twenty, twenty one, twenty two, . . . twenty nine
thirty, thirty one, thirty two, . . . thirty nine
forty, forty one, forty two, . . . forty nine

This follows from using Arabic numerals, which have ten symbols 0 – 9, in a placeholder system where the position of each digit is multiplied by a power of ten. The reason for using ten as the basis of numbers is that we happen to have ten fingers.

The Binary System

Instead of using the decimal system, with ten as its base, computers use a system called binary, based on two values 0 and 1. Like humans have ten fingers, computer circuits have two states; low-voltage or off (0) and high-voltage (1). The two binary digits are called bits, and a bit is either 0 or 1. Computers therefore write 10 to represent 2, 100 to represent 4, 1000 to represent 8, and so on for the powers of 2.

It is customary to "pad out" binary numbers with leading zeroes so that they always contain at least four bits, called a nibble – for example, 0000, 0001, 0010, 0011 (representing 0 to 3 decimal). The reason for doing this is that it makes it easy to represent long binary numbers more compactly using hexadecimal as we will see further below.

Throughout this manual we've written binary numbers either with the suffix of a lower case b or with the prefixes of @ and BIN as supported by the NextBASIC Integer expression evaluator.

Regardless of how useful it is to write numbers in the way computers understand them, we have the obvious problem of representing them on paper: it's much easier for us to write and understand

65535 + 65534 than 1111111111111111b + 1111111111111110b.

The Hexadecimal System

Binary numbers quickly become unwieldly because even modest quantities require long strings of 0s and 1s to represent them. This is a natural result of only using two symbols to

represent each digit. Hexadecimal (or hex for short) was adopted to easily and compactly represent binary numbers. Hexadecimal is a base 16 numbering system with 16 symbols. 0 through 9 are used for the first ten symbols, representing decimal values 0 – 9, and the last six symbols are A, B, C, D, E, F representing decimal values 10 – 15. What comes after F? Just as in decimal we write 10 for ten, in hexadecimal we write 10 for sixteen since each position is associated with a power of 16.

The reason why hexadecimal is so well suited to representing binary numbers is that sixteen is a power of 2. This means binary digits can be grouped together and directly converted to a hexadecimal digit. Since sixteen is the fourth power of 2, four binary digits – a nibble – can be represented by a single hexadecimal digit. Conversion between binary and hexadecimal can then be done by sight and hexadecimal becomes a quick way to represent large binary quantities as well as an easy way to visualize bit patterns.

The table below shows the correspondence between binary, hexadecimal and decimal values:

To convert hex to binary, change each hex digit into a nibble (four bits), using the table above. Conversely, to convert binary to hex, divide the binary number into nibbles, starting on the right, and then change each group into the corresponding hex digit.

Throughout this manual, we've written hexadecimal numbers suffixed by a lower case letter h or prefixed by $ as the latter notation is the one supported by the NextBASIC Integer Expression evaluator.

Bits, Bytes and Words

The bits inside the computer are mostly grouped into sets of eight – these are called bytes. A single byte can represent any number from 0 to 255 decimal (11111111b or FFh). A single byte can also represent any character in the ZX Spectrum Next character set. Its value can be written with two hex digits.

Two bytes can be grouped together to make what is called a word. A word can be written using sixteen bits or four hex digits, and represents a number from 0 to 65535 decimal.

A byte is always eight bits, but words vary in length from computer to computer. In Sinclair computer tradition, 16-bit numbers are called words while 32-bit numbers are called long words.

Setting a bit means making a specific bit 1. Resetting a bit means making a specific bit 0. In digital logic, there is also a concept of "active low" and "active high". This means a signal becomes active when it is 0 or 1 respectively. The Z80n has an M̅R̅E̅Q̅ (or /MREQ) signal, for example. This is an "active low" signal; to distinguish them from "active high" signals, we usually write active low signals with a bar over their names (Or prefix them with a forward slash /). This means the Z80n indicates a memory cycle by making M̅R̅E̅Q̅ 0.

Using Binary and Hex in NextBASIC

Our first introduction to binary and hex was in Chapter 7 which introduced Integer Expressions. Chapter 14 introduced the use of the BIN keyword. Chapter 16 showed us how useful binary was in defining colours with the PALETTE keyword while Chapters 23 and 24 with the introduction of binary bitmasks for the REG and OUT keywords and the memory address space showed the usefulness of hexadecimal.

In reality many keyword parameters are binary; As an example ATTR and RUN AT's decimal parameters are really decimal "translations" of the bits that are being set inside the computer's memory or the Next Registers that these keywords control.