Difference between revisions of "System Function Native Files"

From NARS2000
Jump to navigationJump to search
Line 9: Line 9:
 
       <td></td>
 
       <td></td>
 
       <td></td>
 
       <td></td>
       <td>appends the raveled data in <apll>L</apll> to the file whose tie number is in <apll>R</apll>.</td>
+
       <td>appends the raveled data in <apll>L</apll> to the open native file whose tie number is in <apll>R</apll>.</td>
 
     </tr>
 
     </tr>
 
     </table>
 
     </table>
Line 21: Line 21:
 
</tr>
 
</tr>
 
<tr>
 
<tr>
   <td><apll>Z</apll> is a numeric scalar of the offset in the file of the next byte after the data just appended.</td>
+
   <td><apll>Z</apll> is a numeric scalar.</td>
 
</tr>
 
</tr>
  
Line 27: Line 27:
 
<br />
 
<br />
  
<p>The first item in <apll>R</apll> is the tie number of a file created/opened by <apll>⎕NCREATE</apll> or <apll>⎕NTIE</apll>; the optional second element is the File Conversion code used to convert the data in <apll>L</apll> before writing it to the file.  The File and Workspace Conversion codes are as follows:</p>
+
<p>The first item in <apll>R</apll> is the negative integer tie number of a file created/opened by <apll>⎕NCREATE</apll> or <apll>⎕NTIE</apll>; the optional second item is the File Conversion code used to convert the data in <apll>L</apll> before writing it to the file.  The File and Workspace Conversion codes are as follows:</p>
  
 
<table border="1" cellpadding="5" cellspacing="0" rules="none" summary="">
 
<table border="1" cellpadding="5" cellspacing="0" rules="none" summary="">
Line 105: Line 105:
  
 
<p>If the file conversion code is omitted, then the corresponding code specified implicitly or explicitly when the file was most recently created or opened is used.</p>
 
<p>If the file conversion code is omitted, then the corresponding code specified implicitly or explicitly when the file was most recently created or opened is used.</p>
 +
 +
<p>The result contains the offset in the file of the next byte after the data just appended.
  
 
<p>For example:</p>
 
<p>For example:</p>
Line 157: Line 159:
 
       <td></td>
 
       <td></td>
 
       <td></td>
 
       <td></td>
       <td>creates and opens the file named in <apll>L</apll> and associates with it the tie number from the first element in <apll>R</apll>.</td>
+
       <td>creates and opens the native file named in <apll>L</apll> and associates with it the tie number from the first element in <apll>R</apll>.</td>
 
     </tr>
 
     </tr>
 
     </table>
 
     </table>
Line 169: Line 171:
 
</tr>
 
</tr>
 
<tr>
 
<tr>
   <td><apll>Z</apll> is a numeric scalar of the tie number of the file.</td>
+
   <td><apll>Z</apll> is a numeric scalar.</td>
 
</tr>
 
</tr>
  
 
</table>
 
</table>
 
<br />
 
<br />
 +
 +
<p><apll>L</apll> is the name of the native file to create and is subject to the restrictions of the underlying file system.</p>
 +
 +
<p>The first item of <apll>R</apll> is either zero or the negative 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.</p>
 +
 +
<p>The optional second item of <apll>R</apll> 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:</p>
 +
 +
<table border="1" cellpadding="5" cellspacing="0" summary="">
 +
<tr>
 +
  <td colspan="2"><b>Access Needed<br />To Open</b></td>
 +
  <td colspan="2"><b>Access Granted<br />To Others</b></td>
 +
</tr>
 +
 +
<tr>
 +
  <td>0</td>
 +
  <td>read</td>
 +
 +
  <td>0</td>
 +
  <td>compatibility</td>
 +
</tr>
 +
 +
<tr>
 +
  <td>1</td>
 +
  <td>write</td>
 +
 +
  <td>16</td>
 +
  <td>exclusive</td>
 +
</tr>
 +
 +
<tr>
 +
  <td>2</td>
 +
  <td>read-write</td>
 +
 +
  <td>32</td>
 +
  <td>read</td>
 +
</tr>
 +
 +
