21 Running TANREN

Chapter 21
Running TANREN

TANREN joins object files made by TATARA into one program. This chapter describes how to run it: the command line, how the output file is named, the options, what TANREN prints, and the messages it gives before it starts. The chapters after it describe the rest in detail: link files (chapter 22), where TANREN looks for object files (chapter 23), how a program is laid out in memory (chapter 24), how names are matched between modules (chapter 25), the kinds of output file (chapter 26), and the error messages (chapter 27).

Like TATARA, TANREN needs MSX-DOS2 or Nextor, and a memory mapper.

21.1 The command line

The command line is tanren, followed by the names of the object files and any options:

tanren [options] object [object...]

An object file named without an extension gets .tro, so tanren main sub links MAIN.TRO and SUB.TRO. The case of the letters does not matter, in names or in options.

These two modules make a small program. MAIN.AS calls greet, which is in SUB.AS. Each includes MSXDOS.INC, for the names of the MSX-DOS functions and the system macro, and SUB.AS also includes ASCII.INC, for CHR_CR and CHR_LF, the carriage return and the line feed that end the line it prints (chapter 14):

; MAIN.AS - calls greet, in another module, and ends the program. 
                include msxdos.inc 
                extrn   greet 
                cseg 
start:          call    greet 
                system  _TERM0 
                end     start

; SUB.AS - greet prints a line. 
                include msxdos.inc 
                include ascii.inc 
                public  greet 
                cseg 
greet:          ld      de,msg 
                system  _STROUT 
                ret 
                dseg 
msg:            db      'Hello from TANREN.',CHR_CR,CHR_LF,'$' 
                end

Each is assembled into an object file, and TANREN links the two into MAIN.COM:

A:\>tatara /q main.as main.tro 
A:\>tatara /q sub.as sub.tro 
A:\>tanren main sub 
Tatara MSX Linker v1.2.0 
Copyright (C) 2026 Javier Lavandeira 
https://tatara.tools 
 
2 modules, 16 records, ends at EOF. 
Wrote MAIN.COM, 0100-0125 (38 bytes), entry 0100. 
A:\>main 
Hello from TANREN.

21.1.1 The order of the object files

TANREN places the modules in memory in the order they are named: the code of the first at memory address 0100h, the code of the next straight after it, and so on (chapter 24 describes where the data goes). MSX-DOS always starts a .COM program at memory address 0100h, so the module whose code must run first has to be named first.

Named the other way round, the same two modules make a program that starts with the code of greet:

A:\>tanren sub main 
... 
WARNING: SUB.COM is entered at 0100, not at 0109. 
2 modules, 16 records, ends at EOF. 
Wrote SUB.COM, 0100-0125 (38 bytes), entry 0109.

The summary line says that start, the address on the END line of MAIN.AS, is now at 0109h, but a .COM program cannot start there: MSX-DOS runs whatever is at 0100h. TANREN warns about it before the summary, even with /Q, and still writes the file. The warning comes whenever a file written without /B has an entry address other than its first address. With /B, the entry address goes into the BLOAD header and there is no warning (chapter 26).

21.1.2 Spaces between names

The names and the options are separated by spaces or tabs. Anything else, a comma included, is part of the name:

A:\>tanren main,sub 
... 
ERROR: cannot open MAIN,SUB.TRO

An option can go anywhere on the line, before the names, after them or between them.

21.2 The output file

TANREN names the output file after the first object file, with the extension .com, in the same directory as that object file. With /B, which writes a file for BLOAD, the extension is .bin instead:

A:\>tanren /b main sub 
... 
Wrote MAIN.BIN, 0100-0125 (38 bytes), BLOAD header, entry 0100.

/O: names the output file, with the name written straight after the colon:

A:\>tanren main sub /o:prog.com 
... 
Wrote PROG.COM, 0100-0125 (38 bytes), entry 0100.

The name is used exactly as written. TANREN adds no extension to it, so /o:prog writes a file called PROG, with no extension, which MSX-DOS will not run as a command.

The output file may not be one of the object files, so that a mistake on the command line cannot overwrite an input:

A:\>tanren /o:sub.tro main sub 
... 
ERROR: the output file SUB.TRO is also an input file.

TANREN compares the names as they are written, so it does not notice the same file reached by two different paths.

21.3 The options

Table 21.1 lists TANREN’s options. An address is one to four hexadecimal digits, with no h, as in /p:4000. /D:, /O: and /P: need the colon: /p alone is an unknown option.

