general.unix.q.ptr Definition/General


Command general.unix.q.ptr Definition/General
Applicable release versions: AP 6.2
Category General (155)
Description accessing a Unix file from the Pick file system.
Through the 6.2 OSFI, it is possible to access Unix files as if they were Pick items, using Access, Pick BASIC, FlashBASIC, etc... This section describes the format of the q-pointer, the file structure and the access rules.

Conventions :

Since the Pick file system structure is fundamentally different from the Unix file systems, a few conventions have to be made to map an object from one file system to the other:

- A Pick item is mapped onto a Unix file.

- By default, the Pick attribute marks are converted to newline characters (decimal 10). This conversion can be optionally disabled.

- Again by default, if a Unix file contains the usual Pick delimiters, they are converted in a sequence of two characters, DLE (decimal 16) followed by a displayable character:

- Unix text files generally are terminated by a new-line, while Pick text items do not have a trailing attribute mark (The Pick equivalent of a new-line). By default, the terminating new-line (which would be converted to an attribute mark) is stripped when the item is read into Pick, 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 Unix directory.

- Optionally, a section of white-space preceding a block of alpha-numeric text which aligns to a tab-stop can be replaced by the appropriate number of tab characters. This process is reversed if the item is re-transferred to Unix.

- A Pick file is mapped onto one or more Unix directories. The main data level of the file is mapped to a directory which has the same name. The dictionary of the file, is a sub-directory called ".DICT". Other data levels are mapped onto sub-directories of the ".DICT" directory, prefixed with a period. The dictionary is optional, and required only if if data is actually stored in the dictionary. If the dictionary is missing, the file system will open it, but an error will be 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 Pick file 'bp', with its directory and two data levels "bp":

| | | |
item1 item2 item3 .DICT
| |
ditem1 ditem2

This seemingly complex structure aims at making the most common case (flat file) as simple as possible, and to make the internal objects ('.DICT' ) invisible by default to a Pick TCL 'list' or Unix 'ls' command.

Q-Pointer Format :

The format of the Unix Q-pointer is:
001 Q
003 unix:directory{]options}

'directory' is the name of the Unix directory onto which the main data level of the file is mapped. This directory can be any valid directory name (local directory, mounted Unix removable medium, NFS directory). Special files (device, pipe, etc..) can also be specified with some restrictions.

'options' is an alphanumeric string which 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:
t n Convert 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.

A Specifies that an extra attribute mark always be added when Unix files are moved into Pick, and that that attribute mark always be removed when that item is placed back in Unix. This option is absolutely necessary when saving and/or copying between different files or to backup media. Without this, non-textual items may have an extra new-line appended to them when added to the final Unix destination.

c Specifies the target is a special character file. This option imposes some restrictions (see the section Special Files below).

n Suppress the conversion of Attribute Marks to New Lines. By default, when writing a Pick item, the AM are converted to make the text easy to edit with Unix editors. Note a trailing New Line is added at the end of the Unix file when it is written, unless this option is used.

s Case insensitive item-id and file names. With this option, the filenames and item-ids are converted in lower case, to make them case insensitive. See the section about case sensitivity below.

Item Locks :
Item locks are not supported.

Unix Q-Pointers to Special Files :
It is possible to specify a special character file (pipe, device) as the Unix 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. DELETE is ignored. Sequential access (eg LIST) returns 'no item present'.
- When writing, there is no guarantee that the data is written as one block. This is specially 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 Unix 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 Unix q-pointer, the filenames and item-ids are converted to lower case. 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 Unix tools to access files otherwise used from Pick through a Unix q-pointer with the 'S' option.
The data is the file is never converted.
Examples :
1. Create a Unix q-pointer to a Pick/BASIC program file located on Unix:
    001 Q
    003 unix:/home/dev/bp
Use the default conversion along with tab expansion.

3. Create a Unix q-pointer to a Unix directory to be saved as part of the 
regular Pick file save:
    001 QS
    003 unix:/home/bob
Use the "A" or append option to keep an additional attribute mark on 
the Pick 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.
Related general.super.q.ptr