<tr>
 +
  <td>&nbsp;</td>
 +
  <td>&nbsp;</td>
 +
 +
  <td>48</td>
 +
  <td>write</td>
 +
</tr>
 +
 +
<tr>
 +
  <td>&nbsp;</td>
 +
  <td>&nbsp;</td>
 +
 +
  <td>64</td>
 +
  <td>read-write</td>
 +
</tr>
 +
</table>
 +
 +
<p>If this item is not present, the default value used is <apll>2</apll>.</p>
 +
 +
<p>The optional third item of <apll>R</apll> 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 <apll>⎕NAPPEND</apll>, <apll>⎕NREPLACE</apll>, or <apll>⎕NREAD</apll>.  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:</p>
 +
 +
<apll>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;L ⎕NCREATE tn mode 811<br />
 +
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;L ⎕NCREATE  tn mode (811 1611)<br />
 +
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;L ⎕NCREATE tn mode 'char8'<br />
 +
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;L ⎕NCREATE tn mode ('char8' 'char16')<br />
 +
</apll>
 +
 +
<p>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 <apll>'char16'</apll>.  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 <apll>('char8' 'char16')</apll> which says that the file data is in the format <apll>'char8'</apll> and when read into the workspace should be converted into <apll>'char16'</apll>.</p>
  
 
== <apll>⎕NERASE</apll> ==
 
== <apll>⎕NERASE</apll> ==
 +
 +
<table border="1" cellpadding="5" cellspacing="0" rules="none" summary="">
 +
<tr>
 +
  <td>
 +
    <table border="0" cellpadding="5" cellspacing="0" summary="">
 +
    <tr>
 +
      <td valign="top"><apll>Z←L ⎕NERASE R</apll></td>
 +
      <td></td>
 +
      <td></td>
 +
      <td>erases the open file named in <apll>L</apll> and tied to the number in <apll>R</apll>.</td>
 +
    </tr>
 +
    </table>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td><apll>L</apll> is a character scalar or vector.</td>
 +
</tr>
 +
<tr>
 +
  <td><apll>R</apll> is a numeric scalar or one-element vector.</td>
 +
</tr>
 +
<tr>
 +
  <td><apll>Z</apll> is a numeric scalar.</td>
 +
</tr>
 +
 +
</table>
 +
<br />
 +
 +
<p>The file named in <apll>L</apll> must be identical to the name used as the left argument to the most recent create/tie of the file.</p>
 +
 +
<p>The result is the tie number of the file just erased.</p>
  
 
== <apll>⎕NREAD</apll> ==
 
== <apll>⎕NREAD</apll> ==
 +
 +
<p>***FINISHME***</p>
  
 
== <apll>⎕NRENAME</apll> ==
 
== <apll>⎕NRENAME</apll> ==
 +
 +
<table border="1" cellpadding="5" cellspacing="0" rules="none" summary="">
 +
<tr>
 +
  <td>
 +
    <table border="0" cellpadding="5" cellspacing="0" summary="">
 +
    <tr>
 +
      <td valign="top"><apll>Z←L ⎕NRENAME R</apll></td>
 +
      <td></td>
 +
      <td></td>
 +
      <td>changes to <apll>L</apll> the name of the file tied to <apll>R</apll>.</td>
 +
    </tr>
 +
    </table>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td><apll>L</apll> is a character scalar or vector.</td>
 +
</tr>
 +
<tr>
 +
  <td><apll>R</apll> is a numeric scalar or one-element vector.</td>
 +
</tr>
 +
<tr>
 +
  <td><apll>Z</apll> is a numeric scalar of the tie number just erased.</td>
 +
</tr>
 +
 +
</table>
 +
<br />
 +
 +
<p><apll>L</apll> is the new name of the file.</p>
 +
 +
<p><apll>R</apll> is the negative integer tie number of the open file.</p>
  
 
== <apll>⎕NREPLACE</apll> ==
 
== <apll>⎕NREPLACE</apll> ==
 +
 +
<p>***FINISHME***</p>
  
 
== <apll>⎕NRESIZE</apll> ==
 
== <apll>⎕NRESIZE</apll> ==
 +
 +
