@nataliapc/mcp-openmsx 1.1.14 → 1.2.2

package/resources/programming/basic_wiki/CALL.md

@@ -0,0 +1,391 @@
+# CALL
+
+## Effect
+
+`CALL` is an instruction reserved to extend the existing BASIC instructions.
+
+_Notes:_
+- If you have more then one extension providing an extended instruction with the same name, only the instruction provided by the ROM in a lower numbered slot will be taken into account by the BASIC interpreter.
+- See the existing extended instructions for MSX-BASIC.
+
+## Syntax
+
+`CALL <Instruction> (<Parameter>,<Parameter>...)`
+
+_Note: `CALL` can be replaced by the character underscore `_`. A space is not required after this character._
+
+## Parameters
+
+`<Instruction>` is the name of extended instruction.
+
+`<Parameter>` can take different forms (numeric variable, value, string, etc) and several parameters can follow. Do not put parentheses if there is no parameter.
+
+## Example of CALL-instruction implementation in ROM programs
+
+When ROM cartridge has standard "AB"-header, the slot attributes will be automatically filled during boot time.
+
+```assembly
+; Example of String handling in BASIC CALL-instructions
+; Made By: NYYRIKKI 16.11.2011
+; Edit by: zPasi 13.3.2014: added a call to FRESTR, to free the temporary string in 
+;       routine EVALTXTPARAM
+
+	OUTPUT "PRINT.ROM"
+	ORG     #4000
+ 
+;---------------------------
+; External variables & routines
+CHPUT   EQU     #A2
+CALBAS	EQU	#159
+ERRHAND EQU     #406F
+FRMEVL  EQU     #4C64
+FRESTR	EQU	#67D0
+CHRGTR  EQU     #4666
+VALTYP  EQU     #F663
+USR     EQU     #F7F8
+PROCNM	EQU	#FD89
+ 
+;---------------------------
+; ROM-file header
+	DEFW    #4241,0,CALLHAND,0,0,0,0,0
+ 
+;---------------------------
+; General BASIC CALL-instruction handler
+CALLHAND:
+	PUSH    HL
+	LD	HL,CMDS	        ; Table with "_" instructions
+.CHKCMD:
+	LD	DE,PROCNM
+.LOOP:	LD	A,(DE)
+	CP	(HL)
+	JR	NZ,.TONEXTCMD	; Not equal
+	INC	DE
+	INC	HL
+	AND	A
+	JR	NZ,.LOOP	; No end of instruction name, go checking
+	LD	E,(HL)
+	INC	HL
+	LD	D,(HL)
+	POP	HL		; routine address
+	CALL	GETPREVCHAR
+	CALL	.CALLDE		; Call routine
+	AND	A
+	RET
+ 
+.TONEXTCMD:
+	LD	C,0FFH
+	XOR	A
+	CPIR			; Skip to end of instruction name
+	INC	HL
+	INC	HL		; Skip address
+	CP	(HL)
+	JR	NZ,.CHKCMD	; Not end of table, go checking
+	POP	HL
+	SCF
+	RET
+ 
+.CALLDE:
+	PUSH	DE
+	RET
+ 
+;---------------------------
+CMDS:
+; List of available instructions (as ASCIIZ) and execute address (as word)
+	DEFB	"UPRINT",0      ; Print upper case string
+	DEFW	_UPRINT
+ 
+	DEFB	"LPRINT",0      ; Print lower case string
+	DEFW	_LPRINT
+ 
+	DEFB	0               ; No more instructions
+ 
+;---------------------------
+_UPRINT:
+	CALL	EVALTXTPARAM	; Evaluate text parameter
+	PUSH	HL
+	CALL    GETSTRPNT
+.LOOP
+	LD      A,(HL)
+	CALL    .UCASE
+	CALL    CHPUT  ;Print
+	INC     HL
+	DJNZ    .LOOP
+ 
+	POP	HL
+	OR      A
+	RET
+ 
+.UCASE:
+	CP      "a"
+	RET     C
+	CP      "z"+1
+	RET     NC
+	AND     %11011111
+	RET
+
+;---------------------------
+_LPRINT:
+	CALL	EVALTXTPARAM	; Evaluate text parameter
+	PUSH	HL
+	CALL    GETSTRPNT
+.LOOP
+	LD      A,(HL)
+	CALL    .LCASE
+	CALL    CHPUT  ;Print
+	INC     HL
+	DJNZ    .LOOP
+ 
+	POP	HL
+	OR      A
+	RET
+ 
+.LCASE:
+	CP      "A"
+	RET     C
+	CP      "Z"+1
+	RET     NC
+	OR      %00100000
+	RET
+
+;---------------------------
+GETSTRPNT:
+; OUT:
+; HL = String Address
+; B  = Lenght
+ 
+	LD      HL,(#F7F8)
+	LD      B,(HL)
+	INC     HL
+	LD      E,(HL)
+	INC     HL
+	LD      D,(HL)
+	EX      DE,HL
+	RET
+ 
+EVALTXTPARAM:
+	CALL	CHKCHAR
+	DEFB	"("             ; Check for (
+	LD	IX,FRMEVL
+	CALL	CALBAS		; Evaluate expression
+	LD      A,(VALTYP)
+	CP      3               ; Text type?
+	JP      NZ,TYPE_MISMATCH
+	PUSH	HL
+	LD	IX,FRESTR         ; Free the temporary string
+	CALL	CALBAS
+	POP	HL
+	CALL	CHKCHAR
+	DEFB	")"             ; Check for )
+	RET
+ 
+CHKCHAR:
+	CALL	GETPREVCHAR	; Get previous basic char
+	EX	(SP),HL
+	CP	(HL) 	        ; Check if good char
+	JR	NZ,SYNTAX_ERROR	; No, Syntax error
+	INC	HL
+	EX	(SP),HL
+	INC	HL		; Get next basic char
+ 
+GETPREVCHAR:
+	DEC	HL
+	LD	IX,CHRGTR
+	JP      CALBAS
+ 
+TYPE_MISMATCH:
+	LD      E,13
+	DB      1
+ 
+SYNTAX_ERROR:
+	LD      E,2
+	LD	IX,ERRHAND	; Call the Basic error handler
+	JP	CALBAS
+ 
+;---------------------------
+	DS      #8000-$
+```
+
+## Example of CALL-instruction implementation in BIN-file
+
+When a `CALL-instruction` extension is loaded after boot, user must put the address of `CALL` instruction handler to 4th & 5th byte of memory bank and mark that the extension is available (bit 5) to the slot attribute table manually.
+
+Please note that if the program is erased from memory the next `CALL` instruction execution may crash the computer if the bit from table is not manually cleared.
+
+The correct address inside slot attribute table can be calculated using formula:  
+`ADDRESS = Main slot * 16 + Sub slot * 4 + Memory Bank + #FCC9`
+
+```assembly
+	OUTPUT "X.BIN"
+ 
+	; USAGE:
+	; BLOAD "X.BIN",R
+	; CALL X == CLS
+ 
+SLTATR  EQU #FCC9
+PROCNM	EQU #FD89
+CLS     EQU #C3
+ 
+	; BASIC header:
+ 
+	DB #FE
+	DW BEGIN,END,START
+ 
+	ORG #C004
+BEGIN:
+	; Call handler pointer in Bank 3 fixed offset 4
+	DW CALLHAND
+START:
+	LD A,(#F344) ; SlotID of RAM in Bank 3 (#C000-#FFFF)
+	             ; This variable is ready available only when disk drive is present.
+	AND A
+	JP M,.SKIP   ; SlotID has SubSlot information
+	AND 3
+.SKIP
+	AND 15
+	LD E,A
+	RLCA
+	RLCA
+	RLCA
+	RLCA
+	OR E
+	AND 60
+	LD D,0
+	LD E,A
+	LD HL,SLTATR+3 ; +3 for Bank 3
+	ADD HL,DE
+	SET 5,(HL)     ; Set bit 5 to enable CALL handler
+	RET
+ 
+CALLHAND:
+ 
+	PUSH HL
+	LD HL,PROCNM
+	LD A,(HL)
+	CP "X"
+	JR NZ,.NOT_FOR_ME
+	INC HL
+	LD A,(HL)
+	AND A           ; Commands are zero terminated
+	JR NZ,.NOT_FOR_ME
+	CALL CLS
+	POP HL
+	AND A           ; Clear carry to inform CALL is handled.
+	RET
+ 
+.NOT_FOR_ME:
+ 
+	POP HL
+	SCF
+	RET
+END:
+```
+
+## List of MSX tR default CALL instructions sorted by slots
+
+### Slot #0-2 (MSX-Music)
+
+|||
+|---|:-:|
+|AUDREG||
+|APPEND MK|*|
+|APEEK|*|
+|APOKE|*|
+|BGM||
+|CONT MK|*|
+|COPY PCM|*|
+|CONVP|*|
+|CONVA|*|
+|INMK|*|
+|KEY ON|*|
+|KEY OFF|*|
+|LOAD PCM|*|
+|MDR||
+|MK VOICE|*|
+|MK VEL|*|
+|MK VOL|*|
+|MK TEMPO|*|
+|MK STAT|*|
+|MK PCM|*|
+|MUSIC||
+|REC PCM|*|
+|STOPM||
+|SET PCM|*|
+|SAVE PCM|*|
+|SYNTHE|*|
+|TRANSPOSE||
+|TEMPER||
+|VOICE||
+|VOICE COPY||
+|PAUSE||
+|PLAY||
+|PLAY PCM|*|
+|PCM PLAY||
+|PCM REC||
+|PCM FREQ|*|
+|PCM VOL|*|
+|PLAY MK|*|
+|PITCH||
+
+(*) Detected, but not supported (causes _illegal function call_).
+
+
+### Slot #3-1 (Kanji ROM)
+
+||
+|---|
+|PALETTE|
+|CLS|
+|AKCNV|
+|JIS|
+|SJIS|
+|KACNV|
+|KEXT|
+|KINSTR|
+|KLEN|
+|KMID|
+|KNJ|
+|KTYPE|
+|KANJI|
+|KANJI0|
+|KANJI1|
+|KANJI2|
+|KANJI3|
+|ANK|
+
+### Slot #3-2 (Disk ROM)
+
+|||
+|---|:-:|
+|SYSTEM||
+|FORMAT||
+|CHDRV|*|
+|CHDIR|*|
+|MKDIR|*|
+|RMDIR|*|
+|RAMDISK|*|
+
+(*) Only when DOS2 is active.
+
+### Slot #3-3 (Panasonic Mapper)
+
+|||
+|---|:-:|
+|MWP|*|
+|HIRO|**|
+
+(*) Only in Panasonic `FS-A1GT`  
+(**) Only in Panasonic `FS-A1ST`
+
+`CALL MENU` in Panasonic 2+ machines.
+
+## Related to
+
+`ATTR$()`, `CMD`, `IPL`, `USR`
+
+# Compatibility
+
+MSX-BASIC 1.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/CALL"

