@nataliapc/mcp-openmsx 1.1.15 → 1.2.3

package/resources/programming/basic_wiki/ERR.md

@@ -0,0 +1,143 @@
+# ERR
+
+## Effect
+
+Returns the code number of the error that occured.
+
+Can vary between 1 and 255.
+
+As MSX-BASIC uses values 1 to 25 and Disk BASIC values 50 to 82, you can use the non-defined values to generate specific error messages in your programs. Variables are not usable.
+
+## Syntax
+
+`ERR`
+
+## Example
+
+```basic
+10 ON ERROR GOTO 50
+20 MSX ' Generates an error, as "MSX" is not a valid MSX-BASIC command
+30 END
+50 PRINT "Error code ";ERR
+60 RESUME 30
+70 ON ERROR GOTO 0
+
+run
+Error code  2
+```
+
+## Defined Errors
+
+### MSX-BASIC and Disk BASIC
+
+Errors 72 to 75 have been added by version 2 of Disk BASIC, 76 to 82 by version 3 provided by the Nextor operating system.
+
+|MSX-BASIC|Message|
+|:-:|---|
+|1|NEXT without FOR|
+|2|Syntax error|
+|3|RETURN without GOSUB|
+|4|Out of DATA|
+|5|Illegal function call|
+|6|Overflow|
+|7|Out of memory|
+|8|Undefined line number|
+|9|Subscript out of range|
+|10|Redimensioned array|
+|11|Division by zero|
+|12|Illegal direct|
+|13|Type mismatch|
+|14|Out of string space|
+|15|String too long|
+|16|String formula too complex|
+|17|Can't CONTINUE|
+|18|Undefined user function|
+|19|Device I/O error|
+|20|Verify error|
+|21|No RESUME|
+|22|RESUME without error|
+|23|Unprintable error|
+|24|Missing operand|
+|25|Line buffer overflow|
+
+|Disk BASIC|Message|
+|:-:|---|
+|50|FIELD overflow|
+|51|Internal error|
+|52|Bad file number|
+|53|File not found|
+|54|File already open|
+|55|Input past end|
+|56|Bad file name|
+|57|Direct statement in file|
+|58|Sequential I/O only|
+|59|File not OPEN|
+|60|Bad FAT|
+|61|Bad file mode|
+|62|Bad drive name|
+|63|Bad sector number|
+|64|File still open|
+|65|File already exists|
+|66|Disk full|
+|67|Too many files|
+|68|Disk write protected|
+|69|Disk I/O error|
+|70|Disk offline|
+|71|Rename across disk|
+|72|File write protected|
+|73|Directory already exists|
+|74|Directory not found|
+|75|RAM disk already exists|
+|76|Invalid device driver|
+|77|Invalid device or LUN|
+|78|Invalid partition number|
+|79|Partition already in use|
+|80|File is mounted|
+|81|Bad file size|
+|82|Invalid cluster sequence|
+
+### HI-GRAPhics
+
+HI-GRAPHics is an utility written by Arjen Schrijvers (see Interlacing Demo).
+
+Note that the error messages can be in conflict with Disk BASIC versions 2 and 3.
+
+|HI-GRAPHics|Message|
+|:-:|---|
+|72|Bad display page|
+|73|Bad screen mode|
+|74|Bad display mode|
+
+### Delta BASIC
+
+|Delta BASIC|Message|
+|:-:|---|
+|200|ENDPROC without PROC|
+|201|DEFPROC not found|
+|202|ENDPROC not found|
+|203|MODE error|
+|204|UNNEW without NEW|
+|205|Program recovered|
+|206|TOO MUCH varspace|
+|207|NO ROOM for vars|
+|208|INVALID definition windows|
+|209|INVALID window|
+|210|MISSING definition window|
+|211|LOCATE out of window|
+|212|MEMDISC initialised|
+|213|LINE number too big|
+|214|MOVLIN error|
+|215|COPLIN error|
+|216|STATE size|
+
+## Related to
+
+`ERL`, `ERROR`, `ON ERROR GOTO`, `RESUME`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/ERR"

package/resources/programming/basic_wiki/ERROR.md

