Download count: 16 this month, 5285 altogether.
Downloads for VIR2REAL:
  VMARC archive: v-28K
  zip archive: z-44K

VIR2REAL EXEC

The VIR2REAL EXEC calculates and displays (or writes to a file) the ratio or quotient of the total virtual storage (memory) to the LPAR real storage of your z/VM® system. In addition, other information about your system is shown such as the memory configuration of the LPAR, virtual disk usage, and paging space allocation and usage. This exec can only show the current ratio for the users that are active on the system at the time the exec is run. For advanced tracking of your system, you should obtain and use a performance monitor product.

Usage Notes

1. Why is the ratio of virtual to real storage (memory) important?

   A system with a virtual to real storage ratio that is too large may experience excessive paging rates or other performance issues because real memory is overcomitted. A system with a small ratio (less than or near one to one) that also has unused entitled CPU capacity available should be able to handle more workload. z/VM is known to be very good at managing real storage and performing paging, so running the system with over-committed memory is very common. You have to decide for your system what is an acceptable virtual to real storage ratio.

2. What does VIR2REAL measure?

   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 (memory) size using the INDICATE USER command and adds up the storage numbers. It obtains the real storage size using the QUERY FRAMES command. It outputs the virtual storage totals, the real storage totals and the ratio of the virtual totals to the real total storage.

3. What about VDISKs, CMS users, and other guests?

   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 allocated virtual storage for running applications or as buffers and file cache. Therefore, separate totals for all userids that are running CMS vs. other workloads is shown. CMS usage is determined by detecting the IPL device or NSS name of each virtual machine. Since CMS is usually started via an NSS (Named Saved System) or using a limited number of virtual device numbers, these devices and names are used to detect a virtual machine running CMS. These names and devices can be customized in variables in the exec if your installation uses different NSS names or CMS device numbers.

   VDISKs (virtual disks in storage) also use real memory pages and paging space to hold the information written to these devices. But, a VDISK uses very little storage if no data is written. The exec 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.

4. Other information that is displayed

   Paging space must be available to your system if storage is overcomitted and z/VM must free up memory frames by writing out pages. The exec queries the amount of paging space and its utilization using the QUERY ALLOC command and displays a summary.

   If your system does not have any dump space defined, the output will include NOTE: No dump unit - reason. The reason will show that either automatic dump is turned off or you don't have enough spool space. If you see this message, either turn on automatic dumping or add more spool space to your system.

5. z/VM 6.3 and later systems

   z/VM 6.3 improved several aspects of storage management compared to earlier releases. One improvement is that pages may be written out to the paging volumes "early" when paging demand is low, instead of only writing when required. This may cause the system to use more paging space for the same workload than earlier releases. The z/VM planning documentation contains a formula for computing the minimum paging space you should have defined on the system for your workload. When VIR2REAL is run on a z/VM 6.3 or later system (or if the PLAN63 option is specified) the exec attempts to compute the MINIMUM paging space you should plan to have for the currently running workload, based on the planning formula. If not enough space is available, this output is displayed:

   ATTENTION:
   Your paging space may not be able to hold all of your currently active users.
   Paging space, for all users, should be at least:   xxxxx MB (xx.x GB)
   Paging space, excluding CMS users, should be:      xxxxx MB (xx.x GB)
   

   If these messages are displayed, your system might not be in immediate danger of an abend for running out of page space, but the danger exists of this occurring. You should ensure that you have enough paging space for your workload with enough additional space to allow growth.

   The "Early Writes" and "Keep slot" (6.4 and later) values from the QUERY AGELIST command are shown in the output if either of these is set to NO. Setting either or both of these values to NO may allow your system to use less paging space, but the trade-off is that your system may have more paging overhead if paging occurs. Consult the CP planning documentation to see the recommendations for these values for your system.

   The QUERY PAGING command is issued (6.4 and later) to check the "Paging Alias" (HyperPAV alias) and "Paging HPF" (High Performance FICON, also known as Transport Mode) settings. The settings of these 2 values are shown in the output if either of these is not set to ON. If your storage system supports HyperPAV or HPF, it is recommended to change these settings to ON and change your SYSTEM CONFIG file so that these settings are enabled (ON) at IPL time.

