.TW     Target Write

Syntax:

         TW  string | #expression [,string | #expression [,...]]

See also:

.CP   .EF   .LF   .LI   .SF   .TF  

Function:

This directive allows you to write strings of text directly to the target file.

Boundary Sync:

In Version 3 of the SB-Assembler this directive will perform a boundary sync.

Explanation:

This command will flush the current target file's line buffer and then it writes a string directly to the file. The string can be anything, but usually holds some remarks or programming device commands.

I can think of two main reasons why you would want to write to the target file directly.
The first reason is to enter some comments in the target file. Be careful though, not all programming tools allow you to enter comments in the target file. Comment lines usually begin with a single quote or an exclamation point.
The second reason is to embed programming device commands directly in the target file. This way the target file can be sent directly to the programming device during assembly. Remember though to remove the commands from the target file if you intend to share it with others who don't have such sophisticated programming devices.

The syntax of the .TW directive is somewhat comparable with that of the .AS directive, with the only exception that it is not possible to create strings with a negative ASCII polarity. You may use either a delimited string, or a separate byte per parameter. Multiple parameters must be separated by commas.
You may even use characters from the extended IBM character set if you like.

Please note that strings are not terminated with a CR or LF automatically in version 2! If you do want to end the string with a CR/LF pair you will have to enter them as normal byte parameters.
Version 3 will write an End Of Line at the end of each .TW string.

This directive should be used with some care because you can make the target file useless if you write something to it that your programming device doesn't understand. Also be very careful not to write directly to a binary formatted file because they rarely allow comments or other commands.

Strings may not be empty and must be terminated by the same delimiter that was used to start the string, otherwise an error will reported.
Bytes must evaluate to a value from 0 to 255, otherwise you'll get a Out of range error.

The .TW directive is only parsed during pass 2 of the assembly process. Errors will not be discovered during pass 1.

Please note that it is not possible to put comments or commands at the absolute end of the target file, unless the target file is a binary or HEX unformatted file. The reason for this is very simple. The "end of file" line is only written just before the target file is closed. Therefore the "end of file" line is always the last line to be written to the target file, simply because the file is closed immediately afterwards. And you can't write to an already closed file anymore.
This may cause some problems if your programming device requires some instructions to be given at the very end. Usually these problems occur only when the target file is sent directly to the COM port. In that case we can simply overcome the problem by reopening an new target file to the COM port, this time as binary format.

With version 3 it is no longer possible for .TW to write to unformatted binary files.

Examples:

         .TF   TWTEST.HEX,INT
         .AS   /Test/
         .TW   /'Remark line/,#$0D,#$0A
         .AS   /Test/

The program above generates the target file below:

:04000000546573745C
'Remark Line
:040004005465737458
:00000001FF

Omitting the #$0D,#$0A part of the .TW directive in the example above would result in the probably useless file below:

:04000000546573745C
'Remark Line:040004005465737458
:00000001FF

Please note that the program below will generate a remark line just before the "end of file" record in the target file. The "end of file" line is always the last line of the target file!

         .TF   TWTEST.HEX,INT
         .AS   /Test/
         .AS   /Test/
         .TW   /'Remark line/,#$0D,#$0A
:04000000546573745C
:040004005465737458
'Remark Line
:00000001FF