Host Operating System Files

Through the OSFI, it is possible to access host operating system files as if they were D3 items, using AQL, BASIC, FlashBASIC, and so on. This section describes the format of the Q-pointer, the file structure and the access rules.

Conventions

Since the D3 file system structure is fundamentally different from that of the host operating system, a few conventions have to be made to map an object from one file system to the other:

A D3 item is mapped onto a host operating system file.
By default, the D3 attribute marks are converted to newline characters (decimal 10). This conversion can optionally be disabled.
By default, if a host operating system file contains the usual D3 delimiters, they are converted in a sequence of two characters, DLE (decimal 16) followed by a displayable character:

SM	DLE _
AM	DLE ^
VM	DLE ]
SVM	DLE \
DLE	DLE DLE

For UNIX: Text files generally are terminated by a new line, while D3 text items do not have a trailing attribute mark (the D3 equivalent of a new-line). By default, the terminating new-line (which is converted to an attribute mark) is stripped when the item is read into D3, and re-appended when that item is again exported to UNIX. This provides a comfortable interface for text items, but it will add an additional new line when writing binary items. Therefore, this default mechanism must be disabled with the A option when modifying binary text, and especially when saving a host operating system directory.
Optionally, a section of white-space preceding a block of alphanumeric text that aligns to a tab-stop can be replaced by the appropriate number of tab characters. This process is reversed if the item is retransferred to the host operating system.
A D3 file is mapped onto one or more host operating system directories. The main data level of the file is mapped to a directory that has the same name. The dictionary of the file is a subdirectory called .DICT. Other data levels are mapped onto subdirectories of the .DICT directory, prefixed with a period. The dictionary is optional, and required only if data is actually stored in the dictionary. If the dictionary is missing, the file system opens it, but an error is returned (no item, on a read, and file write-protected on a write) if the application actually tries to access items in it.

For example, consider the D3 file bp, with its directory and two data levels bp:

+------+------+------+

| | | |

item1 item2 item3 .DICT

+-------+

| |

ditem1 ditem2

This seemingly complex structure tries to make the most common case (flat file) as simple as possible, and to make the internal objects (.DICT) invisible by default to a D3 TCL list or UNIX ls command.

Q-Pointer Format

The format of the Q-pointer is:

file.name
	001	Q
	002
	003	hostname:directory{]options}

hostname	Item-ID in the host file (for example, UNIX, Windows, dos, and so on).
directory	Name of the directory onto which the main data level of the file is mapped. This directory can be any valid directory name (local directory, mounted removable medium, NFS directory). Special files (device, pipe, and so on) can also be specified with some restrictions.
options	Alphanumeric string that controls the behavior of the driver. Spaces can be inserted in the option string for readability. It follows the directory name, separated by a Value Mark. NOTE—When options appear in the q-pointer, these will take precedence, but the drive letter will be extracted from the hostname (driver definition).
	tn	Converts white space preceding text aligned to a tab-stop into a series of tabs. By default no conversion occurs. Note that this conversion option may modify the data (especially binary items) and is therefore only suggested for text files. The valid range of numbers for n is 2 through 9.
	a	Adds an extra attribute mark when files are moved into D3, and removes the attribute mark when the item is placed back in the host operating system. This option is absolutely necessary when saving and/or copying between different files or to backup media. Without this, nontextual items may have an extra new-line appended to them when added to the final destination.
	b	Enables the ability to read and write binary data. No data translation occurs.
	c	Specifies the target is a special character file. This option imposes some restrictions.
	d	For Windows: When copying Windows or MS-DOS text files from D3 to the host OS, replaces CR/LFs with attribute marks. When copying Windows or MS-DOS text files from the host OS to D3, replaces attribute marks with CR/LFs.
	lx	For Windows: Enables accessing a file without specifying the MS-DOS drive in the file name. x specifies the MS-DOS drive letter where the file is stored. For example, to access a file located in MS-DOS drive A:, use the la option.
	n	Suppresses the conversion of attribute marks to new lines. By default, when writing a D3 item, the attribute marks are converted to make the text easy to edit. A trailing attribute mark is added at the end of the file when it is written with this option unless the A option is specified.
	o	Prevents the conversion of tabs to spaces when copying files from D3 to the host operating system.
	r	Use raw data. Reads and writes data much faster than the default and/or using some of the other options. Cannot be specified with the A or T options. If a character 255 (segment mark) is read from a file, it is converted into an underscore character.
	s	Case-insensitive item-ID and file names. File names and item-IDs are converted to lowercase and makes them case-insensitive.
	x	Used with the binary driver to allow manipulation of binary data as an hexadecimal string. See the new host definition 'binx'.

Item Locks

Item locks are not supported.

Q-Pointers to Special Files

It is possible to specify a special character file (pipe, device) as the directory, specifying the c option in the Q-pointer. However, there are restrictions:

Special files cannot have a dictionary or other data levels.
Only open, read, write and close operations are permitted. The delete command is ignored. Sequential access (for example, list) returns no item present.
When writing, there is no guarantee that the data is written as one block. This is particularly important on pipes for which the notion of atomic write is critical.
When reading, the device must be able to report the size of the data using the system call fstat(). For example, a pipe may appear empty (size 0) at one point, and then contain data. The application must be prepared to handle empty items.

Case-Sensitivity

When the s option is specified in the Q-pointer, the file names and item-IDs are converted to lowercase. However, the driver does not detect files that may exist in the same directory with a different case. For example /bp/TEST and /bp/test are two different items. The user must be very careful when using tools to access files otherwise used from D3 through a Q-pointer with the s option.

The data in the file is never converted.

WARNING

The delete-account function does not clear or delete any data that is pointed to by super Q-pointers. Only the D3 links to that information are cleared.

Example(s)

Create a Q-pointer to a FlashBASIC program file located on UNIX:

pgm
	001	Q
	002
	003	unix:/home/dev/bp
		t4

Use the default conversion along with tab expansion.

Create a UNIX Q-pointer to a UNIX directory to be saved as part of the regular D3 file save:

bob
	001	Q
	002
	003	unix:/home/bob
		a

Use the a option to keep an additional attribute mark on the D3 data (which is stripped when written back to UNIX). This extra attribute mark ensures that all data can be saved and restored without corruption due to translation.