Description
The REFPAT macro identifies a large data area and tells the system how the program will be referencing that area. Additionally, the program tells the system how many bytes of data it wants the system to bring into central storage on a page fault (that is, each time the program references data that is not in central storage). Use REFPAT if your program accesses a very large data area in a reference pattern that is consistently in a forward or backward direction. The system responds to REFPAT by bringing multiple pages into central storage on a page fault. REFPAT might significantly improve the performance of the program.
REFPAT INSTALL defines the reference pattern and REFPAT REMOVE removes the definition.
Your program can reference an area with one pattern, then later reference the same area with another pattern. Use REFPAT INSTALL to define the first reference pattern and REFPAT REMOVE to remove the definition. Then, issue REFPAT INSTALL to define another pattern for the same area.
- UNITSIZE specifies the size of a "reference unit". A reference unit is a grouping of contiguous bytes that the program references. You might decide a reference unit is the group of bytes that make up an element of an array, or the group of bytes that occur between gaps, or a page (4096 bytes).
- GAP defines the size of "gaps" in the reference pattern. Gaps are areas that the program does not reference; they must be uniform in size and appear throughout the data area at repeating intervals. Not all reference patterns include such a gap.
UNITS specifies how many reference units, as defined on UNITSIZE, you want the system to bring into central storage on a page fault.
The data area can be located in the primary address space, or in a data space identified by the STOKEN parameter.
Each pattern defined by REFPAT INSTALL is associated with the task that represents the caller. A task can have up to 100 reference patterns for different data areas, but cannot have multiple patterns for the same area. Multiple tasks can specify a different reference pattern for the same data area. REFPAT REMOVE removes the association between the pattern and the task.
Environment
The requirements for the caller are:
Environmental factor | Requirement |
---|---|
Minimum authorization: | Problem state and any PSW key |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN=HASN=SASN |
AMODE: | 31-bit |
ASC mode: | Primary or access register (AR) |
Interrupt status: | Enabled for I/O and external interrupts |
Locks: | No locks held |
Control parameters: | Must be in the primary address space. |
Programming requirements
If your program is in AR mode, make sure the SYSSTATE ASCENV=AR macro has been issued to tell the system to generate code appropriate for AR mode.
Restrictions
If you specify STOKEN for a data space, the data space must be owned by a task in the primary address space.
Input register information
Before issuing the REFPAT macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Output register information
- Register
- Contents
- 0
- Reason code if the return code in GPR 15 is not 0; otherwise, used as a work register by the system
- 1
- Used as a work register by the system
- 2-13
- Unchanged
- 14
- Used as a work register by the system
- 15
- Return code
- Register
- Contents
- 1
- Used as a work register by the system
- 2-13
- Unchanged
- 14-15
- Used as work registers by the system
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
Performance implications
The system rejects the REFPAT macro if the values you specify do not benefit the performance of your program. To make sure the system accepts the macro, ask the system to bring in more than three pages (that is, 12288 bytes) on each page fault.
Syntax
The standard form of the REFPAT macro is written as follows:
Syntax | Description |
---|---|
name | name: Symbol. Begin name in column 1. |
␢ | One or more blanks must precede REFPAT. |
REFPAT | |
␢ | One or more blanks must follow REFPAT. |
INSTALL | |
REMOVE | |
,PSTART=start | start: RX-type address or address in register (2) - (12). |
,PEND=end | end: RX-type address or address in register (2) - (12). |
,STOKEN=stoken | stoken: RX-type address or register (2) - (12). |
Default: STOKEN=0 | |
,UNITSIZE=unit size | unit size: RX-type address or register (2) - (12). |
UNITSIZE is required with INSTALL. | |
,GAP=gap variable | gap variable: RX-type address or register (2) - (12). |
Default: GAP=0 | |
,UNITS=unit number | unit number: RX-type address or register (2) - (12). |
Default: UNITS=1 | |
Parameters
The parameters are explained as follows:
- INSTALL
- REMOVE
- INSTALL indicates that the program is to begin referencing the
data area according to a defined pattern. Required parameters on the
INSTALL request are PSTART, PEND, and UNITSIZE. UNITS, GAP, and STOKEN
are optional.
REMOVE indicates that the program has finished referencing the data area, as specified by the previous REFPAT INSTALL request. Required parameters on the REMOVE request are PSTART and PEND. STOKEN is optional on the REMOVE request; UNITSIZE, GAP, and UNITS are not valid.
PSTART and PEND on the INSTALL request must be exactly the same as PSTART and PEND on the REMOVE request for the same reference pattern.
- ,PSTART=start
- A required parameter that contains the address of the first byte
of the data area for which the reference pattern applies. PSTART and
PEND addresses must not straddle the common area boundaries. That
is, for data in the primary address space, all data must be either
in low private, in common, or in high private storage. When a gap exists, define PSTART according to the following rules:
- If direction is forward, PSTART must be the first byte (low-address end) of a reference unit.
- If direction is backward, PSTART must be the last byte (high-address end) of a reference unit.
To code: Specify the RX-type address, or address in register (2)-(12), of a pointer field.
- ,PEND=end
- A required parameter that contains the address of the last byte
of the data area for which the reference pattern applies. If start is
a higher address than end, the system knows that
data reference is in a backward direction.
Whether or not a gap exists, PEND can be any part of a reference unit or a gap.
To code: Specify the RX-type address, or address in register (2)-(12), of a pointer field.
- ,STOKEN=stoken
- Specifies the STOKEN that identifies the data space that contains
the data area. You received the STOKEN either from DSPSERV or from
another program.
If you use STOKEN=0 or do not specify STOKEN, the system assumes the data is in the primary address space.
- ,UNITSIZE=unit size
- Specifies the number of consecutive bytes that you want the system to treat as a reference unit. If the pattern includes a gap, the reference unit is the grouping of bytes that lie between the gaps. If the pattern does not include a gap, you can use any logical grouping of bytes that your data structure suggests, such as an element, a row or two, or a page (4096 bytes). UNITSIZE is required for the INSTALL request.
- ,GAP=gap variable
- Specifies the gap, in bytes, of the reference pattern. The default is GAP=0.
- ,UNITS=unit number
- Specifies the number of reference units, as defined on UNITSIZE,
the system is to page in at one time. The default is one reference
unit or UNITS=1. To figure out how many bytes the system brings in
at a time:
- If there is no gap, multiply the UNITS value by the UNITSIZE value and round up to the nearest 4096-byte boundary.
- If there is a gap, the number depends on values of UNITSIZE, GAP, UNITS, plus the location of the reference units and gaps relative to a page boundary. The system brings in the pages that contain the reference units. It does not bring in pages that contain only data in the gap. z/OS MVS Programming: Assembler Services Guide can help you code the parameters.
Return and reason codes
Return and reason codes, in hexadecimal, from REFPAT are:
Return Code | Reason Code | Meaning |
---|---|---|
00 | None. | REFPAT completed successfully. |
04 | xx0001xx | REFPAT completed successfully; however, the system did not accept the reference pattern the caller specified. The system decided that the normal paging algorithms would be more efficient. |
08 | xx0002xx | Unsuccessful completion. The range that the caller specified on the INSTALL request overlaps the range that a previous request specified. |
08 | xx0003xx | Unsuccessful completion. The number of existing REFPAT INSTALL requests for the task exceeds 100, the maximum number the system allows. |
08 | xx0004xx | Unsuccessful completion. LSQA storage is not available for the macro service. |
08 | xx0101xx | Unsuccessful completion. The caller specified the REMOVE request; however, no INSTALL request was in effect for the specified range. Check to see if the system rejected the previous INSTALL request for the range. |
Example 1
REFPAT INSTALL,PSTART=(4),PEND=(R5),GAP=4096,UNITSIZE=8192,UNITS=4
Example 2
REFPAT REMOVE,PSTART=(4),PEND=(R5)