3.7 cobfa_open()

Open a file.

long  cobfa_open  (
  const char  *fname,                    /* filename        */
  long  openflgs,                        /* open attribute  */
  const struct  fa_keylist  *keylist,    /* record key list */
  long  reclen                           /* record length   */
);

Description

Opens the file indicated by filename <fname> based on the information of the open attribute <openflgs>, record length <reclen>, and record key list <keylist>.

The following functions can be used by specifying file name <fname>.

To open a dummy file, append the character string ",DUMMY" to the end of the file name or specify ",DUMMY" as the file name. Refer to "3.26 Dummy File" for details.
Record sequential files and line sequential files can be accessed faster by specifying an available range. To use High-speed File Processing, append the character string ",BSAM" to the end of the file name. Refer to "3.27 High-speed File Processing" for details.

The values of the open attribute openflgs have the following nine categories, which are associated by a logical OR. The Open Mode category (a) must be specified. The remaining categories (b) to (i) can be omitted (default: *).

Open mode (COBOL syntax)
FA_INPUT
INPUT mode (OPEN INPUT)
FA_OUTPUT
OUTPUT mode (OPEN OUTPUT)
FA_INOUT
I-O mode (OPEN I-O)
FA_EXTEND
EXTEND mode (OPEN EXTEND)
- If the file is a line sequential file (FA_LSEQFILE), I-O mode (FA_INOUT) cannot be specified as the open mode.

File organization (COBOL syntax)

*	FA_SEQFILE	Record sequential file (ORGANIZATION IS SEQUENTIAL)
	FA_LSEQFILE	Line sequential file (ORGANIZATION IS LINE SEQUENTIAL)
	FA_RELFILE	Relative file (ORGANIZATION IS RELATIVE)
	FA_IDXFILE	Indexed file (ORGANIZATION IS INDEXED)

Record format (COBOL syntax)
*
FA_FIXLEN
Fixed-length format (RECORD CONTAINS integer CHARACTERS)
FA_VARLEN
Variable-length format (RECORD IS VARYING IN SIZE)
Access mode (COBOL syntax)
*
FA_SEQACC
Sequential access (ACCESS MODE IS SEQUENTIAL)
FA_RNDACC
Random access (ACCESS MODE IS RANDOM)
FA_DYNACC
Dynamic access (ACCESS MODE IS DYNAMIC)
- If the file is a line sequential file (FA_LSEQFILE) or record sequential file (FA_SEQFILE), an access mode other than sequential access (FA_SEQACC) cannot be specified.
Lock mode (COBOL syntax)
FA_AUTOLOCK
Automatic lock (LOCK MODE IS AUTOMATIC)
FA_MANULOCK
Manual lock (LOCK MODE IS MANUAL)
FA_EXCLLOCK
Exclusive lock (OPEN WITH LOCK / LOCK MODE IS EXCLUSIVE)
- If the open mode is OUTPUT mode (FA_OUTPUT), it is assumed that exclusive lock (FA_EXCLLOCK) is specified as the lock mode.
- If the open mode is INPUT mode (FA_INPUT), automatic lock (FA_AUTOLOCK) or manual lock (FA_MANULOCK) cannot be specified as the lock mode. The specification is ignored.
- If the open mode is INPUT mode (FA_INPUT), the file is opened in shared mode using lock mode as the default. At read, the record lock specification is ignored.
- If the open mode is a mode other than INPUT mode (FA_INPUT), the default lock mode is exclusive lock (FA_EXCLLOCK).
- If the file is a line sequential file (FA_LSEQFILE) or record sequential file (FA_SEQFILE), manual lock (FA_MANULOCK) cannot be specified as the lock mode.
Information
The following describes the relationship between the execution of each API function and exclusive file control.
Exclusive control of files
Exclusive mode
When a file is opened in exclusive mode, other users cannot access the file.
Shared mode
A file opened in shared mode can be used by other users. However, file opening by other users will fail if the file has already been opened in exclusive mode.
The table below shows the state of the file when opened under various combinations of Open mode and Lock mode.
Open mode
FA_INPUT
FA_OUTPUT
FA_INOUT
FA_EXTEND
Lock mode
None
shared
exclusive
exclusive
exclusive
FA_AUTOLOCK
shared
shared
FA_MANULOCK
FA_EXCLLOCK
exclusive
exclusive
exclusive
Exclusive control of records
If a record of a file opened with FA_INOUT in shared mode becomes exclusive via a record lock specification at read time, other users cannot access the record.
Refer to "3.9 cobfa_rdkey()", "3.10 cobfa_rdnext()" and "3.11 cobfa_rdrec()" for record lock specifications at read time.
In the following cases, the exclusive state of the record is released:
All record locks released (cobfa_release)
A file is closed (cobfa_close)
When the lock mode is FA_AUTOLOCK and one the following processes is executed, the exclusive state of the record is released:
Read a record(cobfa_rdkey, cobfa_rdnext, cobfa_rdrec)
Write a record(cobfa_wrkey, cobfa_wrnext, cobfa_wrrec)
Delete a record(cobfa_delcurr, cobfa_delkey, cobfa_delrec)
Rewrite a record(cobfa_rewcurr, cobfa_rewkey, cobfa_rewrec)
Position to the record(cobfa_stkey, cobfa_strec)
Optional file (COBOL syntax)
*
FA_NOTOPT
Non-optional file (SELECT filename)
FA_OPTIONAL
Optional file (SELECT OPTIONAL filename)

	Open mode
