Description

The IARV64 macro allows a program to use the full range of virtual storage in an address space that is supported by 64-bit addresses. The macro creates and frees storage areas above the two gigabyte address and manages the physical frames behind the storage. Each storage area is a multiple of one megabyte in size and begins on a megabyte boundary. You can think of the IARV64 macro as the GETMAIN/FREEMAIN, PGSER or STORAGE macro for virtual storage above the the two gigabyte address.

The two gigabyte address in the address space is marked by a virtual line called the bar. The bar separates storage below the two gigabyte address, called below the bar, from storage above the two gigabyte address, called above the bar. The area above the bar is intended to be used for data only, not for executing programs. Programs use the IARV64 macro to obtain storage above the bar in “chunks” of virtual storage called memory objects. Your installation can set a limit on the use of the address space above the bar for a single address space. The limit is called the MEMLIMIT.

When you create a memory object you can specify a guard area (not accessible) and a usable area. Later, you can change all or some of a guard area into an accessible area and vice versa.

The following services are provided:

GETSTOR: Create a memory object. (REQUEST=GETSTOR option of IARV64)
PAGEOUT: Notify the system that data within physical pages of one or more memory objects will not be used in the near future. (REQUEST=PAGEOUT option of IARV64)
PAGEIN: Notify the system that data within physical pages of one or more memory objects are needed in the near future. (REQUEST=PAGEIN option of IARV64)
DISCARDDATA: Discard data within physical pages of one or more memory objects. (REQUEST=DISCARDDATA option of IARV64)
CHANGEGUARD: Request that a specified range in a memory object be changed from the guard state to the usable state or vice versa. (REQUEST=CHANGEGUARD option of IARV64)
DETACH: Free one or more memory objects. (REQUEST=DETACH option of IARV64)

For guidance information on the use of 64–bit virtual storage allocation, see z/OS MVS Programming: Assembler Services Guide.

After the separate descriptions of each individual Request are the following sections which apply to all of the Requests:

The abend codes in Abend and abend reason codes,
The return and reason codes in Return and reason codes, and
Examples of using IARV64 in Example
Note: The examples apply to REQUEST=GETSTOR and DETACH.

Facts associated with these services:

A segment represents one megabyte of virtual storage on a one megabyte boundary.
The limit of the amount of storage per address space allowed to be used above the bar is called the MEMLIMIT. This is similar to the REGION parameter for storage below the bar. The following category of storage does not count against the MEMLIMIT:
- The guard area in a memory object.

Abend and abend reason codes

IARV64 might abnormally terminate with hexidecimal abend code DC2. Seez/OS MVS System Codes for an explanation and programmer response.

Return and reason codes

When the IARV64 macro returns control to your program:

GPR 15 (and retcode, when you code RETCODE) contains a return code.
When the value in GPR 15 is not zero, GPR 0 (and rsncode, when you code RSNCODE) contains a reason code.

The following table identifies the hexadecimal return and reason codes. IBM® support personnel may request the entire reason code, including the xx value.

Table 1. Return and Reason Codes for the IARV64 Macro
Hexadecimal Return Code	Hexadecimal Reason Code	Meaning and Action
00	—	Meaning: Successful completion Action: None required
02	—	Meaning: Successful completion, with exception. For a LIST request, IARV64 requests have been issued since the previous call to LIST. Action: Re-issue the call if you need the information pertainining to those recent IARV64 requesets.
04	—	Meaning: Successful completion, with exception. For a LIST request, that there are additional MOMBs which were not returned on this calls to LIST. Action: Issue the LIST call again to get the additional information.
06	—	Meaning: Successful completion, with exception. For a LIST request, there are additional MOMBs which were not returned on this calls to LIST and IARV64 requests have been issued since the previous call to LIST. Action: Issue the LIST call again to get the additional information.
08	—	Meaning: The request is rejected because of non-system failure. This reason code can be issued for a conditional IARV64 request. In this case, this reason code is the same as the DC2 reason code issued from an unconditional IARV64 request. See DC2 in z/OS MVS System Codes for an explanation and programmer response. If the reason code is not in DC2, it has one of the following meanings: For a DETACH request, there were no memory objects deleted because none matched the user token provided. For a LIST request, there were no memory objects returned because no memory objects match the selection criteria. Action: For a DETACH request, make sure that the user token was correct. For a LIST request, no action is required. For other requests, see DC2 in z/OS MVS System Codes for an explanation and programmer response.

Example

Operation:

Get 2 MB above the bar
Free the storage

The code is as follows.

         SYSSTATE AMODE64=YES
*************************************************************
* Get storage above 2G                                      *
*************************************************************
         IARV64 REQUEST=GETSTOR,SEGMENTS=NUMSEG,             *
               ORIGIN=O,                                     *
               RETCODE=LRETCODE,RSNCODE=LRSNCODE,            *
               MF=(E,V64L)
*
* Place code to check return/reason codes here
*
*************************************************************
* Free the storage                                          *
*************************************************************
         IARV64 REQUEST=DETACH,MEMOBJSTART=O,                *
               RETCODE=LRETCODE,RSNCODE=LRSNCODE,            *
               MF=(E,V64L)
*
* Place code to check return/reason codes here
*
NUMSEG   DC    AD(2)
ONEMEG   DC    AD(256)
DYNAREA  DSECT
LRETCODE DS    F
LRSNCODE DS    F
O        DS    AD
         IARV64 MF=(L,V64L)