.BI     Binary Include

Syntax:

        .BI  filename.ext [,format]

See also:

.CH   .IN  

Function:

The .BI directive copies the contents of a binary file to the current target file from the current location. This enables you to include for example sampled speech, HTML pages, or images in to your programs, to name but a few use cases.

Boundary Sync:

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

Explanation:

The filename may contain a path name, and a drive letter for Microsoft based operating systems. If no path is given the current directory should hold the file to be included. No default extension is assumed, so if the file has an extension it should be included in the filename.

Binary include files can not be nested. Binary include files can't open other include files by themselves, but it is also not allowed to include a binary file from within a normal include file.
Version 3 of the SB-Assembler doesn't have this restriction any more. There you may use the .BI directive from within an included source file.

If no format is specified the binary include file will be treated as a plain binary file. All bytes are copied as they appear in the file. No attempt is made by the SB-Assembler to figure out in what format the file originally was written!

The format parameter can have any of the following names:

BINUnformatted binary file (default)
E52Elektor's EMON52 format
FPCFour Packed Code formatted file
HEXUnformatted HEX file
INTIntelHex formatted file
MOTMotorola S19, S28 or S37 formatted file
SIGSignetics formatted file
TEKTektronix formatted file

For Version 2 of the SB-Assembler only the first character of the format name is sufficient to select a particular file format. All other characters on the program line following that character will be ignored and treated as comments.
For Version 3 of the SB-Assembler the formats should be given as shown in the table above.

Please Note for Version 2: That the Motorola format is called MOT here, and not S19, S28 or S37 like it is with the .TF directive. Using S19, S28 or S37 as parameter will result in a Binary format error messages if you feed a Motorola formatted file because the SB-Assembler is expecting a Signetics formatted file (which starts with an S).

Address fields of all formatted file formats are ignored. Segment records in Intel HEX files only carry address information and will be ignored too. All data bytes are copied in the order of appearance from the binary include file.

Formatted files don't have to be terminated with the end of file record. No error is given if the end of file record is missing.

Formatted files may contain remark lines. An empty line or a line beginning with ! ; * " or ' will be treated as a remark line.
Records in a formatted file may not contain any spaces. Leading and trailing spaces are ignored though. The only exception to this rule is the EMON52 format where bytes are separated by spaces by default.
The binary include file will be terminated immediately if any error is encountered.

If a label is present in the label field of the source line containing the .BI directive it will be assigned the address of the first byte of the binary include file.

A program line that contains a .BI directive can be listed if the list option is switched on. The generated bytes are never listed though.

Examples:

0000-            BITMAP   .BI  SAMPLE,INT