MMBasic DOS Version Manual
MMBasic DOS Version Manual
User Manual
MMBasic Ver 5.05.02
The compiled object code (the MMBasic.exe file) is free software: you can use or redistribute it as you please.
The source code is available via subscription (free of charge) to individuals for personal use or under a
negotiated license for commercial use. In both cases go to http://mmbasic.com for details.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
This manual is distributed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Australia
license (CC BY-NC-SA 3.0)
Big thanks to the members of the Back Shed forum who beta tested this version of MMBasic and found many,
many bugs. Thanks guys.
Contents
Introduction............................................................................................................................. 3
Serial Communications........................................................................................................... 7
File Input/Output..................................................................................................................... 8
Full Screen Editor ................................................................................................................. 11
MMBasic Characteristics ...................................................................................................... 13
Predefined Read Only Variables .......................................................................................... 15
Commands ........................................................................................................................... 16
Functions.............................................................................................................................. 27
Obsolete Commands and Functions .................................................................................... 31
Limitations
If you are familiar with the Micromite please note that this version does not attempt to emulate the full
Micromite environment. Due to limitations of the DOS window this version does not support, graphics,
specialised input/output, etc.
You can start MMBasic running a BASIC program by including the program's file name on the Windows
command line.
Developing Programs
To prepare a BASIC program you should use a Windows text editor like Notepad to edit your program as a file
within Windows. Do not use a word processing editor like WordPad or Word as they will insert formatting
commands in the file causing errors when run in MMBasic.
To run the program you have four choices:
Use RUN "filename" at the MMBasic command prompt (the greater than symbol '>'). Note that the
double quotes are required (for example, RUN "MYFILE.BAS")
Drag and drop the BASIC program file onto the MMBasic icon in Windows – this will cause Windows
to start up MMBasic which will automatically run your program.
Environment Variables
Windows environment variables can be used to change some characteristics of MMBasic.
MMDIR can be set to the default directory that MMBasic is to start running in. For example:
SET MMDIR=C:\Temp
will start MMBasic running in the directory C:\Temp. Without this the starting directory will be specified by
the operating system and will vary depending on how MMBasic is started. The directory path must be quoted
if it includes spaces. eg: SET MMDIR="C:\Program Files"
MMCOLOURS can be used to change the default colours used by the internal editor (the EDIT command).
The colours are specified as a sequence of 7 numbers separated by commas (,). See the COLOUR command
for the valid numbers and the corresponding colours.
MMEDITOR can be used to change the default editor used in the WEDIT command. For example:
SET MMEDITOR= C:\Edt.exe
The path must be quoted if it includes spaces. eg: SET MMEDITOR= "C:\Program Files\Edt.exe"
Shortcut Keys
At the command prompt you can use a function key to insert the following commands:
F2 RUN
F3 LIST
F4 EDIT
F5 WEDIT
Pressing the key will insert the text at the command prompt, just as if it had been typed on the keyboard.
Character Set
Special characters can be printed by specifying the number of the character using the CHR$() function. The
range of characters includes line drawing characters and accented characters and the full list (for a Windows 10
computer) is illustrated below.
Note that the character values are decimal numbers:
AUTORUN.BAS
If a valid program file name is not provided on the command line MMBasic will attempt to load a program
called AUTORUN.BAS and run it. It will first look for this file in the default directory provided by the
Windows operating system and if it was not found there it will look for it in the root directory of the C: drive.
This program can be used to setup MMBasic in some way (for example set the text colour) or perhaps display a
menu. Within this program the LOAD command can be used to load and run another program. It is also
possible to use the NEW command which will clear the program memory and return to the command prompt.
For example:
"COM8: baud=9600 parity=y data=7 stop=2"
Examples
Opening a serial port using all the defaults set for the port in Device Manager:
OPEN "COM2:" AS #2
Opening a serial port specifying only the baud rate (4800 bits per second):
OPEN "COM32: baud=4800" AS #1
Opening a serial port specifying the baud rate (9600 bits per second) and XON/XOFF flow control:
OPEN "COM1:9600 xon=on" AS #8
Following this the variable x would have the value 123 and y the value 56789.
To seek to a record within the file you would use the SEEK command which will position the read/write
pointer to a specific byte. The first byte in a file is numbered one so, for example, the fifth record in a file that
uses 64 byte records would start at byte 257. In that case you would use the following to point to it:
SEEK #1, 257
When reading from a random access file the INPUT$() function should be used as this will read a fixed number
of bytes (ie, a complete record) from the file. For example, to read a record of 64 bytes you would use:
dat$ = INPUT$(64, #1)
When writing to the file a fixed record size should be used and this can be easily accomplished by adding
sufficient padding characters (normally spaces) to the data to be written. For example:
PRINT #1, dat$ + SPACE$(64 – LEN(dat$);
The SPACE$() function is used to add enough spaces to ensure that the data written is an exact length (64bytes
in this example). The semicolon at the end of the print command suppresses the addition of the carriage return
and line feed characters which would make the record longer than intended.
Two other functions can help when using random file access. The LOC() function will return the current byte
position of the read/write pointer and the LOF() function will return the total length of the file in bytes.
The following program demonstrates random file access. Using it you can append to the file (to add some data
in the first place) then read/write records using random record numbers. The first record in the file is record
number 1, the second is 2, etc.
RecLen = 64
OPEN "test.dat" FOR RANDOM AS #1
DO
abort: PRINT
PRINT "Number of records in the file =" LOF(#1)/RecLen
INPUT "Command (r = read,w = write, a = append, q = quit): ", cmd$
IF cmd$ = "q" THEN CLOSE #1 : END
IF cmd$ = "a" THEN
SEEK #1, LOF(#1) + 1
ELSE
INPUT "Record Number: ", nbr
IF nbr < 1 or nbr > LOF(#1)/RecLen THEN PRINT "Invalid record" : GOTO abort
SEEK #1, RecLen * (nbr - 1) + 1
ENDIF
IF cmd$ = "r" THEN
PRINT "The record = " INPUT$(RecLen, #1)
ELSE
LINE INPUT "Enter the data to be written: ", dat$
PRINT #1,dat$ + SPACE$(RecLen - LEN(dat$));
ENDIF
LOOP
Random access can also be used on a normal text file. For example, this will print out a file backwards:
OPEN "file.txt" FOR RANDOM AS #1
FOR i = LOF(#1) TO 1 STEP -1
SEEK #1, i
PRINT INPUT$(1, #1);
NEXT i
CLOSE #1
If you are used to an editor like Notepad you will find that the operation of this editor is familiar. The arrow
keys will move your cursor around in the text, home and end will take you to the beginning or end of the line.
Page up and page down will do what their titles suggest. The delete key will delete the character at the cursor
and backspace will delete the character before the cursor. The insert key will toggle between insert and
overtype modes.
About the only unusual key combination is that two home key presses will take you to the start of the program
and two end key presses will take you to the end.
At the bottom of the screen the status line will list the various function keys used by the editor and their action.
In more details these are:
ESC This will cause the editor to abandon all changes and return to the command prompt with
the program memory unchanged. If you have changed the text you will be asked if you
really want to abandon your changes.
F1: SAVE This will save the program to program memory and return to the command prompt. If
the program had been previously loaded from, or saved to a file, MMBasic will also
update the file on disc (the file name is shown in the title bar of the window).
F2: RUN This will save the program (as above) and immediately run it.
F3: FIND This will prompt for the text that you want to search for. When you press enter the
cursor will be placed at the start of the first entry found.
F6 Once you have used the search function you can repeatedly search for the same text by
pressing F6.
F4: MARK This is described in detail below.
F5: PASTE This will insert (at the current cursor position) the text that had been previously cut or
copied (see below).
You can also use control keys instead of the functions keys listed above. These control keystrokes are:
LEFT Ctrl-S RIGHT Ctrl-D UP Ctrl-E DOWN Ctrl-X
HOME Ctrl-U END Ctrl-K PageUp Ctrl-P PageDn Ctrl-L
DEL Ctrl-] INSERT Ctrl-N F1 Ctrl-Q F2 Ctrl-W
F3 Ctrl-R ShiftF3 Ctrl-G F4 Ctrl-T F5 Ctrl-Y
The best way to learn the full screen editor is to simply fire it up and experiment.
The editor is a very productive method of writing a program. With the command EDIT you can quickly load
and edit your program. Then, by pressing the F2 key, you can save and run the program. If your program stops
with an error you can press the function key F4 which will run the command EDIT and place you back in the
editor with the cursor positioned at the line that caused the error. This edit/run/edit cycle is very fast.
The editor will colour code the edited program with keywords, numbers and comments displayed in
different colours. You can change the colours by using the environment variable MMCOLOURS (see the full
description at the start of this manual).
Constants
Numeric constants may begin with a numeric digit (0-9) for a decimal constant, &H for a hexadecimal
constant, &O for an octal constant or &B for a binary constant. For example &B1000 is the same as the
decimal constant 8. Constants that start with &H, &O or &B are always treated as 64-bit integer constants.
Decimal constants may be preceded with a minus (-) or plus (+) and may be terminated with 'E' followed by an
exponent number to denote exponential notation. For example 1.6E+4 is the same as 16000.
If the decimal constant contains a decimal point or an exponent, it will be treated as a floating point constant;
otherwise it will be treated as a 64-bit integer constant.
String constants are surrounded by double quote marks ("). Eg, "Hello World".
Arithmetic operators:
^
* / \ MOD Multiplication, division, integer division and modulus (remainder)
+ - Addition and subtraction
Shift operators:
x << y x >> y These operate in a special way. << means that the value returned
will be the value of x shifted by y bits to the left while >> means the
same only right shifted. They are integer functions and any bits
shifted off are discarded and any bits introduced are set to zero.
Logical operators:
NOT logical inverse of the value on the right
<> < > <= =< Inequality, less than, greater than, less than or equal to, less than or
>= => equal to (alternative version), greater than or equal to, greater than or
equal to (alternative version)
= equality
AND OR XOR Conjunction, disjunction, exclusive or
String operators:
+ Join two strings
<> < > <= =< Inequality, less than, greater than, less than or equal to, less than or
>= => equal to (alternative version), greater than or equal to, greater than or
equal to (alternative version)
= Equality
String comparisons respect case. For example "A" is greater than "a".
Implementation Characteristics
Maximum program size is 512KB.
Maximum number of variables is 500.
Maximum length of a command line is 255 characters.
Maximum length of a variable name or a label is 32 characters.
Maximum number of dimensions to an array is 8.
Maximum number of arguments to commands that accept a variable number of arguments is 50.
Maximum number of nested FOR…NEXT loops is 50.
Maximum number of nested DO…LOOP commands is 50.
Maximum number of nested GOSUBs, subroutines and functions (combined) is 1000.
Maximum number of nested multiline IF…ELSE…ENDIF commands is 20.
Maximum number of user defined subroutines and functions (combined): 512
Numbers are stored and manipulated as double precision floating point numbers or 64-bit signed integers. The
maximum floating point number allowable is 1.7976931348623157e+308 and the minimum is
2.2250738585072014e-308.
The range of 64-bit integers (whole numbers) that can be manipulated is ± 9223372036854775807.
Maximum string length is 255 characters.
Maximum line number is 65000.
Compatibility
MMBasic implements a large subset of Microsoft’s GW-BASIC. There are numerous differences due to
physical and practical considerations but most standard BASIC commands and functions are essentially the
same. An online manual for GW-BASIC is available at http://www.antonis.de/qbebooks/gwbasman/index.html
and this provides a more detailed description of the commands and functions.
MMBasic also implements a number of modern programming structures documented in the ANSI Standard for
Full BASIC (X3.113-1987) or ISO/IEC 10279:1991. These include SUB/END SUB, the DO WHILE …
LOOP, the SELECT…CASE statements and structured IF .. THEN … ELSE … ENDIF statements.
MM.DEVICE$ A string representing the device or platform that MMBasic is running on.
Currently this variable will contain one of the following:
"Maximite" on the standard Maximite and compatibles.
"Colour Maximite" on the Colour Maximite and UBW32.
"DuinoMite" when running on one of the DuinoMite family.
"DOS" when running on Windows in a DOS box.
"Generic PIC32" for the generic version of MMBasic on a PIC32.
"Micromite" on the PIC32MX150/250
"Micromite MkII" on the PIC32MX170/270
"Micromite Plus" on the PIC32MX470
"Micromite Extreme" on the PIC32MZ series
MM.VER The version number of the firmware as a floating point number in the form
aa.bbcc where aa is the major version number, bb is the minor version
number and cc is the revision number. For example version 5.03.00 will
return 5.03 and version 5.03.01 will return 5.0301.
MM.ERRNO If a statement caused an error which was ignored these variables will be set
MM.ERRMSG$ accordingly. MM.ERRNO is a number where non zero means that there was
an error and MM.ERRMSG$ is a string representing the error message that
would have normally been displayed on the console. They are reset to zero
and an empty string by RUN, ON ERROR IGNORE or ON ERROR SKIP.
MM.HRES The current height and width of the console window in characters (not
MM.VRES pixels). During execution of a program the window size can be adjusted by
the user and these variables will be automatically updated.
‘ (single quotation mark) Starts a comment and any text following it will be ignored.
Comments can be placed anywhere on a line.
? (question mark) Shortcut for the PRINT command.
CHDIR dir$ Change the current working directory to ‘dir$’
The special entry “..” represents the parent of the current directory and “.”
represents the current directory.
CLOSE [#]fnbr [,[#]fnbr] … Close the file(s) or COM port previously opened with the file number
‘#fnbr’. The # is optional.
Also see the OPEN command.
CLS Clears all text in the console window.
CLEAR Delete all variables and recover the memory used by them.
See ERASE for deleting specific array variables.
COLOUR fc, bc Sets the colours for subsequent characters written to the console window.
'fc' is the foreground colour and 'bg' is the background colour. These values
can be any one of the following:
0 = Black 8 = Gray
1 = Blue 9 = Bright Blue
2 = Green 10 = Bright Green
3 = Cyan 11 = Bright Cyan
4 = Red 12 = Bright Red
5 = Purple 13 = Bright Purple
6 = Yellow 14 = Bright Yellow
7 = White 15 = Bright White
This command can also be spelt as COLOR.
CONST id = expression Create a constant identifier which cannot be changed once created.
[, id = expression] … etc 'id' is the identifier which follows the same rules as for variables. The
identifier can have a type suffix (!, %, or $) but it is not required. If it is
specified it must match the type of 'expression'.
'expression' is the value of the identifier and it can be a normal expression
(including user defined functions) which will be evaluated when the constant
is created.
A constant defined outside a sub or function is global and can be seen
throughout the program. A constant defined inside a sub or function is local
to that routine and will hide a global constant with the same name.
CONTINUE Resume running a program that has been stopped by an END statement, an
error, or CTRL-C.
The program will restart with the next statement following the previous
stopping point. Note that it is not always possible to resume the program
correctly – this particularly applies to complex programs with nested loops
and/or nested subroutines and functions.
CONTINUE DO Skip to the end of a DO/LOOP or a FOR/NEXT loop. The loop condition
or will then be tested and if still valid the loop will continue with the next
iteration.
CONTINUE FOR
PAUSE delay Halt execution of the running program for ‘delay’ ms. Note that unlike the
Micromite MMBasic a fractional number will not be recognised and will be
rounded to the nearest integer.
PRINT expression Outputs text to the serial console. Multiple expressions can be used and must
[[,; ]expression] … etc be separated by either a:
Comma (,) which will output the tab character
Semicolon (;) which will not output anything (it is just used to separate
expressions).
Nothing or a space which will act the same as a semicolon.
A semicolon (;) at the end of the expression list will suppress the automatic
output of a carriage return/ newline at the end of a print statement.
When printed, a number is preceded with a space if positive or a minus (-) if
ACOS( number ) Returns the inverse cosine of the argument 'number' in radians.
ABS( number ) Returns the absolute value of the argument 'number' (ie, any negative sign is
removed and the positive number is returned).
ASC( string$ ) Returns the ASCII code for the first letter in the argument ‘string$’.
ASIN( number ) Returns the inverse sine value of the argument 'number' in radians.
BIN$( number [, chars]) Returns a string giving the binary (base 2) value for the 'number'.
'chars' is optional and specifies the number of characters in the string with
zero as the leading padding character(s).
CINT( number ) Round numbers with fractional portions up or down to the next whole
number or integer.
For example, 45.47 will round to 45
45.57 will round to 46
-34.45 will round to -34
-34.55 will round to -35
See also INT() and FIX().
DATE$ Returns the current date based on the internal DOS clock as a string in the
form "DD-MM-YYYY". For example, "28-07-2012".
EOF( [#]fnbr ) Will return true if the file previously opened for INPUT with the file number
‘#fnbr’ is positioned at the end of the file.
For a serial COM port it will return true if there are no characters currently
waiting in the input buffer to be read.
The # is optional. Also see the OPEN, INPUT and LINE INPUT commands
and the INPUT$ function.
FIX( number ) Truncate a number to a whole number by eliminating the decimal point and
all characters to the right of the decimal point.
For example 9.89 will return 9 and -2.11 will return -2.
The major difference between FIX and INT is that FIX provides a true
integer function (ie, does not return the next lower number for negative
numbers as INT() does). This behaviour is for Microsoft compatibility.
See also CINT() .
HEX$( number [, chars]) Returns a string giving the hexadecimal (base 16) value for the 'number'.
'chars' is optional and specifies the number of characters in the string with
zero as the leading padding character(s).
INKEY$ Checks the console input buffers and, if there is one or more characters
waiting in the queue, will remove the first character and return it as a single
character in a string.
If the input buffer is empty this function will immediately return with an
empty string (ie, "").
INPUT$(nbr, [#]fnbr) Will return a string composed of up to ‘nbr’ characters read from a file or
COM port previously with the file number ‘#fnbr’. This function will read
all characters including carriage return and new line without translation.
If there are less than 'nbr' characters waiting this function will return with as
many that are waiting to be read, this also means that it could return with an
empty string if there are no characters waiting.
The # is optional. Also see the OPEN command.
INSTR( [start-position,] string- Returns the position at which 'string-pattern$' occurs in 'string-searched$',
searched$, string-pattern$ ) beginning at 'start-position'.
Both the position returned and 'start-position' use 1 for the first character, 2
for the second, etc. The function returns zero if 'string-pattern$' is not found.
INT( number ) Truncate an expression to the next whole number less than or equal to the
argument. For example 9.89 will return 9 and -2.11 will return -3.
This behaviour is for Microsoft compatibility, the FIX() function provides a
true integer function.
See also CINT() .
LEFT$( string$, nbr ) Returns a substring of ‘string$’ with ‘nbr' of characters from the left
(beginning) of the string.
LOF( [#]fnbr ) Return the current length of a file opened with the file number ‘#fnbr’ in
bytes.
For a serial COM port this function will return the number of characters
waiting to be sent and in the current implementation this will always be zero
as the serial output is unbuffered.
The # is optional.
MAX( arg1 [, arg2 [, …]] ) Returns the maximum or minimum number in the argument list.
or Note that the comparison is a floating point comparison (integer arguments
MIN( arg1 [, arg2 [, …]] ) are converted to floats) and a float is returned.
MID$( string$, start ) Returns a substring of ‘string$’ beginning at ‘start’ and continuing for ‘nbr’
or characters. The first character in the string is number 1.
MID$( string$, start, nbr ) If ‘nbr’ is omitted the returned string will extend to the end of ‘string$’
OCT$( number [, chars]) Returns a string giving the octal (base 8) representation of 'number'.
'chars' is optional and specifies the number of characters in the string with
zero as the leading padding character(s).
RIGHT$( string$, number-of- Returns a substring of ‘string$’ with ‘number-of-chars’ from the right (end)
chars ) of the string.
SGN( number ) Returns the sign of the argument 'number', +1 for positive numbers, 0 for 0,
and -1 for negative numbers.
STRING$( nbr, ascii ) Returns a string 'nbr' bytes long consisting of either the first character of
or string$ or the character representing the ASCII value 'ascii' which is a
decimal number in the range of 32 to 126.
STRING$( nbr, string$ )
TAB( number ) Outputs spaces until the column indicated by 'number' has been reached.
TIME$ Returns the current time based on the internal DOS clock as a string in the
form "HH:MM:SS" in 24 hour notation. For example, "14:30:00".
TIMER Returns the elapsed time in milliseconds (eg, 1/1000 of a second) since reset.
The timer is reset to zero when MMBasic is started and you can also reset it
by using TIMER as a command. Note that under DOS the timer will reset to
0 for each subsequent 24 hour interval that elapses.
VAL( string$ ) Returns the numerical value of the ‘string$’. If 'string$' is an invalid number
the function will return zero.
This function will recognise the &H prefix for a hexadecimal number, &O
for octal and &B for binary.
GOSUB target Initiates a subroutine call to the target, which can be a line number or a label.
The subroutine must end with RETURN.
New programs should use defined subroutines (ie, SUB…END SUB).
IF condition THEN linenbr For Microsoft compatibility a GOTO is assumed if the THEN statement is
followed by a number. A label is invalid in this construct.
New programs should use: IF condition THEN GOTO linenbr | label
ON nbr GOTO | GOSUB ON either branches (GOTO) or calls a subroutine (GOSUB) based on the
target[,target, target,...] rounded value of 'nbr'; if it is 1, the first target is called, if 2, the second
target is called, etc. Target can be a line number or a label.
New programs should use SELECT CASE.
SPC( number ) This function returns a string of blank spaces 'number' bytes long. It is
similar to the SPACE$() function and is only included for Microsoft
compatibility.
POS For the console, returns the current cursor position in the line in characters.