⎕NCREATE Create a new native file and tie it

This function is used to create a new native file and associate it with the supplied tie number, or one allocated automatically by APLX. You must have the correct host access permission to create the file. The file is automatically opened for reading and writing. If the file already exists, its length is truncated to zero and its owner, group and access permissions are unchanged. Otherwise the file's owner and group are set to the effective owner ID and group ID of the user and the access permissions are set from the PERMISSIONS argument (see below).

The syntax of ⎕NCREATE is ({} means optional) :

          'FILENAME' ⎕NCREATE TIENO {,PERMISSIONS}

'FILENAME' is a character vector specifying the name of the file to create. The name may be either a full host path name, or the path may be omitted in which case the new file is created in the current working directory.

TIENO is an arbitrary non-zero integer to be used as the tie number in subsequent read/write operations to identify the file. It must not currently be in use to tie another file.

Alternatively, TIENO can be zero. In this case, APLX allocates the next available free tie number and returns it as the explicit result of the function. (The value returned is equivalent to the expression 1+⌈/0,⎕NNUMS before the function is created).

PERMISSIONS is used to specify the host access permissions for a newly created file (see below). The value of PERMISSIONS is ANDed with the complement of the user's file mode creation mask to determine the resulting access permissions for the new file. The default value is 438 - read and write but no execute access for all three categories of user.

Access to a host file can be set for three categories of user, the owner of the file, other members of the owner's group, and other users of the system. For each of the three categories of user permission to read, write and execute the file can be granted or denied. The access permissions for a file are shown by the Unix command 'ls -l', which displays them using a 9-character string format to denote the three sets of three permissions. The first set refers to the owner's permissions; the next refers to the permissions off others in the user- group of the file, and the last to all others. For example :

rwxr-x--x User has read, write and execute permissions Group members have read and execute permissions Other users have only execute permission

The PERMISSIONS parameter is formed by adding any combination of the following values :

     256   - read by owner
     128   - write by owner
      64   - execute by owner
      32   - read by group
      16   - write by group
       8   - execute by group
       4   - read by others
       2   - write by others
       1   - execute by others

In order to obtain the access permissions for the new file, the value of PERMISSIONS is ANDed with the complement of the user's file mode creation mask. This mask, set by the shell command 'umask', determines the default access mode for created files.

For example, if the current user's file mode creation mask is 2 and the value of PERMISSIONS is 438 (the default), the created file will have access permissions rw-rw-r--.

Note that if the file already exists its access permissions are not changed by ⎕NCREATE

Special considerations for Client-Server implementations of APLX

In Client-Server implementations of APLX, the front-end which implements the user-interface (the "Client") runs on one machine, and the APLX interpreter itself (the "Server") can run on a different machine.

In such systems, you can specify whether the file should be created on the Client or the Server machine. You do this by preceding the path name with either an Up Arrow ↑ to indicate that the file should be created on the Client, or a Down Arrow ↓ to indicate that it is should be created the Server. (If you do not specify, the default is the Client.)