FA_INPUT	FA_OUTPUT	FA_INOUT	FA_EXTEND
Lock mode	None	shared	exclusive	exclusive	exclusive
FA_AUTOLOCK	shared	shared
FA_MANULOCK
FA_EXCLLOCK	exclusive	exclusive	exclusive

Character encoding type

*	FA_ASCII	The file records have character data encoded in ASCII.
	FA_UCS2	The file records have character data encoded in UCS-2.
	FA_UTF8	The file records have character data encoded in UTF-8.
	FA_UCS2BE	The file records have character data encoded in UCS-2(big-endian).
	FA_UCS2LE	The file records have character data encoded in UCS-2(little- endian).
	FA_UTF32	The file records have character data encoded in UTF-32.
	FA_UTF32BE	The file records have character data encoded in UTF-32 (big-endian).
	FA_UTF32LE	The file records have character data encoded in UTF-32 (little-endian).

The character encoding type specifies the encoding type of the character data of line sequential file records. For line sequential files, the file structure depends on the encoding type. Therefore, the character encoding type is significant when using line sequential files.
The character encoding type can be specified only when the file organization is line sequential file (FA_LSEQFILE). For other file organizations, the file structure does not depend on the encoding type. Therefore, the character encoding type cannot be specified.
For line sequential files to be handled by COBOL applications operating in Unicode mode, when the record data items are national items specify FA_UCS2, FA_UCS2BE, FA_UCS2LE, FA_UTF32, FA_UTF32BE or FA_UTF32LE. When the record data items are not national items, specify FA_UTF8.
For line sequential files to be handled by COBOL applications operating in a mode other than Unicode, specify FA_ASCII.

Key part flag usage specification
FA_USEKPFLAGS
Enables the specification value of the kp_flags member of struct fa_keypart type structure.
- Specify key part flag usage to enable the specification value of member kp_flags of struct fa_keypart type structure included in record key list keylist. See "4.1.1 struct fa_keydesc", for details about struct fa_keypart type.
- Key part flag usage can be specified only when the file organization is indexed file (FA_IDXFILE).
- Key part flag usage must be specified to use indexed files handled by COBOL applications whose operating mode is Unicode.
- If the key part flag usage specification is omitted, the specification value of member kp_flags will be ignored.
High-speed file processing
FA_BSAM
High-speed file processing is specified.
- Specify FA_BSAM to refer to COBOL files with high-speed file processing, or to create files to be referred using high-speed file processing. When the file processing is made high-speed, "High-speed file processing" is used. Refer to "High-speed File Processing" for details.
- You can use FA_BSAM only when the file organization is record sequential (FA_SEQFILE) or line sequential (FA_LSEQFILE).
- Specifying FA_BSAM changes maximum file size, restrictions, and notes to the same as those for high-speed file processing. Refer to "File Processing" of the "NetCOBOL User's Guide", for details.
- When FA_BSAM specification and "High-speed file processing" are specified at the same time, "High-speed file processing" becomes effective.

