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.
See z/OS MVS Programming: Assembler Services Guide for more information about sharing data through the use of the IARVSERV macro.
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. See z/OS MVS Programming: 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. |
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.
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.
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 the example in this book.
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 |
The SHARE, UNSHARE, and CHANGEACCESS parameters designate the services of the IARVSERV macro, and are mutually exclusive.
The parameters are explained as follows:
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.
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.
IARVSERV might abnormally terminate with the abend code X'6C5'. See z/OS MVS System Codes for an explanation and programmer response.
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. 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. |
SERV1 IARVSERV SHARE,RANGLIST=(4),TARGET_VIEW=READONLY
*
IARVRL
SERV2 IARVSERV UNSHARE,RANGLIST=(4),RETAIN=NO
*
IARVRL
SERV3 IARVSERV SHARE,RANGLIST=VRLPTR,TARGET_VIEW=READONLY
*
VRLPTR DC A(MYVRL1)
MYVRL1 DS 7F
IARVRL
SERV4 IARVSERV SHARE,RANGLIST=(5),TARGET_VIEW=TARGETWRITE
*
IARVRL
SERV5 IARVSERV CHANGEACCESS,RANGLIST=(5),TARGET_VIEW=HIDDEN
*
IARVRL
* The following example share one page of storage
* for both source and target using readonly view,
* and use a register to specify the address of the range list
* Clear the VRL share list. This will clear also the Stoken and
* the Alet fields for both Source and Target
XC VRLSHAR,VRLSHAR Clear VRL share list
* Obtain storage for Source (one page only)
TITLE "IARVSERV- GET SOURCE STORAGE - ONE PAGE'
STORAGE OBTAIN,LENGTH=4096
ST 1,SADDR Store Source address
* Obtain storage for Target (one page only)
TITLE 'IARVSERV- GET TARGET STORAGE - ONE PAGE'
STORAGE OBTAIN,LENGTH=4096
ST 1,TADDR Store Target address
* Set the VRL share list
TITLE 'IARVSERV- SET VRL LIST FOR SHARE'
LA 1,1 Load number of pages to share
ST 1,VRLNUMPG Store it in VRL share list
L 1,SADDR Load Source address
ST 1,VRLSVSA Store it in VRL share list
L 1,TADDR Load Target address
ST 1,VRLTVSA Store it in VRL share list
*
LA 7,VRLSHAR Get address of VRLSHAR list
ST 7,VRLPTR Store it in VRLPTR
LA 7,VRLPTR Save address of rangelist
* Now issue share for both Source and Target
TITLE 'IARVSERV- SHARE THE STORAGE'
IARVSERV SHARE, *
RANGLIST=(7), *
NUMRANGE=1, *
TARGET_VIEW=READONLY
* The declares for example
*
VRLSHAR DS 0XL28
VRLSVSA DS A
VRLSSTK1 DS XL4
VRLSALET DS F
VRLNUMPG DS A
VRLTVSA DS A
VRLTSTK1 DS XL4
VRLTALET DS F
VRLEND1 DS 0F
VRLPTR DS XL4
SADDR DS XL4 Address for Source storage
TADDR DS XL4 Address for Target storage
* The following example illustrates how to expediate the return
* of all control blocks used to manage the shared storage by
* unsharing both Source and Target views which were shared in
* the previous example
TITLE 'IARVSERV- SET VRL UNSHARE LIST'
* Clear the VRL unshare list. This will clear also the Stoken
* and the Alet fields for both Source and Target in all ranges
* of the list
XC,VRLUNSH,VRLUNSH
* Set first range in the VRL unshare list
LA 1,1 Load number of pages to unshare
ST 1,SNUMPG1 Store it for first range
L 1,TADDR Get target address
ST 1,TVSA1 Save it in the target address
* Set second range in the VRL unshare list
LA 1,1 Load number of pages to unshare
ST 1,SNUMPG2 Store it for second range
L 1,SADDR Get source address
ST 1,TVSA2 Save it in the target address
*
LA 7,VRLUNSH Get address of VRL unshare list
ST 7,VRLPTR Store it in VRLPTR
LA 7,VRLPTR Save address of rangelist
* Now issue unshare for both Source and Target
TITLE 'IARVSERV- UNSHARE THE STORAGE'
IARVSERV UNSHARE, *
RANGLIST=(7), *
NUMRANGE=2
* The declares for example
*
VRLUNSH DS 0XL56
SVSA1 DS A
SSTK1 DS XL4
SALET1 DS F
SNUMPG1 DS A
TVSA1 DS A
TSTK1 DS XL4
TALET1 DS F
SVSA2 DS A
SSTK2 DS XL4
SALET2 DS F
SNUMPG2 DS A
TVSA2 DS A
TSTK2 DS XL4
TALET2 DS F
VRLEND2 DS 0F