Chapter Four

NOS BASICODE-2 PROTOCOL

We have already explained the Esperanto concept of NOS-BASICODE, and the idea of writing one program that can be of use to a number of different computers. What follows now is a detailed description of the standard, designed for programmers who wish to use BASICODE-2.

1. BASICODE-2: The ground rules

There are four basic rules in the BASICODE-2 protocol:

1. We only use BASIC statements that are understood by all brands of computers. A list of these can be found in section 5 of this chapter.
2. Since rule a. leads to a lot of practical problems, such as the inability to clear the screen in a standard way, line numbers below 1000 are reserved for subroutines. These perform the extra functions needed in most programs that cannot be achieved using the standard BASIC statements. The precise function of these subroutines is described in section 3. GOSUB 100, for example, is used to clear the screen. GOSUB 110 puts the cursor at a specific point on the screen, and so on. These routines are of course specific to each computer brand and therefore they are not part of the main program in BASICODE-2 standard. They are therefore included in the translation programs for each brand of computer. When combined with the BASICODE-2 data, the whole program is then complete.
3. We have to standardise the video display screen as consisting of 24 lines, each of 40 characters. If you are programming in BASICODE-2 then it is important that you bear the screen size in mind! Unfortunately the rule is not quite as simple as this. There are computers in the group with only 16 lines on the screen (e.g. TRS-80) and some that can only accommodate 22 characters per line (e.g. VIC-20). So unless it is really necessary, do not use more than 16 lines on the screen, and do not make lines longer than need be. Better still, use a subroutine which adjusts the lines to the size of the screen. This is possible using BASICODE-2.
4. A line should not be longer than 60 characters including the spaces and the line number.

2. The program construction

The following line number scheme is used to build up a BASICODE-2 program:

0‑999:	Standard routines (see section 3). These routines are different for each computer and are therefore contained in the translation program.
1000:	first line of the BASICODE-2 program. It must be in the following form: 1000 A=(value): GOTO 20: REM program name. (value) is the maximum number of characters that can be used by all strings together. Line 20 is used to reserve memory space for the strings in those computers which need it.
1010‑32767:	the main program. There are no restrictions on this section, except that line numbers above 32767 are forbidden.

Although it is not compulsory, it is a good idea to build up your BASICODE-2 program systematically. Other users can then quickly understand your method of working, and it is then easier to adapt if necessary. We suggest that you use the following scheme:

1000‑19999:	the main program.
20000‑24999:	subroutines which you need for your program, but which contain statements which are not allowed in BASICODE-2.
25000‑29999:	lines with DATA statements.
30000‑32767:	lines with REM statements. You can use this space for any background details about the program, references or your name and address.

It is worth notinh at this point the use of the subroutine lines 20000‑24999. Try to avoid the use of statements that are not allowed in BASICODE-2. In some cases, of course, this is unavoidable, for example, the storage of variables on disk or tape. This is when you use the lines 20000‑24999. It is extremely important that you indicate exactly what these routines are intended to do, or other brand users will not be able to follow your logic. It is also good practice to use line numbers in steps of 10, this leaving plenty of room to insert lines at a later stage.

3. Operation of the BASICODE-2 standard routines

These are written specifically for each computer brand and form part of the translation program. They look different in the various BASIC dialects but in fact they do exactly the same in each case.

GOSUB 100:
This subroutine is used to clear the screen and set the cursor at position 0,0 (i.e. the top left-hand corner of the screen.)

GOSUB 110:
This places the cursor at a specific point on the screen. The exact point can be chosen by specifying the variables HO and VE. HO is the position on a line (0 is the furthest position to the left), and VE is the number of the line. The top line on the screen is considered to be number 0. Remember that in BASICODE-2, the maximum screen size is 24 lines, each of 40 characters. For this reason HO must not be larger than 39, and VE cannot be greater than 23. The variables HO & VE are not changed in value on calling the subroutine.

GOSUB 120:
This gives the position of the cursor on the screen and sets the variables HO and VE. HO=0 is the first position on any line, and VE=0 implies the top line on the screen. By using this subroutine, and GOSUB 110, you can move the cursor about the screen.