6. z/VM Memory Reclamation support

   If APAR VM66173 is installed on z/VM 7.2 (or later), then additional z/VM memory information such as the amounts of Permanent and Reconfigurable memory are shown. Permanent memory cannot be removed. Only memory defined as Reconfigurable can be removed from the system. The VIR2REAL output shows the current values for the amount of Permanent and Reconfigurable memory defined. If the value of Reconfigurable memory is zero, then either all memory is defined as Permanent or z/VM Memory Reclaimation support is not available.

   If Reconfigurable memory is available, be aware that adding or removing memory changes the real memory size of the system and therefore affects the virtual to real memory ratio. VIR2REAL does not attempt to predict how the system will change when the memory size is changed. If the "Check Reclaim" (CHKRECLM) exec is available on the system, use it to predict how the system may change.

7. Writing output to a file or to Rexx variables

   By default, the output is written to the console, but it can also be appended to a file or written to Rexx variables.

   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. If the STEM or VAR keyword is specified and VIR2REAL is invoked from another exec, the same data in CSV format is written to a Rexx variable (VAR keyword) or written along with the header lines using the STEM keyword.

   The APPEND argument will write a single line to a text file with the default name of system id 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, APPEND, or to Rexx variables, the normal output is not displayed unless the "(TYPE" option is also specified.

   Each ratio calculated by the exec is output as a single number. This number is the quotient from the division of the stated value to the total amount of memory that is available for running virtual machines.

8. Using VIR2REAL with CMS Pipelines

   The VIR2REAL EXEC can be invoked as a stage in CMS Pipelines. It writes a single record of output in the same format that is written to a file if the CSV keyword is specified. See usage note 7 for more information on the output. The normal screen output is not displayed unless the TYPE option is specified. Here is an example of this usage which displays the time and the memory ratio. Because the values are "comma separated" a comma is used as a field separator.

   PIPE rexx (vir2real exec) | spec fs , f1 1 /Ratio:/ nw f9 nw | console
   

   CMS Pipelines can define structures to describe data like the record that VIR2REAL produces. VIR2REAL defines a structure that can be used to work with its output record. In order to use this feature, VIR2REAL must be invoked twice, first to define the structure and then to calculate the data and use the structure. For example:

   /* Rexx */
   'PIPE rexx (vir2real exec)'
   'PIPE rexx (vir2real exec)',
      '| spec qualify vir2real member Timestamp 1 /Ratio:/ nw member RatioAll nw',
      '| console'
   

   See the PDF document for a description of the members in the structure.

9. Requirements to run VIR2REAL

   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 commands QUERY FRAMES and QUERY STORAGE 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. If the command QUERY AGELIST is available, it will check the Keepslot and Earlywrites settings. If either one is off, a message is written. If the command QUERY PAGING is available, it will check the settings for Paging Alias and Paging HPF. If either of these values are off, the settings are shown.

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)
Maximum possible storage:                          102400 MB (100.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. The maximum possible storage that could be added to this system without an IPL. Storage can only be added if there is unused storage available in your system.

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.

Change log, latest changes first

Version    Change Description
-------    ------------------
V1.2.17    Correct output if IPL parameter STORE= is used.
V1.2.16    Add output if z/VM Memory Reclamation is available.
V1.2.15    Can be run as a Pipelines stage, CSV output to pipe.
           Also define Pipeline structure for output.
V1.2.14    Add VAR and STEM output options to Rexx variables.
V1.2.13    Fix check for Class E indicate, fix check for CP level
           Add check of QUERY PAGING
V1.2.12    Changes for 6.4 - no XSTORE and show keepslot value
V1.2.11    Work around CP bug if IBMCLASS is not in COMMANDS output
V1.2.10    Add NSS instantiated counts to total instantiated.
V1.2.9     Output to a table or CSV file
V1.2.8A    For 6.3, Get "instan" number, get agelist, allow planning
V1.2.8     Changes for 6.3 recommendations, allow MiB and GiB
V1.2.7     Query dump device, show error if none
V1.2.6     Handle no paging, SSI & ZCMS, better output of percentages
V1.2.5     Fix query of system XSTORE
V1.2.4     Allow output to file, handle CMS IPL devices
V1.2.2     More CP Queries, get VDISK info also, better formatting