@@ -0,0 +1,145 @@
+# ERROR
+
+## Effect
+
+Simulates an error that is specified by its code.
+
+## Syntax
+
+`ERROR <ErrorNumber>`
+
+## Parameter
+
+`<ErrorNumber>` can vary between 1 and 255.
+
+As MSX-BASIC uses values 1 to 25 and Disk BASIC values 50 to 82, you can use the non-defined values to generate specific error messages in your programs. Variables are not usable.
+
+## Example
+
+```basic
+10 ON ERROR GOTO 400
+20 INPUT "X= ";A
+30 IF A&gt;100 THEN ERROR 150
+40  IF A&lt;10 THEN ERROR 151
+50 END
+400 IF ERR=150 THEN PRINT "MAXIMUM 100!"
+410 IF ERR=151 THEN PRINT "MINIMUM 10!"
+420 RESUME 20
+430 ON ERROR GOTO 0
+```
+
+## Defined Errors
+
+### MSX-BASIC and Disk BASIC
+
+Errors 72 to 75 have been added by version 2 of Disk BASIC, 76 to 82 by version 3 provided by the  Nextor operating system.
+
+|MSX-BASIC|Message|
+|:-:|---|
+|1|NEXT without FOR|
+|2|Syntax error|
+|3|RETURN without GOSUB|
+|4|Out of DATA|
+|5|Illegal function call|
+|6|Overflow|
+|7|Out of memory|
+|8|Undefined line number|
+|9|Subscript out of range|
+|10|Redimensioned array|
+|11|Division by zero|
+|12|Illegal direct|
+|13|Type mismatch|
+|14|Out of string space|
+|15|String too long|
+|16|String formula too complex|
+|17|Can't CONTINUE|
+|18|Undefined user function|
+|19|Device I/O error|
+|20|Verify error|
+|21|No RESUME|
+|22|RESUME without error|
+|23|Unprintable error|
+|24|Missing operand|
+|25|Line buffer overflow|
+
+|Disk BASIC|Message|
+|:-:|---|
+|50|FIELD overflow|
+|51|Internal error|
+|52|Bad file number|
+|53|File not found|
+|54|File already open|
+|55|Input past end|
+|56|Bad file name|
+|57|Direct statement in file|
+|58|Sequential I/O only|
+|59|File not OPEN|
+|60|Bad FAT|
+|61|Bad file mode|
+|62|Bad drive name|
+|63|Bad sector number|
+|64|File still open|
+|65|File already exists|
+|66|Disk full|
+|67|Too many files|
+|68|Disk write protected|
+|69|Disk I/O error|
+|70|Disk offline|
+|71|Rename across disk|
+|72|File write protected|
+|73|Directory already exists|
+|74|Directory not found|
+|75|RAM disk already exists|
+|76|Invalid device driver|
+|77|Invalid device or LUN|
+|78|Invalid partition number|
+|79|Partition already in use|
+|80|File is mounted|
+|81|Bad file size|
+|82|Invalid cluster sequence|
+
+### HI-GRAPhics
+
+HI-GRAPHics is an utility written by Arjen Schrijvers (see Interlacing Demo).
+
+Note that the error messages can be in conflict with Disk BASIC versions 2 and 3.
+
+|HI-GRAPHics|Message|
+|:-:|---|
+|72|Bad display page|
+|73|Bad screen mode|
+|74|Bad display mode|
+
+### Delta BASIC
+
+|Delta BASIC|Message|
+|:-:|---|
+|200|ENDPROC without PROC|
+|201|DEFPROC not found|
+|202|ENDPROC not found|
+|203|MODE error|
+|204|UNNEW without NEW|
+|205|Program recovered|
+|206|TOO MUCH varspace|
+|207|NO ROOM for vars|
+|208|INVALID definition windows|
+|209|INVALID window|
+|210|MISSING definition window|
+|211|LOCATE out of window|
+|212|MEMDISC initialised|
+|213|LINE number too big|
+|214|MOVLIN error|
+|215|COPLIN error|
+|216|STATE size|
+
+## Related to
+
+`ERL`, `ERR`, `ON ERROR GOTO`, `RESUME`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/ERROR"

package/resources/programming/basic_wiki/EXP().md

