GETVIS (Get Virtual Storage) Macro

The macro retrieves a block of virtual storage either from the GETVIS area of your partition or of the SVA or from the dynamic space GETVIS area.

Initially, the GETVIS area is cleared to binary zeros, and after each FREEVIS request that the returned storage is cleared again. However, a program might erroneously store data into freed storage that is still addressable; this might result in a later GETVIS request for uncleared storage.

If you code the macro without any operand, the system assumes that the length of the wanted virtual storage area is contained in register 0 and returns the start address of the area it retrieved for you in register 1. If the macro is issued without an operand, the macro must not contain a comment unless the comment begins with a comma.

Format 1: Obtaining Storage from the Partition GETVIS Area

Read syntax diagramSkip visual syntax diagramnameGETVISADDRESS=(1)ADDRESS= name1,LENGTH=(0),LENGTH= name2,PAGE=NO,PAGE=YES,LOC=RES,LOC=BELOWANY,SVA=NO ,SPACE=NO ,PFIX=NO ,POOL=NO ,SPCNTRL=NO ,TSKSUBP=NO ,POOL=YES1,SPID=(1)name3,SPCNTRL=YES,TSKSUBP=YES
Notes:
  • 1 POOL=YES is invalid if LOC=ANY is specified.

Format 2: Obtaining Storage from the Space GETVIS Area

Read syntax diagramSkip visual syntax diagramnameGETVISADDRESS=(1)ADDRESS= name1,LENGTH=(0),LENGTH= name2,PAGE=NO,PAGE=YES,LOC=RES,LOC=BELOWANY,SVA=NO ,SPACE=NO ,PFIX=NO ,POOL=NO ,SPCNTRL=NO ,TSKSUBP=NO ,SPACE=YESFTCHPRPARTKEY,SPID=(1)name3,SPCNTRL=YES

Format 3: Obtaining Storage from the System GETVIS Area

Read syntax diagramSkip visual syntax diagramnameGETVISADDRESS=(1)ADDRESS= name1,LENGTH=(0),LENGTH= name2,PAGE=NO,PAGE=YES,LOC=RES,LOC=BELOWANY,SVA=NO ,SPACE=NO ,PFIX=NO ,POOL=NO ,SPCNTRL=NO ,TSKSUBP=NO ,SVA=YES,POOL=YES1,SPID=(1)name3,PFIX=YES,SPCNTRL=YES
Notes:
  • 1 POOL=YES is invalid if LOC=ANY is specified.

Requirements for the caller

AMODE:
24 or 31
RMODE:
24 or ANY
ASC Mode:
Primary

Parameters

ADDRESS=name1 | (1)
The start address of the requested virtual storage area is returned by the system either in the 4-byte field that is specified as a symbol by name1 or in the specified register. Register 15 must not be used because it contains the return code. The returned address is valid only if the return code in register 15 is zero. If the operand is omitted, the address is returned in register 1 only.
LENGTH=name2 | (0)
The length of the requested storage block can be specified either in the 4-byte field (specified as a symbol by name2) or in the specified register. The length is specified in number of bytes. The smallest unit that can be requested by GETVIS is either of the following:
  • 128 bytes if the GETVIS area is part of a partition or
  • 16 bytes if the GETVIS area is part of the SVA or of the dynamic space GETVIS area.

If the specified length is not a multiple of 128 or 16, respectively, it is rounded to the next higher multiple of 128 or 16. If the operand is omitted, the system assumes that you have specified the length in register 0.

LOC=RES | BELOW | ANY
Indicates the location of the virtual storage that is obtained by the GETVIS request.
RES indicates that the location of the requested virtual storage depends on the location of the caller. If the caller resides below 16M, virtual storage is to be allocated below 16 MB (LOC=RES is treated as LOC=BELOW). If the caller resides above 16 MB, virtual storage can be allocated anywhere (LOC=RES is then treated as LOC=ANY).
Note: The location of the caller is determined by the address portion of the PSW. Since a phase can cross the 16 MB line, LOC=RES requests might return GETVIS areas above and below 16 MB within the same phase.
BELOW indicates that virtual storage is to be allocated below 16 MB. The allocation of storage is done from bottom to top. For partition GETVIS requests, storage is allocated up to the 16 MB line. For system GETVIS requests (SVA=YES), the area is reserved in the 24-bit system GETVIS area only, even if the 31-bit system GETVIS area is located partly or totally below 16 MB.

ANY indicates that virtual storage can be allocated anywhere. For partition GETVIS requests, the system tries to allocate virtual storage above 16 MB. If the attempt fails (or if no area above 16 MB is available), the system tries to allocate virtual storage below 16 MB. If this attempt also fails, no storage is allocated. Storage is always allocated from top to bottom and can cross the 16 MB line. LOC=ANY is treated as LOC=BELOW if the total GETVIS area is located below 16 MB.

For system GETVIS requests (SVA=YES), the system tries to allocate virtual storage in the 31-bit system GETVIS area, even if this area is located partially or totally below 16 MB. If the attempt fails, the system tries to allocate storage in the 24-bit system GETVIS area. If there is no 31-bit system GETVIS area, LOC=ANY is treated as LOC=BELOW.

For dynamic space GETVIS requests (SPACE=YES), a LOC=ANY request is treated as LOC=BELOW, since there is only a 24-bit dynamic space GETVIS area. The same is true if LOC=RES is specified and the caller resides above 16 MB.

Subpool Processing: Both LOC=ANY and LOC=BELOW can be given for the same subpool, so a subpool can contain areas below and above 16 MB. Normally, the system tries to find the requested area within an existing subpool. However, for LOC=ANY requests, the system tries to allocate the requested storage totally above 16 MB (partition) or in the 31-bit system GETVIS area. Only if there is not enough storage available above 16 MB (partition) or in the 31-bit system GETVIS area, the area below 16 MB (partition) or the 24-bit system GETVIS area is searched for. (If the SPID operand is omitted, virtual storage is retrieved from a general GETVIS subpool.)

