@nataliapc/mcp-openmsx 1.1.14 → 1.2.2

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

@@ -0,0 +1,82 @@
+# STRIG()
+
+## Effect
+
+Returns the state of the space key and the joystick/mouse/trackball buttons or enables/disables/stops the call to the subroutine when pressing of the space keys and the joystick/mouse/trackball buttons.
+
+## Syntaxes
+
+`STRIG(<ControllerNumber>)`
+
+`STRIG(<ControllerNumber>) ON|OFF|STOP`
+
+## Parameters
+
+`<ControllerNumber>` is a number between 0 and 4 to define the controller used.
+
+|Controller|Description|
+|---|---|
+|0|Space key|
+|1|Button 1 of joystick/mouse/trackball in port 1|
+|2|Button 1 of joystick/mouse/trackball in port 2|
+|3|Button 2 of joystick/mouse/trackball in port 1|
+|4|Button 2 of joystick/mouse/trackball in port 2|
+
+`STRIG(<ControllerNumber>)` used alone returns -1 when the space key or the joystick/mouse button corresponding to the specified controller is pressed down. Otherwhise, the value is 0.
+
+`STRIG(<ControllerNumber>)` used with `ON`, `OFF`, `STOP` is always combined with `ON STRIG GOSUB`.
+
+With `ON`, the computer will check if the space key or the joystick/mouse button corresponding to the `<sticknumber>` is pressed down and the subroutine specified with `ON STRIG GOSUB` is executed immediately.
+
+With `OFF`, this checking is disabled.
+
+With `STOP`, the checking is made, but the execution of the subroutine specified with `ON STRIG GOSUB` will happen only when a `STRIG() ON` command is executed later in the program.
+
+## Examples
+
+```basic
+10 PRINT "Hit the space key"
+20 P=STRIG(0)
+30 IF P=-1 THEN BEEP
+40 GOTO 20
+```
+
+```basic
+10 ON STRIG GOSUB 80 : STRIG(0) ON
+20 CLS: PRINT "SPACEBAR ROUTINE ENABLED"
+30 FOR I = 1 TO 2000 : NEXT
+40 STRIG(0) OFF
+50 PRINT: PRINT "SPACEBAR ROUTINE DISABLED"
+60 FOR I = 1 TO 2000 : NEXT
+70 STRIG(0) ON : GOTO 20
+80 PRINT: PRINT "SPACEBAR PRESSED DOWN"
+90 FOR I = 1 TO 2000 : NEXT
+100 RETURN 70
+```
+
+```basic
+10 ON STRIG GOSUB 60, 90, 100, 110, 120
+20 CLS
+30 FOR I=0 TO 4: STRIG(I) ON: NEXT
+40 PRINT"Press spacebar or a button joystick"
+50 GOTO 50
+60 PRINT"Spacebar";
+70 PRINT" pressed"
+80 RETURN
+90 PRINT"Button 1 of joystick 1";:GOTO 70
+100 PRINT"Button 1 of joystick 2";:GOTO 70
+110 PRINT"Button 2 of joystick 1";:GOTO 70
+120 PRINT"Button 2 of joystick 2";:GOTO 70
+```
+
+## Related to
+
+`INKEY$`, `ON STRIG GOSUB`, `PAD()`, `PDL()`, `STICK()`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/STRIG()"

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

@@ -0,0 +1,42 @@
+# STRING$()
+
+## Effect
+
+Returns a string with a variable length, all containing either the same character, which is defined as an ASCII code or the first character of a string.
+
+## Syntaxes
+
+`STRING$(<Length>,<CodeNumber>)`
+
+`STRING$(<Length>,"<String>")`
+
+## Parameters
+
+`<Length>` It is the length of the string and must be an integer in range between 0 and 255.
+
+`<CodeNumber>` must be an ASCII code between 32 and 255.
+
+`<String>` is a string of characters between double quotes `"`. It can be replaced by a string variable (also named as alphanumeric variable).
+
+## Example
+
+```basic
+10 PRINT STRING$(8,65)
+20 PRINT STRING$(8,"MSX")
+ 
+RUN
+AAAAAAAA
+MMMMMMMM
+```
+
+## Related to
+
+`ASC()`, `CHR$()`, `SPACE$()`, `SPC()`, `TAB()`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/STRING$()"

package/resources/programming/basic_wiki/SWAP.md