@@ -0,0 +1,38 @@
+# EXP()
+
+## Effect
+
+Returns mathematical constant e (base of the natural logarithm) to the power of a specified number.
+
+## Syntax
+
+`EXP(<Number>)`
+
+## Parameter
+
+`<Number>` must be less or equal 145.06286058562
+
+## Example
+
+```basic
+10 PRINT "e to the power of 1 is ";EXP(1)
+20 PRINT "e to the power of 0 is ";EXP(0)
+30 PRINT "e to the power of 10 is";EXP(10)
+
+RUN
+e to the power of 1 is 2.7182818284588
+e to the power of 0 is 1
+e to the power of 10 is 22026.4657948
+```
+
+## Related to
+
+`LOG()`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/EXP()"

package/resources/programming/basic_wiki/FIELD.md

@@ -0,0 +1,48 @@
+# FIELD
+
+## Effect
+
+Defines random access file record format. The file needs to be opened with `OPEN` before fields can be defined.
+
+The record is separated into single fields. Every data field has a length and a string variable is assigned to access this fixed size space inside the record buffer. The number of fields is not limited but must not exceed the record length as specified with `OPEN` (by default: 256).
+
+The fields inside a record are assigned in same order as they are presented in a program. Presentation can be done with single or multiple `FIELD` instructions. These fields are not separated in any way and their format is not stored, so record format needs to be presented both for reading and writing.
+
+_Notes:_
+- Random access of files in BASIC originates from time before disk drives, so it helps to understand the ideology and functionality, if you think the records as virtual stack of punched cards.
+- `LET` can't be used to modify the record buffer, because it moves variable back to normal variable storage space. When handling random access files, you need to use `LSET` or `RSET` instead of `LET`.
+- The record buffer location in memory can be checked with the `VARPTR` instruction.
+
+## Syntax
+
+`FIELD # <FileNumber>,<CharacterLength> AS <StringVariable>,<CharacterLength> AS <StringVariable> ...`
+
+At least one data field needs to be defined. Parameters can not end with a comma alone.
+
+## Parameters
+
+`<FileNumber>` is the number of the open file, it can vary between 1 and 15, but can't exceed the maximum number of files eventually defined with `MAXFILES`. The `#` in front can be omitted.
+
+`<CharacterLength>` is the length of a data field.
+
+`<StringVariable>` is the variable assigned to this data field.
+
+## Example
+
+```basic
+10 OPEN "A:RECORD.DAT" AS #1 
+20 FIELD #1, 20 AS A$, 10 AS B$, 15 AS C$
+30 CLOSE #1
+```
+
+## Related to
+
+`CLOSE`, `GET`, `LSET`, `MAXFILES`, `OPEN`, `PUT`, `RSET`
+
+## Compatibility
+
+Disk BASIC 1.0 or higher / both modes of Nextor OS
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/FIELD"

package/resources/programming/basic_wiki/FIX().md

@@ -0,0 +1,44 @@
+# FIX()
+
+## Effect
+
+Returns the integer part of a variable by truncating the numbers after the decimal point. 
+
+## Syntax
+
+`FIX (<Expression>)`
+
+## Parameter
+
+`<Expression>` can be a value, a numeric variable or an mathematical expression.
+
+## Example
+
+```basic
+10 PRINT "FIX(1.23) results in ";FIX(1.23)
+20 PRINT "FIX(-1.99) results in ";FIX(-1.99)
+30 PRINT "FIX(-1.01) results in ";FIX(-1.01)
+ 
+RUN
+FIX(1.23) results in 1
+FIX(-1.99) results in -1
+FIX(-1.01) results in -1
+```
+
+## Difference between FIX, INT and CINT
+
+When the variable is negative, `INT` gives the next lower number, whereas `FIX` merely truncates the numbers after the decimal point. `FIX(x)` is equivalent to `INT(ABS(x))*SGN(x)`.
+
+`CINT` is similar to `FIX`, but the integer part is limited between -32768 and 32767.
+
+## Related to
+
+`ABS()`, `CINT()`, `INT()`, `SGN()`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/FIX()"

package/resources/programming/basic_wiki/FN.md

