@nataliapc/mcp-openmsx 1.1.14 → 1.2.2

package/resources/programming/basic_wiki/GET_TIME.md

@@ -0,0 +1,34 @@
+# GET TIME
+
+## Effect
+
+Reads the time in the SRAM of the Real Time Clock (RTC) on MSX2 and higher machines.
+
+## Syntax
+
+`GET TIME <StringVariable>,A`
+
+## Parameters
+
+`<StringVariable>` is a string variable that will contain the time in the format "HH:MM:SS". HH for the hour digits, MM for the minutes digits and SS for the seconds digits.
+
+When `A` is specified, the alarm time that you have  entered with `SET TIME` will be read. SS value is "00". If no any alarm time has been entered, HH and MM values are also "00" (no effect on almost all MSXs).
+
+## Example
+
+```basic
+GET TIME A$:PRINT A$
+ 20:27:43
+```
+
+## Related to
+
+`GET DATE`, `SET DATE`, `SET TIME`
+
+## Compatibility
+
+MSX-BASIC 2.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/GET_TIME"

package/resources/programming/basic_wiki/GOSUB.md

@@ -0,0 +1,41 @@
+# GOSUB
+
+## Effect
+
+Calls a subroutine located on the specified line number.
+
+The subroutine must be terminated with the `RETURN` instruction, to resume program execution with the instruction specified directly after `GOSUB` (on the same line or the next line), except if `RETURN` is followed by a line number.
+
+## Syntax
+
+`GOSUB <LineNumber>`
+
+## Parameter
+
+`<LineNumber>` is a program line number of your subroutine.
+
+## Example
+
+```basic
+10 GOSUB 100
+20 PRINT "Now it's my turn!"
+30 END
+100 PRINT "Me first!"
+110 RETURN
+ 
+RUN
+Me first!
+Now it's my turn!
+```
+
+## Related to
+
+`GOTO`, `ON...GOSUB`, `ON INTERVAL GOSUB`, `ON KEY GOSUB`, `ON SPRITE GOSUB`, `ON STOP GOSUB`, `ON STRIG GOSUB`, `RETURN`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/GOSUB"

package/resources/programming/basic_wiki/GOTO.md

@@ -0,0 +1,41 @@
+# GOTO
+
+## Effect
+
+Jumps to the specified line number and executes the instructions from there.
+
+## Syntaxes
+
+`GOTO <LineNumber>`
+
+`GO TO <LineNumber>`
+
+## Parameter
+
+`<LineNumber>` is a line number of your MSX program.
+
+## Example
+
+```basic
+10 GOTO 100
+20 PRINT "Now it's my turn!"
+30 END
+100 PRINT "Me first!"
+110 GOTO 20
+ 
+RUN
+Me first!
+Now it's my turn!
+```
+
+## Related to 
+
+`GOSUB`, `ON...GOTO`, `ON ERROR GOTO`
+
+## Compatibility 
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/GOTO"

package/resources/programming/basic_wiki/HEX$().md

@@ -0,0 +1,36 @@
+# HEX$()
+
+## Effect
+
+Returns a string with the hexadecimal representation of a value.
+
+## Syntax
+
+`HEX$(<Value>)`
+
+## Parameter
+
+`<Value>` must be an expression, a numeric variable or a value between -32768 and 65535. A single or double precision value can be used but digits after the decimal point will be ignored.
+
+## Example
+
+```basic
+10 PRINT "The hexadecimal representation of 8 is ";HEX$(8)
+20 PRINT "The hexadecimal representation of 127 is ";HEX$(127)
+ 
+RUN
+The hexadecimal representation of 8 is 8
+The hexadecimal representation of 127 is 7F
+```
+
+## Related to
+
+`BIN$`, `OCT$`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/HEX$()"

package/resources/programming/basic_wiki/IF...GOTO...ELSE.md

@@ -0,0 +1,55 @@
+# IF...GOTO...ELSE
+
+## Effect
+
+Checks if a condition has been met and jumps to the number line specified after `GOTO`. Optionally, if the condition has not been met the instruction(s) after `ELSE` will be run.
+
+_Note: If you use the Exprif BASIC extension, no need to use this instruction!_
+
+## Syntaxes
+
+`IF <ConditionExpression> GOTO <LineNumber> ELSE <LineNumber>`
+
+`IF <ConditionExpression> GOTO <LineNumber> ELSE <BASICinstruction>:<BASICinstruction>:...`
+
+## Parameters
+
+`<ConditionExpression>` is an expression false (whose result is zero) or true (whose result is non-zero). For example, the expression A<>9 is equal to 0 if A is different from 9 otherwise the result is -1.
+
+`<LineNumber>` is a line number of the program in memory.
+
+`<BASICinstruction>` can be any MSX-BASIC instruction. When there are several BASIC instructions, they must be separated by the character colon.
+
+`ELSE` can be omitted when it is not followed by one or more BASIC instructions or a program line number, that will be executed when the condition is false.
+
+## Examples
+
+```basic
+10 A=1: IF A GOTO 30
+20 PRINT "A=0":END
+30 PRINT "A is different from 0":END
+ 
+RUN
+A is different from 0
+```
+
+```basic
+10 CLS
+20 PRINT "Hello!"
+30 TIME = 0
+40 IF INKEY$="" GOTO 40
+50 IF TIME <4 GOTO 50
+60 IF INKEY$="" GOTO 60 ELSE 20
+```
+
+## Related to
+
+`IF...THEN...ELSE`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/IF...GOTO...ELSE"

