usage.dat

# MESS Driver Usage Data File
# Maintained by Stefano Priore
# Send corrections/submissions to: stefano.priore@inwind.it

# This file contains detailed documentation for drivers supported by MESS. A typical entry contains a list of keywords supported by the built-in language (usually a BASIC dialect).
# You'll also find a list of control characters, useful to know keyboard combos and, when needed, some advices about peculiarities of the system.
# The info provided is intended to help anyone who wants to effectively program the machine supported by MESS, but even the ones who simply want to load a game and play will find satisfaction here! ;))


$info=oric1
$bio
Command Line Editing
--------------------

Maximum length of a BASIC program line is 78 characters. To delete a line, type its number and RETURN.

DEL - Deletes the character on cursor's left
CTRL X - Aborts the line currently edited
CTRL A - Copies the character under the cursor into an input buffer. Any other character you type is appended to the end of the buffer. When RETURN is pressed, the input buffer is interpreted as if you had typed all the characters it contains.

Control Characters
------------------

CTRL C - Breaks execution
CTRL D - Toggles auto double height on/off
CTRL F - Toggles keyclick on/off
CTRL I - Toggles protected column (far left) on/off
CTRL J - Line feed
CTRL L - Clears screen
CTRL M - Carriage return
CTRL N - Clears row
CTRL P - Toggles printer on/off
CTRL Q - Toggles cursor on/off
CTRL S - Toggles V.D.U. on/off
CTRL T - Toggles CAPS LOCK on/off

To use in PRINT statements use PRINT CHR$(x) where 'x' is a number, A=1, B=2, etc.

Screen Attributes
-----------------

ESC @ - Foreground black
ESC A - Foreground red
ESC B - Foreground green
ESC C - Foreground yellow
ESC D - Foreground blue
ESC E - Foreground magenta
ESC F - Foreground cyan
ESC G - Foreground white
ESC H - Single height, steady, standard charset
ESC I - Single height, steady, alternate charset
ESC J - Double height, steady, standard charset
ESC K - Double height, steady, alternate charset
ESC L - Single height, flashing, standard charset
ESC M - Single height, flashing, alternate charset
ESC N - Double height, flashing, standard charset
ESC O - Double height, flashing, alternate charset
ESC P - Background black
ESC Q - Background red
ESC R - Background green
ESC S - Background yellow
ESC T - Background blue
ESC U - Background magenta
ESC V - Background cyan
ESC W - Background white
ESC X - Text 60 Hz
ESC Y - Text 60 Hz
ESC Z - Text 50 Hz
ESC { - Text 50 Hz
ESC | - Hires 60 Hz
ESC } - Hires 60 Hz
ESC ~ - Hires 50 Hz
ESC DEL - Hires 50 Hz

To use in PRINT statements use PRINT CHR$(27);"X" where 'X' is a letter.

Color Table
-----------

0 = Black
1 = Red
2 = Green
3 = Yellow
4 = Blue
5 = Magenta
6 = Cyan
7 = White

Keywords
--------

NOTE: Variables' names can be of any length, but only the first two characters are significative. Oric 1 supports the following data types:

Integer - ranges from -32768 to +32767. Integer variables' names terminate with '%'.
Floating point - ranges from +/-2.93874*10^-39 to +/-1.70141*10^38.
String - length ranges from 0 to 255. String variables' names terminate with '$'.

Unless explicitly noted, any command or function can accept constants, variables and expressions as a parameter.
Optional parameters are enclosed in <>, the character "|" separates a list of accepted parameters.

Commands
--------

!

! can be defined as a command that doesn't already exist in BASIC. The routine must be written in machine code and its beginning address must be DOKEd at address #2F5. It must also parse the parameters on its own.

CALL addr

0 <= addr <= 65535

Transfers control to machine code routine starting at address 'addr'. Returns to BASIC on reaching an RTS instruction.

CHAR chr,set,fb