The record length <reclen> is treated as the fixed-record length when the record format is the fixed-length format (FA_FIXLEN). When the record format is the variable-length format (FA_VARLEN), the record length is treated as the maximum record length. The record length must not exceed FA_NRECSIZE (typically 32760).

The record key list <keylist> is significant only if the file is an indexed file (FA_IDXFILE). In this case, <keylist> is valid as the list of the primary record key and alternate record key(s) of the file being opened. For the struct fa_keylist type, see "4.1.2 struct fa_keylist ".

If the NULL pointer is specified for <keylist> to open an indexed file, this function automatically identifies the key list structure, record format, and record length of an existing file and opens the file. In this case, the record format and record length specified are ignored.

Execution Conditions

File Organization	Sequential file	Executable
	Record sequential file	Executable
	Relative file	Executable
	Indexed file	Executable
Open Mode	INPUT mode	Executable
	OUTPUT mode	Executable
	I-O mode	Executable
	EXTEND mode	Executable
Access Mode	Sequential	Executable
	Random	Executable
	Dynamic	Executable

Return Values

1 or greater

Successful. Function executed successfully. A code indicating the status may have been set in the I-O status

This return value is the value of the file descriptor of the file that has been opened successfully. Note, however, that this file descriptor is not the value of the file handle returned by the operating system when the file is opened.

-1

Function failed. To get extended error information, call the cobfa_errno or cobfa_stat functions.

Generated Status

Return value of cobfa_errno ()		Return value of cobfa_stat ()
Successful	FA_ENOERR	0	Function executed successfully
Successful	FA_ENOERR	5	No optional file exists but the file is virtually opened. Alternatively, a new file is created when the open mode is not INPUT mode (FA_INPUT).
Failure (not all) (*)	FA_EBADACC	90	The specified combination of file organization, access mode, and open mode cannot be executed
	FA_EFNAME	35	The file does not exist
	FA_EFLOCKED	93	The file has been opened exclusively
	FA_EFNAME	90	The filename is incorrect or file access failed
	FA_EFNAME	91	The filename is not specified
	FA_EBADFLAG	39	The specified attribute such as file organization or record format is different from the organization of the existing file
	FA_EBADKEY	39	Information on the specified record key is different from the key list of the existing indexed file
	FA_EBADKEY	90	Information on the specified record key is incorrect
	FA_EBADLENG	39	The specified record length is different from the record length of the existing file
	FA_EBADFILE	90	The specified file is unreadable

* : Typical status values are described above. For other values, see "Chapter 5 Error Number and I-O Status".

	FA_INPUT	INPUT mode (OPEN INPUT)
	FA_OUTPUT	OUTPUT mode (OPEN OUTPUT)
	FA_INOUT	I-O mode (OPEN I-O)
	FA_EXTEND	EXTEND mode (OPEN EXTEND)

*	FA_FIXLEN	Fixed-length format (RECORD CONTAINS integer CHARACTERS)
	FA_VARLEN	Variable-length format (RECORD IS VARYING IN SIZE)

*	FA_SEQACC	Sequential access (ACCESS MODE IS SEQUENTIAL)
	FA_RNDACC	Random access (ACCESS MODE IS RANDOM)
	FA_DYNACC	Dynamic access (ACCESS MODE IS DYNAMIC)

	FA_AUTOLOCK	Automatic lock (LOCK MODE IS AUTOMATIC)
	FA_MANULOCK	Manual lock (LOCK MODE IS MANUAL)
	FA_EXCLLOCK	Exclusive lock (OPEN WITH LOCK / LOCK MODE IS EXCLUSIVE)

*	FA_NOTOPT	Non-optional file (SELECT filename)
	FA_OPTIONAL	Optional file (SELECT OPTIONAL filename)