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
3213	'flt32'	32-bit floating point (single precision)	F
6413	'flt64'	64-bit floating point (double precision)	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.

⎕NINFO

Z←⎕NINFO R returns a nested scalar with the character vector name of the file specified in R. This is equivalent to Z←0 ⎕NINFO R.

R is a numeric scalar or one-element numeric vector of a native file tie number, or it is a character scalar or character vector of a native file name.

Z is a nested scalar with the character vector native file name.

Z←L ⎕NINFO R returns a nested scalar or nested vector with the set of properties as specified by L of the file specified in R.

L is a numeric scalar or numeric vector with values from 0 to 7 specifying which properties to return.

R is a numeric scalar or one-element numeric vector of a native file tie number, or it is a character scalar or character vector of a native file name.

Z is a nested scalar or nested vector of the same shape as that of L which contains the properties as specified by L.

The valid values in L are the integers from 0 to 7 with the following meanings:

L	Property
0	The character vector name of the item specified in R. This item may be a file or directory.
1	Z File Type 0 Unknown 1 Directory 2 Regular file 3 Character device (not supported) 4 Symbolic link 5 Block device (not supported) 6 FIFO (not supported) 7 Socket (not supported)
2	The numeric scalar file or directory size in bytes.
3	The timestamp (⎕TS) of the last write to the file.
4	The character vector Owner Security Identifier (SID).
5	The character vector Owner Name.
6	The Boolean scalar indicating whether or not the file is hidden.
7	The character vector target of a Symbolic Link (only if the File Type is 4).

For example:

      (0..7),⍪(0..7) ⎕NINFO 'C:\autoexec.bat' ⍝ Regular file #1
 0          C:\autoexec.bat 
 1                        2 
 2                      441 
 3   2016 7 27 13 43 47 615 
 4             S-1-5-32-544 
 5   BUILTIN\Administrators 
 6                        0 
 7 
      (0..7),⍪(0..7) ⎕NINFO 'C:\Users' ⍝ Directory #2
 0                 C:\Users 
 1                        1 
 2                     4096 
 3   2016 11 12 8 45 32 558 
 4                 S-1-5-18 
 5      NT AUTHORITY\SYSTEM 
 6                        0 
 7 
      (0..7),⍪(0..7) ⎕NINFO 'C:\PHP' ⍝ Symbolic Link #3
 0                 C:\PHP 
 1                      4 
 2                      0 
 3   2015 2 7 14 59 9 769 
 4           S-1-5-32-544 
 5 BUILTIN\Administrators 
 6                      0 
 7           G:\PHP-5.5.0
      (0..7),⍪(0..7) ⎕NINFO ⊃7 ⎕NINFO 'C:\PHP' ⍝ Target of Symbolic Link #4
 0              G:\PHP-5.5.0 
 1                         1 
 2                      8192 
 3   2016 11 14 12 40 51 557 
 4              S-1-5-32-544 
 5    BUILTIN\Administrators 
 6                         0 
 7 
      (0..7),⍪(0..7) ⎕NINFO 'C:\$Recycle.bin' ⍝ Hidden file #5
 0        C:\$Recycle.bin 
 1                      1 
 2                   4096 
 3   2016 8 3 9 34 8 657  
 4           S-1-5-32-544 
 5 BUILTIN\Administrators 
 6                      1 
 7 

The design for this system function was taken from Dyalog APL with minor changes. The differences include: Block vs. character devices are not supported; the operands 'Follow' and 'Wildcard' to the Variant operator are not needed. That is, the target of the Symbolic Link (produced by a 7 in the left argument) is always filled in if the File Type is 4 (Symbolic Link) as demonstrated in the above examples #3 and #4, and wildcards are automatically detected by examining the character vector right argument.

For example:

      ⍉⊃0 1 2 ⎕NINFO 'C:\Program Files*'
 C:\Program Files       1 28672 
 C:\Program Files (x86) 1 81920

⎕NLOCK

Z←L ⎕NLOCK R locks or unlocks the file and returns the right arg.

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

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

Z is the same as R.

The first item in L is an integer scalar representing the Lock Type: 0 for Unlock, 1 for a Read Lock, and 2 for a Write Lock.

The optional second item in L is the Lock Timeout in seconds. If not present, this value is assumed to be zero. It may be a fractional value.

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

