Description of VIR2REAL

Download count: 34 this month, 3851 altogether.

Downloads for VIR2REAL:
VMARC archive: v-19K

The VIR2REAL EXEC calculates and displays (or writes to a file) the ratio of the virtual storage (memory) to the real storage of your system.  The virtual storage is the sum of all the of virtual storage sizes for all logged on users of your running VM system.  A system with a virtual to real storage ratio that is too large may experience excessive paging rates or other performance problems because the real memory is overcomitted.  A system with a small ratio (less than or near 1 to 1) that has sufficient CPU capacity available should be able to handle more workload.  This exec just shows the current ratio for the userids that are active on the system at the time the exec is run.  For tracking the ratio over time, you should obtain and use a performance monitor product.

The exec operates by finding all users logged on to a system using QUERY NAMES AT *.  (This exec can only show the ratio for the system you are logged on to, not other systems of a cluster.)  It obtains each user's storage size and how it was started (IPL) using the INDICATE USER command and adds up the storage numbers.  It obtains the real storage size using the QUERY FRAMES and QUERY XSTORAGE commands.  The output is the virtual storage totals, the real storage totals and the ratio of the virtual totals to the real total storage.

Virtual machines running CMS may have large virtual storage sizes, but may be only using a small part of that storage for work.  This is in contrast to Linux virtual machines which attempt to use all of their virtual storage.  Therefore, separate totals for all userids that are running CMS vs. other workloads is shown.  CMS usage is determined by a virtual machine IPLing a defined list of NSS names or virtual device numbers.  These names and devices can be customized in the exec.

VDISKs (virtual disks in storage) also use real memory pages and paging space to hold the information written to these devices.  The exec also queries the number of VDISKs defined using the QUERY VDISK command and the total amount of VDISK space that is defined on your system.  If VDISKs are defined, then the ratio of all of the VDISK space plus the total virtual storage is shown.

