⍇ File read

One-argument form

⍇ reads data from a file. The right argument specifies the file and component number of the data required.

The one-argument ⍇ statement takes this form ({} means optional):

             R←⍇ {[LIBRARY]} FILE, COMPONENT {,USER, PASSWORD}

LIBRARY identifies the library volume from which data is to be read. If you omit the library number, library 0 is assumed. If included, the library number is put in square brackets. (see also the section on ⎕MOUNT).

FILE identifies the file the data is to be read from (a positive integer)

COMPONENT identifies the data item you want to read (an integer). Component number 0 means the last component, and if the component number is omitted, it is assumed to be 0.

USER and PASSWORD are used for file security in shared file applications; the defaults are 1↑⎕AI and 0 respectively if omitted (both integers). User number 0 also means the owner.

             ⍇ 3 300                 (Component 300 is read from file 3 on
       2.6 7.1 3.3                    on library 0. The data is displayed)

             A←⍇ 2 40                (The data in component 40 of file 2 is
                                      read and is assigned to A)

             A←⍇[3] 10 19 1000 99    (Data  is  read from component 19  of  file
                                      10 on library 3, belonging to user 1000
                                      and with password 99)

A variant of the one-argument form is used for reading the file access matrix. Here the negative of the file number is used and the value returned is the present access matrix. (See the discussion of file access matrices above)

             A←⍇¯3                   (The file access matrix of file 3 on
                                      library 0 is assigned to A)

Two-argument form

The two argument form of ⍇ provides information about the files and components. The general syntax is:

             R ← A ⍇ {[LIBRARY]} FILE {,COMP,USER,PASSWORD}

The action of ⍇ in this form is governed by the value of A, as the next table shows (library, file, component ,user and password are as defined for the one argument form). The file number is required when information is sought about a given file and the component number is only used when information about a given component is sought. If the file number is omitted it defaults to 0, as does the component number.

      A   File no.  Comp. no.           Result of ⍇

      1    FILE        0                The number of components in the file
      2    FILE        0                A nine-element file description vector
      2     0          0                An eight-element user quota vector
      3    FILE     COMP                A six-element component description vector
      5     0          0                A vector of the file numbers belonging to
                                        the user, in ascending order
      6    FILE        0                A three-element vector of file hold
                                        information
      7    FILE     COMP                A three-element vector of component hold
                                        information

The file description vector comprises:

     1 - File number
     2 - Maximum allowed size in bytes
     3 - Actual size
     4 - Number of components
     5 - Date file was created, MMDDYY
     6 - Time file was created, HHMMSS
     7 - Date file was last updated, MMDDYY
     8 - Time file was last updated, HHMMSS
     9 - Bytes attributable to file overhead

The user quota vector comprises:

     1 - User number
     2 - Aggregate file allocation quota
     3 - Current aggregate file size
     4 - Number of files quota
     5 - Number of files in existence
     6 - Allocation assigned to a new file
     7 - Free space remaining in dataspace
     8 - Largest contiguous space left in dataspace

The component description vector comprises:

     1 - File number
     2 - Component number
     3 - User number
     4 - Date component was written, MMDDYY
     5 - Time component was written, HHMMSS
     6 - Size of component in bytes

The file hold information request returns the following:

     1 - Number of components held
     2 - User holding the file (or 0)
     3 - Hold restriction (0, 1 or 2)

And finally, the component hold vector:

     1 - Component number
     2 - User holding the component (or 0)
     3 - Hold restriction (0, 1 or 2)

For example:

             5⍇[1] 0                 (A vector of all files on volume 1)
       1 117 10923478

             2⍇[1] 117 0             (The file description vector of file 117 on
                                      library 1)
       117 500000 388864 60 10383 2429 22384 223357 56

File Rename

The file may be renamed with a variant of the two argument ⍇ function. The general form of the operation is ({} means optional ):

            R←(NEWFILE,OVER,USER {,NEWPASS})⍇ {[LIBRARY]}OLDFILE,0,USER,{OLDPASS}

NEWFILE means the new file number

OLDFILE means the original file number

NEWPASS means the new password (if a password is to be changed it must be specified in both arguments)

OLDPASS means the original password

R, the result, is 1 for a successful rename; 0 if the operation failed

OVER means whether or not the rename may overwrite an existing file (except when changing the password).

      OVER = 0 means that overwriting is not allowed
      OVER = 64 means that overwriting is allowed

When overwriting, the file being overwritten must have delete access set, and the password (if any) must be correct. Otherwise a file locked error is shown.