Appendix K
The include files

The nine include files in A:\TATARA\INCLUDE hold 903 names and one macro. They save writing addresses and numbers by hand; they do not explain them. This appendix says what each file holds and where the names in it are described. Chapter 14 shows how to use them.

The names were taken from the MSX-Datapack, and are spelt as it spells them, except where a file says otherwise. Each name has a comment of one line in its file, and each file starts with a comment that explains how to use what is in it. What a routine needs in its registers, and what it gives back, is in the books listed in section K.10.

Table K.1 lists the files in the order of this appendix, the order in which a program is most likely to need them.

A program for MSX-DOS needs MSXDOS.INC, and usually ERRORS.INC. A program that runs from a cartridge, or is loaded from BASIC, needs BIOS.INC and WORKAREA.INC instead, and SUBROM.INC for what the MSX2 added. The rest are for programs that work with the hardware directly.

Figure K.1 shows where the addresses that the files name are in the Z80’s 64 KB.

K.1 MSXDOS.INC

The MSX-DOS and MSX-DOS2 function numbers, from _TERM0 (00h) to _REDIR (70h), with BDOS, the entry at 0005h, and the system macro, which loads C and calls BDOS (section 14.3). The names are the official ones, those of the MSX-DOS2 sources, with their leading underscore. Numbers below 31h are in MSX-DOS1 too; 31h and above are MSX-DOS2 only.

Read about them in the MSX-DOS2 function specification, and in the MSX-Datapack, volume 3.

K.2 ERRORS.INC

The error codes of MSX-DOS and MSX-DOS2, from .NCOMP (0FFh) down to .OVDEST (81h), in four groups: disk errors, the errors the functions return, the errors that end a program, and the errors of the command interpreter. The names start with a dot, as the manual prints them. The file runs downwards, because the codes were given out counting down from 0FFh.

Read about them in the MSX-DOS2 function specification, and in the MSX-Datapack, volume 3.

K.3 BIOS.INC

The entry points of the MAIN ROM, from CHKRAM (0000h) to WRRES (017Dh), in address order. The entries added for the MSX2 and the MSX2+ are marked in the file. The entries that the MSX turbo R added, for changing the CPU and for the PCM, are not in it.

Under MSX-DOS, only five of these can be called directly; the others need an inter-slot call (section 14.4).

Read about them in the MSX2 Technical Handbook and the MSX-Datapack, volume 2.

K.4 WORKAREA.INC

The system work area, the variables the BIOS and BASIC keep in RAM, from DISKVE (0F323h) to EXPSLT (0FFFFh). The comment of each name starts with its length in bytes, and the area is not one run of bytes: the gaps between the groups belong to the system and are not published.

Read about them in the MSX2 Technical Handbook and the MSX-Datapack, volume 2.

K.5 SUBROM.INC

The entry points of the SUB ROM, which the MSX2 added, from SUBROM_GRPPRT (0089h) to SUBROM_WRTCLK (01F9h). The SUB ROM is in another slot, so none of them can be called directly: they are reached through EXTROM or SUBROM, in BIOS.INC. Every name starts with SUBROM_, because the SUB ROM uses some of the MAIN ROM’s names for other routines at other addresses.

Read about them in the MSX2 Technical Handbook and the MSX-Datapack, volume 2.

K.6 HOOKS.INC

The hooks, the five-byte entries in RAM that the system calls at fixed moments, from H.KEYI (0FD9Ah) to ENAINT (0FFD4h). They are inside the work area, and EXTBIO, the entry of the extended BIOS, is among them. Two hooks have two names each, an older one and the one MSX-MIDI gave them.

Read about them in the MSX2 Technical Handbook and the MSX-Datapack, volumes 2 and 3.

K.7 PORTS.INC

The I/O ports, from IO_MUSREG (07Ch) to IO_MAPSEG (0FCh), and a few memory addresses that behave like ports, such as those of the MSX-MUSIC and MSX-AUDIO cartridges. The MSX has no standard names for its ports, so these names are Tatara’s own: a port is IO_ and a name, and is written with three hex digits.

Read about the ports in the MSX2 Technical Handbook, the MSX turbo R Technical Handbook and the MSX-Datapack, volumes 2 and 3.

K.8 ASCII.INC

The control codes, from CHR_NUL (0) to CHR_DEL (127), with CHR_SPACE, CHR_EOF, the end of a text file, and the two quotation marks. The values are decimal, unlike those of the other files, and each comment says what the MSX does when the code is printed.

Read about them in the MSX-Datapack, volume 2.

K.9 EXTBIO.INC

The extended BIOS: the device numbers, the function numbers and the offsets in the jump tables of the devices that answer through it, such as MSX-DOS2’s mapper routines, the RS-232C, MSX-AUDIO, MSX-MIDI and MSX-JE. Every name starts with EXTBIO_ and the name of the device. The file ends with the FM BIOS of MSX-MUSIC, whose names start with FMBIOS_: these are addresses in the MSX-MUSIC ROM, which is in another slot.

Read about them in the MSX-Datapack, volumes 2 and 3.

K.10 Further reading

These are the books and documents the descriptions above refer to. The MSX-Datapack and the MSX turbo R Technical Handbook were published in Japanese only.

MSX2 Technical Handbook

(ASCII). The BIOS, the SUB ROM, the work area, the hooks, the VDP and the I/O ports of the MSX2. It was also published in English.

MSX-Datapack

(ASCII), three volumes. The complete reference, with the BIOS and the SUB ROM in volume 2, and MSX-DOS2 in volume 3. The include files were made from it.

MSX turbo R Technical Handbook

(ASCII). What the MSX turbo R added: the R800, the CPU switching, the PCM and the MIDI.

MSX-DOS2 Function Specification

and MSX-DOS2 Program Interface Specification (ASCII). The functions, their registers and the error codes, and how a program runs under MSX-DOS2.