The SAVE function writes modified window pages to a file, if they lie in a file region defined by SPAN and OFFSET.
If modified window pages exist in the defined region and these pages lie beyond the logical end-of-file, the file is extended: the last modified page defines the new logical EOF. When a file is extended, unmodified window pages that lie between the previous and the new logical EOF are also written to the file. If no window has been defined for file segments that need to be added, no pages are written to the file for these segments, and the contents of the corresponding file pages are undefined (see also the logical extension of files as described in the “Introductory Guide to DMS” [1]).
If the logical last page of the file is in a window that was defined with DISPOS=*UNCHNG, and if no conditions exist for logical file extension, then the file is truncated if the logical last page was not accessed, i.e. if the logical last page is still in its initial state. Truncation ends when a page which is no longer in the initial state, a previously saved page (with SAVE), or a page which does not belong to a DISPOS=*UNCHNG window is encountered (see also the logical truncation of files as described in the “Introductory Guide to DMS” [1]).
A page that is written to file with SAVE is no longer considered modified, i.e. will not be written to the file by a subsequent SAVE unless it is modified again after the last SAVE.
The SAVE function cannot be used if the file is opened with MODE=*INPUT.
The SAVE function evaluates only the function operands described below.
Format FCT=*SAVE
Operation | Operands |
|
|
| |
| |
|
Operand descriptions
FCT
Specifies the DIV function to be executed.
Only a direct specification is allowed for the MF=L form.
= *SAVE
The DIV function SAVE writes modified window pages in the file back to disk (see also "DIV function: SAVE").
= addr
Symbolic address of a 1-byte field containing the value for the SAVE function (DIVPSAVE; see the layout of the parameter list on "DIV function: CLOSE").
= (r)
Register containing the value for the SAVE function.
ID
Specifies the OPEN for which the DIV function is to be executed.
If the same parameter list is used as in OPEN, the ID need not be specified, since the ID of the OPEN will already be in the parameter list. The ID is contained in the DIVPID field of the parameter list.
If a different parameter list is used than the one for OPEN, the ID can be specified here and be transferred to the new parameter list by using the MF=M form of the DIV macro.
ID cannot be specified with the MF=L form.
= addr
Symbolic address of an 8-byte field containing the identification.
= (r)
Register containing the address of the 8-byte field.
MACID
See the description under the format FCT=*OPEN on "DIV function: OPEN".
MF
The forms of the MF operands are described in detail in the appendix ("Macro types").
OFFSET
The operands OFFSET and SPAN specify the file region to which the SAVE function applies.
OFFSET specifies the beginning of the file region. It indicates from which block (i.e. which 4-Kbyte page) the file region begins.
SPAN defines the number of 4-Kbyte blocks in the file region (i.e. the length of the region).
The SAVE function applies to all window pages of the file region defined by OFFSET and SPAN.
Default value: | OFFSET = 0 |
If SPAN is omitted or SPAN = 0 is specified, the file region is selected so as to enable the last page of the last window defined for the OPEN to be included in the region. If neither OFFSET nor SPAN is specified, all pages of all windows defined for the OPEN are taken into account.
Only a direct specification is allowed for the MF=L form.
= number
Specifies the first block of the file region to be mapped in virtual address space. The value of OFFSET is limited by the maximum size of a file in 4-KB pages minus 1:
0 <= number <= 8388606 for LARGE_FILE=*FORBIDDEN
0 <= number <= 1073741823 for LARGE_FILE=*ALLOWED
= addr
Symbolic address of a 4-byte field containing the numeric value (binary) of the specification for the first block of the file region to be mapped in virtual address space.
= *equ
Equate representing the numeric value of the specification for the first block of the file region to be mapped in virtual address space. The '*' character must precede the name of the equate.
= (r)
Register containing the numeric value of the specification for the first block of the file region to be mapped in virtual address space.
PARAM
See the description under the format FCT=*OPEN on "DIV function: OPEN".
PREFIX
See the description under the format FCT=*OPEN on "DIV function: OPEN".
SPAN
SPAN and OFFSET define the file region to which the SAVE function applies.
Default value: | SPAN = 0 |
For a description of SPAN see the OFFSET operand.
Only a direct specification is allowed for the MF=L form.
= number
Specifies the first block of the file region to be mapped in virtual address space. The value of SPAN is limited by the maximum size of a file in 4-KB pages:
0 <= number <= 8388607 for LARGE_FILE=*FORBIDDEN
0 <= number <= 1073741824 for LARGE_FILE=*ALLOWED
= addr
Symbolic address of a 4-byte field containing the length of the file region in 4-Kbyte blocks (binary).
= *equ
Equate that specifies the length of the file region in 4-Kbyte blocks (binary). The '*' character must precede the name of the equate.
= (r)
Register containing the length of the file region in 4-Kbyte blocks (binary).
Special parameters in the parameter list
The following parameter is a return parameter that can only be accessed directly via the parameter list. The name of the parameter list generated by means of MF=D (without a PREFIX specification) is specified:
DIVPSIZE
Since the file may be logically extended or truncated by SAVE, DIVPSIZE is updated after every successful call to SAVE and contains the number of the last logical 4K page of the file (1 means that the first file page is the last logical page; 0 means that the file is empty).