package/resources/programming/basic_wiki/IF...THEN...ELSE.md

@@ -0,0 +1,50 @@
+# IF...THEN...ELSE
+
+## Effect
+
+Checks if a condition has been met and executes the instruction(s) specified after `THEN`. Optionally, if the condition has not been met the instruction(s) after `ELSE` will be run.
+
+_Note: If you use the Exprif BASIC extension, no need to use this instruction!_
+
+## Syntaxes
+
+`IF <ConditionExpression> THEN <LineNumber> ELSE <LineNumber>`
+
+`IF <ConditionExpression> THEN <LineNumber> ELSE <BASICinstruction>:<BASICinstruction>:...`
+
+`IF <ConditionExpression> THEN <BASICinstruction>:<BASICinstruction>:... ELSE <LineNumber>`
+
+`IF <ConditionExpression> THEN <BASICinstruction>:<BASICinstruction>:... ELSE <BASICinstruction>:<BASICinstruction>:...`
+
+## Parameters
+
+`<ConditionExpression>` is an expression false (whose result is zero) or true (whose result is non-zero). For example, the expression `A>5` is equal to 0 if `A` is less than 6 otherwise the result is -1.
+
+`<LineNumber>` is a line number of the program in memory.
+
+`<BASICinstruction>` can be any MSX-BASIC instruction. When there are several BASIC instructions, they must be separated by the character colon.
+
+`ELSE` can be omitted when it is not followed by one or more BASIC instructions or a program line number, that will be executed when the condition is false.
+
+## Example
+
+```basic
+10 INPUT "What is your age";A
+20 IF A < 18 THEN PRINT "You are way too young to be playing Starship Rendezvous":END ELSE PRINT "Good for you!"
+ 
+RUN
+What is you age?
+Good for you!
+```
+
+## Related to
+
+`IF...GOTO...ELSE`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/IF...THEN...ELSE"

package/resources/programming/basic_wiki/IMP.md

@@ -0,0 +1,83 @@
+# IMP
+
+## Effect
+
+Performs a bitwise `IMP`-operation (logical implication) between two expressions.
+
+The logical implication can be read as the condition _"if p is true, q is also true"_. On the other hand, if p is false, the  condtion still holds and thus the value of `p IMP q` is true.
+
+The truth table of p IMP q is:
+```
+0 IMP 0  =  1 
+0 IMP 1  =  1 
+1 IMP 0  =  0 
+1 IMP 1  =  1
+```
+
+This operation is equivalent to: `((NOT first_operand) OR second_operand)`
+
+## Syntax
+
+`<Value> IMP <Value>`
+
+## Parameter
+
+`<Value>` is a value between -32768 and 32767. It can also be a numeric variable, an mathematical expression or expression from a condition.
+
+_Notes:_
+- If you use binary expressions, it is best to put the first expression in parenthesis to avoid the bug in interpreter that causes a syntax error. This problem does not happen with decimal, hexadecimal or octal expressions.
+- When the expression is performed in a condition (`IF...THEN...ELSE` or `IF...GOTO...ELSE`), if the result of the whole expression is zero the value is taken as false, otherwise it's taken as true.
+
+## Examples
+
+```basic
+10 ' Continue only after user has (pressed and) released SPACE-key:
+20 S=LE:LE=STRIG(0):IF SIMPLE GOTO 20
+```
+
+```basic
+PRINT 15 IMP 11
+-5
+```
+Binary explanation:
+```
+0000000000001111 
+0000000000001011  IMP
+----------------
+1111111111111011
+```
+-5 is actually the number 65531
+
+```basic
+PRINT 5 IMP 13
+-1
+```
+Binary explanation:
+```
+0000000000000101 
+0000000000001101  IMP
+----------------
+1111111111111111
+```
+-1 is actually the number 65535
+
+```basic
+PRINT &B00001111 IMP &B11110001
+Syntax error
+Ok
+PRINT (&B00001111) IMP &B11110001
+-15
+```
+-15 is actually the number 65521
+
+## Related to
+
+`AND`, `EQV`, `MOD`, `NOT`, `OR`, `XOR`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/IMP"

