APLX Native File Support

APLX provides a full set of system functions which let you access the native file system on your host machine.

In many cases, the easiest way to read or write data in files is to use the ⎕IMPORT and ⎕EXPORT functions. These allow you to read or write the entire contents of a file in a single call, in a number of common formats, for example in formats which spreadsheets can access. However, for more detailed control of the contents of a file, or to access files which are too big to read into a variable in the workspace, you will need to use the native file functions described below.

See also ⎕SQL, which allows you to read and write data held in relational databases.

Native file functions using tie numbers

Most of the APLX native file functions refer to a host file through a file tie number, a non-zero integer value used to identify the file once it has been opened. You can specify the tie number yourself as an argument to the ⎕NTIE or ⎕NCREATE functions. Alternatively, you can provide an argument of 0 and let APLX choose a unique tie number for you (in this case it is returned as the explicit result of the function). The name of the file to tie is supplied to the ⎕NTIE or ⎕NCREATE call as a character vector and may be a file name or a full host path name. If the full path is omitted the current working directory is assumed. Case is significant in host file names under Linux or AIX, but not under Windows and MacOS.

Files may be accessed totally randomly, that is you can read and write data as an arbitrary stream of bytes anywhere in the file. The ⎕NREAD and ⎕NWRITE functions also allow you to specify an optional conversion to apply to the file data. For example you can read data as raw bytes or translate text files into the internal representation used by APLX. Unicode text is also supported. You can read numeric data as 2 or 4-byte integers, or as booleans or 8-byte floats. In addition you can specify that data is byte-swapped for transfer between machines with different byte-ordering conventions.

When you have finished using a file it must be untied using the ⎕NUNTIE function. This will close the file and release any file locks that have been set by the ⎕NLOCK function. Files are also untied automatically by a )CLEAR or an )OFF. Tied files are not affected by a )LOAD operation.

Errors may arise using the native file system for a number of reasons, for example an attempt to tie a non-existent file or to read beyond the end of a file. In the event of an error of this type, the system function will return a FILE I/O ERROR. In addition, if error trapping is not enabled, a short informative message is displayed:

     'TEST.DATA' ⎕NTIE 1
  A file or directory in the path name does not exist.
  FILE I/O ERROR
     'TEST.DATA' ⎕NTIE 1
     ^

The text of the specific error message is also available using the ⎕NERROR function. This returns the error message for the last native file system function to give rise to a FILE I/O ERROR.

File size limits

In 32-bit versions of APLX, the maximum integer is 2147483647. Because file sizes and positions are expressed as integers, this effectively puts a limit of 2GB on the size of native files which you can directly access in the 32-bit versions of APLX.

In APLX64, the maximum integer is 9223372036854775807, making it possible to directly access files of up to 8,589,934,592 GB.

Special considerations for Client-Server versions of APLX

In Client-Server implementations of APLX, you can specify whether the native file access should take place on the Client or Server machine. See the description of ⎕NCREATE for more information.