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.

On REFPAT INSTALL, you describe the data area, the reference pattern, and tell the system how many bytes of data you want it to bring into central storage on a page fault. Two parameters, UNITSIZE and GAP, determine the reference pattern:

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.

Parent topic: REFPAT — Define and end a reference pattern

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

When control returns to the caller, the general purpose registers (GPRs) contain:
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
When control returns to the caller, the ARs contain:
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

Define a reference pattern in which the program processes 8192 bytes and skips over 4096 bytes in a continuing way throughout an array. Registers 4 and 5 contain pointers to locations in storage which contain the starting and ending addresses of the array. Ask the system to bring in eight pages on each page fault. 
REFPAT  INSTALL,PSTART=(4),PEND=(R5),GAP=4096,UNITSIZE=8192,UNITS=4

Example 2

Tell the system you have finished using the array using that pattern: 
REFPAT  REMOVE,PSTART=(4),PEND=(R5)