@@ -0,0 +1,62 @@
+# SWAP
+
+## Effect
+
+Exchanges the contents of two variables.
+
+## Syntax
+
+`SWAP <Variable1>, <Variable2>`
+
+## Parameters
+
+`<Variable1>` and `<Variable2>` are numeric variables, array variables or string variables.
+
+Every type of variable (integer, single precision, double precision, string) can be used. The only restriction is that both variables are of the same type.
+
+## Examples
+
+```basic
+10 X=3:Y=7
+20 A$="PIERRE":B$="JEAN"
+30 CLS
+40 GOSUB 90
+50 SWAP X,Y
+60 SWAP A$,B$
+70 GOSUB 90
+80 END
+90 PRINT "X=";X;"Y=";Y
+100 PRINT
+110 PRINT "A$=";A$;"  B$=";B$
+120 PRINT
+130 RETURN
+ 
+RUN
+X= 3 Y= 7
+
+A$=PIERRE  B$=JEAN
+
+X= 7 Y= 3
+
+A$=JEAN  B$=PIERRE
+```
+
+SWAP can be used to swap values inside an array as well...
+
+```basic
+10 ' Move sprite to 8-directions by using cursor keys (by NYYRIKKI)
+20 FORI=2TO8:XD(I)=SGN(5-I):YD(8-I)=XD(I):NEXT: SWAP YD(0),YD(8):SCREEN2,1:SPRITE$(0)="0HH0"
+30 FORI=0TO1:S=STICK(J):I=-STRIG(J):X=X+XD(S):Y=Y+YD(S):PUTSPRITE0,(X,Y),8:NEXT
+```
+
+## Related to
+
+`LET`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/SWAP"

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

@@ -0,0 +1,38 @@
+# TAB()
+
+## Effect
+
+Inserts the amount of spaces needed to reach a variable position in a `PRINT` or `LPRINT` instruction.
+
+## Syntax
+
+`TAB(<Number>)`
+
+## Syntax
+
+`<Number>` is the position defined by a number between 0 and 255.
+
+If the cursor has already reached the specified position on the same line, the function is ignored.
+
+## Example
+
+```basic
+10 PRINT "MSX";TAB(10);"Forever!"
+20 PRINT TAB(10);"www.msx.org"
+ 
+RUN
+MSX       Forever!
+          www.msx.org
+```
+
+## Related to
+
+`LPRINT`, `PRINT`, `SPACE$()`, `SPC()`, `STRING$()`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/TAB()"

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

@@ -0,0 +1,36 @@
+# TAN()
+
+## Effect
+
+Returns the tangent of a variable.
+
+## Syntax
+
+`TAN(<Number>)`
+
+## Parameter
+
+`<Number>` can be a value, a numeric variable or an expression in radians.
+
+## Example
+
+```basic
+10 PRINT "The tangent of 1 is ";TAN(1)
+20 PRINT "The tangent of -1.23 is ";TAN(-1.23)
+ 
+RUN
+The tangent of 1 is 1.5574077246549
+The tangent of -1.23 is -2.8198157342686
+```
+
+## Related to
+
+`ATN()`, `COS()`, `SIN()`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/TAN()"

package/resources/programming/basic_wiki/TIME.md

@@ -0,0 +1,59 @@
+# TIME
+
+## Effect
+
+This is a timer that is incremented by 1 on each time VDP completes screen draw. Depending of screen refresh rate this happens either 50 or 60 times a second.
+
+This special integer value stored in `JIFFY` (0FC9Eh) can be read or write like a normal integer.
+
+## Syntax
+
+`TIME`
+
+## Examples
+
+```basic
+5 ' European machine
+10 CLS
+20 LOCATE 10,6
+30 PRINT "HH:MM:SS START"
+40 TIME=0
+50 T=TIME
+60 H=INT(T/180000)
+70 T=T-(H*180000)
+80 M=INT(T/3000)
+90 T=T-(M*3000)
+100 S=INT(T/50)
+110 LOCATE 10,8
+120 PRINT USING "##:##:##";H;M;S
+130 GOTO 50
+```
+
+```basic
+5 ' Japanese machine
+10 CLS
+20 LOCATE 10,6
+30 PRINT "HH:MM:SS START"
+40 TIME=0
+50 T=TIME
+60 H=INT(T/216000)
+70 T=T-(H*216000)
+80 M=INT(T/3600)
+90 T=T-(M*3600)
+100 S=INT(T/60)
+110 LOCATE 10,8
+120 PRINT USING "##:##:##";H;M;S
+130 GOTO 50
+```
+
+## Related to
+
+`ON INTERVAL GOSUB`, `RND()`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/TIME"