PAGE=NO | YES
PAGE=YES causes the requested storage area to start on a 2 K boundary if the requested size is not larger than 2 K, or on a 4 K boundary if the requested size is larger than 2 K. This might reduce the number of page faults, but increases storage fragmentation.
PFIX=NO | YES
If PFIX=YES is specified, the requested storage area is PFIXed. PFIX=YES is allowed only if the SPID operand is specified and SVA=YES.

If PFIX=YES is specified, z/VSE backs virtual pages that reside below 16 MB with real storage below 16 MB, and virtual pages that reside above 16 MB with real storage that can be located anywhere (preferably above 16 MB).

PFIX=YES is not allowed with SPACE=YES.

POOL=NO | YES
If POOL=YES is specified, GETVIS expects to find, in register 1, an address within the defined GETVIS area where the search is to be started.

POOL=YES must not be specified together with SPACE, SPID, or with TSKSUBP=YES.

The POOL operand is invalid when specified with LOC=ANY. It is ignored for LOC=RES requests if the caller resides above 16 MB. If POOL is specified, the address in register 1 (where the search for the required area is started) is regarded either as a 24-bit or 31-bit address, depending on the AMODE of the caller. The address is ignored if it does not point to the LOC=BELOW area.

SPACE=NO | YES | FTCHPR | PARTKEY
SPACE=YES indicates that the requested storage area is to be taken from the dynamic space GETVIS area. The requester needs storage protection key zero.

If the GETVIS request is for a static partition, the storage area is taken from the system GETVIS area. If the request is for a static partition and the SPID operand is omitted, the storage is retrieved from a partition-related general GETVIS subpool.

SPACE=NO indicates that the storage area is not to be taken from the dynamic space GETVIS area.

SPACE=FTCHPR has the same function as SPACE=YES, but the area is fetch-protected, that is, require key zero for read and write operations. The operand is only allowed if the SPID operand is specified.

SPACE=PARTKEY has the same function as SPACE=YES, but the area is protected with the key of the partition. The operand is only allowed if the SPID operand is specified.

The SPACE operand must not be specified together with PFIX=YES, POOL=YES, SVA=YES, and TSKSUBP=YES.

SPCNTRL=NO | YES
SPCNTRL=YES indicates that access to the subpool specified in the SPID operand is only allowed when the correct subpool index (which is part of the subpool ID) is specified.

When you initialize a subpool (by setting the subpool index to zero), the system creates a controlled subpool, that is, any further request for the subpool is only allowed if the correct subpool index is passed (independent of the SPCNTRL specification).

When you refer to an existing subpool, the index must point to a subpool with the same name as the supplied one. Otherwise, a return code is passed indicating an invalid subpool index.

SPCNTRL=YES is only allowed if the SPID operand is specified.

SPID=name3 | (1)
This operand can be used to create a subpool of pages of virtual storage from the partition or dynamic space GETVIS area or from the SVA.

Each subpool is defined by an 8-byte area (the subpool ID) or a register that points to the area. This 8-byte area consists of a 6-byte field containing the subpool name (which you must supply) and a 2-byte subpool index that is set by the system and should be initialized to zero when you first create the subpool. The entire 8-byte area must be used for subsequent references to the subpool. The subpool ID field is passed to the supervisor in register 1.

The address of the subpool ID is regarded either as a 24-bit or 31-bit address, depending on the AMODE (24 or 31) of the caller.

The same subpool name can be used for a SPACE=YES request within different partitions. If the request is routed to the SVA, the system does not return a unique subpool name (the subpool name is made unique internally).

The subpool name must not begin with the character I to avoid conflicts with internal IBM® subpools.

When you omit the SPID (or TSKSUBP) operand, virtual storage is retrieved from a general GETVIS subpool.

SPID must not be specified together with POOL or TSKSUBP=YES.

SVA=NO | YES
SVA=YES can be specified only in a program that runs with storage protection key zero. If SVA=YES is specified, the system retrieves the wanted block of virtual storage from the system GETVIS area. If SVA=NO is specified or the operand is omitted, the system retrieves the block from the partition in which your program runs.

SVA=YES must not be specified together with SPACE or TSKSUBP=YES.

TSKSUBP=NO | YES
This operand, if specified for a subtask, indicates whether the requested storage area is to be taken from an exclusive task subpool, which is freed when the task is terminated. If specified for a main task, this operand is ignored.

If TSKSUBP (or SPID) is not specified, GETVIS space is retrieved from the general GETVIS subpool.

TSKSUBP=YES must not be specified together with SPACE, SPID, POOL=YES, or SVA=YES.

Return Codes in Register 15

0
GETVIS completed successfully.
4
The size of the (real) partition GETVIS area is 0K.
8
The specified length is negative or exceeds the GETVIS area.
12
No more virtual storage is available in the GETVIS area, or a GETVIS request with length zero has been specified for either a non-existing subpool or a subpool that has no free space.
16
The maximum number of subpools is exhausted.
20
Invalid GETVIS option.
24
Invalid subpool ID.
32
PFIX for an SVA subpool request failed.
36
An invalid subpool index was specified and (a) the request was done with SPCNTRL=YES and/or (b) the specified subpool name denotes an existing subpool that was created with SPCNTRL=YES. (A subpool index is invalid if it points to a subpool other than the supplied one. This includes a subpool index of zero for an already existing subpool.)
40
No access to the specified subpool is allowed, if a PFIX request is pending.