U_OPEN - open a UFAS file.

Usage:

#include <ufas.h>
fp = u_open( filename, accpro [, option]* );

Where:

char *filename;: is the name of the file to be opened. For Indexed and ISP files, the two file names are supplied in one string, separated by a ";". In Batch, a filename of the form "fc*XX" refers to filecode 'XX'.
char *accpro;: indicates the access mode and processing mode to be used. This consists of a string containing a selection of the characters "rwabl". The meaning of each character, as well as valid combinations, are discussed below.
option: modifies the default action normally done by "u_open". Each option consists of one or more function arguments, the first of which is a keyword indicating which option is being selected. Any extra arguments required by that option follow the keyword.
U_FILE fp;: is a pointer which is passed to the other UFAS functions to indicate which file is referenced. If the open fails (but control is returned), the NULL pointer will be returned.

Description:

"u_open" allocates memory for a FIB (plus a little extra information), builds the FIB as required by the given file name and options, and performs a call equivalent to the DLOPEN GMAP macro.

Access and Processing Modes:

The string given for this argument consists of a selection of the following characters:

a: the file is to be opened in the "Extend" processing mode.
b: the file is to be opened for Random access.
l: the file is to be opened for Sequential access.
r: the file is to be opened in the "Input" processing mode.
w: the file is to be opened in the "Output" processing mode.

Note that the selection characters were chosen to match those of the Standard library (Append, Block I/O, Linked I/O, Read, Write). The default access mode is Sequential; the default processing mode is Input. The combination "bl" indicates Dynamic access; the combination "rw" indicates "Input/Output" processing mode.

In sequential access, the file is assumed to have UFF Sequential organization. In other access modes, the file is assumed to have UFF Relative organization.

Options:

The following options are available to override the default actions of "u_open".

U_NBUF, nbuf

sets the number of buffers to "nbuf". The default is 1.

U_RSZ, reclen

sets the record length (or maximum record length for Variable-length records). The default is 256 bytes.

U_IFLR

forces the use of fixed-length records. For UFF Sequential files and GFRC tapes, the default is variable-length records; all others default to fixed-length.

U_USERER, funcptr

causes the given function to be called as an error procedure when UFAS encounters an error. The default action is to supply no error functions, and thus abort the program when an error occurs.

U_CISZ, cisize

sets the Control Interval size, in bytes. The default is 1280 bytes (one llink).

U_FLNAME, label

sets the internal file label in batch. The default is not to check labels. This option is not allowed in TSS.

U_PREHDR, fincptr

U_POSTHDR, funcptr

U_PREEOF, funcptr

U_POSTEOF, funcptr

set label processing routines to be called before or after processing header or trailer labels on GFRC tapes.

U_PARTREC, value

forces the state of the partitioned record indicator. If 'value' is 0, records will not be partitioned; if 'value' is 1, records may be partitioned. If this option is not specified, partitioned records will be assumed except unless you specify U_IFLR (fixed length records) or a non-zero GFRC media code.

U_NREW

causes the file not to be rewound on open, as documented under the DLOPEN macro in the UFAS Manual.

U_REWOPT, opt

uses the value 'opt' as the rewind value when the file is explicitly closed by a call to 'u_close'. The 'opt' can be one of:

U_RWFL - Rewind file.
U_NRFL - Do not rewind file.
U_RLFL - Rewind and Lock file.
U_LKFL - Lock file.
U_RUFL - Rewind and Unload file.
U_R3FL - Lock, Rewind, and Unload file.

These options are discussed more fully in the descriptions of the DCLOS macro for various file organizations in the UFAS Manual. The default is U_RWFL.

U_FILENO, file_no

indicates that the file number "file_no" should be opened. This implies that the file is on a multi-file volume set (the MULTI option is set in the FIB), and, if file_no is non-zero, overrides the "U_NREW" option.

U_FILENO, 0

sets the multi-file volume option in the FIB, but does not select any particular file. Instead, the first or next (depending if U_NREW is specified) file is opened.

U_REL

forces the file organization to be UFF Relative, despite opening the file for sequential access.

U_IND, keydesc

forces the file organization to be UFF Indexed. A pointer to a list of key descriptions is given by "keydesc". This list must conform to the description of the KEYPTR keyword for the FIBMAC macro for UFF Indexed files (Section 5) of the UFAS Manual.

U_ISP, keydesc

forces the file to be in ISP format. A pointer to the key descriptor is given by "keydesc". This descriptor must be in the format described under the KEYPTR keyword for the FIBMAC macro for ISP format files (Section 6) of the UFAS Manual.

U_GFRC, media_code

forces the file organization to be GFRC sequential. The file must be open for Input or Output processing mode only.

U_SYM, symbol

causes the given symbol to be used as the UFAS routine table. Normally, a full set of UFAS routines is loaded, and "u_open" selects the appropriate one for the organization, access, and processing modes. However, by force-loading the symbol "u_usym", none of the UFAS routines are loaded and the user must always supply his own via this option.

Notes:

If a file is opened for other than Output processing, the user must ensure that the supplied organization and record length (or the defaults supplied by "u_open") are compatible with those of the file being opened.

The files are accessed using the same rules as "fopen" uses. Tapes are supported for UFF sequential format and GFRC format, sequential disk files are supported for GFRC format, all other formats require random disk files. If "u_open" must create the file, it will be created just large enough for 1 data control interval in addition to the header.

In TSS, the final element of any filename must not contain an underscore, due to a UFAS bug which treats this character as some sort of delimiter.