Paging space must be available to your system if storage is overcomitted and z/VM must free up memory by writing out pages.  The exec queries and displays the amount of paging space and its utilization using the QUERY ALLOC command.  In z/VM releases prior to z/VM 6.3 it was recommended that you do not allow your paging devices to be more than 50% full.  With z/VM 6.3 and later, there is no performance penalty for allowing paging devices to be more than 50% full.  However, z/VM 6.3 and later releases may use more paging space than previous releases, so it is still very important to ensure that your system has enough paging space.  If VIR2REAL is run on a z/VM 6.3 or later system, or the option PLAN63 is specified (in other words, you invoke the exec with the command VIR2REAL (PLAN63 on your older system), the exec calculates the minimum recommended paging space required for the current state of your system.  This calculation is based on the planning information from the CP Planning Guide.  The exec only calculates the minimum required for your system at the moment in time when the exec is run.  You should consult the CP Planning Guide document to plan for the amount of paging space needed for future growth of your system.

If you run VIR2REAL on a 6.3 or later system or specify the PLAN63 option, and the exec calculates that there is insufficient paging space on your system, it will display these lines:
Your paging space may not be able to hold all of your currently active users.
Paging space, for all users, should be at least:    nnnn MB (nn.n GB)
Paging space, excluding CMS users, should be:       nnnn MB (nn.n GB)

To repeat, the values displayed are the minimum recommended amount for the current workload on your system at the time VIR2REAL was run.  You must consult the z/VM CP Planning Guide to calculate the correct amount of paging space required for your system's current and future workload.  The QUERY AGELIST values of Early Writes and Keep Slot (on 6.4 and later) are shown in the output because these settings may affect how much paging space is actually used by your system.

By default, the output is written to the console, but it can also be appended to a file by specifying the FILE argument.

If you want to track the values calculated by VIR2REAL EXEC over time, the values can be written to a text or CSV formatted file.  If you invoke the exec as VIR2REAL CSV, a single line of comma separated values will be written to a file.  The default file name is VRyymmdd CSV A and you can override the name by specifying the new name as a argument.  The APPEND argument will write a single line to a text file with the default name of VRyymmdd A.  If you invoke VIR2REAL with some automation at a regular interval, you can track the changes to your system over time.  This is no substitute for a z/VM performance monitor product, but it does provide you with a simple method of gathering this data.  If VIR2REAL is invoked with one of the arguments FILE, CSV, or APPEND, the normal output is not displayed unless the (TYPE option is also specified.

Note:  The exec must be run on a userid with sufficient CP privileges.  The minimum default IBM privileges are B and E. It uses the CP command QUERY FRAMES, to obtain real storage values and INDICATE USER userid to obtain the virtual storage values.  It uses QUERY XSTORAGE on z/VM 6.3 and earlier releases to obtain expanded storage usage information.  If the QUERY VDISK command is available, it will also show information about vdisks.  If the command QUERY ALLOC is available, it will show the amount of page space and its utilization.  If the command QUERY DUMP is available, it will check the system dump space and show the output of the command if no dump space is available.

An example of the output from VIR2REAL, with footnotes:

Storage information for VM system PTCVMD01
CMS users IPL NSSes "CMS GCS" or devices "0190 0490". 1

Total Virtual storage (only ids not running CMS):  205312 MB (200.5 GB) 2
Total Virtual storage (only ids running CMS):        1104 MB (  1.1 GB) 3
Total Virtual storage (all logged on userids):     206416 MB (201.6 GB)
Total of all Instantiated pages:                   207123 MB (200.9 GB) 4
Usable real storage (pageable) for this system:     81127 MB ( 79.2 GB) 5
Total LPAR Real storage:                            81920 MB ( 80.0 GB)
Expanded storage usable for paging:                  2048 MB (  2.0 GB) 6

Total Virtual disk (VDISK) space defined:           43256 MB ( 42.2 GB)
Average Virtual disk size:                            158 MB

Virtual to (usable) Real storage ratio:     2.5 : 1 7
Virtual + VDISK to Real storage ratio:      3.1 : 1 8
Virtual to Real ratio (non CMS work only):  2.5 : 1 9
Total Instantiated to Real storage ratio:   2.5 : 1 10

Paging:  78 volumes active, usable space is:        183072 MB (178.8 GB)
Total Paging space in use, 25% utilization:         446188 MB ( 45.1 GB)

Notes about the output:

  1. This line lists the device numbers and NSS names active on the system that are considered to be CMS users.  The search values are defined in the exec and can be changed if desired.
  2. The total virtual storage of all users except those running systems with NSS names or virtual device numbers shown in the previous output line.
  3. The total virtual storage of all the NSS and CMS virtual device users.
  4. Starting with z/VM 6.3, VM keeps track of the number of pages that exist both in storage and on disk.  Pages that exist are called instantiated pages.  This value shows the total number of instantiated pages that exist on your system.  If VIR2REAL is run on an older system, this line is not shown.
  5. The amount of storage that is available for running virtual machines.  It is less than the total storage available on the LPAR because the CP nucleus and other control blocks reserve some of the storage.
  6. This may be less than the amount of expanded storage defined to the LPAR if some of it is dedicated to users.  Expanded storage is not recommended for z/VM 6.3 systems and not supported at all on z/VM 6.4 and later systems.  If your z/VM 6.3 system does not have any expanded storage, this line is not displayed.
  7. The ratio of all virtual storage to the real storage.
  8. The ratio of all virtual storage plus all defined VDISKS to the real storage.
  9. The ratio of the storage of all active users' that are not running CMS to the real storage.
  10. The ratio of instantiated pages of all users to real storage.

Also included in the package is QSHARE EXEC.  This exec will query the share (priority) and quick dispatch setting of all logged on users and put all of this information a file.  It also calculates the share per virtual cpu for multiprocessor virtual machines.

Feedback: Bruce Hayden IBM Advanced Technical Sales Support (ATS)