Home
The Retro Rocket operating system is built of a collection of programs running a dialect of BASIC called Retro Rocket BASIC. This dialect is similar to BBC BASIC. At the top level, once the kernel has mounted the boot file system (usually a CD ROM or a SATA hard drive) it will spawn an instance of /programs/init which contains the statements needed to get any other file systems mounted, and to start rocketsh which accepts user input.
rocketsh allows running of arbitrary BASIC programs, and will search initially under the /programs directory for programs it can run directly.
All included programs below are packaged with the operating system and can be found under the /programs directory.
Displays all ASCII characters between 33 and 127.
Removes a file from the filesystem
Displays the files within a directory in the filesystem
Evaluates some BASIC code
A test program to demonstrate file I/O. Opens itself and dumps out the ASCII values of each character as it reads it.
Demonstrates graphics statements by drawing rectangles, triangles and circles on the screen.
Resolves a hostname
The initialisation script ran on bootup, mounts filesystems and launches rocketsh
Returns IP address information for any online network interfaces
Outputs the ASCII contents of a file, mainly useful for BASIC programs.
Create a new directory in the filesystem
List active processes and their information
Remove a directory from the filesystem
The interactive shell used to execute commands and run programs. Launched by init.
A graphics demonstration program which displays a gradient filled sine wave on screen
A socket demonstration program which connects to a remote server and outputs the contents of a HTTP request
A generic test program which demonstrates some trivial functionality of the Retro Rocket BASIC language such as procedures, functions, and loops.
Programs in Retro Rocket are simialar in strucuture to a BBC BASIC program. Each line is numbered, and each number must be greater than the line number before it. It is possible to have gaps in the numbering.
The program will execute moving from one line to the next, and each line must have at least one statement, and any parameters required for that statement (see the statements section of this page).
Variables may be declared, of the three types listed below. For each of these variables, they may remain local to the current program or be inherited by other programs ran by the current program.
For an example of programs in the operating system see the /os/programs directory.
Line numbering in Retro Rocket BASIC is an all-or-nothing affair. Retro Rocket will examine your program when it loads it, and if the first character is a digit, the program is assumed to be line numbered. The line numbers you specify will be used without any adjustment, this will effectively enable use of GOTO and GOSUB in your program.
If the first character of your program is not a digit, the program is assumed to not have line numbers, and the interpreter will automatically number the lines for you starting at 10 with increments of 10. It is important to note that in this case, although you could still use GOTO and GOSUB it would be much more difficult in this scenario as you have to figure out the line numbers using your editor. As GOTO and GOSUB are discouraged anyway, and there are better alternatives such as FOR, REPEAT, PROC and FN, there are very few situations where GOTO or GOSUB are required in your program.
Data within a program you wish to work with should be declared and stored as variables. Retro Rocket BASIC supports three types of scalar variable, plus array types:
Integer variables are represented by any variable without a suffix, e.g. A or MYVAR. Integer variables are 64 bit signed values.
Real variables are represented by a variable with the suffix #, e.g. B# or MYVAR#. Real variables are 64 bit double precision IEEE floating point values.
String variables are represented by a variable with the suffix $, e.g. C$ or MYVAR$. String variables are null-terminated C style sequences of 8 bit ASCII characters.
Arrays of variables are represented by a variable (with a valid suffix or no suffix, as above) and suffixed further by an array subscript, e.g. an index into the array, zero based, and surrounded by brackets. For example to access array element 50 from an array of strings you would access it in the form myarray$(50). Arrays must be allocated by the DIM statement, and can be dynamically extended using REDIM.
As a special case, it is possible to initialise all elements in an array to the same value by not specifying the subscript. For example arrayname=0 will initialised all array elements to zero and array$="foo" will set all elements in a string array to "foo".
-
TRUE- Always contains the numeric value1 -
FALSE- Always contains the numeric value0 -
PID- Contains the process ID of the current process -
ARG$- Contains the command line passed to the current process -
PROGRAM$- Contains the fully qualified pathname to the current process -
PI#- Contains the constant π, e.g.3.141592653589793238
In the documentation below, the following parameter types are used:
-
statementAnother single statement, and its parameters where applicable. -
integer-expressionA mathematical expression or simple value that evaluates to an integer value, e.g.7orA + 6. -
real-expressionA mathematical expression or simple value that evaluates to a real value, e.g.7.5orA# + 2.8 + B. -
string-expressionA string expression or simple constant value that evaluates to a string value, e.g."hello"or"hi " + A$ -
expressionAny of the three parameter types above, where the value should match whatever is applicable, e.g. string-expression for a string variable, etc. -
string-variableA string variable name, e.g.mystr$ -
integer-variableAn integer variable name, e.g.val -
real-varaibleA real varaible name, e.g.radius# -
variable-nameAny valid variable name from the types shown above -
printableA list of one or more of all of the above choices, separated by,or;, and optionally terminated by a;. If the list is not terminated by a;symbol, a line feed is added to the end of the output created. When separating values, a,causes the values to be separated by tabulation, otherwise there is no spacing between the values.
LET variable-name = expressionvariable-name = expressionDeclares a new variable. This keyword is completely optional, and a variable may be declared or modified with or without it.
PRINT printableOutputs text to the screen at the current cursor position.
IF expression THEN statement ELSE statementExecutes statements if an expression evaluates to true
DIM variable-name,integer-expressionDeclare an array of variables of size defined by the expression. The type of variables stored in the array is determined by the type of variable-name. Arrays are zero-indexed and range checked, so the lowest value you may store in an array is 0 and the highest is integer-expression - 1.
REDIM variable-name,integer-expressionExtend or reduce the size of an array of variables to the new size defined by the expression. If you shrink the array to a size less than it's current size, any elements between the old maximum and new maximum are permanently lost. The type of variables stored in the array is determined by the type of variable-name. Arrays are zero-indexed and range checked, so the lowest value you may store in an array is 0 and the highest is integer-expression - 1. Calling REDIM with the existing size (e.g. not changing it's capacity) is an non-op.
CHAIN string-expressionStarts a new program, pausing the current program until the new program has finished. Any variables marked as GLOBAL will be passed to the child program. Once the new program has finished, the current program will continue from the line below the CHAIN statement.
BACKGROUND integer-expressionSets the current text background colour to the matching integer-expression. The background colours are VGA colours, set via ANSI escape codes.
FOR numeric-variable = numeric-expression TO numeric-expression
FOR numeric-variable = numeric-expression TO numeric-expression STEP numeric-expression
NEXTLoop until the variable reaches the end condition. If the STEP expression evaluates to a negative value, then the variable will decrement to the lower value.
FOR numeric-variable = numeric-expression TO numeric-expression
NEXTLoop until the variable reaches the end condition.
GOTO numeric-constantJump to the specified line number. Only constant numeric values are supported for GOTO.
GOSUB numeric-constantJump to the specified line number, returning to the statement below the GOSUB when RETURN is encountered. Only constant numeric values are supported for GOSUB.
RETURNWhilst in a PROC or GOSUB, this will return back to where the procedure or subroutine was called. Outside of this context, executing a RETURN is an error condition.
CALL numeric-addressNot currently implemented. Will call a native routine at the given memory address.
INPUT variablePause the program waiting for user input, which will be echoed to the terminal. The input will then be placed in a variable. String, integer and real variables are accepted. Invalid input (e.g. text when expecting a number) will cause the input value to be zero.
COLOR 14Change the foreground colour to a VGA colour code. The default colour of the terminal is 7, e.g. white.
EVAL string-expressionEvaluate a BASIC expression in the context of the current program. On error, ERROR$ is set to the last error message, ERROR is set to 1 and the error is displayed in red on the terminal.
CLOSE numeric-variableClose a currently open file handle and flush any pending writes.
DEF FN name(variable-name,...)
DEF PROC name(variable-name,...)Define a new function or procedure. The parameter list is optional. A function is ended by starting a line with an = symbol, to indicate the return value, whereas a procedure returns no value, and its end is indicated by the RETURN statement.
PROCname(varaible-name,...)Call a procedure. The variables passed must match the type and number specified where the procedure was defined. When complete, the procedure will return to the statement after where it was called.
FNname(varaible-name,...) (as part of an expression)Call a function. The variables passed, and the return type must match the type and number specified where the procedure was defined. To define a function that returns a real number, the name must end with #, and to return a string, the function name must end with $. When complete, the function will return the value into the expression where it was called.
ENDEnd execution of the current program, returning control to whichever program started it.
REM any-textAdd a remark (comment) to a program. The entire line after the REM statement is ignored.
GLOBAL variable-name = expressionDeclare a variable, but mark it as GLOBAL, meaning its value is copied (not referenced) to any programs this program creates. This is used to pass command line parameters to your program by rocketsh.
SOCKREAD integer-variable, variableRead data from an open TCP socket represented by the integer variable, into the second variable which may be a string, integer or real value. The scemantics of this statement operate identically to INPUT, as in this call blocks your program until enough data is read from the socket to satisfy a valid value.
SOCKWRITE integer-variable, printableWrite data to an open TCP socket represented by the integer variable, from the printable content specified by printable. The scemantics are identical to the PRINT function.
CONNECT integer-variable, string-expression, integer-expressionConnect to a TCP socket. The first parameter is an integer variable (if it does not exist, it will be created) to receive a handle to the connection for use with SOCKREAD, SOCKWRITE and SOCKCLOSE. The second parameter is a string representation of the IP address, to resolve a hostname to an IP address string use the DNS$ function. The final parameter is the port number to connect to.
On failure to connect, the integer variable will be less than zero.
``basic SOCKCLOSE integer-variable
Close a TCP socket. The parameter should be an integer variable containing the handle allocated by the `CONNECT` statement.
#### CLS
```basic
CLS
Clear the screen and home the cursor to the top left of the screen.
GCOL integer-expressionChange the current graphics colour. The graphics colour is represented as a 32 bit value where each 8 bit segment refers to one of alpha, red, green or blue in that order. You can use the RGB() function to define these values in a user friendly way from three integer values.
LINE integer-expression, integer-expression, integer-expression, integer-expressionDraw a line from the first two X,Y coordinates to the last two X,Y coordinates using the current graphics colour (GCOL).
TRIANGLE integer-expression, integer-expression, integer-expression, integer-expression, integer-expression, integer-expressionDraw a filled triangle between the three sets of X,Y coordinates using the current graphics colour (GCOL).
RECTANGLE integer-expression, integer-expression, integer-expression, integer-expressionDraw a filled horizonally aligned rectangle between the two sets of X,Y coordinates using the current graphics colour (GCOL).
CIRCLE integer-expression, integer-expression, integer-expressionDraw a filled circle with its centre at the X,Y coordinates of the first two paramters with radius of the final parameter using the current graphics colour (GCOL).
POINT integer-expression, integer-expressionDraw a single pixel point at thee X,Y coordinates of the two paramters using the current graphics colour (GCOL).
CURSOR integer-expression,integer-expressionMove the text cursor to the coordinates provided by the given integer values.
REPEAT
...
UNTIL expressionRepeats a block of code until the expression evaluates to true. The REPEAT must match up with an UNTIL.
REPEAT
...
UNTIL expressionRepeats a block of code until the expression evaluates to true. The UNTIL must match up with a REPEAT.
WRITE integer-variable, printableWrite data to an open file represented by the integer variable, from the printable content specified by printable. The scemantics are identical to the PRINT function.
ABS(numeric-expression)Return the absolute value of a numeric expression, e.g. negative values are made positive.
LEN(string-expression)Returns the length in ASCII characters of a string expression
OPENIN(string-expression)Opens a file for input (reading), returning an integer file handle used for READ and CLOSE.
OPENOUT(string-expression)Opens a file for output (writing), returning an integer file handle used for WRITE and CLOSE.
OPENUP(string-expression)Opens a file for input and output (reading and writing), returning an integer file handle used for READ, WRITE and CLOSE.
EOF(integer-variable)Returns true if the end of the file has been reached, false if otherwise.
READ(integer-variable)Returns a single byte value read from a file.
INSTR(string-expression, string-expression)Returns TRUE if the first expression is contained in the second expression.
ASC(string-expression)Returns the ASCII value of the first character of the string expression.
GETNAMECOUNT(string-expression)Returns the number of files in the directory represented by the string expression.
GETSIZE(string-expression, integer-expression)Returns the size of a file in a directory. The string expression is a directory path, and the integer expression is an index between 0 and GETNAMECOUNT() - 1 for the same directory.
GETPROCCOUNTReturns the number of running processes.
GETPROCID(integer-expression)Returns the process ID for a running process, the integer expression is an index between 0 and GETPROCCOUNT - 1
GETPROCPARENT(integer-expression)Returns the parent process ID for a running process, the integer expression is an index between 0 and GETPROCCOUNT - 1
GETPROCCPUID(integer-expression)Returns the process CPU ID for a running process, the integer expression is an index between 0 and GETPROCCOUNT - 1
RGB(integer-expression, integer-expression, integer-expression)Returns an RGB value from three integer values between 0 and 255.
TERMWIDTHReturns the width of the current terminal in characters
TERMHEIGHTReturns the height of the current terminal in characters
CURRENTXReturns the current X text cursor position on the terminal in character cells
CURRENTYReturns the current Y text cursor position on the terminal in character cells
MEMORYReturns the total memory, used and free, for all BASIC programs and the operating system in bytes
MEMUSEDReturns the total memory used by all BASIC programs and the operating system in bytes
MEMFREE
Returns the total free memory for all BASIC programs and the operating system in bytes
SIN(real-expression)Returns the sine of the provided expression
COS(real-expression)Returns the cosine of the provided expression
TAN(real-expression)Returns the tangent of the provided expression
POW(real-expression, real-expression)Raises the first expression to the power of the second expression and returns the result
NETINFO$(string-expression)Returns network confdiguration settings. The string-expression should be one of:
-
ip- Returns the current IP address -
gw- Returns the gateway address -
mask- Returns the network mask -
dns- Returns the DNS server address
DNS$(string-expression)Resolves a hostname, returning the resolved version as an IP string.
LEFT$(string-expression, integer-expression)Returns the leftmost integer-expression characters of string-expression.
MID$(string-expression, integer-expression, integer-expression)Returns a substring of string-expression, starting at the first integer parameter offset and extending for a length of the second parameter.
CHR$(integer-expression)Returns the ASCII character represented by the integer expression
READ$(integer-expression)Read a full line from a file until the next carriage return or end of file, using the file handle specified by the integer-expression.
GETNAME$(string-expression, integer-expression)Returns the file name for an entry in a directory, the integer expression is an index between 0 and GETNAMECOUNT - 1
GETPROCNAME$(integer-expression)Returns the process name for a running process, the integer expression is an index between 0 and GETPROCCOUNT - 1
RAMDISK$(string-expression)Create a ramdisk device with the content of a separate block device who's name is in the string-expression. Returns the name of the new block device.
RAMDISK(integer-expression, integer-expression)Create a ramdisk device of X blocks each block being Y bytes, where X and Y are the two integer-expression values. Note that the block device will be unformatted, and cannot be immediately mounted to a mountpoint. Returns the name of the new block device.