32 <= chr <= 127 : ASCII code of the character.
0 <= set <= 1 : 0 = standard character set, 1 = alternate character set
0 <= fb <= 3 : 0 = background color, 1 = foreground color, 2 = inverse mode, 3 = does nothing

Draws a character at current cursor position - top left of the character is at cursor position.

CIRCLE r,fb

1 <= r <= 119
0 <= fb <= 3 : 0 = background color, 1 = foreground color, 2 = inverse mode, 3 = does nothing

Draws a circle centered at current cursor position with radius 'r'. No part of the circle may leave the screen.

CLEAR

Sets variables to their empty value.

CLS

Clears screen display.

CLOAD"<filename>"<,S><,A start,E end>

filename : a string whose length ranges from 0 to 17
0 <= start <= 65535
0 <= end <= 65535

Loads a file called 'filename' from tape. ',S' must be specified if the file has been CSAVEd with the same option; ',A' and ',E' set starting and ending address of a memory block.

CONT

Continues execution of a program after break.

CURMOV x,y,fb

-239 <= x <= 239
-199 <= y <= 199

Sets the cursor to a new position. 'x' and 'y' are relative to old position. Final cursor position must be between (0,0) and (239,199).

CURSET x,y,fb

0 <= x <= 239
0 <= y <= 199
0 <= fb <= 3 : 0 = background color, 1 = foreground color, 2 = inverse mode, 3 = does nothing

Sets the cursor to absolute 'x' and 'y' position.

CSAVE"<filename>"<,S><,AUTO><,A start,E end>

filename : a string whose length ranges from 0 to 17
0 <= start <= 65535
0 <= end <= 65535

Saves a file called 'filename' to tape. The file is saved at 1200 baud, unless ',S' option is used, which slows the output to 300 baud. Memory blocks can be saved specifying the start and end address.

DATA datalist

Stores a list of data that can be READ into variables. 'datalist' is a comma-separated list of numeric and/or string constants.

DEF FN a(x)=expr

expr : a valid numeric expression

Defines numeric functions.

DEF USR = addr

0 <= addr <= 65535

Defines start of USR routine.

DIM var1(n1<,n2,...>)<,var2(...)...>

var1, var2,... : a valid variable name
n1, n2,... >= 1

Dimension arrays. Arrays can have up to 12 dimensions. Arrays used without declaration are predimensioned to 10.

DOKE addr,val

0 <= addr <= 65534
0 <= val <= 65535

Stores ('val' DIV 256) at address 'addr'+1 and ('val' MOD 256) at 'addr'.

DRAW x,y,fb

-239 <= x <= 239
-199 <= y <= 199
0 <= fb <= 3 : 0 = background color, 1 = foreground color, 2 = inverse mode, 3 = does nothing

Draws a vector from current cursor to current cursor plus 'x' and 'y'. Final cursor position must be between (0,0) and (239,199).

END

Ends program.

EXPLODE

Produces predefined sound.

FILL row,cell,n

0 <= row <= 199
0 <= cell <= 39
0 <= n <= 127

Fills 'cell' character cells by 'row' rows with 'n' value.

FOR var=start TO end <STEP incr> ... NEXT <var>

Creates a loop to repeat all program lines between FOR and NEXT. STEP determines the incremental size; if omitted default is 1.

GET x$

Strobes the keyboard and waits until a key is pressed, which is stored in 'x$'.

GOSUB nline

Causes program branch to subroutine beginning at line 'nline'.

GOTO nline

Causes program branch to line 'nline'.

GRAB

Assigns the area in memory from #9800 to #B400 (48K) or from #1800 to #3400 (16K) to user RAM.

HIMEM addr

0 <= addr <= 65535

Lowers top of memory available for BASIC programs.

HIRES

Switches to high resolution mode. Background is set to black, foreground to white, cursor to (0,0). Text lines remain in existing colors.

IF cond THEN ... <ELSE ...>

cond : a valid logical expression

If the expression following IF is true, then executes all instructions between THEN and ELSE. If the expression is false, then executes only the instructions following ELSE.