package/resources/programming/basic_wiki/INKEY$.md

@@ -0,0 +1,65 @@
+# INKEY$
+
+## Effect
+
+Returns either a single character read from the keyboard or (if no key is pressed) an empty string.
+
+This instruction can be combined with `CHR$()` to check if a specific key has been pressed. It's useful not only for the alphanumeric keys, but also the cursor keys, the spacebar or another special key.
+
+However, if you want to make your game or application compatible with joysticks, it's better to directly use the `STICK()` and `STRIG()` instructions.
+
+## Syntax
+
+`INKEY$`
+
+## Special keys common to all MSX machines
+
+|Code for CHRS()|Key|Alternative <sup>*</sup>|
+|:-:|:-:|:--|
+|8|BS||
+|9|TAB||
+|11|HOME||
+|12|CLS||
+|13|RETURN||
+|18|INS||
+|24|SELECT||
+|27|ESC||
+|28|→|`STICK(n) = 3`|
+|29|←|`STICK(n) = 7`|
+|30|↑|`STICK(n) = 1`|
+|31|↓|`STICK(n) = 5`|
+|32|SPACE|`STRIG(n) = -1`|
+|127|DEL||
+
+<sup>(*)</sup> n is a value between 0 and 2 for `STICK()`, 0 and 4 for `STRIG()`
+
+## Examples
+
+```basic
+10 A$=INKEY$
+20 IF A$="" THEN 10
+30 PRINT "You pressed ";A$;" - CHR$(";ASC(A$);")"
+ 
+RUN
+You pressed M - CHR$( 77 )
+```
+
+_Note: The result will be an 'empty' character with some special keys._
+
+```basic
+10 A$=INKEY$
+20 IF A$=CHR$(28) THEN 30 ELSE 10
+30 PRINT "You pressed the key to move the cursor to the right"
+```
+
+## Related to
+
+`CHR$()`, `INPUT$`, `STICK()`, `STRIG()`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/INKEY$"

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

@@ -0,0 +1,33 @@
+# INP()
+
+## Effect
+
+Returns the value of an input port.
+
+## Syntax
+
+`INP(<PortNumber>)`
+
+## Parameter
+
+`<PortNumber>` is the I/O port number to read. It needs to be between 0 and 255.
+
+## Example
+
+```basic
+10 A=INP(&HA8)
+20 A$="00000000"+BIN$(A)
+30 PRINT RIGHT$(A$,8)
+```
+
+## Related to
+
+`OUT`, `SOUND`, `VDP()`, `WAIT`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/INP()"

package/resources/programming/basic_wiki/INPUT$().md

@@ -0,0 +1,51 @@
+# INPUT$()
+
+## Effet
+
+Returns a string characters of defined length retrieved from the keyboard or a sequential file. 
+
+## Syntax
+
+`INPUT$(<Number>,#<FileNumber>)`
+
+## Parameters
+
+`<Number>` is the number of characters to retrieve.
+
+`#` precedes file number. It is optional and has no effect.
+
+`<FileNumber>` is the number of file assigned to the sequential file opened with the `OPEN` command.
+
+## Examples
+
+```basic
+10 A$=INPUT$(3)
+20 PRINT A$
+ 
+RUN
+MSX
+```
+
+```basic
+10 OPEN "CAS:DATA" FOR INPUT AS #1
+20 IF EOF(1) THEN 40
+30 A$=INPUT$(3,1) : PRINT A$ : GOTO 20
+40 CLOSE#1 : END
+```
+
+## Data
+
+- The data retrieved from the keyboard or a sequential file are stored in only one value (not several values) and it's always a string (never a number).
+- `INPUT$` accepts all characters, especially the control-sequences (with exception for CTRL/C). Therefore `INPUT$` is useful for data transfer from other machines. In such transmissions all characters might be important.
+
+## Related to
+
+`CLOSE`, `EOF`, `INKEY$`, `INPUT`, `LINE INPUT`, `OPEN`, `PRINT`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/INPUT$()"

package/resources/programming/basic_wiki/INPUT.md

