OPEN

General Format

OPEN [ EXCLUSIVE ]      { {INPUT } { [Sharing-Phrase] { File-name-1 [ WITH NO REWIND ] } ... } ...      {OUTPUT} { File-name-1 [Lock-Option] (only with -CA option)  }     {I-O   }      {EXTEND}

Where Sharing-Phrase is:

SHARING WITH { ALL OTHER }                { NO OTHER  }                { READ ONLY }

Where Lock-Option is:

{ ALLOWING { NO OTHERS } }               { OTHERS   }               { READERS   }               { WRITERS   }              { UPDATERS  }               { ALL       }      { {WITH} {LOCK       }    }      {FOR } {MASS-UPDATE}            {BULK-ADDITION}

Syntax rules

1.	The OPEN statement for a report file shall not contain the INPUT phrase or the I-O phrase.

2.	The EXTEND phrase shall be specified only if the access mode of the file connector referenced by file-name-1 is sequential.

3.	The files referenced in the OPEN statement need not all have the same organization or access.

4.	The NO REWIND phrase may be specified only for sequential files.

5.	The NO REWIND phrase may be specified only when the INPUT or OUTPUT phrase is specified.

6.	If the SHARING phrase is omitted from the OPEN statement and the ALL phrase is specified in the SHARING clause of the file control entry for file-name-1 or if the ALL phrase is specified on the OPEN statement, the LOCK MODE clause shall be specified in the file control entry for file-name-1.

7.	The I-O phase shall not be specified if the FORMAT clause is specified in the file description entry for file-name-1.

General rules

1.	The file connector referenced by file-name-1 shall not be open. If it is open, the execution of the OPEN statement is unsuccessful and the I-O status associated with file-name-1 is set based on your iscobol.file.status * setting.

2.

The successful execution of an OPEN statement associates the file connector referenced by file-name-1 with a physical file if the physical file is available, and sets the open mode of the file connector to input, output, I-O, or extend, depending on the keywords INPUT, OUTPUT, I-O or EXTEND specified in the OPEN statement. The open mode determines the input-output statements that are allowed to reference the file connector as shown in the following table.

Open mode	File is available	File is unavailable
INPUT	Normal open	Open is unsuccessful
INPUT (optional file)	Normal open	Normal open; the first read causes the at end condition or invalid key condition
I-O	Normal open	Open is unsuccessful
I-O (optional file)	Normal open	Open causes the file to be created
OUTPUT	Normal open; the file contains no records	Open causes the file to be created
EXTEND	Normal open	Open is unsuccessful
EXTEND (optional file)	Normal open	Open causes the file to be created

A physical file is available if it is physically present and is recognized by the operating environment. The table above shows the results of opening available and unavailable physical files that are not currently open by another file connector. The table below shows the results of opening available physical files that are currently open by another file connector, including those implicitly opened by the SORT and MERGE statements.

 

Open request		Most restrictive existing sharing mode and open mode
		sharing with no other	sharing with read only		sharing with all other
		extend I-O input output	extend I-O output	input	extend I-O output	input
SHARING WITH NO OTHER	EXTEND I-O INPUT OUTPUT	Unsuccessful open	Unsuccessful open	Unsuccessful open	Unsuccessful open	Unsuccessful open
SHARING WITH READ ONLY	EXTEND I-O	Unsuccessful open	Unsuccessful open	Unsuccessful open	Unsuccessful open	Normal open
	INPUT	Unsuccessful open	Unsuccessful open	Normal open	Unsuccessful open	Normal open
	OUTPUT	Unsuccessful open	Unsuccessful open	Unsuccessful open	Unsuccessful open	Unsuccessful open
SHARING WITH ALL OTHER	EXTEND I-O	Unsuccessful open	Unsuccessful open	Unsuccessful open	Normal open	Normal open
	INPUT	Unsuccessful open	Normal open	Normal open	Normal open	Normal open
	OUTPUT	Unsuccessful open	Unsuccessful open	Unsuccessful open	Unsuccessful open	Unsuccessful open

3.	The successful execution of an OPEN statement makes the associated record area available to the runtime element. If the file connector associated with file-name is an external file connector, there is only one record area associated with the file connector for the run unit.

4.	When a file connector is not open, no statement shall be executed that references the associated file-name, either explicitly or implicitly, except for a MERGE or SORT statement with the USING or GIVING phrase, or an OPEN statement.

5.	The OPEN statement for a report file connector shall be executed before the execution of an INITIATE statement that references a report-name that is associated with file-name-1.

6.

For a given file connector, an OPEN statement shall be successfully executed prior to the execution of any other permissible input-output statement. In the table below, an 'X' at an intersection indicates that the specified statement, used in the access mode given for that row, may be used with the open mode given at the top of the column.

 

Access mode	Statement	Open mode
		Input	Output	I-O	Extend
Sequential	READ	X		X
	WRITE		X		X
	REWRITE			X
	START	X		X
Sequential (relative and indexed files only)	DELETE			X
Random	READ	X		X
	WRITE		X	X
	REWRITE			X
	START
	DELETE			X
Dynamic	READ	X		X
	WRITE		X	X
	REWRITE			X
	START	X		X
	DELETE			X

7.	Execution of the OPEN statement does not obtain or release the first record.

8.

During the execution of the OPEN statement when the file connector is matched with the physical file and the physical file exists, the attributes of the file connector as specified in the file control paragraph and the file description entry are compared with the fixed file attributes of the physical file. If the attributes don't match, a file attribute conflict condition occurs, the execution of the OPEN statement is unsuccessful, and the I-O status associated with file-name-1 is set based on your iscobol.file.status * setting. The implementor defines which of the fixed-file attributes are validated during the execution of the OPEN statement. The validation of fixed-file attributes may vary depending on the organization of the file.

9.

If the physical file is not present, and the INPUT phrase is specified in the OPEN statement, and the OPTIONAL clause is specified in the file control entry for file-name-1, the file position indicator in the file connector referenced by file-name-1 is set to indicate that an optional input file is not present.

10.

When the organization of the file referenced by file-name-1 is sequential or relative and the INPUT or I-O phrase is specified in the OPEN statement, the file position indicator for that file connector is set to 1. When the organization is indexed, the file position indicator is set to the characters that have the lowest ordinal position in the collating sequence associated with the file, and the prime record key is established as the key of reference.

11.

When the EXTEND phrase is specified, the OPEN statement positions the file immediately after the last logical record for that file. The last logical record for a sequential file is the last record written in the file. The last logical record for a relative file is the currently existing record with the highest relative record number. The last logical record for an indexed file is the currently existing record with the highest prime key value.

12.

If the I-O phrase is specified, the physical file shall support the input and output statements that are permitted for the organization of that file when opened in the I-O mode. If the physical file does not support those statements, the I-O status value for file-name-1 is set based on your iscobol.file.status * setting and the execution of the OPEN statement is unsuccessful. The successful execution of an OPEN statement with the I-O phrase sets the open mode of file connector referenced by file-name-1 to open in the I-O mode.

13.

If the physical file is not present, and the EXTEND or I-O phrase is specified in the OPEN statement, and the OPTIONAL clause is specified in the file control entry for file-name-1, the OPEN statement creates the file. This creation takes place as if the following statements were executed in the order shown:

 

OPEN OUTPUT file-name.

CLOSE file-name.

 

These statements are followed by execution of the OPEN statement specified in the source element.

14.

If the OUTPUT phrase is specified, the successful execution of the OPEN statement creates the physical file. After the creation of the physical file, the file contains no records. If physical pages have meaning for the physical file, the positioning of the output medium with respect to physical page boundaries is implementordefined following the successful execution of the OPEN statement.

15.	Upon successful execution of the OPEN statement, the current volume pointer is set:

A.	To point to the first or only reel/unit in the physical file if INPUT or I-O is specified.

B.	To point to the reel/unit containing the last record in the physical file if EXTEND is specified.

C.	To point to the newly created reel/unit in the physical file for an unavailable file if EXTEND, I-O, or OUTPUT is specified.

16.

If more than one file-name is specified in an OPEN statement, the result of executing this OPEN statement is the same as if a separate OPEN statement had been written for each file-name in the same order as specified in the OPEN statement. These separate OPEN statements would each have the same open mode specification, the sharing-phrase, retry-phrase, and REWIND phrase as specified in the OPEN statement. If an implicit OPEN statement results in the execution of a declarative procedure that executes a RESUME statement with the NEXT STATEMENT phrase, processing resumes at the next implicit OPEN statement, if any.

17.	The SHARING phrase is effective only for files that are shareable.

18.	The SHARING phrase specifies the level of sharing permitted for the physical file associated with file-name-1 and specifies the operations that may be performed on the physical file through other file connectors sharing the physical file.

19.

The SHARING phrase overrides any SHARING clause in the file control entry of file-name-1. If there is no SHARING phrase on the OPEN statement, then file sharing is completely specified in the file control entry. If neither a SHARING phrase on the OPEN statement nor a SHARING clause in the file control entry is specified, the implementor shall define the sharing mode that is established for each file connector.

20.	The ALLOWING phrase is similar to SHARING phrase. It is supported by the compiler only with –ca compiler option.

A.	The ALLOWING phrase permits the following types of file locking: ALLOWING ALL, ALLOWING READERS, and ALLOWING NO OTHERS. File locking is enforced for all file types residing on disk but may not be enforced for non-disk files for some operating systems.

B.	The following phrases imply the ALLOWING ALL form of file locking:

i.	No lock-option specified

ii.	ALLOWING ALL

iii.	ALLOWING WRITERS

iv.	ALLOWING UPDATERS

 

This file locking mode indicates that other programs can access the file without restriction except that another program may not execute an OPEN OUTPUT while this program keeps the file open

C.	The following phrases imply the ALLOWING READERS form of file locking:

i.	ALLOWING READERS

ii.	EXCLUSIVE or WITH LOCK specified with the INPUT phrase

 

A file open in this mode does not allow any other program to open this file other than with the INPUT phrase. Also, this OPEN will fail if any other programs currently have the file open unless the INPUT phrase was used by all of these other programs

D.	These phrases imply the ALLOWING NO OTHERS form of file locking:

i.	ALLOWING NO OTHERS

ii.	EXCLUSIVE or WITH LOCK specified with the OUTPUT, I-O, or EXTEND phrases

iii.	WITH MASS-UPDATE

iv.	WITH BULK-ADDITION

 

This form of file locking does not allow any other programs to open the file, and this OPEN will fail if any other programs currently have the file open.

21.	If the file connector referenced by file-name-1 is locked by a previously-executed CLOSE statement with the LOCK phrase, the execution of the OPEN statement is unsuccessful and the I-O status associated with that file connector is set based on your iscobol.file.status * setting.

22.	If the execution of the OPEN statement is unsuccessful, the physical file is not affected and the value is placed in the I-O status associated with file-name to indicate the condition that caused the OPEN statement to be unsuccessful.

23.	The WITH MASS-UPDATE phrase indicates to the runtime system that the file will be heavily updated by the program. The runtime system may be able to use this information to access the file more efficiently.

24.	The WITH BULK-ADDITION is similar to WITH MASS-UPDATE. It behaves differently depending on the file handler.

A.	JIsam treats BULK-ADDITION the same way as MASS-UPDATE

B.	c-tree supports BULK-ADDITION from version 9.5.46192 and manages it by creating indexes at the close of the file. Unique key violations are traced in the c-tree server log file without triggering Declaratives.

Examples

Open several files for input, output and i-o

open input  customers invoices purchase-orders open output rep-customers rep-invoices open i-o    invoice-detail

Open files and lock them until they get closed

open i-o customers with lock open input invoices with lock

Open files locking them for massive update or addition

open i-o pay-receipts for mass-update open i-o pending-invoices for bulk-addition