GOSUB 200:
This checks if a key has been depressed, and if so, puts the character in the variable N$. If no key was pressed then N$ is an empty string. In principle it is possible to put any character on the keyboard into N$, including control characters. But be careful. Not all control characters have the same function on different brands of computers. So it is best to avoid control characters. The RETURN (or ENTER, NEWLINE, etc) key, though, does have ASCII code 13 on all computers.

GOSUB 210:
This subroutine waits until a key has been depressed and then sets the character in the variable N$. It differs from GOSUB 200 in that this subroutine waits until a key has been pressed, whilst GOSUB 200 only checks whether a key has been depressed.

GOSUB 250:
This is used to activate the beep on most computers with this facility. Not that the pitch and length of the tone is not specified in this routine, and therefore it is not suitable for making music.

GOSUB 260:
This gives a random number in the variable RV. The number is always smaller than 1 and larger than, or equal to, 0. It is a useful routine in statistical programs or in games.

GOSUB 270:
This tidies up the variable space and reports how much memory space is still available. The variables are not erased! The number of free bytes over is placed in the variable FR.

GOSUB 300:
This creates a string SR$ using the value of the variable SR. This string has no spaces at either the beginning or the end of the number, in contrast to the BASIC statement STR$( ). In some BASIC dialects it does contain spaces, so the statement STR$( ) is thus forbidden in BASICODE-2.

GOSUB 310:
This routine creates a string SR$ which is determined by the variables CT, CN and SR. SR$ is equivalent in value to the variable SR and is always in fixed-point notation. The total length of SR$ is thus CT characters, of which CN characters come after the decimal point. If the number does not fit into the given form, then SR$ will consist of CT asterisks. IF necessary, SR will be rounded off. The variables CT, CN and SR are not changed by calling this routine. Here are a few examples:
CT=7: CN=3: SR=2/3: GOSUB 310 gives SR$ as "0.667"
CT=8: CN=5: SR=-1.1E-3: GOSUB 310 gives SR$ as "-0.00110"
CT=3: CN=0: SR=23.6: GOSUB 310 gives SR$ as "24"
CT=3: CN=1: SR=100: GOSUB 310 gives SR$ as "***"

GOSUB 350:
Prints SR$ on the printer, but does not close that particular line. Thus you can print more than once per line using this particular subroutine. But remember that not all users have a printer and so try to include a choice in your program between using the printer or the screen display.

GOSUB 360:
Closes the line on the printer and begins with a new line.

4. Variables

There are a few restrictions governing the use of variables in BASICODE-2 programming. This is necessary to make the exchange between different brands as simple as possible.

1. Numeric variables are real and single precision. Do not count on precision greater than 6 places of decimal.
2. Names for variables should be a maximum of two characters long. The first character must be a letter, the second character (if used) can be either a letter or a number. The names of the variables should be written using BLOCK CAPITALS. Small letters are not allowed. In the case of string variables, the name is always followed by a $. All other characters, such as !,#, or % are forbidden.
3. Logic variables are those which are "true" or "false". You are not allowed to use the numerical value of the logic variables. This is because in some cases the "true" is interpreted as +1, in other computers as ‑1. The result can only be used in an IF…THEN construction (i.e. A=3* (B=1) is not allowed).
4. Before a variable is used, it must be given a value. Do not assume that a variable is automatically fiven a zero value at the start of the program.
5. The maximum string variable length is 255 characters.
6. Names of variables may not begin with the letter O. These are reserved for use within the BASICODE-2 standard routines.
7. The following variables are excluded: AS; AT; FN; GR; IF; PI; ST; TI; TI$; TO.
8. For communication with the BASICODE-2 subroutines use is made of the following variables: HO; VE; FR; SR; CN; CT; RV; IN$; SR$.

5. BASIC statements and operators

ABS	INPUT	RESTORE
AND	INT	RETURN
ASC	LEFT$	RIGHT$
ATN	LEN	RUN
CHR$	LET	SIGN
COS	LOG	SIN
DATA	MID$	SQR
DIM	NEXT	STEP
END	NOT	STOP
EXP	ON	TAB
FOR	OR	TAN
GOSUB	PRINT	THEN
GOTO	READ	TO
IF	REM	VAL
+	^	<>
-	=	<=
*	<	>=
/	>

