4 A first program

Chapter 4
A first program

This chapter builds and runs two of the examples: HELLO, a program in one source file, and TWOMOD, the program in two modules from chapter 2. It shows every command, and what TATARA and TANREN print in reply.

4.1 Before you start

You need the installation of chapter 3: the two programs on the PATH, the TATARA environment variable set, and the examples in A:\TATARA\EXAMPLES. This chapter works in A:\TATARA\EXAMPLES\HELLO, and then in A:\TATARA\EXAMPLES\TWOMOD. Go to the first of them:

A:\>cd \tatara\examples\hello 
A:\TATARA\EXAMPLES\HELLO>

4.2 The program

HELLO.AS is the smallest complete program: it prints a line and returns to MSX-DOS2.

; HELLO.AS - the smallest complete program. 
; 
; One source, one object, one .COM. It prints a line and gives the 
; machine back to MSX-DOS. 
 
                include msxdos.inc      ; BDOS, _STROUT, _TERM0 and the 
                                        ;   "system" macro, found through 
                                        ;   TATARA - see BUILD.BAT 
 
                cseg                    ; RELOCATABLE code. Nothing here 
                                        ;   knows its own address, and the 
                                        ;   linker chooses one - 0100h for a 
                                        ;   .COM, unless /P: says otherwise 
 
start:          ld      de,msg 
                system  _STROUT 
                ld      c,_TERM0 
                jp      BDOS 
 
msg:            db      "Hello from Tatara.",13,10,"$" 
 
                end     start           ; where it starts, for the linker

Taking it a few lines at a time:

The first lines start with a semicolon. A semicolon starts a comment: TATARA ignores it and the rest of the line. Comments are for the people who read the program. Chapter 6 describes how a line is written.
include msxdos.inc reads the file MSXDOS.INC at that point, as if its lines were written there. That file defines the names BDOS, _STROUT and _TERM0, and the macro system (chapters 13 and 14). TATARA finds it through the TATARA environment variable.
cseg starts the code segment: what follows is relocatable code, and TANREN decides where it goes (chapter 10).
start: and msg: are labels. start is the address of the first instruction, and msg the address of the text.
ld de,msg and system _STROUT ask MSX-DOS2 to print the text at msg, up to the $ that ends it.
ld c,_TERM0 and jp BDOS end the program, and MSX-DOS2 shows its prompt again.
db puts bytes into the program: the text, then 13 and 10, which move to the start of the next line, then the $ (chapter 11).
end start ends the source file, and tells TANREN that the program starts at start.

4.3 Assembling it

Assemble HELLO.AS into the object file HELLO.TRO:

A:\TATARA\EXAMPLES\HELLO>tatara hello.as hello.tro 
Tatara MSX Macro-Assembler v1.2.0 
Copyright (C) 2026 Javier Lavandeira 
https://tatara.tools 
 
ended at HELLO.AS(22)

TATARA prints its banner, reads the source file, and prints a summary: where the source ended, here at line 22 of HELLO.AS, the line with END. It has written HELLO.TRO, the object file of chapter 2: machine code with holes in it.

Warning. If TATARA is not set, TATARA cannot find MSXDOS.INC, and stops:
A:\TATARA\EXAMPLES\HELLO>tatara hello.as hello.tro 
Tatara MSX Macro-Assembler v1.2.0 
Copyright (C) 2026 Javier Lavandeira 
https://tatara.tools 
 
ERROR: cannot open MSXDOS.INC 
    included from HELLO.AS(6)
 
The second line says where the file was asked for: line 6 of HELLO.AS. Set the environment variable as in section 3.4, and assemble again.

4.4 Linking it

Link HELLO.TRO into the program HELLO.COM:

A:\TATARA\EXAMPLES\HELLO>tanren /o:hello.com hello.tro 
Tatara MSX Linker v1.2.0 
Copyright (C) 2026 Javier Lavandeira 
https://tatara.tools 
 
1 module, 7 records, ends at EOF. 
Wrote HELLO.COM, 0100-0121 (34 bytes), entry 0100.

The option /O: names the program file. Without it, TANREN names the program after the first object file, so here the name would be HELLO.COM anyway; this manual gives /O: so that the name can be seen in the command.

