ACC.FIL - access a file.

Usage:

retval = acc.fil( name, opts, ret[, open_info] );

Where:

name

is a string with the file name (catfile string) in it. ACC.FIL may edit this string to remove passwords. In batch, a file name FC*XX or FC*XX/YYY refers to filecode XX. A file name FC*XX/YYY is used by OPEN to refer to YYY on the tape accessed under filecode XX. ACC.FIL ignores the YYY.

opts

is a vector of four words containing the options for the access. The possible values of these four words are listed below.

opts[0]

Permissions/options

Bit Usage
 0  read access
 1  write access
 2  access qualifier (append in TSS)
 3  access qualifier (execute in TSS)
15  do not rewind file on access
16  if the file must be created, create linked
    even if access is random
17  ensure file type/access mode (bit 35) match
18  test access
19  concurrent access
35  access random

For a full list of the combinations of bits 0-3, 18, and 19, see the TSS System Programmer's Reference Manual, or the GCOS manual (under MME GEMORE). Bits 17 and 35 form a pair that is interpreted as follows:

00 - Access asis sequential/random
01 - Access random, error if not possible
10 - Access asis, error if not linked
11 - Access asis, error if not random

opts[1]

Size

lower half: initial file size in llinks
upper half: max file size;

Zero implies unlimited See "file access/create conventions" below.

opts[2]

AFT flag

 1 - generate unique altnames for permfiles
 0 - do not use AFT. Treat "name" as a permfile
+1 - use AFT file if quick access
+2 - same as -1, but also indicates no check for
     a duplicate aftname or file code in the current
     list of IOVs
+3 - same as 0, but with no check for a duplicate
     aftname or file code
+4 - same as +1, but with no check for a duplicate
     aftname or file code

See below for an explanation of altname rules.

opts[3]

Error action flag

+1 - message and exit
 0 - no message, no exit
-1 - message but no exit

ret

is a pointer to a vector where ACC.FIL will place the following five words of information.

ret[0] and ret[1]: In TSS, these contain the lower case ASCII filename (AFT name). In batch, they contain the filecode (ret[0]) and the tape volume if any (ret[1]).
ret[2] and ret[3]: These contain the access status from the file system.
ret[4]: This contains the file descriptor returned by DRL FILACT in TSS, or by MME GEFADD in batch. From this, you can determine if the file is temporary, random, etc. as well as the file's size. For a disk file, bit 21 (040000) being on indicates a permanent file which is dynamically accessed and which should be deaccessed by the user when finished. This will avoid such problems as unnecessarily filling the AFT in TSS, or exhausting PAT space in batch.

open_info

is an optional argument to provide additional information for ACC.FIL. At present, the entire word must be zero except for bit 35. If this bit is on, it indicates that the program doesn't care about the contents of the file being accessed (see the "zw" option of OPEN).

retval

is zero if the file access is successful. Otherwise, it is set to the negative of the filact return status.

Description:

In TSS, there are two versions of ACC.FIL available. By default, the file accessing subroutines are loaded with the user program. However, there is a subsystem called .GET which contains a copy of the file access code. If a program specifies

extrn .get;

calls to ACC.FIL will invoke a version of the function which does a DRL CALLSS to .GET in order to access a file. This saves space, but in many cases costs time.

We strongly recommend that you use OPEN to open a file instead of ACC.FIL. OPEN calls ACC.FIL to access the file, but it also sets things up so you can use CLOSE to deaccess the file.

ACC.FIL uses the standard .EPOST facility to post an error message, if an error condition occurs.

File access/create conventions:

A file is accessed according to the following conventions in TSS.

For a "quick access" name (less than nine characters, and no "/", "$" or altname), the AFT is first searched for a file with the given name. If such a file is not found, the file is sought under the user's current working catalog. Failing that, an error occurs on files being accessed for reading. An error also occurs on files being accessed for writing if the size in "opts[1]" is zero. If the size is non-zero, a temporary file of at least that size is created for the write.

For a permanent file description or if "opts[2]" is zero, ACC.FIL will search for the file in the specified UMC and catalog (a name beginning with a "/" is assumed to be under the current working catalog). An error occurs if this search fails, unless the specified file is being opened for writing. In this case, a file of the specified size, limit, and mode is created (provided there is no problem with permissions and resources).

The value of "opts[2]" dictates whether ACC.FIL checks for duplicate altnames. There are several possibilities:

opts[2] = -1: ACC.FIL tries to generate a non-conflicting altname.
opts[2] = 0 or 1: ACC.FIL searches the current set of open files to see if they have altnames that conflict with the current file. ACC.FIL generates an error (.HER37) if a conflicting name is found.
opts[2] = 2, 3, or 4: ACC.FIL does not search for conflicting altnames; it ruthlessly accesses the file. Any files already accessed under that name are removed from the AFT. If the conflicting file was a temporary file, removing it from the AFT makes it go away forever; if the conflicting file was a permanent file, it is simply deaccessed.

In batch, ACC.FI performs similar operations for duplicate file codes, depending on the value of "opts[2]".

In batch, if a file name (as opposed to filecode) is specified, it is treated as a permfile name and the above rules apply. If a filecode is specified (FC*XX), that filecode is used if it exists. If the filecode does not exist, an error occurs for read access and for write access with size equal zero. If the size is non-zero and write access is being requested, a temporary disk file is created.

Specifying an altname of the form "fc*XX" will cause the file to be accessed under the specific filecode "XX" rather than a filecode generated by the B library. If this feature is used, it is the user's responsibility to avoid conflicts with existing filecodes. Generated filecodes are in the sequence "01", "02", ... and so these should be avoided by the user.

It is not possible to access a non-structured file (such as a catalogued tape) by pathname. Such files should be accessed with a $~PRMFL card, and opened by using the filecode.

In TSS, the value in .UID is used as the effective userid for DRL FILACT. This will only affect subsystems with "mail" privilege. In batch, .UID is used as the effective userid for the MME GEFSYE used to create output files. This is only effective for programs running with privity. However, it will also be necessary for a user with PRIVITY to set .SUID in his SSA in order to establish an effective userid for MME GEMORE. Setting .UID will have no effect on TSS programs which use .GET.

Statuses:

ACC.FIL will return a negative value if the access is not successful and "opts[3]" is 0 or -1. If the access was successful, a zero value is returned.

The following statuses may be generated by ACC.FIL itself rather than the file system.

0003: Permissions denied. This is generated if a quick access name is used and there is a matching file with insufficent permissions in the AFT already.
0005: Not found/incorrect name. This is given if read access if requested on an undefined filecode in batch.
0010: Link space exhausted. This is returned if a GEMORE request for scratch disk space is denied, or if DRL DEFIL returns a status with this meaning.
0030: Unsupported device. This is returned if the filecode in batch is attached to something other than disk, tape, or SYSOUT.
0034: Bad pathname. This will be returned if SCAF could not parse the file name.
0036: AFT full. This is returned if DRL DEFIL returned AFT full status.
0040: No PAT space. This will be returned if DRL DEFIL returned a no PAT space status.
0050: Mode conflict. This is a non-standard status which is returned if there is a linked/random conflict.
0053: Null file.
0060: Not a file. This non-standard status is returned if an attempt is made to access a catalog as a file. (Might not be generated on GCOS 3 systems.)