System Function Native Files

Data Conversion

Reading from and writing to disk files naturally involves data conversion as there are more ways to represent simple homogeneous data on disk than in the workspace. For example, a common disk data type is an 8-bit character which NARS2000 doesn't support in the workspace as yet, however it does support 16-bit characters. The other data types available on disk, but not supported in the workspace include 8-, 16-, and 32-bit integer, whereas the corresponding data type in the workspace is a 64-bit integer.

When reading from a file, you must specify both datatypes; that is, the datatype of the data in the file and the datatype you want to use in the workspace. When writing to (appending or replacing) a file, the workspace datatype is implicit in the data so you need only specify the datatype in the file to which you want the data converted.

A conversion from a larger size to a smaller size (e.g., 'int64' to 'int8') is allowed only if all of the larger size values (e.g., 64-bit integers) are within the range of the smaller size values (e.g., 8-bit integers — ¯128 to 127); if not, then a DOMAIN ERROR is signalled.

The following table summarizes the conversion codes:

Numeric Value	Character Name	Datatype	File(F) or Workspace(W)
110	'bool'	1-bit Boolean	FW
811	'char8'	8-bit character	F
1611	'char16'	16-bit character	FW
3211	'char32'	32-bit character	F
812	'int8'	8-bit integer	F
1612	'int16'	16-bit integer	F
3212	'int32'	32-bit integer	F
6412	'int64'	64-bit integer	FW
6413	'flt64'	64-bit floating point	FW

The rightmost column in the above table specifies whether the conversion can be used as a file (F) and/or a workspace (W) conversion code. As you can see, the workspace conversion codes correspond to the four simple homogeneous datatypes available in a workspace.

You may use either the numeric value or upper-/lower-case character name to identify the conversion code. For example, '...' ⎕ncreate tn mode ('char8' 'char16') and '...' ⎕ncreate tn mode (811 1611) are equivalent.

⎕NAPPEND

Z←L ⎕NAPPEND R appends the raveled data in L to the open native file whose tie number is in R.

L is an arbitrary (but simple homogeneous) array.

R is a numeric scalar or one- or two-element vector.

Z is a numeric scalar.

The first item in R is the negative integer tie number of an open native file.

The optional second item in R is the file conversion code used to convert the data in L before writing it to the file. The file and workspace conversion codes are as specified above. If the file conversion code is not present, then the corresponding code specified implicitly or explicitly when the file was most recently created or opened is used.

The result contains the offset in the file of the next byte after the data just appended.

For example:

      tn←'C:\foo' ⎕ncreate 0 ⍝ Implicit file conversion code of 'char8' and workspace conversion code of 'char16'
      'Now is the time ' ⎕nappend tn

After which the file data consists of

  0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
|4E|6F|77|20|69|73|20|74|68|65|20|74|69|6D|65|20|  Now is the time

      'Now is the time ' ⎕nappend tn 'char16'

After which the file data consists of

  0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
|4E|6F|77|20|69|73|20|74|68|65|20|74|69|6D|65|20|  Now is the time
|4E|00|6F|00|77|00|20|00|69|00|73|00|20|00|74|00|  N o w   i s   t
|68|00|65|00|20|00|74|00|69|00|6D|00|65|00|20|00|  h e   t i m e  

If the workspace data (in L) is wider than the width specified by the file conversion code and it cannot be truncated at the high end without losing data, then a DOMAIN ERROR is signalled. For example, if the data in L is character ('char16') and the file conversion code is one of 'char8', 'int8', or 'bool', then enough of the high-order bits of each character in L must be zero so that the actual value fits without loss of data.

For example:

      tn←'C:\foo' ⎕ncreate 0
      '⊤○⍵ ⍳⌈ ∼∆∊ ∼⍳⍦∊ ' ⎕nappend tn
DOMAIN ERROR
      '⊤○⍵ ⍳⌈ ∼∆∊ ∼⍳⍦∊ ' ⎕nappend tn
                         ∧
      '⊤○⍵ ⍳⌈ ∼∆∊ ∼⍳⍦∊ ' ⎕nappend tn 'char16'

After which the file data consists of

  0  1  2  3  4  5  6  7  8  9  A  B  C  D  E  F
|A4|22|CB|25|75|23|20|00|73|23|08|23|20|00|3C|22|  ⊤○⍵ ⍳⌈ ∼
|06|22|0A|22|20|00|3C|22|73|23|66|23|0A|22|20|00|  ∆∊ ∼⍳⍦∊ 

⎕NCREATE

Z←L ⎕NCREATE R creates and opens the native file named in L and associates with it the tie number from the first element in R.

L is a character scalar or vector.

R is a numeric scalar or one-, two-, or three-element vector.

Z is a numeric scalar.

L is the name of the native file to create and is subject to the restrictions of the underlying file system.

The first item in R is either zero or the negative integer tie number to associate with the open native file. If the tie number is zero, the system automatically generates the next available negative integer to use as the tie number.

The optional second item in R is the access mode to use when creating the file. This mode is the sum of two integer values, the first of which specifies the type of access you are requesting after creating the file, and the second of which specifies the type of access you are granting to subsequent users while you have the file opened. The following table illustrates the two types of modes:

Access Needed To Open		Access Granted To Others
0	read	0	compatibility
1	write	16	exclusive
2	read-write	32	read
		48	write
		64	read-write

