⎕FSTAC Set component-file access matrix

In multi-user versions of APLX, each user can be allocated a unique user number (shown by 1↑⎕AI). Individual APLX component files are tagged with a User Number, and have an associated File Access Matrix which indicates which users can access the file, what operations they may perform, and whether they need to specify a pass number to tie the file. Users will be allocated their user number by the logon procedure adopted by their system. Each user can thus 'own' a number of files, and can grant or deny access to these files.

You can change the Access Matrix for a file using the syntax:

      MATRIX ⎕FSTAC TIENO {PASS}

The Access Matrix is three columns wide. The first column is a list of user numbers, with 0 being taken to mean ALL users. The second column is a list of integers which indicate the access privileges for the indicated user. The third column is the list of pass numbers which must be used by the given user to access the file with those rights (0 means no pass number is required). The access matrix may have a maximum of 19 rows. When a file is created, the default access matrix allows only the owner to access it, and grants the owner all rights, with no pass number.

TIENO is the tie number you used to tie or create the file (or the tie number returned by APLX if you tied or created it using 0 instead of your own tie number). If you tied the file using a pass number, you must provide the same pass number, as the PASS parameter.

When any operation on a file is attempted, APLX looks through the access matrix to find the first match for the user number (in the first column) and the pass number supplied when the file was tied (in the third column). A user number of 0 in the access matrix matches any user ID. If a match is found, the user is granted the permissions specified by the second element of the row. If no match is found, and the user is not the owner of the file, no permissions are granted. If no match is found, and the user is the owner of the file, all permissions are granted.

The access privileges can be specified in two ways. A positive privilege states what the user can do, and a negative privilege states what the user cannot do.

The privilege code is a number generated by adding various powers of 2 (1, 2, 4, 8, 16,....), each power of 2 corresponding to a particular privilege. Positive privilege codes are merely the sum of the individual privileges granted, whilst negative privilege codes are generated by adding ¯1 and the result of negating the sum of all the privileges denied.

Power     Value		Operation
of 2

  0		    1		⎕FREAD    		
  1		    2		⎕FTIE (exclusive)     
  2		    4		⎕FERASE   		
  3		    8		⎕FAPPEND  		
  4		   16		⎕FREPLACE ⎕FWRITE
  5		   32		⎕FDROP ⎕FDELETE
  7		  128		⎕FRENAME			
  9		  512		⎕FRDCI ⎕FCSIZE			
 10		 1024		⎕FRESIZE			
 11		 2048		⎕FHOLD			
 12		 4096		⎕FRDAC			
 13		 8192		⎕FSTAC			
 14		16384		⎕FDUP		

Permission to use ⎕FSTIE (shared tie) is implicitly granted to any user who has any permission to use the file. ⎕FCREATE ⎕FLIB ⎕FNAMES ⎕FNUMS and ⎕FUNTIE do not need explicit APLX permissions (although the operating-system may restrict your rights). ⎕FSIZE does not require explicit permission, but you must supply a pass number if the file was tied with one.

Examples of privilege codes are:

Privilege   	Meaning 

     0      No access 
     1      ⎕FSTIE ⎕FREAD 
     3      ⎕FSTIE ⎕FTIE ⎕FREAD 
    17      ⎕FSTIE ⎕FREAD ⎕FREPLACE ⎕FWRITE 
   ¯33      Full access except for ⎕FDROP ⎕FDELETE
    ¯1      Full access