Chapter 5
Running TATARA
Chapter 4 ran TATARA in one way: tatara hello.as hello.tro. This chapter describes the whole command line: the filenames it takes, what happens when one is left out, every option, and everything TATARA prints on its own behalf. The sessions use HELLO and run in A:\TATARA\EXAMPLES\HELLO.
5.1 The command line
A TATARA command has this form:
tatara [options] source [object [listing]]
The words in square brackets can be left out. source is the file to assemble, object the object file to write, and listing a file for the listing, which section 5.5 describes.
An option is a slash followed by one letter, such as /Q. The letter can be typed in upper or lower case. Options can go anywhere on the line, before, between or after the filenames, and each one is a word of its own: write /l /s, not /ls. TATARA reads only the first letter after a slash and ignores the rest of the word, so /ls is the same as /l.
5.2 Filenames
The filenames are taken in order: the first is the source file, the second the object file, and the third the listing file. A fourth is an error (section 5.6).
5.2.1 No extension is added
TATARA uses each name exactly as it is typed, and adds no extension of its own. The extensions in table 5.1 are the usual ones, and the examples use them, but they have to be typed.
| File | Usual extension |
| source file | .AS (.ASM and .Z80 are also common) |
| object file | .TRO |
| listing file | .LST or .PRN |
Warning. tatara hello looks for a file named HELLO, with no extension, and stops if there is none:
A:\TATARA\EXAMPLES\HELLO>tatara hello Tatara MSX Macro-Assembler v1.2.0 Copyright (C) 2026 Javier Lavandeira https://tatara.tools ERROR: cannot open HELLO
A name can include a drive and a directory, as any MSX-DOS2 filename can: tatara src\main.as obj\main.tro reads the source from the directory SRC and writes the object file to OBJ.
5.2.2 Leaving out the object file
Without a second filename, TATARA reads and assembles the source in the same way, reports any errors, and writes nothing. It is a quick way to find out whether a source has errors:
A:\TATARA\EXAMPLES\HELLO>tatara hello.as Tatara MSX Macro-Assembler v1.2.0 Copyright (C) 2026 Javier Lavandeira https://tatara.tools ended at HELLO.AS(22)
5.2.3 When the object file is written
TATARA reads the source twice, and creates the object file only after the first reading has gone through the whole source. An error found during the first reading stops TATARA before that, so it leaves an object file of the same name as it was. Here BAD.AS holds a single line that is not an instruction, and HELLO.TRO is the same file, with the same time, before and after:
A:\TATARA\EXAMPLES\HELLO>dir hello.tro Volume in drive A: is MAIN Directory of A:\TATARA\EXAMPLES\HELLO HELLO TRO 93 26-09-29 2:15 93 bytes in 1 file 12384K free A:\TATARA\EXAMPLES\HELLO>tatara bad.as hello.tro Tatara MSX Macro-Assembler v1.2.0 Copyright (C) 2026 Javier Lavandeira https://tatara.tools BAD.AS(1): ERROR: not a directive, a macro or an instruction. A:\TATARA\EXAMPLES\HELLO>dir hello.tro Volume in drive A: is MAIN Directory of A:\TATARA\EXAMPLES\HELLO HELLO TRO 93 26-09-29 2:15 93 bytes in 1 file 12376K free
The error message names the file and the line, in brackets, and says what is wrong. Chapter 20 describes the messages.
5.2.4 The object file cannot be the source
If the second filename is the same as the first, TATARA refuses to start, because writing the object file would destroy the source:
A:\TATARA\EXAMPLES\HELLO>tatara hello.as hello.as Tatara MSX Macro-Assembler v1.2.0 Copyright (C) 2026 Javier Lavandeira https://tatara.tools ERROR: the output file is the input file.
TATARA compares the two names as they were typed. It does not notice the same file written in two ways, such as hello.as and a:hello.as, so take care with the order of the names.
5.3 The options
Table 5.2 lists the options for everyday use. Each has a chapter of its own, or is described in this one.
| Option | What it does | Chapter |
| /P | prints a listing on the screen | 18 |
| /L | writes a listing to the file named third | 18 |
| /S | prints the symbol table when the assembly ends | 19 |
| /C | makes symbol and macro names case-sensitive | 7 |
| /Q | leaves out the banner and the summary line | 5 |
| /V | prints the banner, and stops | 5 |
| /? | prints the usage screen, and stops | 5 |
/C changes one thing: without it, Start, START and start are the same name, as they are in M80; with it, they are three different names. Instructions, registers and directives can be written in either case with or without /C.
5.3.1 Options for diagnosis
Three more options appear on the usage screen. They show what TATARA made of a source, and are meant for tracking down a problem in TATARA itself rather than for everyday use.
- /F
-
Instead of listing each line, prints the four fields TATARA divided it into (chapter 6), each in square brackets.
- /M
-
Prints every macro definition as TATARA stored it.
- /H
-
Prints, at the end, how many blocks of the memory TATARA keeps for macros are still in use.
5.4 What TATARA prints
5.4.1 The banner and the summary line
Every run that assembles a source starts with the banner: the program’s name and version, the copyright, and the web address, followed by a blank line. It ends with the summary line, which says where the source ended: the file and the line of its END, or its last line if it has none. Chapter 4 showed both. If END is in an include file, the summary line names that file (chapter 13).
/Q leaves out both. Errors are printed with or without /Q, so a run with /Q that prints nothing is one that succeeded:
A:\TATARA\EXAMPLES\HELLO>tatara /q hello.as hello.tro A:\TATARA\EXAMPLES\HELLO>
/V prints the banner and stops without assembling anything, even if a source is named:
A:\TATARA\EXAMPLES\HELLO>tatara /v Tatara MSX Macro-Assembler v1.2.0 Copyright (C) 2026 Javier Lavandeira https://tatara.tools A:\TATARA\EXAMPLES\HELLO>
5.4.2 The usage screen
/? prints the banner and the usage screen, a summary of the command line, and stops. Typing tatara with no filename at all prints the same screen.
A:\TATARA\EXAMPLES\HELLO>tatara /? Tatara MSX Macro-Assembler v1.2.0 Copyright (C) 2026 Javier Lavandeira https://tatara.tools Usage: TATARA [options] <source> [output] TATARA /P [options] <source> [output] TATARA /L [options] <source> <output> <listing> Options: /P Assemble to the screen /L Write a listing file, named third on the line /S Print the symbol table when the assembly ends /C Make symbol and macro names case-sensitive /F Print the fields of each line, for diagnosis /M Print every macro definition, for diagnosis /H Print how many heap blocks are still in use /Q Omit the banner above and the summary line /V Print the program version /? Print this screen <source> : The file to assemble, M80 syntax (.as, .asm or .z80) <output> : The relocatable object it produces, usually .tro <listing> : The listing file, usually .lst or .prn
The screen fills the 24 lines of the MSX display, so the line with the command scrolls off the top.
5.5 Listings
A listing is a printout of the source as TATARA assembled it, divided into pages with a heading on each. TATARA produces one when /P or /L is given, or when a third filename is named.
/P prints the listing on the screen. The session below shows only its beginning:
A:\TATARA\EXAMPLES\HELLO>tatara /p hello.as Tatara MSX Macro-Assembler v1.2.0 Copyright (C) 2026 Javier Lavandeira https://tatara.tools Tatara v1.2.0 29-Sep-26 PAGE 1 ; HELLO.AS - the smallest complete program. ; ; One source, one object, one .COM. It prints a line and gives the ; machine back to MSX-DOS.
Each page starts with a form feed, which clears the MSX screen, so a listing longer than one page goes past faster than it can be read. /P is useful for a quick look at a short source.
/L writes the listing to the file named third on the line, with the address and the bytes of each line in front of it:
A:\TATARA\EXAMPLES\HELLO>tatara /l hello.as hello.tro hello.lst Tatara MSX Macro-Assembler v1.2.0 Copyright (C) 2026 Javier Lavandeira https://tatara.tools ended at HELLO.AS(22)
The listing includes the lines of every file the source includes, and ends with a table of all the symbols, so even HELLO.LST is about 20 KB long: most of it is MSXDOS.INC. Chapter 18 describes what a listing contains and how a source controls it.
5.6 When TATARA does not start
Table 5.3 lists the messages TATARA prints when it stops before assembling a single line. Some of them come before the banner, because TATARA checks the command line first.
Message |
Meaning |
ERROR: Tatara needs MSX-DOS2 or Nextor. |
The MSX is running MSX-DOS1. |
ERROR: Tatara needs a memory mapper. |
The MSX has no memory mapper (chapter 1). |
ERROR: unknown option. |
A slash is followed by a letter that is not one of TATARA’s options, or by nothing. |
ERROR: too many filenames. |
More than three filenames were given. |
ERROR: the output file is the input file. |
The object file has the same name as the source. |
ERROR: cannot open name |
The source file does not exist, or its name was typed without the extension. |
ERROR: cannot create name |
The object file cannot be written, for instance because the disk is full or write-protected. |
Two of them look like this:
A:\TATARA\EXAMPLES\HELLO>tatara /x hello.as ERROR: unknown option. A:\TATARA\EXAMPLES\HELLO>tatara a b c d ERROR: too many filenames.