INK color

0 <= color <= 7

Changes foreground color of whole screen.

INPUT <"text";>var

var : a valid variable name

Stops program execution and wait for an input to be stored in 'var' before continuing.

<LET> var=expr

var : a valid variable name

Assigns 'expr' to 'var'.

LIST <start><-><end>

Lists program lines between 'start' and 'end'.

LLIST <start><-><end>

Like LIST, but output is redirected to printer.

LORES set

0 <= set <= 1 : 0 = standard character set, 1 = alternate character set

Switches to low resolution mode. TEXT screen is set to background black.

LPRINT <printlist>

Like PRINT, but output is redirected to printer.

MUSIC chn,oct,note,vol

1 <= chn <= 3
0 <= oct <= 6
1 <= note <= 12
0 <= vol <= 15

Produces musical notes on channel 'chn'. 'oct' controls the octave of the note and 'vol' the volume as for SOUND command.

'note' = 1 : C
         2 : C#
         3 : D
         4 : D#
         5 : E
         6 : F
         7 : F#
         8 : G
         9 : G#
        10 : A
        11 : A#
        12 : B

NEW

Deletes current program and all variables.

ON expr GOSUB nline1<,nline2,...>

expr : a valid numerical expression >= 1

Branches to subroutine at 'nline'-th line number specified.

ON expr GOTO nline1<,nline2,...>

expr : a valid numerical expression >= 1

Branches to 'nline'-th line number specified.

PAPER color

0 <= color <= 7

Changes background color of whole screen.

PATTERN x

0 <= x <= 255

Sets the pattern register for drawing commands.

PING

Produces predefined sound.

PLAY tone,noise,envmod,envper

0 <= tone <= 7
0 <= noise <= 7
1 <= envmod <= 7
0 <= envper <= 32767

Controls how sound is generated and which channels are enabled.

'tone' = 0 : All channels off
         1 : Channel 1 on
         2 : Channel 2 on
         3 : Channel 1 and 2 on
         4 : Channel 3 on
         5 : Channel 1 and 3 on
         6 : Channel 2 and 3 on
         7 : Channel 1, 2 and 3 on

'noise' controls the routing of the noise channel and fuctions as for 'tone'. 'envmod' controls the envelope shape and 'envper' controls the period.

PLOT x,y,x$

0 <= x <= 38
0 <= y <= 26

Prints a character on the LORES or TEXT screen using 'x' and 'y' coordinates.

POKE addr,val

0 <= addr <= 65535
0 <= val <= 255

Stores 'val' in memory location 'addr'.

POP

Causes one RETURN address to leave the stack of RETURN addresses. The next RETURN encountered after the POP branches to one statement beyond the second most recently executed GOSUB.

PRINT <printlist>

Prints strings, variables and constants to screen. 'printlist' is made of such elements separated by commas or semicolons. A semicolon causes the next element to be printed just after the previous one; a comma causes the element to be printed at the next tabulation stop. Tab stops are at columns 1,6,11,...

PULL

Pulls one address from the stack in REPEAT loops. See POP.

READ var1<,var2,...>

var1<,var2,...> : a valid variable name

Reads next item in DATA list and assigns it to a specified variable.

RELEASE

Assigns area described in GRAB command to HIRES screen.

REM <...>

Allows comments to be put in progam lines. Everything after REM statement is ignored.

REPEAT ... UNTIL cond

cond : a valid logical expression

Creates a loop to repeat all program lines up to UNTIL statement. Tests 'cond' in UNTIL statement: if false, repeats loop; if true continues execution at next program line.

RESTORE

Sets READ pointer to first item on first DATA line.

RETURN

Returns the computer to the statement immediately after the most recent GOSUB.

RUN <nline>

Executes a BASIC program from line 'nline', or from lowest line if 'nline' is not specified. Also clears all variables.

SHOOT

Produces predefined sound.

SOUND chn,per,vol

1 <= chn <= 6
0 <= per <= 65535
0 <= vol <= 15