Above we have listed the BASIC commands and operators, most of which can be used without any problems in BASICODE-2 programs. We have no intention at this point to examine in full each of the commands and operators. Many books have already been written on the subject. However we have decided to give a short summary since there are a few restrictions on certain BASIC commands in BASICODE-2.

BASIC commands and their meaning

ABS	Gives the absolute value of the stated variable. For example: A=10:B=ABS(A) B is now=10 A=-20:B=ABS(A) B is now=20 A=-1:B=ABS(A-5) B is now=6
AND	Logic AND, can only be used for logic variables. The result is a logical result. Use brackets to show clearly the order in which the work is to be done. Examples: IF (A=5) AND (B=0) THEN …. Q=(A-5) AND (B=0): IF Q THEN….
ASC	This gives the ASCII value of the first character of the given string. Examples: A$="A":B=ASC(A$) B is now=65 A$="BEER":B=ASC(A$) B is now=66
ATN	Gives the arctangent in radians of the given variable. For example: PRINT ATN(1) 0.785398 PRINT ATN(-1) -0.785398
CHR$	This gives a character with the same ASCII value as the given variable. The variable can be anywhere between 32 up to and including 127. Be very careful with values less than 32, since control characters on different brands of computers vary. Only the RETURN key always has the same value, ASCII code 13. In addition not all computers recognise lower case letters. So be careful with ASCII codes larger than 96. For example: A$=CHR$(66) A$ now contains the letter B
COS	This gives the cosine of the given angle in radians. For example: PRINT COS(1) .540302
DATA	After this term will follow numbers and/or strings until the end of the line, which can be read using READ. On a DATA line there should be no other statements, such as REM. The elements should be separated by a comma. String variables must be placed between quotation marks. For example: DATA 100,200,"HELLO","BASICODE",4,6,89
DIM	This statement is used to dimension arrays. An array can only be dimensioned once in a program, and before it is used. The maximum number of dimensions is two, whilst the maximum number of elements is limited by the size of the memory. One DIM statement can be used for more than one array. But there are two points to note: In some computers arrays up to 10 elements do not have to be dimensioned. In BASICODE-2 programs, an array must always be dimensioned. The element with number 0 is also allowed, so A(0) and AD$(0,0) do exist. For example: DIM A$(12], HD(100,100), MP(1000)
END	Used to indicate the end of a program. Do not just let a program stop. Always finish with an END statement.
EXP	Raises the number e (=2.71828…) to a specified power. For example: PRINT EXP(2) 7.38906
FOR…TO…STEP…NEXT…	Program loop construction. The loop will be used at least once. STEP can be left out, in which case the step is automatically 1. NEXT must only be followed by a single variable. For example: FOR X=10 TO 100 Program in loop NEXT X FOR C=A TO B STEP -3 Program in loop NEXT C FOR I=1 TO 10:FOR J=1 TO 5 Program in loop NEXT J:NEXT I Note: don't jump out of a FOR-NEXT loop before it has ended. A way to end the loop is by raising the variable to exceed the end point.
GOSUB	Used to call a subroutine and indicated by the line number following the statement. For example: GOSUB 100. Note, though, that A=100:GOSUB A is not allowed.
GOTO	Indicates a jump to a given line number. For example: GOTO 1500 Note, though, that A=1500:GOTO A is not allowed.
IF…THEN	Conditional split, for between IF and THEN will be logical variables or logical comparisons. If the logic is "true" then the process continues through to statements after THEN. If not, then the computer simply moves to the next line. A line number may be given after THEN, from which the program should continue. Note that ELSE is forbidden in BASICODE-2. For example: IF A=3 THEN B=0: C=5 IF A>3 THEN 1500 C=(A>3):IF C THEN GOSUB 100 Note: Use IF…THEN 2000 and not: IF…GOTO 2000. Use IF…THEN GOSUB 2000 and not: IF…GOSUB 2000
INPUT	Asks the user to input either a number or a string variable. A string may not consist of either commas or colons. If commas or colons are needed, then it is better to make use of subroutine 210. A prompt string is not allowed, and neither is more than one variable after an INPUT. Most BASICs print a question mark on the screen to show that input is required. In some computers, when the RETURN key is pressed, the line from the last cursor point to the end of the line is erased. Examples: PRINT "WHAT'S YOUR NAME": INPUT N$ PRINT "KEY VALUE IN": INPUT A: INPUT B But note!! INPUT "YOUR NAME";A$ is forbidden.
INT	Gives the pargest who number (integer) less than or equal to the given variable. For example: A=2.1:B=INT(A) B is now=2 B=INT(‑1.5) B is now=-2
LEFT$	Used to select a number of characters from a given string starting with the character farthest to the left. You may select a minimum of 1 character up to the maximum number of characters in the string. For example: A$=LEFT$("BASICODE",5) A$ now consists of "BASIC". But note that C$= LEFT$("BASICODE",0) is not allowed.
LEN	Reports the length of a given string. For example: A$="BASICODE": A=LEN(A$) A is thus 8 A$="": A=LEN(A$) A is thus 0
LET	The variable name left of the equal sign is assigned the value of the strong or expression to the right of the equal sign. It is not really necessary, since LET A=5 is the same as A=5.
LOG	Calculates the natural log of the given variable or expression. For example: PRINT LOG(1) 0 PRINT LOG(10) 2.302585
MID$	Takes a number of characters from a string. MID$(A$,X,Y) gives Y characters from A$, beginning with the Xth character. Note that the first character is number 1, so X=0 or Y=0 is forbidden. For example: A$="THIS IS BASICODE" B$=MID$(A$,9,8) B$ now consists of "BASICODE"
NEXT	Closing statement for a program loop (see FOR). A NEXT statement must always be followed by a variable. Examples are given under FOR.
NOT	Logic negation, only usable on logic variables (see also AND). For example: A=5: B=NOT(A=6) B is "true" A=(5=5):B=NOT A B is "false"
ON…GOSUB… ON…GOTO…	Makes a jump to either a subroutine or a program line. After ON follows an expression or variable. After GOSUB or GOTO follows a series of line numbers. The expression or variable should be a whole number and determines which line number is to be chosen. You can think of the line numbers as having numbers: if the variable is 1 then the first line number is chosen, if the variable is 2 then the second line number is chosen, etc. But the variable cannot be greater than the number of line numbers given. For example: ON K GOTO 1100,3400,1500 K has to be 1, 2, or 3 ON (K-5) GOSUB 600,700,300 K has to be 6, 7, or 8
OR	Logic OR can only be used with logic variables (see AND). For example: IF A=5 OR B<3 THEN… C=(A-5) OR (B<3):IF C THEN…
PRINT	Prints a variable or a string on the screen beginning at the present cursor position. More than one variable in a PRINT statement must be separated by semi-colons. If it is not desired that the computer should automatically continue with the next line then the end of the instruction must be finished off with a semi-colon. Some computers print one or more spaces before and/or after the number(s) being printed. If you do not want this, then use subroutine 300 or 310. For example: A=5:A$="HELLO":PRINT A:A$ 5HELLO PRINT "HELLO":PRINT "THERE" HELLO THERE CN=3:CT=5:SR=5:GOSUB 310:PRINT "FIVE=";SR$ FIVE=5.000
READ	Reads the elements after the DATA statements and gives them to variable(s) which follow the READ statement. More than one variable after a READ statement should be separated by commas. After the RUN command, the computer will read the DATA starting with the lowest line number. All data on that line will be read before continuing with any other DATA lines. But note: A numeric variable must read only numbers, a string variable can only read strings. For example: DATA 1,"COMPUTER",3 READ A,A$:READ B or READ A:READ A$:READ B or READ A,A$,B
REM	This is used for adding REMarks in the program to help other users understand what you are doing. Anything after a REM statement until the end of the line is ignored in BASIC by the computer. But do not use a colon after the REM statement as this gives problems with some computers.
RESTORE	This statement resets READ-ing from the first DATA statement in the program. But note that you may not give a line number after a RESTORE statement.
RETURN	Is used to indicate the end of a subroutine. The computer then jumps back to the line after the respective GOSUB statement that started the subroutine sequence. A subroutine should always be closed with a RETURN statement.
RIGHT$	Gives a number of characters of a given string, ending with the last character. The minimum number that can be asked is 1, the maximum being the length of the string. For example: A$="BASICODE":B$=RIGHT$(A$,4) B$ now consists of "CODE". But note that A$="PROTOCOL":A=0:B$=RIGHT$(A$,A) is not allowed because A=0.
RUN	Starts the program afresh, while all variables are erased. Note that a line number after RUN is not allowed. For example: IF (A$="J") OR (A$="j") THEN RUN Note that RUN 100 is forbidden.
SIN	Gives the sine of a variable which should be given in radians. See COS for further details.
SGN	Is used to give the sign of a variable, i.e. -1 if the variable is negative, 0 if the variable is zero, and +1 if the variable is positive. For example: A=5:B=SGN(A) B is now 1 A=-.001:B=SGN(A) B is now -1
SQR	Calculates the square root of a variable or expression, which cannot be negative. For example: A=SQR(2*50) A is now 10
STEP	Sets the step size in a loop. See FOR.
STOP	Stops the program, but retains the possibility of going further, keeping the same variables.
TAB	Is used in PRINT statements to move the cursor to a specific point on the screen. You can only use TAB to move the cursor further on a line, and depending on the computer, either spaces will be printed or whatever is on the line will be kept. Note that TAB(0) is not allowed. Although most computers start counting at 0, there are those that start at 1. So for this reason it is better to use subroutine 110. For example: PRINT "A";TAB(5);"B";TAB(10);"C" gives: A      B           C on some computers and: A     B          C on others.
TAN	Calculates the tangent of a given angle in radians. See COS.
THEN	See IF.
TO	See FOR.
VAL	Gives the numeric VALue of a string. But if the string is not purely numeric, the result is not the same on all computers. For example: A$="1.4E6":A=VAL(A$) A is now=1.4E6 A$="12D":A=VAL(A$) A is now undetermined, A=12 or A=0 being possible.
	Summary
	Now follows a short summary of the operators allowed in BASICODE-2.