Option	What it does	Chapter
/B	writes a BLOAD header on the output file, whose default extension becomes .bin	26
/D:addr	starts the data segments at addr	24
/M	prints the segment and group tables, and the symbols	25
/O:file	names the output file	this chapter
/P:addr	starts the code segments at addr	24
/Q	leaves out the banner and the summary line	this chapter
/R	prints every record in the object files, for diagnosis	appendix F
/V	prints the banner, and stops	this chapter
/?	prints the usage screen, and stops	this chapter

Table 21.1: TANREN’s options.

/P: changes where the code starts, and the summary line shows it:

A:\>tanren /p:4000 /o:high.bin main sub 
... 
Wrote HIGH.BIN, 4000-4025 (38 bytes), entry 4000.

21.4 What TANREN prints

TANREN starts with a banner, as TATARA does, and ends with a summary of two lines:

2 modules, 16 records, ends at EOF. 
Wrote MAIN.COM, 0100-0125 (38 bytes), entry 0100.

The modules are the object files TANREN read, and the records are the pieces of information in them: the bytes of each segment, the names, and the places where TANREN has to fill in an address (appendix F).
ends at EOF says that each object file ended where its last record said it would. If one has anything after that, the line says AND BYTES AFTER THEM. instead, and a line before it names the file. TATARA does not make such a file, so assemble that module again (section 27.3).
Wrote names the output file, the addresses of its first and last bytes, and how many bytes that is. With /B, the file on the disk is seven bytes longer than that, because of the BLOAD header, and the line says so.
entry is the address named on an END line. It is written into the header by /B. Without /B, it should be the first address of the file, or TANREN warns.

When none of the modules has any bytes to write, the second line is Nothing to write: no module has any content. instead.

/Q leaves out the banner and the summary. Errors are printed with or without it, so a link with /Q that prints nothing has succeeded. /V prints the banner and stops, and /?, or tanren with no object file at all, prints the banner and the usage screen:

A:\>tanren 
Tatara MSX Linker v1.2.0 
Copyright (C) 2026 Javier Lavandeira 
https://tatara.tools 
 
Usage:  TANREN [options] <object|@list> [more...] 
 
Options:  /B Write a BLOAD header on the output file 
          /D:<addr> Start the data segments at <addr> 
          /M Print the segment and group tables 
          /O:<file> Write the image to <file> 
          /P:<addr> Start the code segments at <addr> 
          /Q Omit the banner above and the summary line 
          /R Print every record in the object files 
          /V Print the program version 
          /? Print this screen 
 
<object>  : A .tro file; .tro is assumed when you leave it off. 
@<list>   : A file of the same words; ; is a comment, .lnk 
            is assumed. 
<addr>    : One to four hex digits, as in /P:4000. 
<file>    : The output. Default: the first object with .com 
            (.bin with /B). It may not be an input file.

21.5 The 127-character command line

MSX-DOS gives a command 127 characters, counting the name of the program and the spaces. At the prompt, COMMAND2 accepts no more: every key after the 127th only beeps. In a batch file, a longer line is not run at all, and COMMAND2 prints *** Command too long.

A program of many modules can need more than that. A link file holds the same words in a file, as many as needed, and the command line names only the file: tanren @prog (chapter 22).

If some other program starts TANREN with a longer line, MSX-DOS cuts it at 127 characters without saying so. When TANREN’s command line is exactly 127 characters long, it cannot tell whether anything was cut, and it warns, even with /Q:

WARNING: the command line is 127 characters, which is all 
MSX-DOS gives - anything past it was dropped in silence. 
Use @<file> if a module is missing.

21.6 When TANREN does not start

Table 21.2 lists the messages TANREN prints before it links anything. The first three come before the banner.

Message	Meaning
ERROR: Tanren needs MSX-DOS2 or Nextor.	The MSX is running MSX-DOS1.
ERROR: Tanren needs a memory mapper.	The MSX has no memory mapper.
ERROR: unknown option.	An option TANREN does not have, or /D, /O or /P without a colon.
ERROR: cannot open NAME.TRO	No object file of that name was found (chapter 23 describes where TANREN looks).
ERROR: the output file NAME is also an input file.	The output file would overwrite an object file.

Table 21.2: Messages before linking.

A mistake found while linking, such as a name that no module defines, is described in chapter 27.

Chapter 21Running TANREN