package/resources/programming/basic_wiki/TROFF.md

@@ -0,0 +1,21 @@
+# TROFF
+
+## Effect
+
+Debug instruction to stop/disable tracing of MSX-BASIC program execution and return to normal program execution mode. Using the `NEW` instruction will also disable the tracing.
+
+## Syntax
+
+`TROFF`
+
+## Related to
+
+`NEW`, `TRON`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/TROFF"

package/resources/programming/basic_wiki/TRON.md

@@ -0,0 +1,39 @@
+# TRON
+
+## Effect
+
+Debug instruction to start/enable tracing of MSX-BASIC program execution. Once executed the line number will be printed to screen each time execution moves to a new line.
+
+## Syntax
+
+`TRON`
+
+## Example
+
+```basic
+10 FOR I=1 TO 3
+20 PRINT I
+30 NEXT
+40 END
+TRON
+Ok
+
+RUN
+[10][20] 1
+[30][20] 2
+[30][20] 3
+[30][40]
+Ok
+```
+
+## Related to
+
+`TROFF`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/TRON"

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

@@ -0,0 +1,66 @@
+# USR()
+
+## Effect
+
+This function calls a subroutine in machine language, passing a value to it. The location of the subroutine has to be defined first, using the `DEF USR` instruction.
+
+The value goes into the system variable `DAC` (&HF7F6, 8 bytes), and its type to `VALTYP` (&HF663, 1 byte). The return value of the function is taken from the same variable, so if it's not modified by the machine language subroutine, it returns the same value that it's passed.
+
+## Syntax
+
+`USR<Number>(<Value>)`
+
+## Parameters
+
+`<Number>` is optional and can range from 0 to 9. When omitted, 0 is assumed.
+
+`<Value>` is a value, a variable or a string that can be retrieved by the machine subroutine.
+
+## Example
+
+```basic
+10 ' Example of USR function usage by NYYRIKKI
+11 ''''''''''''''''''''''''''''''''''''''''''''''''''''
+12 ' ML-Program to read PSG (See SOUND-command)
+13 ''''''''''''''''''''''''''''''''''''''''''''''''''''
+14 DATA"1E 05      LD E,5        ;Illegal function call
+15 DATA"3A 63 F6   LD A,(#F663)  ;VALTYP
+16 DATA"FE 02      CP 2          ;Integer type
+17 DATA"C2 6F 40   JP NZ,#406F   ;Error handler
+18 DATA"2A F8 F7   LD HL,(#F7F8) ;Input integer
+19 DATA"7C         LD A,H
+20 DATA"A7         AND A
+21 DATA"C2 6F 40   JP NZ,#406F   ;>256 = ERROR
+22 DATA"7D         LD A,L
+23 DATA"FE 10      CP 16
+24 DATA"D2 6F 40   JP NC,#406F   ;>15 = Error
+25 DATA"CD 96 00   CALL #96      ;Read PSG
+26 DATA"32 F8 F7   LD (#F7F8),A  ;Return value
+27 DATA"C9         RET
+28 ''''''''''''''''''''''''''''''''''''''''''''''''''''
+29 ' Put program to memory
+30 ''''''''''''''''''''''''''''''''''''''''''''''''''''
+31 DEFINT A-Z:AD=&HC000
+32 READ A$:P=1
+33 B$=MID$(A$,P,2):IF B$="  " THEN 32 ELSE P=P+3
+34 POKE AD,VAL("&H"+B$):AD=AD+1:IF B$<>"C9" THEN 33
+35 ''''''''''''''''''''''''''''''''''''''''''''''''''''
+36 ' Example of how to use USR function
+37 ''''''''''''''''''''''''''''''''''''''''''''''''''''
+38 DEFUSR=&HC000 ' This defines USR() start address
+39 PLAY"CDE"
+40 X=USR(0)+USR(1)*256:IF OX<>X THEN PRINT X:OX=X
+41 IF INKEY$="" THEN 40
+```
+
+## Related to
+
+`DEF USR`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/USR()"

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

@@ -0,0 +1,36 @@
+# VAL()
+
+## Effect
+
+Returns the numerical value of the contents of a string, omitting leading spaces, line feeds and tabs
+
+## Syntax
+
+`VAL(<String>)`
+
+## Parameter
+
+`<String>` is alphanumeric variable or a string that contents a numerical value coded in ASCII code.
+
+## Example
+
+```basic
+10 X=VAL("  1.23")
+20 X=X+1
+30 PRINT X
+ 
+RUN
+2.23
+```
+
+## Related to
+
+`STR$()`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/VAL()"

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

