Description

The requirements for the caller are:

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 z/OS MVS Programming: Assembler Services Reference IAR-XCT.

The standard form of the IARVSERV macro is written as follows:

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

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.