@@ -0,0 +1,61 @@
+# FN
+
+## Effect
+
+Performs the functions defined by `DEF FN`. It is used as expression.
+
+## Syntax
+
+`FN <FunctionName> (<Value>,<Value>...)`
+
+## Parameters
+
+`<FunctionName>` is the function name,  the length of the function name can be as long as you want, only the first two characters of the function name will actually be used. 
+Furthermore, if a function is to return a string, the name of the function has to be suffixed by a `$`.
+
+`<Value>` is optional, it is a value that will be used in the `<Expression>` defined by `DEF FN`. Several values can be specified, they must be separated by a comma.
+
+## Examples
+
+```basic
+10 DEF FN SQUARE (X)=X^2
+20 PRINT "The square of 2 is ";FN SQUARE(2)
+30 PRINT "The square of 4 is ";FN SQUARE(4)
+ 
+RUN
+The square of 2 is  4
+The square of 4 is  16
+```
+```basic
+10 DEF FN PER(X,P)=X/(100/P)
+20 INPUT"Value";X
+30 INPUT"Percentage";P
+40 PRINT P;"% of";X;"="; FN PER(X,P)
+ 
+RUN
+Value? 30
+Percentage? 50
+50% of 30 = 15
+```
+```basic
+10 ' Limit mouse movement to screen using limit function
+20 DEF FNL(N,MI,MA)=((N&lt;MI)AND(MI-N))+N+((N&gt;MA)AND(MA-N))
+30 SCREEN 5
+40 SPRITE$(0)=" P "
+50 R=PAD(12) ' Read mouse from port 1
+60 X=FNL(X+PAD(13),0,255) : Y=FNL(Y+PAD(14),0,211)
+70 PUT SPRITE 0,(X-2,Y-2)
+80 IF NOT STRIG(1) THEN 50
+```
+
+## Related to
+
+`CLEAR`, `DEF FN`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/FN"

package/resources/programming/basic_wiki/FOR...NEXT.md

@@ -0,0 +1,80 @@
+# FOR...NEXT
+
+## Effect
+
+Sets up a loop in order to repeat a block of instructions until the counter variable has exceeded the end value.
+
+## Syntax
+
+`FOR <Variable1>=<StartValue> TO <EndValue> STEP <Increment>`  
+...  
+`NEXT <Variable1>,<Variable2>,...`
+
+_Notes:_
+- Several `FOR...NEXT` loops are possible.
+- "..." can be several program lines
+- `NEXT` can be applied on several loops,
+
+For example:  
+`NEXT <Variable1>,<Variable2>`  
+has the same effect as  
+`NEXT <Variable1> : NEXT <Variable2>`  
+ (see also examples below).
+
+## Parameters
+
+`<Variable1>` is the numeric variable used for the loop. After the instruction `NEXT`, the variables are optional. They are used only to indicate to which loop it corresponds.
+
+`<Variable2>`,etc are variables from preceding outer loops.
+
+`<StartValue>` is the variable value on which the loop begins.
+
+`<EndValue>` is the limit value of the loop.
+
+`STEP` is an optional part that can be only used with `<Increment>` together.
+
+`<Increment>` is the value to add at each back to begin. By default the value is 1.
+
+_Note: if `<EndValue>` is inferior to `<StartValue>` then `<Increment>` must be negative._
+
+`NEXT` is an instruction that causes the increment and then go back to the line just after that of the `FOR` instruction as long as the result does not exceed `<EndValue>`.
+
+_Note: Each variable behind `NEXT` is optional except the last specified. Do not put a comma after this variable._
+
+Within a loop another loop can be implemented, so loops can be nested. To avoid confusion, it's better to specify the corresponding variable(s) after `NEXT`. Every loop will be executed at least once because the termination condition is checked in the `NEXT` instruction(s).
+
+## Examples
+
+```basic
+10 FOR x=1 TO 25 STEP 5
+20 PRINT x
+30 NEXT
+
+RUN
+ 1
+ 6
+11
+16
+21
+```
+```basic
+10 FOR I=1 TO 4
+20 PRINT I;
+30 NEXT:PRINT
+40 FOR I=0 TO 5 STEP 5
+50 FOR J=0 TO I+2
+60 PRINT J;
+70 NEXT J,I:PRINT
+
+RUN
+ 1 2 3 4
+ 0 1 2 0 1 2 3 4 5 6 7
+```
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/FOR...NEXT"

package/resources/programming/basic_wiki/FRE().md