The optional second item in R is starting byte offset in the file from which to begin locking. If not present, the offset is assumed to be zero.

The optional third item in R is the byte length of the lock. If not present, the length is assumed to be the entire file.

The result is the same as R.

⎕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.

⎕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 renamed.

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.

System Variables (A value may be assigned to these except for ⎕DM)
⎕ALX	⎕CT	⎕DM	⎕DT	⎕ELX	⎕FC	⎕FEATURE	⎕FPC	⎕IC	⎕IO
⎕LR	⎕LX	⎕PP	⎕PR	⎕PW	⎕RL	⎕SA	⎕WSID
Niladic System Functions (a value cannot be assigned to these)
⎕A	⎕AV	⎕EM	⎕ET	⎕LC	⎕NNAMES	⎕NNUMS	⎕SI	⎕SYSID	⎕SYSVER
⎕T	⎕TC	⎕TCBEL	⎕TCBS	⎕TCESC	⎕TCFF	⎕TCHT	⎕TCLF	⎕TCNL	⎕TCNUL
⎕TS	⎕WA
Monadic or dyadic system functions (a value cannot be assigned to these)
⎕AT	⎕CR	⎕DC	⎕DFT	⎕DL	⎕DR	⎕EA	⎕EC	⎕ERROR	⎕ES
⎕EX	⎕FMT	⎕FX	⎕MF	⎕NAPPEND	⎕NC	⎕NCREATE	⎕NERASE	⎕NINFO	⎕NL
⎕NLOCK	⎕NREAD	⎕NRENAME	⎕NREPLACE	⎕NRESIZE	⎕NSIZE	⎕NTIE	⎕NUNTIE	⎕STOP	⎕TF
⎕TRACE	⎕UCS	⎕VR
Note that quad functions and variables (except for the ⎕A family of functions) are case insensitive

---

See Also
System Commands	System Variables and Functions	Operators

Keyboard

Alt+Shift

⍪

≡

≢

⍒

⍋

⌽

⍉

⊖

⍟

⍱

⍲

⍠

⌹

Alt

⋄

¨

¯

<

≤

∅

≥

>

≠

∨

∧

×

÷

Shift

~

!

@

#

$

%

^

&

*

(

)

_

+

Key

`

1

2

3

4

5

6

7

8

9

0

-

=

Alt+Shift

⍷

√

⍨

⍸

⍥

⍣

⍞

⍬

⊣

Alt

?

⍵

∊

⍴

§

↑

↓

⍳

○

π

←

→

⊢

Shift

Q

W

E

R

T

Y

U

I

O

P

{

}

|

Key

q

w

e

r

t

y

u

i

o

p

[

]

\

Alt+Shift

∫

∂

⌻

⍢

⍙

⍤

⍫

⌷

Alt

⍺

⌈

⌊

∞

∇

∆

∘

‼

⎕

⍎

⍕

Shift

A

S

D

F

G

H

J

K

L

:

"

Key

a

s

d

f

g

h

j

k

l

;

'

Alt+Shift

⊆

⊇

χ

⍡

⍭

⊙

Alt

⊂

⊃

∩

∪

⊥

⊤

⍦

⍝

⍀

⌿

Shift

Z

X

C

V

B

N

M

<

>

?

Key

z

x

c

v

b

n

m

,

.

/

NARS 2000 Lang Tool Bar

←

→

+

-

×

÷

*

⍟

⌹

○

!

?

√

|

⌈

⌊

⊥

⊤

⊣

⊢

≡

≢

<

≤

=

≥

>

≠

∨

∧

⍱

⍲

↑

↓

⊂

⊃

⌷

⍋

⍒

⍳

∊

⍸

⍷

∪

∩

⊆

⊇

~

§

π

..

,

⍪

⍴

⌽

⊖

⍉

/

\

⌿

⍀

⊙

¨

⍨

⍤

⍣

⍡

⍥

⍦

.

∘

⍠

‼

⌻

∂

∫

⍞

⎕

⍎

⍕

⋄

⍝

∇

∆

⍙

_

⍺

⍵

¯

⍬

∞

∅

Second Row

i j k

i j k l

g

p

r

v

x

[[Category:Mouse Group {{{1}}}|{{{2}}}]]