# Binary files (system files)

Binary files are used to access binary items through the
OSFI. It is possible to access binary items as if they were normal
D3 items, using AQL, BASIC, FlashBASIC, and so on.

## Conventions

Since a standard D3 item is
generally accessed in a different manner than a binary item, several
conventions are observed:

- The following characters in binary items are converted to the corresponding escape character sequences when read through the binary interface. This conversion is reversed when writing an item. This translation scheme is identical to that used by the UNIX interface, making it possible to store foreign data inside a D3 binary item exactly as it is stored in the foreign file system. An attempt to read a nonbinary item returns the item without any translation. | SM | DLE | _ | | --- | --- | --- | | AM | DLE | ^ | | VM | DLE | ] | | SVM | DLE | \ | | DLE | DLE | DLE |

- When writing an item through the binary interface, the resulting item is always made binary. The length of the actual data (after applying the above translations in reverse) is stored in the item header and is transferred by all standard utilities including copy, t-dump, t-load, save, and restore.

- Older D3 binary items that do not have binary lengths may return a number of 0s (zeros) at the end of the data when that item is read.

## Q-Pointer Format

The format of the binary
Q-pointer is:

| file.name | | |
| --- | --- | --- |
| | 001 | Q |
| | 002 | |
| | 003 | binary:file.name{]x} |
where

| binary | Name of the binary host in the dm,hosts, file. |
| --- | --- |
| file.name | Name of the D3 file. The use of the binary Q-pointer is generally unnecessary for non-D3 files since the drivers accessing those files already convert binary data into a nonbinary, escape format identical to that used by the binary driver. |
| x | Allows manipulation of binary data as an hexadecimal string. |
Optionally, the file may be opened directly by adding the *binary*: prefix to the file name.

Warning:

- When editing binary items with the Update processor, we suggest using the (R option to display nonprintable characters as periods.

- We strongly caution against changing BASIC object code using this utility as doing so may cause aborts and or data corruption. Use the pverify command to verify the validity of FlashBASIC object code.

- Creation of QS-pointers (Q-pointers that are saved using the file-save) pointing to files accessed with this driver is not recommended as nonbinary items are restored as binary.

## Example(s)

The following example displays
the textual portion of some BASIC object code.

```
ct dict binary:bp test
001 ............]}..............:. B..B..who._.. u0.P..E._..
test.]9885.[38516.]7.]bh/]brad.]6.2.0.M0.A2.D2.F5.].^._.
......................................................
```
The following example copies a binary image from an MS-DOS
machine (via an NFS link) into a standard D3 item. Note that the standard
D3 item is *not* a binary item since any binary information
representing escape character sequences is processed as escape character
sequences (whether they are or not) when the data is transferred from
MS-DOS to D3. The second command copies this item into a true D3 binary
item. The data in this binary item corresponds exactly to the data
in the original MS-DOS image.

```
copy /dos PIC001.GIF
 to: (pictures
 1 PIC001.GIF
```

```
copy pictures PIC001.GIF
 to: (bin:pictures2
 1 PIC001.GIF
```

---
Source: https://d3codex.com/systemfiles/binary-files-system-files/ - part of the D3Codex reference.