.CH     CHain file

Syntax:

        .CH  filename [.ext]

See also:

.BI   .IN  

Function:

With the .CH directive you can CHain include files together without going back to the main source file first.

Boundary Sync:

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

Explanation:

The .CHain directive works exactly the same as the .INclude directive if it's encountered in the main source file. It remembers where we are in the main source file, opens a new source file and starts assembling from the beginning of that new source file. If the new source file is finished, it is closed and we continue where we left off in the main source file.

But if the .CHain directive is encountered inside an include file it will close the current include file immediately, opens the new .CHained file and starts assembling from the top of this new file. This effectively chains the new include file to the previous include file without going back to the main source file first.

Please note that all lines that follow the .CH directive in an include file are ignored by the SB-Assembler. They are not even treated as comment lines because they will never be listed in list files. The program line containing .CH, when encountered inside an include file, is always the last line of the file that is interpreted and listed in the list file.

Please note that it is technically possible to create an endless loop this way. The assembler checks if the new chained file name is the same as a still open include or chained file name, giving you a *** Fatal Error: Recursive opening of source file is not allowed error if does.

On Version 2 of the SB-Assembler the .CH directive must be followed by a filename, which may be preceded by a drive letter and a path name according to the normal MS-DOS rules. With Version 3 of the SB-Assembler the filename may be preceded by a path name (and drive letter on Microsoft operating systems) according to the rules of the operatingsystem in use.
The extension .ext is optional. If the extension is omitted the default assembler source extension .asm is used.

Examples:

The example below shows a list file of the lines as they are interpreted by the SB-Assembler. It is not the source file itself, it is part of 3 source files in this case, the main source file, the file DECLARE.asm and the file MACRO.LIB.

         .IN   DECLARE           Called from the main source file

LABEL    .EQ   10                Imaginary part of the .INclude file
          :
          :
          :
ANOTHER  .EQ   $FF
         .CH   C:\LIB\MACRO.LIB  Chain to the file MACRO.LIB

MACRO    .MA                     First line of the chained source file
          :
          :
          :
         .EM                     Last line of the chained source file

         NOP                     We're back in the main source file