@@ -0,0 +1,93 @@
+# INPUT
+
+## Effect
+
+Retrieves data from the keyboard or reads data from a sequential file, storing the input (strings or numbers) into variables.
+
+## Syntaxes
+
+`INPUT "<Prompt>"; <Variable>,<Variable>...`
+
+`INPUT#<FileNumber>,<Variable>,<Variable>...`
+
+_Note: Parameters can not end with a comma alone._
+
+## Parameters
+
+`<Prompt>` is the text displayed that will be followed by a question mark to ask what you need to input. String variable is ignored.
+
+`<Variable>` is a numeric/string variable that will take the input value/string. We can add variables to enter a series of values, each separated by a comma.
+
+`<FileNumber>` is the number of file opened by `OPEN`.
+
+_Note: Using this parameter does not go to text screen mode when the instruction is executed in a graphic screen mode, and with device `"CON"` only the characters that has been typed will be retrieved, other characters on same input line will not be retrieved._
+
+## Examples
+
+```basic
+10 INPUT "What is your favorite computer system";A$
+20 PRINT A$
+ 
+RUN
+What is your favorite computer system?
+MSX
+```
+
+```basic
+10 INPUT "What is your preferred number";A
+20 PRINT A
+ 
+RUN
+What is your preferred number?
+13
+```
+
+```basic
+10 OPEN "CAS:DATA" FOR INPUT AS #1
+20 IF EOF(1) THEN 40
+30 INPUT#1,X$,Y$,Z$ : PRINT X$,Y$,Z$ : GOTO 20
+40 CLOSE#1 : END
+```
+
+```basic
+10 COLOR 15,4,4:SCREEN 2
+20 OPEN"con" FOR INPUT AS #1
+30 INPUT#1,A$: CLOSE#1
+40 PSET(124-(LEN(A$)*4),92),4
+50 OPEN"grp:" AS #1
+60 PRINT#1,A$: CLOSE#1
+70 IF NOT STRIG(0) THEN 70  ' Press Space key to exit
+80 END
+```
+
+## Data
+
+### Retrieved from keyboard
+
+You need to enter as many values as in the `INPUT` command and they need to be separated by a comma. Strings are accepted, but if they include a comma they need to be surrounded with `"` (Input format is similar to `DATA` statement).
+
+If there's an error in the entered values, the message _? Redo from start_ is displayed and the `INPUT` command is executed again.
+
+If values are missing `??` is displayed and user is given possibility to enter the missing value(s).
+
+In case of too many values are given a message `? Extra ignored` will be displayed and the program will continue without storing the extra values.
+
+If a string or number already has a value and the new input is empty (only Return/Enter pressed on the keyboard) then the old value remains unchanged.
+
+### Read from sequential file
+
+If the values are read from a sequential file, the variables on this file need to be in the same order than the variables of the `INPUT` command.
+
+In case of strings on a sequential file, the end of the string is determined by a comma, RETURN or Line Feed. However, if the first character of the string is a quotation mark `"` then the second quotation mark is viewed as the end of the string.
+
+## Related to
+
+`CLOSE`, `EOF`, `INPUT$`, `LINE INPUT`, `OPEN`, `PRINT`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/INPUT"

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

@@ -0,0 +1,44 @@
+# INSTR()
+
+## Effect
+
+Returns the position of the first occurrence of a substring in a specified string, this from a specified position.
+
+Special values:
+- 0 if the specified string is empty OR the substring is not found in the string OR the starting position is higher than the length of the string.
+- value of starting position if the required substring is empty AND the specified string is not empty AND the starting position is not higher than the length of the string.
+
+_Note: For strings with Japanese or Korean characters, you need to use `CALL KINSTR`._
+
+## Syntax
+
+`INSTR(<Start>,"<String1>","<String2>")`
+
+## Parameters
+
+`<Start>` is the starting position in the string to find the substring. The first character in the string is numbered 1. The highest possible position is 255. When omitted, the search will start from the first character.
+
+`<String1>` and `<String2>` are strings of characters between double quotes `"`. They can include non-printable characters and be replaced by a numeric or string variable (also named as alphanumeric variable).
+
+`<String2>` is the substring to be found in `<String1>`.
+
+## Example
+
+```basic
+10 PRINT INSTR("I like MSX!","MSX");
+ 
+RUN
+8
+```
+
+## Related to
+
+`CALL KINSTR`, `LEN`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/INSTR()"

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

@@ -0,0 +1,44 @@
+# INT()
+
+## Effect
+
+Returns the largest integer equal to or smaller than a variable.
+
+## Syntax
+
+`INT (<Expression>)`
+
+## Parameter
+
+`<Expression>` can be a value, a numeric variable or an mathematical expression.
+
+## Example
+
+```basic
+10 PRINT "INT(1.23) results in ";INT(1.23)
+20 PRINT "INT(-1.99) results in ";INT(-1.99)
+30 PRINT "INT(-1.01) results in ";INT(-1.01)
+ 
+RUN
+INT(1.23) results in 1
+INT(-1.99) results in -2
+INT(-1.01) results in -2
+```
+
+## 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()`, `FIX()`, `SGN()`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/INT()"