A file is opened, and an ID is entered in the parameter list. This ID must be used in subsequent calls in order to identify the OPEN association of these calls.
If the same parameter list is used for every DIV call that is associated with a DIV OPEN, the ID will have already been entered into the parameter list and need not be taken into account.
The size of the file is returned in the parameter list after the call.
The OPEN function evaluates only the function operands described below. However, additional operands can be used even at this stage, to prepare the parameter list for other DIV function calls.
Format FCT=*OPEN
Operation | Operands |
|
|
| |
| |
|
Operand descriptions
ENV
Influences the compatibility of parallel openers dependent on their execution location (see DIV - Data In Virtual section "Compatibility matrix for DIV-OPEN").
Only direct specification is permitted with the MF=L form.
= *HOST
The maximum possible parallelism is restricted to openers running in the same host.
= *XCS
The openers can run in different hosts in an XCS network without restricting the compatibility (e.g. write operations with SHARUPD=*YES can run in parallel).
= addr
The symbolic address of a one-byte field containing the value of ENV.
= (r)
A register containing the value of ENV.
FCT
Specifies the DIV function to be executed.
Only a direct specification is allowed for the MF=L form.
= *OPEN
A file is opened, and an ID is entered into the parameter list. This ID must be used in subsequent calls in order to indicate the OPEN association of these subsequent calls.
If the same parameter list is used for every DIV call that is associated with a DIV OPEN, this ID will have already been entered into the parameter list and need not be taken into account.
Following the call to OPEN, the OPEN ID and the size of the file will be contained in the DIVPSIZE field of the parameter list, respectively.
= addr
Symbolic address of a 1-byte field containing the value for the OPEN function (for more information on the DIVPOPEN value, see the layout of the parameter list on "DIV function: CLOSE").
= (r)
Register containing the value for the OPEN function.
FILE
Specifies the name of the file. The FILE specification is not evaluated if a value has been specified for the LINK operand.
Only a direct specification is allowed for the MF=L form.
= 'name'
The name must be enclosed within single quotes.
Length of file name: 1-54 characters (including the catalog ID).
= addr
Symbolic address of a 54-byte field containing the file name.
= (r)
Register containing the address of a 54-byte field with the file name.
LARGE_FILE
The LARGE_FILE operand determines whether or not the file size may grow beyond 32 GB during data processing (see "Files larger than 32 GB"). The operand is entered in the TFT (Task File Table) and is not evaluated until the file is opened with OPEN.
Default value: | LARGE_FILE = *FORBIDDEN |
In the case of MF=L, only direct specification is permitted.
= FORBIDDEN
The default value means that the specifications in the TU-FCB are to be used.
= ALLOWED
The file is created as a “large file”: the file size may exceed 32 GB.
= addr
The address of an 8-byte field that contains the value for LARGE_FILE.
= (r)
Register containing the address of an 8-byte field with the value for LARGE_FILE.
LINK
Specifies the link name of the file.
The file link name/TFT links the program and file (for information on the file link name/TFT, see the “Introductory Guide to DMS” [1]).
Only a direct specification is allowed for the MF=L form.
= 'name'
If the file link name is enclosed in single quotes “name” may be up to 8 characters long. If the file link name can be addressed via the command interface, it must correspond to the data type <structured_name 1..8> (see the “Commands” manual [3]).
= addr
Address of an 8-byte field containing the file link name.
= (r)
Register which contains the address of an 8-byte field containing the file link name.
LOCVIEW
Operand that specifies whether pages are to be read into a window as soon as MAP is called, or only when the page is accessed.
Default value: | LOCVIEW = *NONE |
The LOCVIEW operand is only effective for windows created with DISPOS=*OBJECT
Only a direct specification is allowed for the MF=L form.
= *MAP
When a window is defined (function FCT=*MAP), all file pages are read into the window as soon as MAP is called. When the file is being read by a SHARUPD=*WEAK user, DIV prevents the file pages from being updated by a parallel write operation from a SHARUPD=*WEAK user who calls SAVE.
= *NONE
A page will be read from the file into the window when first accessed (default setting).
= addr
Symbolic address of a 1-byte field containing a value for LOCVIEW (DIVPLNON | DIVPLMAP; see the layout of the parameter list on "DIV function: CLOSE").
= (r)
Register containing a value for LOCVIEW.
MACID
Defines the second through fourth characters of each field name and equate generated when the macro is expanded.
= IVP
Default value: MACID=IVP
= macid
“macid” is three-character string that defines the second to the fourth character (inclusive) of the generated field names and equates.
MF
The forms of the MF operands are described in detail in the appendix (see "Macro types").
MODE
Specifies OPEN mode (see section "Multiuser operation" in chapter Opening a file):
OPEN mode cannot be changed by an ADD-FILE-LINK command (return code DIVPICFS (INCOMPATIBLE_FILE_SPEC)).
Default value: | MODE=*INPUT |
Only a direct specification is allowed for the MF=L form.
= *INPUT
The file can only be read, so the SAVE function cannot be executed in this OPEN mode.
Parallel INPUT opens are possible, even with the UPAM access method, regardless of the SHARUPD mode.
The file must exist, i.e. must have been opened once with OUTIN.
= *INOUT
The file can be modified, i.e. can be saved with the DIV function SAVE.
The file must exist, i.e. must have been opened once with OUTIN.
Parallel OPEN calls are possible, depending upon the SHARUPD mode.
= *OUTIN
A new file will be created, i.e. the file will be “empty” after the OPEN, and may then be written to. As with MODE=*INOUT, the file can be written to by the SAVE function.
Parallel OPEN calls are possible, depending upon the SHARUPD mode.
In multiuser mode (SHARUPD=*WEAK|*YES), a MODE=*OUTIN user must always be the first to open the file; otherwise, the OPEN call will be rejected.
= addr
Symbolic address of a 1-byte field containing a value for MODE (DIVPINPT | DIVPINOT | DIVPOUTI; see layout of the parameter list, "DIV function: CLOSE").
= (r)
Register containing a value for MODE.
PARAM
Indicates the address of the operand list. This operand is only evaluated in conjunction with MF=E (see also "Macro types").
PREFIX
Specifies the first character of each field name and equate generated when the macro is expanded.
= D
Default value: PREFIX=D
= pre
“pre” is a one-character prefix with which the generated field names and equates are to begin.
SHARUPD
Controls parallel access by a number of users (see the section “Multi-user mode on a single computer” in the “Introductory Guide to DMS” [1].
Default value: | SHARUPD = *NO |
Only a direct specification is allowed for the MF=L form.
= *NO
Allows multiple concurrent reads with MODE=*INPUT or one write with
MODE=*INOUT | *OUTIN.
= *WEAK
Allows multiple concurrent reads with MODE=*INPUT and one write with MODE=*INOUT | *OUTIN.
The data in the window of a read-authorized user (MODE=*INPUT) will therefore depend on the changes that are made by a parallel write-authorized user (MODE=*INOUT | *OUTIN) and on the time at which a page is read into the window. Users with read and write authorization must therefore coordinate their activities. If LOCVIEW=*MAP is specified, the consistency of data in a window is not affected by parallel write operations even if the tasks are not coordinated.
= *YES
Multiple write-authorized users may open a file.
Notes
In this case, data consistency is not maintained by DIV, but must be ensured by the users themselves, e.g. by sequential calls to SAVE.
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).
The SHARUPD mode can be changed by means of an ADD-FILE-LINK command.
= addr
Symbolic address of a 1-byte field containing a value for SHARUPD (value DIVPSNO | DIVPSWEA | DIVPSYES; see layout of the parameter list, "DIV function: CLOSE").
= (r)
Register containing a value for SHARUPD.
Note
DIVPID and DIVPSIZE are return parameters that can only be accessed directly via the parameter list. See subsection "Parameter list" for details.