VSMLIST — List virtual storage map

Description

The VSMLIST macro provides information about the allocation of virtual storage. The information is returned in a work area that you specify. The format of the work area is described under “Virtual Storage Management” in z/OS MVS Programming: Authorized Assembler Services Guide.

The following information can be requested:

The ranges of virtual storage allocated to the SQA, by subpool, and the free space within those ranges
The ranges of virtual storage allocated to the CSA, by subpool, and the free space within those ranges
The ranges of CSA space that are unallocated
The ranges of virtual storage allocated to the LSQA in the current address space, by subpool, and the free space within those ranges
The ranges of virtual storage allocated to private area subpools, by TCB, and the free space within those ranges
The ranges of private area that are unallocated.

For detailed information about virtual storage subpools, see “Virtual Storage Management” in z/OS MVS Programming: Authorized Assembler Services Guide.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	For LINKAGE=SYSTEM, problem state and PSW key 8-15. For LINKAGE=BRANCH, supervisor state and PSW key 0.
Dispatchable unit mode:	Task or SRB.
Cross memory mode:	Any PASN, any HASN, any SASN.
AMODE:	24- or 31-bit. All addresses must be 31-bit addresses.
ASC mode:	Primary.
Interrupt status:	Enabled or disabled for I/O and external interrupts.
Locks:	For LINKAGE=SYSTEM, the caller may not hold a lock higher than the local lock. For LINKAGE=BRANCH, see the LINKAGE parameter description for locking requirements.
Control parameters:	Must be in the primary address space. All input parameters, except for the TCB, can reside above 16 megabytes if the caller is running in 31-bit addressing mode. The TCB resides below 16 megabytes.

Programming requirements

All addresses are associated with the current address space.

You must set bytes 0-3 of the work area to zero before the first invocation of the macro for a given request.

Restrictions

None.

Input register information

The VSMLIST macro is sensitive to the SYSSTATE macro with the OSREL parameter

If the caller has issued the SYSSTATE macro with the OSREL=ZOSV1R6 parameter (Version 1 Release 6 of z/OS® or later) before issuing the VSMLIST macro, the caller does not have to place any information into any general purpose register (GPR) unless using it in register notation for a particular parameter, or using it as a base register.
Otherwise, the caller must ensure that the following general purpose register contains the specified information:
Register

Contents

13

The address of an 18-word save area

Output register information

When control returns to the caller, the GPRs contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14: Used as a work register by the system
15: Return code

When control returns to the caller, the ARs contain:

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

None.

Syntax

The VSMLIST macro is written as follows:

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede VSMLIST.

VSMLIST

␢	One or more blanks must follow VSMLIST.

SP=SQA
SP=CSA
SP=LSQA
SP=PVT
SP=`sp list addr`	`sp list addr`: RX-type address or register (0), (2) - (12)

,WKAREA=(`addr,length`)	`addr`: RX-type address or register (1) - (12)
	`length`: Symbol, decimal digit, or register (0), (2) - (12).

,TCB=(`tcb addr`)	Default: TCB address in PSATOLD.
,TCB=`(tcb addr,`ALL)	`tcb addr`: RX-type address or register (0), (2) - (12).
,TCB=(, ALL)	Note: The TCB parameter is required only for SRB routines, if SP=PVT or SP=`sp list addr` and the list contains private area subpools.

,SPACE=ALLOC	Default: SPACE=ALLOC
,SPACE=FREE	Note: SPACE=UNALLOC can be specified only for SP=CSA or SP=PVT.
,SPACE=UNALLOC

,LOC=24	Default: LOC=31
,LOC=31

,REAL31	Default: REAL31
,REAL64
,REALPGFMSZ

,LINKAGE=SYSTEM	Default: LINKAGE=SYSTEM
,LINKAGE=BRANCH

,PVTSP=ALL	Default: PVTSP=ALL
,PVTSP=OWNED

Parameters

The parameters are explained as follows:

SP=SQA

SP=CSA

SP=LSQA

SP=PVT

SP=sp list addr

Specifies the storage areas for which information is requested. The following subpools are listed for the specified storage areas:

SQA: 226, 239, 245, 247, 248
CSA: 227, 228, 231, 241
LSQA: 205, 215, 225, 255
PVT: 0-127, 129–132, 229, 230, 236, 237, 244, 249, 251, 252

GETMAIN/FREEMAIN/STORAGE processing translates the original subpool numbers that were specified on the GETMAIN, FREEMAIN, or STORAGE macros to different subpool numbers as shown below:

Original Subpool Number	Translated Subpool Number
203-205	205
213-215	215
223-225	225
233-235, 253-255	255
0, 240, 250	0

VSMLIST reports the translated subpool numbers, not the original subpool numbers. In addition, VSMLIST does not report incorrect subpool numbers (subpool numbers greater than 255) or undefined subpool numbers.