+	In the case of numbers of variables this operator adds two numbers or variables together. In the case of strings, two are coupled to each other. For example: B=1:A=B+9 B is now=10 A$="BAS":B$="ICO":C$="DE.":D$=A$+B$+C$ D$ therefore is "BASICODE.".
-	Subtracts two numbers or variables from each other. For example: A=10-3-4 A is now=3
*	Multiplies two numbers or variables together. For example: A=5:B=3*2*A B is now=30
/	Divides two numbers or variables. For example: A=5:B=100/A/2 B is now=10
△	Raises a number or variable to a specified power. For example: A=2:B=16:C=A△B C is now=65536
=	Logic operator: indicates equality between the two expressions on either side of it. See also AND. Or: the variable name to the left of the equal sign is assigned the value of the string or expression to the right of the equal sign. Examples: A=(5=6) A is "false" A=4*6 A is now=24 A$="HELLO" A$ now contains "HELLO"
<	Compares two numbers or expressions and checks whether the one to the left of the operator is less in value than the one to the right. The result is therefore a logic variable. If strings are being compared, then the string to the left of the operator is checked to see if it comes earlier in alpha-numeric order than the string to the right. You can use this operator for alphabetical sorting. For example: A=5:B=(A<7) B is "true" A$="HO":B$="HA":A=(A$ A is thus "false"
>	Identical to < except that the test is now "greater than" or "later" in alpha-numeric order.
<>	Checks to see whether two variables or expressions are "un-equal". The result is a logical value. For example: A=(6<>7) A is "true" A$="HO":B$="H":A=(A$<>B$) A is therefore "true" IF A<>5 THEN…
<=	Less than or equal to. For the function of this operator see <, but substitute "less than or equal to" in place of "less than".
>=	Greater than or equal to. For the function of this operator see >, but substitute "greater than or equal to" in place of "greater than".
	Note: When using the last three operators the order of the two characters is important. For example: A=>5 is wrong.
	We trust the BASICODE-2 protocol is explained clearly enough, and look forward to your program contributions. For details of how to contribute, see Chapter One.
	Jochem Herrmann