⎕Fxxx Component File System

As an alternative to the powerful multi-user component file system accessed using the file primitives ⍇ ⍈ ⍐ ⍗, APLX also implements a second component file system similar to that used in many other APL interpreters, with important extensions. This is based on the system functions ⎕FCREATE ⎕FTIE ⎕FREAD and so on.

⎕Fxxx files are identified by a file name, and created using ⎕FCREATE. For each APL component file, a separate operating-system file will be created. When you want to use an existing file, you first 'tie' (open) it using ⎕FTIE or ⎕FSTIE, and then you refer to the file by the tie number which you have specified or which has been automatically allocated by APLX. (This is in contrast to the ⍈ ⍇-based system, where a single 'dataspace' holds multiple APL component files, component files are always identified by number, and there is no need to 'tie' a file to use it.) Once the file has been tied, components are accessed by component number. When you have finished using a file, you must close it using ⎕FUNTIE. (They are untied automatically when the APL task ends, but they are not untied automatically when you )CLEAR the workspace or )LOAD another workspace).

Components within a file are numbered sequentially, initially from 1 to N, where N is the number of components in the file. You read components from an existing file using ⎕FREAD. You can write a component to the file using the ⎕FAPPEND and ⎕FREPLACE facilities implemented by other APL interpreters; these allow you to append to the end of the file, or to replace an existing component respectively. You can also delete components using ⎕FDROP, but only from the start or the end of the file. Components are not re-numbered, so if you drop components from the start of the file, the first component will no longer be number 1.

APLX retains upwards compatibility with this simple model, but in addition provides the more general functions ⎕FWRITE (which allows you to insert components anywhere within the range of existing components, or immediately before or after them), and ⎕FDELETE (which allows you to delete a component anywhere in the file). When you use these extensions, components are automatically re-numbered so that they always comprise sequential integers from the first component M to the last component 1+M-N, where N is the number of components in the file.

Individual components may be any valid APL data, including nested arrays and overlays created using ⎕OV (which can contain multiple functions and variables). The components keep their type and shape when stored and retrieved. When you replace a component, the new component does not have to be the same size as the original; the file system automatically expands the file if necessary to accommodate a larger component, and if possible releases space when you replace an existing component with a smaller one.

When using the file system in a multi-user or multi-tasking environment, you can optionally tie a file for exclusive use (⎕FTIE), or for shared access (⎕FSTIE). A file may be kept secure from other users by a pass number, and you can set an access matrix which determines what operations other users can perform. To facilitate concurrent use of shared files whilst maintaining data integrity, the file hold facility ⎕FHOLD allows you to hold one or more files temporarily for exclusive use.

Special considerations for Client-Server implementations of APLX

See ⎕FCREATE for details on how component files can be located on either the Client or Server machine.

Mixing 32-bit and 64-bit Component Files

If you are running both 32-bit and 64-bit versions of APLX, then it is possible to share component files between the two architectures, but there are some special points you should be aware of. The rules are as follows:

• If the file has been created from a 32-bit version of APLX, then it will always remain as a 32-bit component file. It can be accessed from 64-bit APLX64 systems, but all components will be held in 32-bit form. If you write a component from APLX64, then the data is converted to 32-bit form before it is written. This means no component can be bigger than 2GB, nor have more than 2,147,483,647 elements. It also means that any 64-bit integer data will be converted to floating-point form if it contains integers of magnitude bigger than 2*31. If it contains integers of magnitude bigger than 2*53, the data conversion will involve loss of precision. The maximum size of the file is currently 2GB.
• If the file has been created from a 64-bit APLX64 interpreter, it will be a 64-bit component file. It cannot be accessed from 32-bit APLX systems. Data can be of any type or size, subject only to an overall size limit for a single component file of 1024GB.

Component File Functions

For more information, see the descriptions of the ⎕Fxxx system functions:

⎕FAPPEND	Append component to file
⎕FCREATE	Create a new component file
⎕FCSIZE	Read component size information
⎕FDELETE	Delete component from file
⎕FDROP	Drop components from start or end of file
⎕FDUP	Duplicate component file, reclaiming wasted space
⎕FERASE	Erase component file
⎕FERROR	Return operating-system error
⎕FHOLD	Hold/Release component files for exclusive access
⎕FLIB	Return names of component files in directory
⎕FNAMES	Return names of currently-tied files
⎕FNUMS	Return tie numbers in use
⎕FRDAC	Read component-file access matrix
⎕FRDCI	Read component information
⎕FRDFI	Read file information
⎕FREAD	Read component
⎕FRENAME	Rename component file
⎕FREPLACE	Replace existing component
⎕FRESIZE	Set maximum file size
⎕FSIZE	Read file-size and component-range information
⎕FSTAC	Set component-file access matrix
⎕FSTIE	Tie file for shared use
⎕FTIE	Tie file for exclusive use
⎕FUNTIE	Untie component file(s)
⎕FWRITE	Append, replace or insert component