If this item is not present, the default value used is 2.

The optional third item in R is the default file and/or workspace conversion code(s) to use when reading from and/or writing to the file. These code(s) may be overwritten by using an explicit conversion code in the call to ⎕NAPPEND, ⎕NREPLACE, or ⎕NREAD. If present, this item may be a numeric scalar, one-or two-element numeric vector, or a one- or two-element nested vector of character vectors. For example:

      L ⎕NCREATE tn mode 811
      L ⎕NCREATE tn mode (811 1611)
      L ⎕NCREATE tn mode 'char8'
      L ⎕NCREATE tn mode ('char8' 'char16')

If only one element is specified in the code, it is used as the file conversion code when writing data to the file, and the workspace conversion code is 'char16'. If both elements are specified, the first is the file conversion code and the second is the workspace conversion code. The latter conversion code is used when reading data from the file into the workspace. If this item is not specified, the default conversion code used is ('char8' 'char16') which says that the file data is unsigned 8-bit characters and when read into the workspace should be converted into unsigned 16-bit characters

Specifying the conversion code when creating/opening the native file avoids having to specify non-default conversions for subsequent read and/or write operations.

⎕NERASE

Z←L ⎕NERASE R erases the open file named in L and tied to the number in R.

L is a character scalar or vector.

R is a numeric scalar or one-element vector.

Z is a numeric scalar.

The file named in L must be identical to the name used as the left argument to the most recent create/tie of the file.

The first item in R is the negative integer tie number of an open native file.

The result is the tie number of the file just erased.

⎕NNAMES

Z←⎕NNAMES returns a matrix of the names of all open native files, padding each row with blanks as necessary.

Z is a character matrix.

The result contains the names of the open native files using the names as specified when the file(s) were most recently created/opened. The rows of the result are in the same order as the tie numbers in ⎕NNUMS.

⎕NNUMS

Z←⎕NNUMS returns a numeric vector containing the tie numbers of all open native files .

Z is a numeric vector.

The result contains the tie numbers of all open native files and are in the same order as the rows of ⎕NNAMES.

⎕NREAD

Z←⎕NREAD R reads from the open native file whose tie number is the first item in R.

R is a numeric scalar or one-, two-, three-, or four-element vector.

Z is a vector.

The first item in R is the negative integer tie number of an open native file.

The optional second item in R is the file and workspace conversion codes. If the file and/or workspace conversion codes are not present, then the corresponding codes specified implicitly or explicitly when the file was most recently created or opened are used. For example, file and workspace conversion codes of ('int8' 'int64') mean that the data in the file consists of one byte signed integers (with a range of ¯128 to 127) and are to be converted (and signed extended) to 64-bit integers in the workspace.

The optional third item in R is the number of elements (not bytes) to read. If this item is not present, the number of elements read is however many are present from the current file pointer to the end of the file.

The optional fourth item in R is the starting byte offset in the file from which to begin reading. If this item is not present, the offset used is the current file pointer.

To set a file pointer to a particular byte offset to be used by a subsequent ⎕NREAD or ⎕NREPLACE, use ←⎕NREAD tn ⍬ 0 off.

⎕NRENAME

Z←L ⎕NRENAME R changes to L the name of the file tied to R.

L is a character scalar or vector.

R is a numeric scalar or one-element vector.

Z is a numeric scalar of the tie number just erased.

L is the new name of the file.

R is the negative integer tie number of an open native file.

⎕NREPLACE

Z←L ⎕NREPLACE R replaces the raveled data in L into the open native file whose tie number is in R.

L is an arbitrary (but simple homogeneous) array.

R is a numeric scalar or one-, two-, or three-element vector.

Z is a numeric scalar.

The first item in R is the negative integer tie number of an open native file.

The optional second item in R is the file conversion code used to convert the data in L before writing it to the file. If the file conversion code is not present, then the corresponding code specified implicitly or explicitly when the file was most recently created or opened is used.

The optional third item in R is the starting byte offset in the file from which to begin writing. If this item is not present, the offset used is the current file pointer.

⎕NRESIZE

Z←L ⎕NRESIZE R changes to L the size of the open file whose tie number is in R.

L is a numeric scalar or one-element vector.

R is a numeric scalar or one-element vector.

Z is a numeric scalar of the tie number just erased.

L is the new size of the file. If it is smaller than the current file size, the file is truncated. If it is larger, the file size is increased as per the underlying file system.

R is the negative integer tie number of an open native file.

⎕NSIZE

Z←⎕NSIZE R returns the file size of the open native file whose tie number is in R.

R is a numeric scalar or one-element vector.

Z is a numeric scalar.

R is the negative integer tie number of an open native file.

The result is the file size of the open native file.

⎕NTIE

Z←L ⎕NTIE R opens the existing file named in L and associates with it the tie number from the first element in R.

L is a character scalar or vector.

R is a numeric scalar or one-, two-, or three-element vector.

Z is a numeric scalar of the tie number of the file.

L is the name of the native file to open and is subject to the restrictions of the underlying file system.

The items in R are defined identically to how they are used in ⎕NCREATE.

⎕NUNTIE

Z←⎕NUNTIE R closes the open native file(s) whose tie number(s) are in R.

R is a numeric scalar or vector.

Z is a numeric vector.

The elements in R are zero or more tie numbers of open native files to be closed.

The result is a list of the tie numbers of the files successfully closed.