<table border="1" cellpadding="5" cellspacing="0" rules="none" summary="">
 +
<tr>
 +
  <td>
 +
    <table border="0" cellpadding="5" cellspacing="0" summary="">
 +
    <tr>
 +
      <td valign="top"><apll>Z←L ⎕NRESIZE R</apll></td>
 +
      <td></td>
 +
      <td></td>
 +
      <td>changes to <apll>L</apll> the size of the open file whose tie number is in <apll>R</apll>.</td>
 +
    </tr>
 +
    </table>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td><apll>L</apll> is a numeric scalar or one-element vector.</td>
 +
</tr>
 +
<tr>
 +
  <td><apll>R</apll> is a numeric scalar or one-element vector.</td>
 +
</tr>
 +
<tr>
 +
  <td><apll>Z</apll> is a numeric scalar of the tie number just erased.</td>
 +
</tr>
 +
 +
</table>
 +
<br />
 +
 +
<p><apll>L</apll> 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.</p>
 +
 +
<p><apll>R</apll> is the negative integer tie number of the open file.</p>
  
 
== <apll>⎕NSIZE</apll> ==
 
== <apll>⎕NSIZE</apll> ==
 +
 +
<p>***FINISHME***</p>
  
 
== <apll>⎕NNAMES</apll> ==
 
== <apll>⎕NNAMES</apll> ==
 +
 +
<table border="1" cellpadding="5" cellspacing="0" rules="none" summary="">
 +
<tr>
 +
  <td>
 +
    <table border="0" cellpadding="5" cellspacing="0" summary="">
 +
    <tr>
 +
      <td valign="top"><apll>Z←⎕NNAMES</apll></td>
 +
      <td></td>
 +
      <td></td>
 +
      <td>returns a matrix of the names of all open native files, padding each row with blanks as necessary.</td>
 +
    </tr>
 +
    </table>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td><apll>Z</apll> is a character matrix.</td>
 +
</tr>
 +
 +
</table>
 +
<br />
 +
 +
<p>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 <apll>⎕NNUMS</apll>.</p>
  
 
== <apll>⎕NNUMS</apll> ==
 
== <apll>⎕NNUMS</apll> ==
 +
 +
<table border="1" cellpadding="5" cellspacing="0" rules="none" summary="">
 +
<tr>
 +
  <td>
 +
    <table border="0" cellpadding="5" cellspacing="0" summary="">
 +
    <tr>
 +
      <td valign="top"><apll>Z←⎕NNUMS</apll></td>
 +
      <td></td>
 +
      <td></td>
 +
      <td>returns a numeric vector containing the tie numbers of all open native files .</td>
 +
    </tr>
 +
    </table>
 +
  </td>
 +
</tr>
 +
<tr>
 +
  <td><apll>Z</apll> is a numeric vector.</td>
 +
</tr>
 +
 +
</table>
 +
<br />
 +
 +
<p>The result contains the tie numbers of all open native files and are in the same order as the rows of <apll>⎕NNAMES</apll>.
  
 
== <apll>⎕NTIE</apll> ==
 
== <apll>⎕NTIE</apll> ==
Line 218: Line 425:
 
</table>
 
</table>
 
<br />
 
<br />
 +
 +
<p>***FINISHME***</p>
  
 
== <apll>⎕NUNTIE</apll> ==
 
== <apll>⎕NUNTIE</apll> ==
 +
 +
<p>***FINISHME***</p>

Revision as of 21:07, 18 March 2012

⎕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 a file created/opened by ⎕NCREATE or ⎕NTIE; the optional second item 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 follows:

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 float FW

You may use either the numeric value or upper-/lower-case character name to identify the conversion code.

If the file conversion code is omitted, 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 of R is either zero or the negative 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 of 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 of 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 in the format 'char8' and when read into the workspace should be converted into 'char16'.

⎕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 result is the tie number of the file just erased.

⎕NREAD

***FINISHME***

⎕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 the open file.

⎕NREPLACE

***FINISHME***

⎕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 the open file.

⎕NSIZE

***FINISHME***

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

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


***FINISHME***

⎕NUNTIE

***FINISHME***