If SP=sp list addr is specified, the user must supply the address of a subpool list. The first halfword of the list contains the number of entries in the list. Each of the following halfwords in the list contains a subpool number. If a valid subpool number appears more than once in the subpool list, it is reported only once.

,WKAREA=(addr,length)

Indicates the address and length of a user-supplied work area. The system uses this work area to hold the parameter list, control information, and data that is to be returned to the caller. The work area should begin on a word boundary and be a minimum of 4K bytes in length.

You must set bytes 0-3 of this work area to zero before the first invocation of VSMLIST for a specific request. See “Virtual Storage Management” in z/OS MVS Programming: Authorized Assembler Services Guide for a description of the work area.

,TCB=(tcb addr)

,TCB=(tcb addr,ALL)

,TCB=(,ALL)

Specifies the TCB associated with the virtual storage allocated to the private area subpools. The TCB must be located in the currently addressable address space. If ALL is specified, the storage associated with the TCB and all of its subtasks is reported.

Note:

If ALL is specified and the TCB is high in the task structure (for example, the TCB for RCT), more than one region could be listed. The regions in the private area are the RCT region, the V=V region, and the V=R region (for V=R jobs).
The TCB resides in storage below 16 megabytes.

,SPACE=ALLOC

,SPACE=FREE

,SPACE=UNALLOC

Specifies whether allocated, allocated and free, or unallocated storage is to be reported.

ALLOC indicates that the virtual addresses and lengths of blocks of storage allocated to the specific area are to be listed.

FREE indicates that in addition to the information supplied by ALLOC, the virtual addresses and lengths of free space within the allocated blocks are to be listed.

UNALLOC indicates that the virtual addresses and lengths of unallocated blocks of storage are to be listed. Both TCB and REAL are ignored when UNALLOC is specified.

Note: An allocated block of storage is a block that is a multiple of 4K in size and contains some storage that has been allocated via a GETMAIN or STORAGE macro. The free storage is the storage within an allocated block that has not been allocated via a GETMAIN or STORAGE macro. An unallocated block of storage is a block that is a multiple of 4K in size and contains no allocated storage.

,LOC=24

,LOC=31

Indicates whether information should be returned about virtual storage areas residing above and below 16 megabytes or only those residing below 16 megabytes. If LOC=31 is specified, information is returned for all storage areas below 2 gigabytes. If LOC=24 is specified, information is returned only for storage areas below 16 megabytes.

Note: Specifying LOC=BELOW is the same as specifying LOC=24. Specifying LOC=ANY is the same as specifying LOC=31. The old values are still supported, but IBM® recommends using the newer values instead.

,REAL31

,REAL64

,REALPGFMSZ

Indicates that the high order bit and the 2 lower order bits of the address field of the allocated block descriptor should be set to show the value specified on the LOC parameter of the GETMAIN, STORAGE, or CPOOL macro invocation used to obtain that storage area. If the storage block was allocated using any LOC specification of GETMAIN or STORAGE, except for LOC=(*,24), one or more of these indicators are turned on. If the storage block was allocated using the LOC=(*,24) specification of GETMAIN or STORAGE, the indicators are turned off.

Note: The asterisk character (*) indicates that any of the allowable values for the first suboperand of the LOC keyword.

REAL31

If the storage block is backed in real 31-bit or 64-bit storage, the high bit indicator is on (one). If the storage block is backed in real 24-bit storage, the high bit indicator is off (zero). The low bit and second lowest bit indicators are always off.

REAL64

If the storage block is backed in real 64-bit storage, the low bit indicator is on (one) and the high bit indicator is off (zero). If the storage block is backed in real 31-bit storage, the high bit indicator is on (one) and the low bit indicator is off (zero). If the storage block is backed in real 24-bit storage, the high bit indicators are off (zero). The 2nd lowest bit indicator is always off (zero).

REALPGFMSZ

Specifies the following indicators:

If the storage block was obtained with the PAGEFRAMESIZE1MB parameter, the second lowest bit indicator is on (one), the low bit indicator is on (one) and the high bit indicator is off (zero).
If the storage block is backed in real 64-bit storage but was not obtained with the PAGEFRAMESIZE1MB parameter, the low bit indicator is on (one), the 2nd lowest bit indicator is off (zero) and the high bit indicator is off (zero).
If the storage block is backed in real 31-bit storage, the high bit indicator is on (one), the low bit indicator is off (zero) and the 2nd lowest bit indicator is off (zero).
If the storage block is backed in real 24-bit storage, the high bit indicator, the low bit indicator and the second lowest bit indicators are off (zero).

Note:

If REAL31, REAL64 and REALPGFMSZ are not specified, then none of these indicators are turned on.
The REAL31 parameter provides the same function as the deprecated REAL parameter, which is still supported by VSMLIST.

,LINKAGE=SYSTEM

,LINKAGE=BRANCH

