Description
Use the IARVSERV macro to define virtual storage areas to be shared by programs. This sharing can reduce the amount of processor storage required and the I/O necessary to support many applications that process large amounts of data. It also provides a way for programs executing in 24 bit addressing mode to access data residing above 16 megabytes.
Using IARVSERV allows programs to share data in virtual storage without the central storage constraints and processor overhead of other methods of sharing data. The type of storage access is controlled so that you can choose to allow read only or writing to the shared data with several variations. The type of storage access is called a view. Data to be shared is called the source. The source is the original data or the virtual storage that contains the data to be shared. This data is made accessible through an obtained storage area called the target. The source and target form a sharing group.
- Request that a virtual storage area (source) be eligible to be shared through a target view (SHARE parameter).
- Request that the source and targets no longer be shared (UNSHARE parameter).
- Request that the type of storage access to the data be changed.
See z/OS MVS Programming: Authorized Assembler Services Guide for more information about sharing data through the use of the IARVSERV macro. IARVSERV is also described in z/OS MVS Programming: Assembler Services Reference ABE-HSP.
Environment
The requirements for the caller are:
Environmental factor | Requirement |
---|---|
Minimum authorization: | Problem state with PSW key that allows access to the source, target, or both, depending on the value specified through the TARGET_VIEW parameter. If the value specified on the NUMRANGE parameter is greater that 16, supervisor state or PSW key 0-7 is required. See z/OS MVS Programming: Authorized Assembler Services Guide for additional information. |
Dispatchable unit mode: | Task or SRB. |
Cross memory mode: | Any PASN, any HASN, any SASN. |
AMODE: | 31- or 64-bit. |
ASC mode: | Primary or access register (AR). |
Interrupt status: | Enabled for I/O and external interrupts. |
Locks: | The caller may hold the local lock, but is not required to hold any locks. |
Control parameters: | Control parameters must be in the primary address space. |
Programming requirements
- You must specify a range list that is mapped by the IARVRL macro. This is done using the RANGLIST parameter.
- If you specify more than 16 ranges, you must put the range list in fixed storage.
- The address space owing the source or targets must be swapped
in when IARVSERV is issued if either the source or target area is:
- in an address space other than the home address space of the caller, or
- in a data space owned by an address space other than the home address of the caller.
The address space must remain swapped in until the IARVSERV macro has completed.
- Before your program issues the IARVSERV macro, it must use the GETMAIN, STORAGE, or DSPSERV macro to obtain storage for the source, target, or both.
- Attributes for storage depend on the subpool specified on the GETMAIN, STORAGE, or DSPSERV macros. See z/OS MVS Programming: Authorized Assembler Services Guide for information on virtual storage management and subpool attributes. The following table shows the permitted combinations of storage attributes supported for the source and target areas (with the exceptions as noted in Restrictions).
Source Area | Target Area |
---|---|
Pageable | Pageable |
Fixed in non-swappable storage with central storage below 16 megabytes | Any kind of storage |
Fixed in non-swappable storage with central storage above 16 megabytes | Any storage that does not require the backing of central storage below 16 megabytes (if fixed) |
Fixed in swappable storage | Any kind of storage, provided that TARGET_VIEW=UNIQUEWRITE parameter is specified |
Restrictions
- For the SHARE parameter, the source area must not contain pages in the nucleus (read-only, extended read-only, read-write and extended read-write areas).
- For the SHARE parameter, the target area must not contain page-protected or page-fixed pages.
- For the UNSHARE parameter, the sharing group must not contain page protected-pages unless the RETAIN=YES parameteris specified. The sharing group must also not contain any page-fixed pages.
- The TPROT instruction cannot be used to determine whether the invoker has write access to views in a share group with unique-write views or to a target-write view. The TPROT instruction will indicate that these views are protected when the invoker has write access.
Input register information
Before issuing the IARVSERV 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 GPR 15 contains a non-zero return code; 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
- 0-1
- Used as work registers 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
Take care when using the RETAIN=YES parameter value. With RETAIN=YES, storage is not returned to the system which reduces the amount available to the system and other programs, thus potentially affecting system performance.
In order to expedite the return of all internal control blocks for the shared storage back to the system, IBM recommends issuing IARVSERV UNSHARE against all views for both source and target that are originally shared. For an example of how to code the UNSHARE parameter, see z/OS MVS Programming: Assembler Services Reference IAR-XCT.
Syntax
The standard form of the IARVSERV macro is written as follows:
Syntax | Description |
---|---|
name | name: symbol. Begin name in column 1. |
␢ | One or more blanks must precede IARVSERV. |
IARVSERV | |
␢ | One or more blanks must follow IARVSERV. |
SHARE | |
UNSHARE | |
CHANGEACCESS | |
,RANGLIST=ranglist_addr | ranglist_addr: RS-type address, or register (2) - (12). |
,NUMRANGE=numrange_addr | numrange_addr: RS-type address, or register (2) - (12). |
Default: 1 range | |
,TARGET_VIEW=READONLY | |
,TARGET_VIEW=SHAREDWRITE | |
,TARGET_VIEW=UNIQUEWRITE | |
,TARGET_VIEW=TARGETWRITE | |
,TARGET_VIEW=LIKESOURCE | |
,TARGET_VIEW=HIDDEN | |
,COPYNOW | |
,RETAIN=NO | Default: RETAIN=NO |
,RETAIN=YES | |
,PLISTVER=IMPLIED_VERSION | |
,PLISTVER=MAX | Default: IMPLIED_VERSION |
,PLISTVER=plistver | plistver: 0 |
Parameters
The SHARE, UNSHARE, and CHANGEACCESS parameters designate the services of the IARVSERV macro, and are mutually exclusive.
The parameters are explained as follows:
- SHARE
- Requests that the source be made shareable through the target to create a sharing group. When you issue the IARVSERV macro with SHARE, you must specify the RANGLIST and the TARGET_VIEW parameters. The NUMRANGE parameter is optional.
- UNSHARE
- Requests that the specified virtual storage no longer be used to access shared storage. When you issue the IARVSERV macro with UNSHARE, you must specify the RANGLIST parameter. The NUMRANGE, and RETAIN parameters are optional. Using the RETAIN parameter can allow the target area data to remain available to other programs that can access the target area.
- CHANGEACCESS
- Requests that the type of access to the specified virtual storage be changed. When you issue the IARVSERV macro with CHANGEACCESS, you must specify the RANGLIST and the TARGET_VIEW parameters. The NUMRANGE parameter is optional.
- ,RANGLIST=ranglist_addr
- Specifies the name (RS-type) or address (in register 2-12) of a required input fullword that contains the address of the range list. The range list consists of a number of entries (as specified by NUMRANGE) where each entry is 28 bytes long. A mapping of each entry is provided through the mapping macro IARVRL.
- ,NUMRANGE=numrange_addr
- Specifies the name (RS-type) or address (in register 2-12) of an optional parameter that provides the number of entries in the supplied RANGLIST. Only authorized programs can specify more that 16 entries in the range list. If you do not specify NUMRANGE, the system assumes the range list contains only one entry.
- ,TARGET_VIEW=READONLY
- ,TARGET_VIEW=SHAREDWRITE
- ,TARGET_VIEW=UNIQUEWRITE
- ,TARGET_VIEW=TARGETWRITE
- ,TARGET_VIEW=LIKESOURCE
- ,TARGET_VIEW=HIDDEN
- Specifies the way you want to share storage when used on storage
not already part of a sharing group, or how you want to change or
add storage access to the sharing group for storage already shared. The keywords that are valid for TARGET_VIEW and their meanings follow:
- READONLY
- Specifies that the target can be used only to read shared data. Any attempt to alter shared data by writing into the target will cause a program check.
- SHAREDWRITE
- Specifies that the target can be used to read or modify shared data. When a program changes data in the target, the new data becomes visible among all those programs that have READONLY and SHAREDWRITE access to the source. Those programs with UNIQUEWRITE access to the source will not see the changed data.
- UNIQUEWRITE
- Specifies that the target can be used to read shared data and to retain a private copy of the shared data should the source or any target get altered. When another user of the target modifies the data, the page in the target containing the modified data becomes a private copy that is unique to that user (with UNIQUEWRITE) and not accessible to any other program.
- TARGETWRITE
- Specifies that the target can be used to read shared data and retain a private copy of the shared data if this view of the shared data is altered. When another user of the target area writes new data into the target area, any page in the target area containing the new data becomes a private copy that is unique and is not seen by to any other user. The page is no longer a member of any sharing group. The original source data is unchanged. When a SHAREDWRITE view of the data gets altered, the TARGETWRITE view will see those changes.
- LIKESOURCE
- Specifies that the view type for the new target area is to be the same as the current view of the source. If the source is not currently shared, a copy of the source is made to the new target as if COPYNOW had been coded.
- HIDDEN
- Specifies that the data in the target area will be inaccessible until the view type is changed to READONLY, SHAREDWRITE, UNIQUEWRITE, or TARGETWRITE. Any attempt to access a hidden target area will cause a program check.
- ,COPYNOW
- Specifies whether the target should get a copy of the source data when using UNIQUEWRITE or LIKESOURCE. You can use COPYNOW only when you specify TARGET_VIEW=UNIQUEWRITE or TARGET_VIEW=LIKESOURCE.
- ,RETAIN=YES
- ,RETAIN=NO
- Specifies whether a copy of the shared data is to be retained
in the target after the system finishes processing the UNSHARE request.
- RETAIN=YES
- Specifies that the target view should retain a copy of the shared data. Using UNSHARE with RETAIN=YES requires the system to allocate new resources to back the target area.
- RETAIN=NO
- Specifies that the contents of the target area are unpredictable.
To ensure zeroes, the user should issue a PGSER RELEASE or DSPSERV
RELEASE on the area after unsharing it. RETAIN=NO is the default.
Note: PGRLSE, PGSER RELEASE, PGSER FREE with RELEASE=Y, and PGFREE RELEASE=Y may ignore some or all of the pages in the input range and will not notify the caller if this was done.
Any pages in the input range that match any of the following conditions will be skipped, and processing continues with the next page in the range:- Storage is not allocated or all pages in a segment have not yet been referenced.
- Page is in PSA, SQA or LSQA.
- Page is V=R. Effectively, it's fixed.
- Page is in BLDL, (E)PLPA, or (E)MLPA.
- Page has a page fix in progress or a nonzero FIX count.
- Pages with COMMIT in progress or with DISASSOCIATE in progress.
- ,PLISTVER=IMPLIED_VERSION
- ,PLISTVER=MAX
- ,PLISTVER=plistver
- Specifies the version of the macro. PLISTVER determines which
parameter list the system generates. PLISTVER is an optional input
parameter on all forms of the macro, including the list form. When
using PLISTVER, specify it on all macro forms used for a request and
with the same value on all of the macro forms. The values are:
- IMPLIED_VERSION, which is the lowest version that allows all parameters specified on the request to be processed. If you omit the PLISTVER parameter, IMPLIED_VERSION is the default.
- MAX, if you want the parameter list to be the largest size
currently possible. This size might grow from release to release
and affect the amount of storage that your program needs.
If you can tolerate the size change, IBM recommends that you always specify PLISTVER=MAX on the list form of the macro. Specifying MAX ensures that the list-form parameter list is always long enough to hold all the parameters you might specify on the execute form; in this way, MAX ensures that the parameter list does not overwrite nearby storage.
- 0, if you use the currently available parameters.
To code, specify in this input parameter one of the following:- IMPLIED_VERSION
- MAX
- A decimal value of 0
ABEND codes
IARVSERV might abnormally terminate with the abend code X'6C5'. See z/OS MVS System Codes for an explanation and programmer response.
Return and reason codes
When the IARVSERV macro returns control to your program, GPR 15 contains the return code. If the return code is not 0, GPR 0 contains the reason code.
Hexadecimal Return Code | Hexadecimal Reason Code | Meaning and Action |
---|---|---|
00 | None | Meaning: The IARVSERV request completed
successfully. Action: None required. |
04 | xx0101xx | Meaning IARVSERV SHARE completed successfully.
The processor does not support SHARE for UNIQUEWRITE. A unique copy
of the target was made by the system. Action: None required. |
04 | xx0102xx | Meaning: IARVSERV SHARE completed successfully.
However, the system found a condition that would lead to a storage
requirement conflict for sharing with UNIQUEWRITE. For example, the
source might be in non-pageable storage. A copy of the target was
made by the system to avoid this conflict. Action: None required. However, you might want to correct the storage conflict. |
04 | xx0103xx | Meaning: IARVSERV SHARE found that some
source pages were not obtained using the GETMAIN or STORAGE macros,
or the source and target keys do not match and the request is for
a UNIQUEWRITE target view. If the corresponding target pages were
obtained using the GETMAIN or STORAGE macro, then they have been made
first reference. Action: This is not necessarily an error. If you think you should not get this reason code, check program to be sure GETMAIN or STORAGE is issued and storage is of the same storage key for all source and target storage prior to using IARVSERV. |
04 | xx0203xx | Meaning: IARVSERV UNSHARE completed successfully.
However, the system has overridden the RETAIN=NO option and kept a
copy of the data in the target. Action: None required. However, you may want to correct your use of DIV. |
04 | xx0204xx | Meaning: IARVSERV UNSHARE completed successfully.
The system has overridden the RETAIN=YES option because the shared
data is associated with a DIV object, and the target area is not the
original window mapped to the DIV object. The data in the target
is unpredictable. Action: None required. |
04 | xx0205xx | Meaning: IARVSERV UNSHARE completed successfully.
Some pages in the target area no longer belong to any sharing group.
This could be due to a copy being created by UNIQUEWRITE, or a second
invocation of UNSHARE on the same view. Action: None required. |
04 | xx0301xx | Meaning: IARVSERV CHANGEACCESS completed
successfully. The processor does not support CHANGEACCESS for UNIQUEWRITE,
and a unique copy of the target page was made. Action: None required. |
04 | xx030Cxx | Meaning: IARVSERV CHANGEACCESS completed
successfully. The system processed a CHANGEACCESS request for UNIQUEWRITE
or TARGETWRITE for non-shared pages as a SHAREDWRITE request. Action: None required. |
08 | xx0104xx | Meaning: Environmental error. An unauthorized
user attempted to share more pages than allowed by the installation
(as defined through the installation exit IEFUSI). Action: Contact your system programmer to find out your installation limit and reduce the number of shared pages. |
08 | xx0105xx | Meaning: Environmental error. IARVSERV
SHARE was requested with TARGETWRITE, but the SOP hardware feature
was not available. Action: Contact your system programmer to find out when the SOP feature might become available. |
08 | xx0305xx | Meaning: Environmental error. IARVSERV
CHANGEACCESS was requested with TARGETWRITE, but the SOP hardware
feature was not available. Action: Contact your system programmer to find out when the SOP feature may become available. |
0C | xx010Axx | Meaning: Environmental error. IARVSERV
SHARE cannot complete the request because of a shortage of resources. Action: Retry the request one or more times to see if resources become available. Contact the system programmer to determine resources available to you. |
0C | xx013Cxx | Meaning: System error. IARVSERV SHARE cannot complete the request because
a required page is unavailable or lost. Action: Check the paging data set for possible I/O errors. Refer to X'028' abend description in z/OS MVS System Codes for paging error advice. |
0C | xx020Bxx | Meaning: System error. IARVSERV UNSHARE cannot complete the request
because of a required page being unavailable or lost. Action: Check the logrec data set for possible I/O errors. Refer to X'028' abend description in z/OS MVS System Codes for paging error advice. |
0C | xx030Bxx | Meaning: System error. IARVSERV CHANGEACCESS cannot complete the request
because of a required page being unavailable or lost. Action: Check the logrec data set for possible I/O errors. Refer to X'028' abend description in z/OS MVS System Codes for paging error advice. |
Example 1
SERV1 IARVSERV SHARE,RANGLIST=(4),TARGET_VIEW=READONLY
*
IARVRL
Example 2
SERV2 IARVSERV UNSHARE,RANGLIST=(4),RETAIN=NO
*
IARVRL
Example 3
SERV3 IARVSERV SHARE,RANGLIST=VRLPTR,TARGET_VIEW=READONLY
*
VRLPTR DC A(MYVRL1)
MYVRL1 DS 7F
IARVRL
Example 4
SERV4 IARVSERV SHARE,RANGLIST=(5),TARGET_VIEW=TARGETWRITE
*
IARVRL
Example 5
SERV5 IARVSERV CHANGEACCESS,RANGLIST=(5),TARGET_VIEW=HIDDEN
*
IARVRL