@@ -0,0 +1,50 @@
+# VARPTR()
+
+## Effect
+
+Returns a pointer to either:
+- the beginning of file work area.
+- or the actual memory address of the first byte of the variable passed (in page 2 or 3 of the RAM, starting at &H8000).
+
+In case of file number, the first byte of file work area contains information about how the file was opened. (1= input, 2=output, 4=random) In Disk BASIC 1.x the file work area offsets +1 & +2 point to FCB (File Control Block) associated with the specified file number. In Disk BASIC 2.x offset +1 contains number of the opened file handle.
+
+In case of variable, the pointed variable is stored on 2, 3, 4 or 8 bytes depending on the variable  type: the numbers are coded on 2 bytes for integer, 4 for simple precision or 8 for double precision. In case the variable is string the address of string pointer is returned, this string pointer contains length & address of the string (3 bytes).
+
+See [Math-pack routines](https://www.msx.org/wiki/BASIC_Routines_In_Main-ROM#Math-pack_routines) for more info about the format of each type.
+
+## Syntaxes
+
+`VARPTR(<VariableName>)`
+
+`VARPTR(#<FileNumber>)`
+
+## Parameters
+
+`<VariableName>` can be any variable in use.
+
+`<FileNumber>` is the number of opened file: 1 up to 15 depending on `MAXFILES` or 0 for the tempory file FCB.
+
+## Example
+
+```basic
+10 X=5
+20 V=VARPTR(X)
+30 PRINT V
+40 PRINT "&H"+HEX$(V)
+ 
+RUN
+-32735
+&H802B
+```
+
+## Related to
+
+`CLOSE`, `MAXFILES`, `OPEN`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/VARPTR()"

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

@@ -0,0 +1,103 @@
+# VDP()
+
+## Effect
+
+Reads the content of a VDP register, or writes a value in a VDP register. Reading or writing depends on the use of the instruction in program. Used alone followed by an equal sign (=) and a value implies a write. Otherwise, the instruction will read.
+Note: Some registers can also be combined with `OUT` and/or `INP()` for more possibilities (advanced use).
+
+## Syntaxes
+
+`VDP(<Number>)`
+
+`VDP(<Number>)=<Value>`
+
+The first syntax is used to read, and the next is used to write (except in a condition of course).
+
+## Parameter
+
+`<Number>` specifies a VDP register. The number of registers that are directly accessible varies according the MSX generation. 
+
+|Number|Corresponding VDP register|Modes|Machines|
+|---|---|---|---|
+|0 to 7|Control registers 0 to 7|Read / Write|MSX1 and higher|
+|8|Status register 0|Read|MSX1 and higher|
+|9 to 24|Control registers 8 to 23|Read / Write|MSX2 and higher|
+|26 to 28|Control registers 25 to 27|Read / Write|MSX2+ and higher|
+|33 to 47|Control registers 32 to 46 for graphic commands|Write|MSX2 and higher|
+|-1 to -9|Status registers 1 to 9|Read|MSX2 and higher|
+
+_Notes:_
+- Status registers are only readable.
+- Most control register are readable but in fact it is the corresponding value from the system variables that is read. The corresponding system variables are refreshed at each writing with the `VDP()` instruction or when a Bios routine is called.
+- The command registers (32 to 46) can only be written with the `VDP()` instruction. Reading them leads to an _"Illegal function call"_ error message.
+- The Sprite Color register is not numbered, the values are stocked in VRAM in sprite color table whose base address is  base address of sprite attribute table minus 512 (200 in hexadecimal). Only `VPEEK()` and `VPOKE` can be useful with this register, similar to the Table Base Address Registers (control registers 2 to 6, 10, 11).
+
+`<Value>` can vary between 0 and 255. See `VDP Registers` for detail.
+
+## Combinations
+
+The following combinations extend the possibilities of the `VDP()` instruction on MSX2 and higher:
+
+|VDP()|OUT|OUT|OUT|INP()|VDP()|Description|
+|---|---|---|---|---|---|---|
+|VDP(15) = three senior bits of VRAM address|OUT &H99, 8 low-bits of VRAM address| OUT &H99, type operation 1 + 6 remaining bits of VRAM address|OUT &H98,value|||Indirect access to write a specific VRAM address|
+|VDP(15) = three senior bits of VRAM address|OUT &H99, 8 low-bits of VRAM address|OUT &H99, type operation 0 + 6 remaining bits of VRAM address||PRINT INP(&H98)||Indirect access to read a specific VRAM address|
+|VDP(16) = number of status register (0-9)||||A = INP(&H99)|VDP(16) = 0: PRINT A|Indirect access to read a status register|
+|VDP(17) = number of color palette register (0-15)|OUT &H9A, red and blue data separated by a 0 bit|OUT &H9A, green data||||Indirect access to write a color palette register|
+|VDP(18) = number of control register (0-23, 25-27, 32-46)|OUT &H9B,value|||||Indirect access to write a control register|
+
+## Examples
+
+```basic
+10 FOR I=0 TO 8
+20 A=VDP(I)
+30 B$="00000000"+BIN$(A)
+40 PRINT RIGHT$(B$,8)
+50 NEXT I
+```
+
+Example to modify color 7 on MSX2 and higher with the following RGB values: R=4, G=3, B=5. Binary value of R is 100, of G is 011 and of B is 101, first binary value for `OUT` is 01000101 = 69, second binary value for `OUT` is 00000011 = 3.
+
+```basic
+VDP(17)=7: OUT &H9A,69: OUT &H9A,3
+```
+
+```basic
+5 ' Make a fast copy VRAM to VRAM (HMMC) with VDP instruction
+10 SCREEN 5
+20 CIRCLE(63,105),127,7,,,2
+30 PAINT(0,211),6,7: PAINT(0,0),10,7
+40 IF VDP(-2) AND 1 THEN 40 ' Wait the end of a graphical command
+50 VDP(33)=0: VDP(34)=0 ' X coordinate of source (two bytes)
+60 VDP(35)=0 ' Y coordinate of source
+70 VDP(40)=0 ' Source page
+80 VDP(37)=128: VDP(38)=0 ' X coordinate of destination (two bytes)
+90 VDP(39)=0 ' Y coordinate of destination
+100 VDP(40)=0 ' Destination page
+110 VDP(41)=128: VDP(42)=0 ' Width (two bytes)
+120 VDP(43)=212: VDP(44)=0 ' Height (two bytes)
+130 VDP(46)=0 ' Directions
+140 VDP(47)=&HD0 ' value to execute the HMMC command
+150 IF NOT STRIG(0) THEN 150
+160 ' Notes:
+170 ' The line 40 is only required to wait the end of precedent graphic command
+180 ' The advantage of making a copy with VDP() instructions
+190 ' is that there is no limit imposed by the Basic on the ordinate
+```
+
+## References
+
+- `VDP Ports`
+- `VDP Registers`
+
+## Related to
+
+`BASE()`, `COLOR=`, `INP()`, `OUT`, `SCREEN`, `VPEEK()`, `VPOKE`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/VDP()"

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

@@ -0,0 +1,46 @@
+# VPEEK()
+
+## Effect
+
+Returns the value of a byte within the video memory (VRAM).
+
+## Syntax
+
+`VPEEK (<Address>)`
+
+## Parameter
+
+`<Address>` must be in the range -32768 to 65535.
+
+On MSX1 the usable VRAM area is 0-16383.
+
+On MSX2 and up the usable VRAM area is 0-65535. In order to address all of the 128kB VRAM, `SET PAGE` instruction must be used. Please note that VRAM addressing is different (interleaved) in `SCREEN` modes 7, 8, 10, 11 and 12. However this is important to notice only if you switch between these two addressing modes between reading / writing.
+
+## Example
+
+```basic
+10 SC=PEEK(&HFCAF) ' Current screen mode (= 0/1 for text)
+20 AD=ASC("0")*8+BASE(SC*5+2) '"0" Font address in VRAM
+30 'Make empty & "ball"-font to "0" & "1"
+40 FOR I=0 TO 7:VPOKE AD+I,0:VPOKEAD+I+8,248:NEXTI
+50 VPOKE AD+8,112:VPOKEAD+14,112:VPOKEAD+15,0
+60 A$=INPUT$(1):CLS
+70 IF A$<" " THEN SCREEN SC:END
+80 ' Display ball picture of font A$
+90 AD=ASC(A$)*8+BASE(SC*5+2) 'A$ Font address in VRAM
+100 FOR I=0 TO 7
+110 PRINT RIGHT$("0000000"+BIN$(VPEEK(AD+I)),8)
+120 NEXT I:GOTO 60
+```
+
+## Related to
+
+`BASE()`, `SET PAGE`, `SCREEN`, `VDP()`, `VPOKE`
+
+## Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/VPEEK()"