The first line of the summary says what TANREN read: one module, made of seven records, up to the end of the file (chapter 21). The second says what it wrote: HELLO.COM, which occupies the addresses 0100h to 0121h, 34 bytes, and starts at 0100h. The directory now holds all three files:

A:\TATARA\EXAMPLES\HELLO>dir hello.* 
 Volume in drive A: is MAIN 
 Directory of A:\TATARA\EXAMPLES\HELLO 
 
HELLO    AS        603 26-09-28 17:32 
HELLO    TRO        93 26-09-29  1:27 
HELLO    COM        34 26-09-29  1:27 
 730 bytes in 3 files   12664K free

The name of the volume, the dates and the free space will be different on your MSX.

4.5 Running it

Type the program’s name:

A:\TATARA\EXAMPLES\HELLO>hello 
Hello from Tatara.

MSX-DOS2 loaded HELLO.COM at 0100h, the address TANREN placed it at, and started it there. Two commands took the program from source file to running program.

4.6 The build file

Every example has a build file, BUILD.BAT: a batch file that runs the commands that build the example. HELLO’s runs the two commands of this chapter, with the option /Q, which leaves out the banner and the summary. An error is printed with or without /Q, so a run that prints nothing is a run that succeeded. Type type build.bat to read it.

Warning. A build file sets the TATARA environment variable when it starts, and clears it when it finishes. After you run one, TATARA is empty for the rest of the session, and the next program that includes a file stops with cannot open. Set the environment variable again, as in section 3.4, or reset the MSX so that AUTOEXEC.BAT sets it.

This manual has you type the commands instead. It is the better way to learn them.

4.7 A program in two modules

TWOMOD is the program of chapter 2: MAIN.AS prints two lines by calling putstr, which is defined in PUTSTR.AS. Go to its directory, and assemble the two source files, one command for each:

A:\TATARA\EXAMPLES\HELLO>cd ..\twomod 
A:\TATARA\EXAMPLES\TWOMOD>tatara main.as main.tro 
Tatara MSX Macro-Assembler v1.2.0 
Copyright (C) 2026 Javier Lavandeira 
https://tatara.tools 
 
ended at MAIN.AS(23) 
 
A:\TATARA\EXAMPLES\TWOMOD>tatara putstr.as putstr.tro 
Tatara MSX Macro-Assembler v1.2.0 
Copyright (C) 2026 Javier Lavandeira 
https://tatara.tools 
 
ended at PUTSTR.AS(32)

The two object files could be named on TANREN’s command line, as HELLO.TRO was. This example uses a link file instead: a text file that holds what would otherwise be typed on the command line. TWOMOD.LNK names the program and the two object files:

; TWOMOD.LNK - the link, in a file instead of on the command line. 
; 
; TANREN reads this when it is given @TWOMOD, and the words in it are 
; the words it would have read from the command line. A ; starts a 
; comment and the rest of the line is ignored. 
; 
; MSX-DOS gives a command line 127 characters and cuts a longer one 
; without saying so. That is the whole reason this exists: the 
; assembler is itself linked from a file of nineteen module names. 
 
/o:twomod.com 
 
main.tro putstr.tro

A program with many modules needs a link file, because an MSX-DOS2 command line holds at most 127 characters (chapter 22). TANREN reads a link file when its name is given after an @:

A:\TATARA\EXAMPLES\TWOMOD>tanren @twomod 
Tatara MSX Linker v1.2.0 
Copyright (C) 2026 Javier Lavandeira 
https://tatara.tools 
 
2 modules, 14 records, ends at EOF. 
Wrote TWOMOD.COM, 0100-0154 (85 bytes), entry 0100.

These are the numbers of table 2.3: MAIN at 0100h, PUTSTR straight after it, and 85 bytes in all, ending at 0154h. Run the program:

A:\TATARA\EXAMPLES\TWOMOD>twomod 
Two modules, one program. 
The linker joined them.

4.8 What is next

Part II describes the assembler in full, starting with how to run it (chapter 5). Part IV has a worked guide to each of the other examples.

Chapter 4A first program