package/resources/programming/basic_wiki/CALL_ADJUST.md

@@ -0,0 +1,40 @@
+# CALL ADJUST
+
+## Effect
+
+Enables the internal lightpen interface.
+
+It is required to use `CALL ADJUST` before using `PAD()` with the values 20 to 23.
+
+This instruction enables the lightpen interface (bit6 of the VDP R#8) but not the lightpen interrupts (bit5 of the VDP R#0), and sets the system variables XOFFS=23 and YOFFS=0.
+
+Since it doesn't enable the light pen interrupts, this command is not enough to make `GTPAD`/`PAD()` functional. The lightpen interrupts will have to be enabled via VDP register write.
+
+This instruction is available **only** with the MSX2 computers manufactured by _Daewoo_:
+- AVT CPC-300
+- Bawareth Perfect MSX2
+- Daewoo CPC-300
+- Daewoo CPC-400
+- Daewoo CPC-400S
+- Talent DPC-300
+- Wandy CPC-300
+
+It is also maybe available with the _Sanyo MPC-X Graphic Expander Unit_ and the _Sanyo MPC-27_ computer.
+
+## Syntax
+
+`CALL ADJUST`
+
+# Related to
+
+`PAD()`
+
+## Compatibility
+
+Only MSX2 computers manufactured by _Daewoo_.
+
+This instruction is part of Hangul BASIC on the Korean MSX2 computers.
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/CALL_ADJUST"

package/resources/programming/basic_wiki/CALL_IMPOSE.md

@@ -0,0 +1,28 @@
+# CALL IMPOSE
+
+## Effect
+
+Sets superimposition mode.
+
+## Syntax
+
+`CALL IMPOSE (<Mode>)`
+
+## Parameter
+
+`<Mode>` is a value between 0 and 2 to set video mode.
+- 0 for computer screen (internal synchronization).
+- 1 for superimpose (composite video).
+- 2 for external video.
+
+## Related to
+
+`COLOR`, `SCREEN`, `SET VIDEO`
+
+## Compatibility
+
+P-BASIC
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/CALL_IMPOSE"

package/resources/programming/basic_wiki/CALL_OPTIONS.md

@@ -0,0 +1,26 @@
+# CALL OPTIONS
+
+## Effect
+
+Launches a special screen where you can select printer options:
+
+- width (many possibilities).
+- printer type (MSX, Arabized MSX, Arabic only, Neutral).
+
+When you confirm your choices with the RETURN key, you go back to the calling program.
+
+## Syntax
+
+`CALL OPTIONS`
+
+## Related to
+
+`CALL CHCOPY`, `CALL HCOPY`
+
+## Compatibility
+
+Arabic BASIC 2.01 and higher (only Sakhr MSX2)
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/CALL_OPTIONS"

package/resources/programming/basic_wiki/CALL_PAUSE.md

@@ -0,0 +1,119 @@
+# CALL PAUSE
+
+`CALL PAUSE` is a standard instruction for _MSX turbo R_, but it is also an extended instruction available in _ChakkariCopy Basic_, _DM-System2 Basic_ and _Hitachi Basic_.
+
+# CALL PAUSE as standard MSX-BASIC instruction
+
+## Effect
+
+Stops execution of a BASIC program for the specified time.
+
+## Syntax
+
+`CALL PAUSE (<Time>)`
+
+## Parameter
+
+`<Time>` is waiting time exprimed in milliseconds. The value can be between 0 and 65535.
+
+_Note: You can interrupt the execution during the waiting period by pressing `CTRL`+`STOP`._
+
+## Example
+
+```basic
+CALL PAUSE(1000)
+```
+
+## Using
+
+When `CALL PAUSE` is being executed, interrupt is enabled. Even when `CALL PAUSE` is being executed, you can quit the program by the `CTRL` + `STOP` keys.
+
+This instruction is used when you want to take a timing without being affected by the CPU execution speed.
+
+## Related to
+
+`TIME`, `WAIT`
+
+## Compatibility
+
+MSX-BASIC 4.0 or higher
+
+# CALL PAUSE in ChakkariCopy Basic
+
+## Effect
+
+Puts the cartridge into `PAUSE` mode.
+
+_Note: the paused program can only be resumed by pressing the `PAUSE` button. It cannot be resumed by software._
+
+## Syntax
+
+`CALL PAUSE`
+
+## Related to
+
+`CALL SCHANGE`
+
+## Using
+
+In the `PAUSE` mode it's only possible to print a hardcopy by pressing the `COPY` button or to resume execution by pressing the `PAUSE` button. It's the same operation as pressing the `PAUSE` button on the cartridge.
+
+## Compatibility
+
+ChakkariCopy BASIC
+
+# CALL PAUSE in DM-System2 Basic
+
+## Effect
+
+Stops execution  of a BASIC program for the specified time.
+
+_Note: You can interrupt the execution during the waiting period by pressing `CTRL`+`STOP`._
+
+## Syntax
+
+`CALL PAUSE (<Time>)`
+
+## Parameter
+
+`<Time>` is waiting time exprimed in milliseconds. The value can be between 0 and 65535.
+
+## Example
+
+`CALL PAUSE(1000)`
+
+## Using
+
+When the `CALL PAUSE` is being executed, interrupt is enabled. Even when the `CALL PAUSE` is being executed, you can quit the program by the `CTRL` + `STOP` keys.
+
+This instruction is used when you want to take a timing without being affected by the CPU execution speed. It's exactly the same instruction as the standard `CALL PAUSE` for _MSX Turbo R_, but can be used also on _MSX2_ and _MSX2+_.
+
+## Related to
+
+`CALL INTWAIT`, `CALL VDPWAIT`, `CALL WAIT`
+
+## Compatibility
+
+DM-System2 BASIC
+
+# CALL PAUSE in Hitachi Basic
+
+## Effect
+
+Puts the built-in data reader of the _Hitachi MB-H2_ computer in pause mode.
+
+## Syntax
+
+`CALL PAUSE`
+
+## Related to
+
+`CALL FF`, `CALL PLAY`, `CALL REC`, `CALL REW`, `CALL STOP`
+
+## Compatibility
+
+Hitachi BASIC version 1
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/CALL_PAUSE"

package/resources/programming/basic_wiki/CALL_PCMPLAY.md

@@ -0,0 +1,60 @@
+# CALL PCMPLAY
+
+## Effect
+
+Plays a PCM audio file on a _MSX turbo R_ computer. It must be previously loaded in computer RAM or VRAM with `BLOAD` or in an array with `COPY`.
+
+If the computer mode is `Z80` mode, the mode is automatically switched to the `R800` mode before the execution, and after finishing the `Z80` mode is restored.
+
+If the `STOP` key is pushed during the playing, the program execution is quit and returns to BASIC.
+
+## Syntaxes
+
+`CALL PCMPLAY(@<StartAddress>,<EndAddress>,<SamplingFrequency>,S)`
+
+`CALL PCMPLAY(<Array>,<length>,<SamplingFrequency>)`
+
+The `S` and `<Length>` parameters are optional. Parameters can not end with a comma alone.
+
+## Parameters
+
+`<StartAddress>` and `<EndAddress>` are used to specify the area of the computer RAM (or VRAM). The `<start address>` needs always to be preceded by `@`.
+
+`<SamplingFrequency>` is a number between 0 and 3 to choose one of the four available sampling frequencies:
+
+```
+ 0 = 15.75 KHz
+ 1 = 7.875 KHz
+ 2 = 5.25 KHz
+ 3 = 3.9375 KHz
+```
+
+If you specify the sampling rate to 15.75 KHz under `Z80` mode or `R800` ROM mode, you get _"Illegal function call"_ error message.
+
+The parameter `S` is used to play from VRAM instead of RAM. This can be done in any screen mode but only the active pages are valid when the screen mode is higher than 4.
+
+`<Array>` must be a numeric type variable array.
+
+`<Length>` can generally be omitted. When specified, the playing of an array will be stopped when this length is reached.
+
+_Note: The format of the data is absolute binary and 1 to 255 is a normal data. 0 is a special data and causes 0 level (127) to be outputted by a number of the cycles specified by 1 byte proceeding the 0._
+
+## Example
+
+```basic
+10 CLEAR 300,&HB000
+20 BLOAD"PCMTEST.BIN"
+30 CALL PCMPLAY(@&HB000,&HDFFF,1)
+```
+
+## Related to
+
+`BLOAD`, `CALL PCMREC`, `COPY`
+
+## Compatibility
+
+MSX-BASIC 4.0 or higher
+
+## Source
+
+Retrieved from "https://www.msx.org/wiki/CALL_PCMPLAY"