The Datafile PD-CD 3/PDCD_3.iso/pocketbk/utilsm/psionics/fileio

Text File | 1995-01-17 | 13KB | 293 lines

PSIONICS FILE - FILEIO
======================
Filing system IO interfaces
Last modified 1994-09-16
===========================

This document describes the use of the IO interface for accessing the filing
system. For general discussion on IO, see the Psionics file DEVICES.

The filing system is a special device driver, called "FIL:". Whenever an open
fails to locate a device, or if the name opened is not that of a device driver,
the driver name "FIL:" is prefixed, and the open is retried. Thus the original
name becomes the channel name. For file IO, the channel name is, or controls,
the file name.

An addition filing system called "TXT:" also exists. This is identical to
"FIL:", and accesses the same files, except that all files are assumed to
be text files (see below). There is no normal need to use "TXT:"; instead,
use "FIL:" and open files with a format component of 2 (see below).


Filing system organisation
--------------------------

The filing system is divided into one or more nodes. A node has a name ending
with a double colon. The nodes most commonly met are:
  "LOC::"  files in the internal ram and on attached SSDs and 3-Link pods
  "REM::"  files accessed via the 3-Link (not the 3-Link pod itself)
  "ROM::"  files in the internal rom

A node may be monolithic, or may be divided into devices. The devices available
and the format of their names depends on the node. For example:
  LOC::  devices are usually "M:", "A:", "B:", and possibly "C:".
  REM::  device names depend on the remote system
  ROM::  monolithic
Unless explicitly stated otherwise, the term device includes monolithic nodes.

A node may be flat or hierarchical. In the former case, each device is a single
directory which contains files. In the latter, each device has a directory
hierarchy starting with a root directory; each directory can hold files and
other directories.

The format of file and directory names depends on the node. Various system
calls (such as FilChangeDirectory) can be used to manipulate file names. The
LOC:: node uses \ as a directory name terminator (the root directory is just
called "\"), and allows both file and directory names to consist of up to 8
characters, a dot, and then up to 3 characters. The ROM:: node is flat, and
uses the same rules for file names.

The full pathname of a file consists of the node, the device (if any), the path
of directories (if any), and the filename, all joined with no intervening
spaces. It is limited to 128 characters.

The system has the concept of a current path. When any filename does not
include a filing system, device, or directory, that of the current path is
used. For example, if the current path is "LOC::A:\APP\", then the names
"XXX\YYY", "REM::\QQQ", and "M:ZZZ" actually refer to "LOC::A:\APP\XXX\YYY",
"REM::A:\QQQ", and "LOC::M:\APP\ZZZ".


Opening files
-------------

There are two kinds of open: open for scanning, and open for access. These
are both done with the IOOPEN keyword, but once the file is open, it is used
in totally different ways.


Opening for scanning
--------------------

A file is opened for scanning by specifying one of the following modes to
IOOPEN:
    $0030 = scan a directory
    $0050 = scan a node
    $0060 = scan all nodes
    $0040 = format a device
    $8040 = format a device in low density

In each case, once the file is opened, it is scanned or formatted by making
several calls to function 1 until one fails with error -36 (end of file).
[Note: the IOREAD keyword should be equivalent to function 1. However, there
have been reports of problems with using it.] Once a call fails, the handle
should be closed. All these calls will ignore the length variable (argument 2).

Scanning generates a list of names. There are three different scans that can
be done:
* Scan all nodes; the name opened is ignored (and so would normally be "FIL:"),
  and a list of all the available nodes is returned.
* Scan a node; the node is extracted from the name opened, and a list of all
  devices on that node is returned.
* Scan a directory; the name opened should either identify a directory (on
  the LOC:: node, this is done by having it end with a backslash), or should
  contain wildcards in the filename part. [If neither of these is true, only
  the original name will normally be returned; "A:" counts as a directory for
  these purposes.] A list of all names in the directory, or all matching names,
  is returned.

One member of the list is returned, as a cstr, by each call to function 1. The
buffer (argument 1) should be at least 128 bytes long.


Formatting is used to prepare a device to contain files and to erase any
previous contents. If a device supports multiple densities, it can be formatted
at normal or low density. The node and device part of the name identifies the
device to format; the remainder, if any, specifies a new volume name for the
device (otherwise the previous one is reused).

The first call to function 1 will write a count into the first word of the
buffer (argument 1); subsequent calls will ignore the buffer. This first call
will not alter the device, and if the handle is closed immediately afterwards,
nothing will happen. Otherwise, the count indicates the number of subsequent
calls required to format the device. If the handle is closed before that number
of calls has been made, the device will be left in an unusable state; it can
be recovered by reformatting, but any information normally transferred to a
reformatted device, such as the previous volume name or the unique serial
number, will be lost.

As an example, when formatting a 2Mb flash SSD, the format count was 513. This
consisted of:
* 256 calls which each wrote all zeroes to 8192 bytes of the card, starting
  at address 0.
* 8 blocks of 32 calls; the first call in each block restored 256 kbytes to
  all $FF, and the other 31 did nothing.
* A final call which restored the initial area of the card (serial number,
  volume name, empty root directory, etc.).


Opening for access
------------------

A file is opened for access in order to read or write the file. To open a file
for access, the mode parameter to IOOPEN has the following value:
    Bits 0 to 3: (service component)
      0 = open an existing file
      1 = create a new file
      2 = replace an existing file
      3 = open a file for appending only
      4 = open a new file with an existing name
    Bits 4 to 7: (format component)
      0 = open a binary file for stream access
      1 = open a binary file for text access
      2 = open a text file for text access
    Bit  8: allow writing
    Bit  9: allow random access
    Bit 10: allow shared access
These individual components are now described.


Service component
-----------------

The service component indicates what to do with the existing contents of the
file. There are five possibilities:
* 0 and 3 open an existing file, leaving the content unchanged. They differ
  only in the setting of the current position (0 = start, 3 = end). If the
  file does not exist, the open fails.
* 1 and 2 will create the file if it does not exist; 1 will fail if the file
  does already exist, while 2 will succeed. After opening, the file will
  be empty (length 0), and so the current position will be at both the start
  and end of the file.
* 4 is equivalent to 1, but with a new file name. The file name passed is
  examined to determine the directory, and a new file is created in that
  directory; the resulting name overwrites the passed name. If the IOOPEN
  keyword is used, the name parameter is replaced by ADDR(qstr), as explained
  in the OPL manual. If the IoOpen system call is used, the name (a cstr) is
  passed in the same way as for other modes, and will be overwritten; there
  should thus be room for 128 bytes.


Format component
----------------

There are two kinds of file: text and binary. A text file consists of a
sequence of records, each ending with a newline character, while a binary
file consists of arbitrary data, which is not broken into records.

Each node has its own way of storing text and binary files. On some nodes,
the two types are completely distinct. On others, text files are merely a way
of i