Indicates whether the VSMLIST routine uses a PC instruction (LINKAGE=SYSTEM) or branch entry (LINKAGE=BRANCH) for linkage and whether the VSMLIST routine provides serialization and recovery.

If LINKAGE=SYSTEM is specified, the VSMLIST routine provides linkage using a PC instruction and also provides recovery and serialization.

The caller's secondary ASID is preserved when a PC is issued.

Note: Serialization is not provided across calls to VSMLIST.

If LINKAGE=BRANCH is specified, the VSMLIST routine uses branch entry for linkage and does not provide recovery or serialization. Before issuing VSMLIST, provide serialization as follows:

For LSQA or PVT requests, obtain the LOCAL lock.
For SQA or CSA requests, issue the SETLOCK macro right before and right after the VSMLIST request, as follows:
```
       SETLOCK OBTAIN,TYPE=VSMFIX,MODE=UNCOND
       VSMLIST request
       SETLOCK RELEASE,TYPE=VSMFIX
```
If your program is covered by a functional recovery routine (FRR) and the FRR receives control after SETLOCK OBTAIN has been issued and before SETLOCK RELEASE has been issued, your FRR must either issue SETLOCK RELEASE,TYPE=VSMFIX or must issue the SETLOCK and SETRP macros as follows:
```
       SETLOCK TEST,TYPE=VSMFIX,BRANCH=(NOTHELD,NOVSMFIX)
       SETRP FRELOCK=VSMFIX
NOVSMFIX DS 0H
```
Note:
1. Your program will be disabled for I/O and external interrupts from the time the SETLOCK OBTAIN completes until the SETLOCK RELEASE completes. See the descriptions of the SETLOCK and SETRP macros for additional usage information.
2. Your program and your FRR must not issue any of the following macros before issuing SETLOCK RELEASE,TYPE=VSMFIX:
  - GETMAIN
  - FREEMAIN
  - STORAGE

,PVTSP=ALL

,PVTSP=OWNED

Indicates for each task, which subpool information will be returned.

ALL indicates that information is returned for subpools which are owned or shared by the task.

OWNED indicates that information is returned only for the subpools which are owned by the task.

ABEND codes

The VSMLIST macro might issue abend code X'C78'. For detailed abend code information, see z/OS MVS System Codes.

Return and reason codes

When the VSMLIST macro returns control to your program, GPR 15 contains one of the following hexadecimal return codes:

Table 1. Return Codes for the VSMLIST Macro
Return Code	Meaning and Action
0	Meaning: Successful completion. Action: None.
4	Meaning: Partially successful completion. More information remains to be returned in the work area. Action: Reissue the macro to obtain additional information until a return code of 0 is returned in register 15. Do not change the value of bytes 0-3 of the work area before reissuing the macro.
8	Meaning: System error. The system encountered an error while scanning virtual storage management data areas. The information in the data area is valid, but incomplete. This return code is obtained only by users who specify LINKAGE=SYSTEM. Action: Notify system support personnel that there might be an error in virtual storage management's control structure. If there is a problem with VSM's control structure, the entire system will be adversely affected and you might need to wait until the problem is identified and resolved by support personnel. Support personnel should take a dump of the virtual storage management control structure to help identify the cause of the problem. If the problem appears to involve common storage, the contents of common storage should be dumped to view the VSM control structure. If the problem appears to involve private storage, private storage should be dumped.
C	Meaning: Program error. The system detected one of the following errors: The work area was too small. An incorrect parameter was specified. Incorrect control information was in the work area. This return code is obtained only by users who specify LINKAGE=BRANCH. Users who specify LINKAGE=SYSTEM receive a X'C78' abend for these errors. Action: Ensure that the work area is at least 4096 bytes long. Verify that the work area is correctly defined and initialized and that parameters are specified properly. Verify that your program has not inadvertently modified the VSMLIST work area.

Example 1

List the ranges of the allocated and free storage in the SQA. Specify the address of the VSM work area in register 2 and the length of the work area in register 3.

VSMLIST SP=SQA,SPACE=FREE,WKAREA=((2),(3))

Example 2

List the ranges of the allocated storage in the CSA. Specify the address of the work area in register 2 and the length of the work area in register 3. Provide branch entry linkage.

VSMLIST SP=CSA,SPACE=ALLOC,WKAREA=((2),(3)),LINKAGE=BRANCH

Example 3

List the ranges of unallocated storage in the private area. The variable X contains the address of the work area, which has a length of 4096 bytes.

VSMLIST SP=PVT,SPACE=UNALLOC,WKAREA=(X,4096)

Example 4

List the ranges of allocated storage, below 16 megabytes, in each of the subpools specified in the subpool list at location Y. The variable X contains the address of the work area, which has a length of 4096 bytes.

VSMLIST SP=Y,SPACE=ALLOC,WKAREA=(X,4096),LOC=BELOW