2. PERFORMANCE REPORTING ANALYSIS › 2.5 Virtual Storage Management Analysis › 2.5.4 Virtual Storage Concepts in MVS/XA › 2.5.4.3 VSM Management and Measurement Macros

2.5.4.3 VSM Management and Measurement Macros

There are ten macro instructions which can be used either to
request that VSM perform some management function or some
measurement function upon virtual storage.  These are the
GETMAIN, FREEMAIN, CPOOL, VSMLIST, VSMLOC, and VSMREGN
macros, plus four others whose functions have been replaced
in MVS/XA by the more efficient CPOOL macro.  Although these
latter four macros are still supported for compatibility, we
will not discuss them here.

VSMLOC can be used to verify that a control block or storage
location has been allocated.  This verification function is
useful in operations such as recovery procedures, but is of
limited value in the management of virtual storage, and thus
will not be discussed further here.  The major features of
the other macros are summarized below.

GETMAIN AND FREEMAIN

The GETMAIN and FREEMAIN macros form a logical pair.
GETMAIN's function is to allocate one or more areas of
virtual storage to an active address space.  When requesting
GETMAIN services, the length of the portion of virtual
storage desired, together with its required subpool number,
need to be specified.  Subpools will be described in more
detail later.  Their use is a technique used by VSM to
classify the memory it is managing.  For most subpools, the
storage obtained via GETMAIN is released either when the
associated task issues a FREEMAIN or at task termination.
The VSMLOC macro is a related macro that can be used to
verify that a particular portion of virtual storage has been
previously allocated via a GETMAIN.

CPOOL

The CPOOL macro performs a set of functions that are
superficially similar to those performed by GETMAIN and
FREEMAIN.  The CPOOL macro performs the following "cell pool
services":  BUILD, GET, FREE, and DELETE.  The purpose of
these services is to manage pools of equal sized cells of
virtual storage.  These are commonly used to construct chains
of control blocks or other collections of equal-sized packets
of storage.

The BUILD function creates a cell pool.  The following
information is used by the CPOOL macro when specifying the
BUILD function:  size of each cell, primary and secondary
cell count, subpool number, storage protect key, the address
of the TCB with which this pool is to be associated, and some
header text for diagnostic purposes.  The primary and
secondary cell counts are treated much like primary and
secondary space values during disk file allocation.  The
BUILD process will create as many cells as are specified in
the primary cell count.  If subsequent requests for cells
depletes a cell pool, then the secondary cell count will be
used to extend the cell pool into secondary extents.

The GET function of the CPOOL macro obtains a cell from the
previously built pool.  If the pool is depleted, the macro
call can specify either that the request fail or that the
pool be extended by acquiring enough virtual storage to build
the number of additional cells specified in the secondary
cell count during the initial building function for the cell
pool.

The FREE function of the CPOOL macro returns a cell to the
pool, whereas the DELETE function deletes the entire cell
pool and frees the storage of all the extents of the pool and
its associated control blocks.

VSMREGN AND VSMLIST

Two other analytical macros are a part of the VSM-related
services available to programs.  The first of these, VSMREGN,
is used to obtain the address and length of the private area
region for a given TCB, both below and above the 16MB line.

The second of these macros, VSMLIST, is used extensively by
RMF in its tracking of virtual storage usage.  For various
portions of virtual storage, this macro can provide several
different detailed lists of virtual storage areas:

o  Allocated pages - The addresses and lengths of groups of
   contiguous pages which have had some or all of their
   memory allocated via GETMAINs.  These measurements will be
   in multiples of 4KB.

o  Unallocated pages - The addresses and lengths of groups of
   contiguous pages in which no GETMAINs have allocated
   space.  These measurements will also be in multiples of
   4KB.

o  Free space - The addresses and lengths of fragments of
   memory which, although within allocated pages, have not
   been reserved for use via GETMAINs.  These measurements
   will not necessarily be in multiples of 4KB.

The ways that RMF makes use of this VSMLIST macro will be
explained in more detail later during the discussion of RMF
measurement of virtual storage usage.