Produces a sound of period 'per' on channel 'chn'. Channels 4, 5 and 6 are used to mix white noise with channels 1, 2 and 3. When 'vol' is 0, volume level is controlled by the PLAY command.

SPC(x)

0 <= x <= 255

Prints 'x' spaces on the screen. Used in conjunction with PRINT or LPRINT.

STOP

Stops execution of a program and prints "BREAK IN...".

TAB(x)

0 <= x <= 255

Moves PRINT position 'x' places from left of the screen. Used in conjunction with PRINT or LPRINT

TEXT

Switches to text mode.

TROFF

Switches off the trace function.

TRON

Switches on the trace function.

WAIT n

Waits for 'n'*10 milliseconds.

ZAP

Produces predefined sound.

Functions
---------

&(n)

0 <= n <= 65535

& can be defined as a function that doesn't already exist in BASIC. The routine must be written in machine code and its beginning address must be DOKEd at address #2FC.

#hex

0 <= hex <= FFFF

Returns the hexadecimal number 'hex' in decimal form.

ABS(x)

Returns absolute value of 'x'.

ASC(x$)

Returns the ASCII code of the first character of 'x$'.

ATN(x)

Returns arctangent of angle 'x'. 'x' must be in radians.

CHR$(x)

0 <= x <= 255

Returns the ASCII character corresponding to 'x'.

COS(x)

Returns cosine of angle 'x'. 'x' must be in radians.

DEEK(addr)

0 <= addr <= 65534

Returns PEEK('addr')+256*PEEK('addr'+1).

EXP(x)

Returns natural exponential of 'x'.

FALSE

Returns 0.

FNa(x)

a : a valid function name

Returns the result of an user defined function evaluated in 'x'.

FRE(0|"")

Returns the amount of free memory (FRE(0)) or forces garbage collection (FRE("")).

HEX$(x)

0 <= x <= 65535

Returns the decimal number 'x' in hexadecimal form.

INT(x)

Returns largest integer less than or equal to 'x'.

x$=KEY$

Strobes keyboard and continues execution wheter or not a key has been pressed. 'x$' contains value of any key pressed.

LEFT$(x$,n)

n >= 1

Returns the first 'n' characters of 'x$'.

LEN(x$)

Returns the length of 'x$'.

LN(x)

x > 0

Returns natural logarithm of 'x'.

LOG(x)

x > 0

Returns base 10 logarithm of 'x'.

MID$(x$,x<,n>)

x >= 1

Returns a substring of 'x$' starting at position 'x', of length 'n'.

PEEK(addr)

0 <= addr <= 65535

Returns the contents of memory location 'addr'.

PI

Returns 3.14159265.

POINT(x,y)

0 <= x <= 239
0 <= y <= 199

Returns 0 if specified pixel is background and -1 if pixel is foreground.

POS

Returns the current horizontal position of the cursor.

RIGHT$(x$,n)

n >= 1

Returns the last 'n' characters of 'x$'.

RND(x)

Returns a pseudo-random number: if 'x' >= 1, then the number is between 0 and 1. If 'x' = 0, then most recently generated number is returned. if 'x' < 0, then number returned is the same for each 'x'.

SCRN(x,y)

0 <= x <= 38
0 <= y <= 26

Returns the ASCII code for the character at position 'x','y' in LORES and TEXT modes.

SGN(x)

Returns -1 if 'x' is negative, 0 if zero and 1 if positive.

SIN(x)

Returns sine of angle 'x'. 'x' must be in radians.

SQR(x)

x >= 0

returns the square root of 'x'.

STR$(expr)

expr : a valid numerical expression

Converts a numerical expression into a string.

TAN(x)

Returns tangent of angle 'x'. 'x' must be in radians.

TRUE

Returns -1.

USR(x)

Passes 'x' to a machine code subroutine whose starting address is defined by the DEF USR command.

VAL(x$)

Returns the numerical value of string 'x$'.

$end