Relearning MSX #22: Programming for MSX-DOS (part 2)

Posted by in How-to, MSX, Retro, Technology | September 02, 2015

The previous post ended with the description of the first of the three MSX-DOS functions: I/O. This time we will see an introduction to the other two: file management and program execution.

File management

Without doubt, the most useful peripheral in a computer system is the storage device, whether it’s a floppy disk drive, a hard disk, optical media, or some kind of flash storage attached via a generic interface.

Early MSX computers supported only cassette tape as storage media. It was slow and somewhat unreliable, but it was very cheap.


A cassette data recorder used in personal computers during the mid-80s. This model supported reading tapes at 2400 bps, twice the normal speed (MSX Magazine, May 1985) (Click to enlarge)

Besides the low speed, the big drawback of tapes was that the only way to access the data on them was sequentially: in order to access a program in a tape, you had to either read all other data stored before it, or manually rewind the tape to the location of the program you wanted to load. Needless to say, this wasn’t very fun.


Typical gaming session when loading games from cassette tape during the 80s.

Later there were external 3.5 inch floppy disk drives that you could plug to the MSX via a disk drive interface plugged to the cartridge slot, and also MSX computers that came standard with at least an internal floppy disk drive. Compared to cassette tapes, floppy disks are much faster, have more capacity, and allow us to access any program or file stored in them in any random order. However, storing data on a floppy disk is more complex than saving to or loading programs from a tape.

Managing the disk was the operating system’s main function in those days, thus the name MSX-DOS, from Disk Operating System.

A file on a floppy disk (or a hard drive, for that matter) is composed of two parts:

  • A chunk of data somewhere in the disk
  • A file name (or directory entry) that gives a name, and points to the data on disk


MSX-DOS manages this connection between file names and data. It also provides the functionality that programs require to work with files, so when we write a new program we don’t need to worry about how the files are actually stored on the disk and other annoying low-level details.

The original MSX-DOS supported 13 internal commands that you could type at the command prompt (you should know what it is already, but don’t hesitate to ask if you don’t!). Internal commands are those that the operating system understands without having to read from the disk.

COPYCopy files
DATEDisplay or set the system date
DEL / ERASEDelete file(s)
DIRList all files
FORMATFormat (initialize) a disk
MODEChanges the number of rows displayed on the screen
PAUSEUsed in batch commands. Pauses and waits for the user to press a key (optionally with a message)
REMAlso for use in batch commands. Adds a comment.
REN / RENAMEChange a file's name
TIMEDisplay or set the system time
TYPEPrints the contents of a file on the screen
VERIFYEnable/disable verifying that files have been stored correctly on the disk

MSX-DOS2 supports many more of these internal commands because it adds support for environment variables, directories, etc. We’ll see these as we need them.

Program execution


External commands

Programs stored in the disk that can run under MSX-DOS have the extension .COM. We call these user programs, or also external commands. We run these by entering the name in the command line, without the .COM extension, and optionally especifying the drive and path:


Running external command VF.COM, stored in the \FREEWARE\1\ directory in drive A: (Click to enlarge)

Under MSX-DOS2, the PATH environment variable tells the system where to look in the disk when we enter in the command line a program name that doesn’t exist in the current path. We’ll see how this works in a future post.

How programs are executed

When we enter a program name in the command line, the operating system loads the program in memory and then transfers control to it. MSX-DOS loads every program at memory address 100h. This is precisely why the example program in chapter #20 had this line near the beginning:

ORG    100h

This is a more detailed view of what happens when MSX-DOS loads a program:


First, MSX-DOS reads the file from the disk and stores it starting from memory address 100h. After storing the program in memory it transfers control to memory address 100h via the Z80 CALL instruction. This is why programs can return to MSX-DOS when they terminate by using the RET instruction.

In the previous diagram we see three memory areas:

The system scratch area

Memory addresses 0 to FFh contain some data used by MSX-DOS to communicate with user programs (such as the command line parameters), and it also contains the jump address for system calls. We’ll see this area in more detail in a future post.

The TPA (Transient Program Area)

From memory address 100h until the start of the system area we have the TPA. This is where MSX-DOS stores user programs when they’re running. Programs can use this area freely for executable code, program data, etc.

Where exactly does the system area start? We can find out by examining the memory address stored in addresses 6 and 7. That’s the MSX-DOS entry address. In other words, every time we do a CALL 0005h in assembler we’re transferring control to the MSX-DOS code that lives at the start of the system area.

The system area

This area contains not only the MSX-DOS routines, but also system variables that are vital to the proper operation of both user programs and the operating system. Do not modify anything in this area unless you know very well what you’re doing.


This time we’ve also touched a couple basic concepts: management of files on disk and how MSX-DOS runs programs. We’ll leave the technical details for future chapters for now.

In the next post…

Get ready for some action. The last few articles haven’t been very technical, but the next one will be. We’ve touched some MSX-C and some assembler, and advanced users are asking about ways to use assembler routines from C. That will be the subject of the next post. It will be more technical than what we’ve seen yet, but that’s fine. If there’s anything in the article that you don’t understand, then probably you don’t need it yet and can safely ignore it and leave it for later.

In any case, you can always ask! Just post in the comments below.

5 comments on “Relearning MSX #22: Programming for MSX-DOS (part 2)

  1. Francesc on said:

    Great article!

    You use the phrase “we will see this or that in in a future post” A LOT.

    Perfect then, there will be loads of future posts! :)

  2. Having a lot of experience with cassettes in my MSX past, I can’t confirm that the Skip stuff is a typical gaming session. As you have to write down where programs begin (using the tape counter), you can simply tell the MSX to load the first program it encounters. So you practically never use the name of the file to load the program. MSX-BASIC reports the name of the file it found and that’s your confirmation that everything is going alright, but that’s all practical usage of it…

    • Sorry, to clarify: when you want to load a certain program, the workflow is thus as follows:
      1. insert the tape the program is on
      2. rewind the tape
      3. reset the counter
      4. fast forward the tape until you’re at the tape counter value where the program begins
      5. you type in the loading instruction (you have to know it), e.g. CLOAD (so, without the file name indeed)

      Comfortable? No! I was so glad when I moved on to disk drive :)

      • Hahaha yes, I already explain that in the article (last sentence before the Skip: Skip: Skip: screenshot). It was an attempt at a bit of humor. ;-)

        I also got sick of the BLOAD”CAS:”,R / RUN”CAS:” after a while, but now I miss it. I guess I’m getting old(er).

Leave a Reply

Your email address will not be published. Required fields are marked *