Opening a file

A program can process a file only after calling an OPEN function. Among other things, the OPEN function verifies whether a user has the necessary access rights, whether the file is already open and whether the file open modes are compatible with each other. The file open modes and file access by many users are to a great extent similar to the OPEN function of other DMS access methods (see the “Introductory Guide to DMS” [1])
The file can be set for read-only or read and write access. Following a write access, the file can be modified, extended or rewritten from the beginning of the file.
The file can be simultaneously accessed by a single user with write authorization and/or many users with read authorization as well as many users with read and write authorization.The user can specify whether a given data space or the entire file should be read immediately into a window when it is defined, or whether a given page should be read into a window only when the page is first accessed. 

List of most important macro operands for opening a file

Operand	Operand values	Meaning
FCT	*OPEN	Opening a file
LARGE_FILE		The LARGE_FILE function operand specifies whether the file that is to be opened may grow to become a “large file” with a file size that may exceed 32 GB.
	*ALLOWED	The file may become a large file.
	*FORBIDDEN	The file may not become a large file.
MODE		The function operand MODE specifies which operation (read, write) should be performed on the file (write means executing the DIV function SAVE).
	*INPUT	The file is opened as the input file; the SAVE function is not permitted.
	*INOUT	The file must exist; both read and write operations are permitted.
	*OUTIN	A new file will be created; both read and write operations are permitted.
SHARUPD		Depending on the MODE setting, the function SHARPUPD is used to indicate which multiuser operation modes should be allowed (see the tables under “Multiuser operation” below):
	*NO	One write-authorized user or many read-authorized users can open the file simultaneously.
	*WEAK	One write-authorized user and many read-authorized users can open the file simultaneously.
	*YES	Multiple write-authorized users can open the file simultaneously.
LOCVIEW		The LOCVIEW operand is used to specify when a page should be read into a window.
	*MAP	All pages of the specified file region are read into a window as soon as it is defined (FCT=*MAP).
	*NONE	A page is not read into a window from the disk file until a page is accessed.

Multiuser operation

A UPAM file can be created and processed with the access methods UPAM (see "UPAM - User Primary Access Method"), FASTPAM (see "FASTPAM - Fast Primary Access Method") or DIV. FASTPAM and DIV can, however, only process UPAM files with the attribute BLKCTRL=NO.

Authorization for parallel file processing is dependent on the operand open values specified for SHARUPD, MODE, LOCKENV and LOCVIEW.

The permissible parallel opens are shown in the following table:

Compatibility matrix for DIV-OPEN

USER B

USER B

USER B

USER B

USER B

USER B

USER B

USER B

USER B

USER B

SHARUPD=

*YES

*YES

*YES

*NO

*NO

*NO

*WEAK

*WEAK

*WEAK

*WEAK

OPEN mode

I N P U T

I N O U T

O U T I N

I N P U T

I N O U T

O U T I N

I N P U T

L M A P

I N O U T

O U T I N

U S E R A

*YES

INPUT INOUT OUTIN

X O O

O O O

X

X X X

X

*NO

INPUT INOUT OUTIN

X

X

X X X

X

*WEAK

INPUT LMAP INOUT OUTIN

X X

X

X X

X

X X X X

X X O

X O

Table 1: DIV: Permissible SHARUPD/OPEN combinations

LMAP: INPUT LOCVIEW=MAP (only with DIV))

X: OPEN permitted

O: OPEN permitted only

• if the same block-oriented access method is used by all (either UPAM/FASTPAM or DIV)

• and the same value is used by all for the LOCKENV operand
  (either LOCKENV=*HOST or LOCKENV=*XCS)

• and all are running on the same host or, with LOCKENV=*XCS, in an XCS network

Comments

• Read operations with SHARUPD=*WEAK may have opened a file simultaneously with any write operation.

  All read operation window pages with DIV-SHARUPD=*WEAK which specified LOCVIEW=*MAP with OPEN are read from the file into the window when MAP is reached. DIV thereby ensures that no file pages can be modified during reading by the parallel SAVE of a write operation with DIV-SHARUPD=*WEAK.
  This protection against parallel writing does not exist for a UPAM/FASTPAM write operation.

  For this reason, read operations with DIV-SHARUPD=*WEAK for which LOCVIEW= *MAP was specified, are compatible to write operations with DIV-SHARUPD=*WEAK, but not, however, to other write operations.

  All other conditions formulated for entry 'O' above must also be fulfilled (all openers with the same value for the LOCKENV operand and all openers in the same host or, if in different hosts, with the entry LOCKENV=*XCS).

  Read operations with DIV-SHARUPD=*WEAK which specified LOCVIEW=*NONE with OPEN possess the same compatibility as read operations with UPAM/FASTPAM-SHARUPD=*WEAK.

• Openers with DIV-SHARUPD=*YES are not compatible with openers with UPAM/FASTPAM-SHARUPD=*YES.

• Read operations are always compatible with each other (regardless of access method, SHARUPD specification, LOCKENV specification and host).

• SHARUPD=*YES:
  The file size is checked whenever the allocator is called.
  If this check indicates a file size >= 32 GB and the attribute LARGE_FILE=*FORBIDDEN is set in the associated FCB or the attribute EXCEED-32GB=*FORBIDDEN is set in the TFT then processing is canceled.
  In this case, DIV returns the code X'00400030' in its local parameter list DIV(I).