@@ -0,0 +1,66 @@
+# FRE()
+
+## Effect
+
+- Returns the amount of bytes in memory which can be used for BASIC programs, variables, etc... if the parameter is a numeric value.
+- Returns the amount of bytes in memory which can be used for strings If the parameter is a string.
+
+## Syntaxes
+
+`FRE(<Value>)`
+
+`FRE("<String>")`
+
+## Parameters
+
+`<Value>` can be any value or a numeric variable.
+
+`<String>` can be any string between double quotes `"` or a string variable (also named as alphanumeric variable).
+
+## Examples
+
+Get free memory for your Basic program:
+
+```basic
+10 PRINT "First there are ";FRE(0);" bytes free"
+20 DIMB(100)
+30 PRINT "Now there are ";FRE(0);" bytes free"
+ 
+RUN
+First there are 23332 bytes free
+Now there are 22516 bytes free
+```
+
+Get free memory for strings in your Basic program:
+
+```basic
+PRINT FRE("")
+ 200
+Ok
+
+A$="MSX"
+PRINT FRE(A$)
+ 197
+Ok
+```
+
+## Tips to increase the free RAM in MSX-BASIC
+
+- Use `ELSE` instead of `REM` when you comment out instructions (helps also with `RENUM` problems).
+- In other comments (especially in "comment only" lines where `:` is not needed) use `REM` instead of `'` (i.e. `10 ELSEGOTO10` takes up 10 bytes in RAM, `10 REMGOTO10` takes up 12 bytes and `10 'GOTO10` takes up 14 bytes of RAM).
+- Don't use `SPACE` characters between instructions (but it will make your code less easy to read).
+- Define variables as integers when ever possible.
+- Allocate correct amount of space for strings and tables.
+- Disable BASIC extensions that you don't need (i.e. hold down `SHIFT` during boot to disable all disk drives or `CTRL` to disable 2nd drive).
+
+## Related to
+
+`CLEAR`, `ELSE`, `ERASE`, `NEW`, `REM`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/FRE()"

package/resources/programming/basic_wiki/GET_DATE.md

@@ -0,0 +1,60 @@
+# GET DATE
+
+## Effect
+
+Reads the date in the SRAM of the Real Time Clock (RTC) on MSX2 and higher machines.
+
+## Syntax
+
+`GET DATE <StringVariable>,A`
+
+## Parameters
+
+`<StringVariable>` is a string variable that will contain the date in one of formats showed in table below.
+
+When `A` is specified, the alarm date that you have entered with `SET DATE` will be read (no effect on almost all MSXs).
+
+## Date format
+
+The date is made of three elements: the day (DD), the month (MM) and the year (YY). It can be displayed in 3 different formats, the used format depends from the country for which the computer was released.
+
+When `A` is specified, MM and YY values are "00". If no any alarm date has been entered, DD value is also "00".
+
+|Date format|Countries|
+|:-:|---|
+|DD/MM/YY|Brazil, Egypt, France, Germany, Kuwait|
+|MM/DD/YY|Argentina, Saudi Arabia, Soviet countries, USA and Spain|
+|YY/MM/DD|Japan and Korea|
+
+## Example
+
+```basic
+GET DATE A$:PRINT A$
+ 09/26/15
+```
+
+If you want to convert this format to Y/M/D (which would be closest to ISO8601 format) based on the system's date format as reported in &H002B, you can use the following snippet, it will print the original date in the system's date format, followed by the date in Y/M/D format:
+
+```basic
+1 GET DATE A$:PRINT A$:ON ((PEEK(&H2B) AND &B01110000)/16+1) GOSUB 3,4,5
+2 PRINT A$:END
+3 RETURN ' Y/M/D is already the right format, nothing to change here
+4 A$=MID$(A$,7,2)+"/"+MID$(A$,1,2)+"/"+MID$(A$,4,2):RETURN ' Convert from M/D/Y format
+5 A$=MID$(A$,7,2)+"/"+MID$(A$,4,2)+"/"+MID$(A$,1,2):RETURN ' Convert from D/M/Y format
+
+RUN
+31/05/21
+21/05/31
+```
+
+## Related to
+
+`GET TIME`, `SET DATE`, `SET TIME`
+
+## Compatibility
+
+MSX-BASIC 2.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/GET_DATE"