Query a virtual server (QVS)
Products can use the query virtual server (QVS) interface to obtain a virtual server's ID and capacity. A virtual server is the “logical hardware” environment in which an image runs. In the case of an image running in a logical partition, the virtual server is the logical partition. In the case of an image running as a first level VM guest, the virtual server is the first level guest. Note that the virtual server concept is not extended to second or higher level VM guests. In those cases, the virtual server is still considered to be the first level VM guest. For an image running in basic mode, the virtual server is the whole machine. In other words, for a CPC in basic mode, the logical hardware environment equals the physical hardware environment.
Customers can define a capacity limit for each logical partition. This limit is enforced by Workload Manager based on the average CPU usage of the logical partition. Peaks of CPU usage are allowed above the limit as long as the average CPU usage stays below the limit.
This service gives software vendors or software providers the option of licensing their software to a virtual server.
One way a software product can use the virtual server ID and capacity query service is to call the service when it starts. Based on the information returned, the product can verify that it is licensed to run on the specific virtual server and that the virtual server does not have more capacity than the product is licensed for. Note that this service does not make any of these licensing checks — it simply returns the information to enable a software product to make the appropriate checks based on the conditions of its license.
- QvsCecValid
- The physical hardware level information is valid.
- QvsImgValid
- The logical partition level information is valid. This flag will be off if not running in logical partition mode.
- QvsVmValid
- The virtual machine information is valid. This flag will be off if not running in a virtual machine.
- QvsCecManufacturerName
- QvsCecPlantofManufacture
- QvsCecMachineType
- QvsCecModelId
- QvsCecSequenceCode
- QvsCecCapacity
- QvsCecCapacityStatus
- QvsImgLogicalPartitionId
- QvsImgLogicalPartitionName
- QvsImgCapacity
- QvsVmName
- QvsVmCapacity
QvsCecCapacity, QvsImgCapacity, and QvsVmCapacity contain the maximum service rate that theoretically could be achieved at each level. The value is in millions of service units per hour (MSU).
QvsCecCapacity is equal to the individual CPU speed multiplied by the number of online and offline physical CPUs.
QvsCecCapacityStatus indicates if the machine is running at nominal capacity or at reduced capacity.
- The partition's defined capacity set via the Hardware Management Console, if any
- The individual CPU speed multiplied by the number of online and offline logical CPUs, if the partition is uncapped and has no defined capacity
- The capacity at the partition's weight, if the partition is capped via the Hardware Management Console.
If QvsImgValid is on, and either the image is in ESA/390 mode or QvsVmValid is on, then QvsImgCapacity is equal to the individual CPU speed multiplied by the number of online and offline logical CPUs.
QvsVmCapacity is the individual CPU speed multiplied by the number of online and offline virtual CPUs.
In all cases, the individual CPU speed in based on the MP factor for the number of online and offline physical CPUs.
Note that the capacity of a virtual server can change dynamically. One example of a dynamic capacity change is a CPU upgrade on demand of the underlying hardware. A second example is a dynamic change of the defined capacity limit for a logical partition. If an unauthorized program is interested in knowing about dynamic capacity changes, it must poll the virtual server ID and capacity query service. Given dynamic capacity changes are rare, a low polling rate should be sufficient.
Authorized programs interested in knowing about dynamic capacity changes can also listen for ENF signal 61. This ENF is signaled when a change in dynamic capacity occurs and provides the listener exit the new capacity at each level in the hierarchy.
Return and reason codes
When processing is complete for the QVS SYSEVENT, the last byte of register 15 contains one of the following hexadecimal return codes:
Return Code | Meaning |
---|---|
00 | Successful completion. |
04 | The parameter list is too small. |