The MAP function creates a window in an address space (program or data space). A window is assigned to a file region or an entire file.
The address space must be allocated before calling the MAP function (explicitly by REQM, implicitly by the linking loader). The address space in which a window is located cannot be released until the window has been disabled (using UNMAP).
The window region should not include a READ-ONLY page, and at the time of MAP, no I/O fixed page, i.e. no page on which I/O is enabled (e.g. asynchronous I/O by UPAM during the MAP function).
The address space must not be shareable.
When the MAP function is executed, DIV ensures that all pages of the file which are represented by the window are allocated for. If part or all of a window lies beyond the physical end-of-file, the required additional pages are allocated. No allocation is made for a user opening the file in INPUT mode.
The DISPOS operand can be used to specify whether pages of the file are to be displayed in the window, or whether the data in the address space should be retained.
MAP only evaluates the function operands described below.
Format FCT=*MAP
Operation | Operands |
|
|
| |
| |
| |
|
Operand descriptions
AREA
Specifies the starting address of the window within the address space defined by the SPID operand (data or program space).
The address space must be allocated before calling the MAP function (macro REQM, DSPSRV, linking loader) and cannot be released until the window is disabled (UNMAP).
The window must lie on a 4K page boundary. Its length is specified by the SPAN operand.
Each page in the virtual address space may only belong to a single window. Once a page is assigned to a window, any request to use it for another window is rejected. In the MF=L form, the starting address of the window can only be specified by a symbolic address.
= addr
Symbolic address of a 4-byte field containing the starting address of the window.
= (r)
Register containing the starting address of the window.
DISPOS
Determines what data should be visible in the window after MAP: unchanged data in the address space (as before MAP), or the data of the corresponding pages of the file.
Default value: | DISPOS = *OBJECT |
Only a direct specification is allowed for the MF=L form.
= *OBJECT
The file pages appear in the window. Pages behind the last logical page appear filled with X'00'.
= *UNCHNG
The window pages retain their contents and are not replaced by pages from the file.
A window defined with DISPOS=*UNCHNG can be used to initialize the corresponding file pages with the page contents of the virtual address space when SAVE is called (see the SAVE function and the logical extension of filesas described in the “Introductory Guide to DMS” [1]).
DISPOS=*FRESH must not be specified with FCT=*MAP.
= addr
Symbolic address of a 1-byte field containing a value for DISPOS (DIVPOBJ | DIVPUNCH; see layout of the parameter list, "DIV function: CLOSE")).
= (r)
Register containing a value for DISPOS.
FCT
Specifies the DIV function to be executed.
Only a direct specification is allowed for the MF=L form.
= *MAP
The MAP function is used to define a window in an address space (program or data space). See "DIV function: MAP" for details.
= addr
Symbolic address of a 1-byte field containing the value for the MAP function (value DIVMAP, see the layout of the parameter list on "DIV function: CLOSE").
= (r)
Register containing a value for the MAP 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 for which the window is created.
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 file region defined by OFFSET and SPAN is assigned to the window in virtual address space.
Default value: | OFFSET = 0 |
If OFFSET = 0, the first window page corresponds to the first page of the file. The file is read into the window from the beginning of the file up to the length defined by SPAN.
If SPAN is not specified (or SPAN=0), the window size is selected such that the last window page corresponds to the logical last page of the file. If neither OFFSET nor SPAN is defined, an appropriate window size that can accommodate the entire file (until the logical last page) in the window is selected.
If the file is empty and SPAN has been assigned default values, the call will be rejected.
SPAN and OFFSET can be selected such that pages lying beyond the logical EOF appear in the window. Pages which follow the logical EOF are displayed in the window filled with X'00'.
SPAN and OFFSET can also be selected such that pages which follow the physical EOF appear in the window. If OPEN OUTIN | INOUT is then called, MAP will allocate additional blocks for the file, ending with the file page that corresponds to the last window page.
Note
A file can be physically extended with MAP, and SAVE can be used to extend (or reduce) it logically.
The logical EOF is not changed by MAP (only by SAVE).
A file page can be assigned to only one window for the same OPEN, but may be assigned to multiple windows if they are part of different OPEN calls.
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".
PFCOUNT
If pages of a window are accessed sequentially (in ascending order), the number of page fault interrupts can be reduced by specifying a PFCOUNT. If a file page is read into a window as a consequence of a page fault interrupt, and if PFCOUNT has been specified for the window, all following pages are read in a single read operation until the number of pages specified in PFCOUNT, the end of the window, or a previously read page is reached.
Only a direct specification is allowed for the MF=L form.
= number
Specifies how many additional pages are to be read.
0 <= number <= 15
= addr
Symbolic address of a 4-byte field containing a numeric value (binary) for the number of pages.
= *equ
Equate, representing the numeric value. The '*' character must precede the name of the equate.
= (r)
Specifies a register containing the numeric value.
SPAN
The operands OFFSET and SPAN define the file region for which the window is created. The file region specified by SPAN and OFFSET is assigned to the window in virtual address space.
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 length of the file region in 4K blocks. The value for SPAN is restricted to the maximum address space (2 Gbytes) in units of 4K pages.
0 <= number <= 524287
= addr
Symbolic address of a 4-byte field which specifies the length of the data area in 4KB blocks (binary).
= *equ
Equate to define the length of the file region in 4K blocks (binary). The '*' character must precede the name of the equate.
= (r)
Register containing the length of the file region in 4K blocks (binary).
SPID
Specifies the address space (program or data space) in which the window is to be created.
Default value: | SPID = 0 |
If SPID is omitted or SPID = 0 is specified, the window is created in program space; otherwise, SPID defines a data space.
SPID cannot be specified with the MF=L form.
= addr
Symbolic address of an 8-byte field containing the identification of the data space.
= (r)
Register with the address of an 8-byte field containing the identification of the data space.