SET SHARE

Read syntax diagramSkip visual syntax diagram Set SHARE userid TYPEALLTYPEALLCPZIIPIFLICFINITialABSolutennn%RELativennnnnNOLimitLIMITSoftLIMITHardABSolutemmm%LIMITSoftLIMITHardRELativemmmmmLIMITSoftLIMITHardNOLimitLIMITSoftLIMITHard

Authorization

Privilege Class: A

Purpose

Use SET SHARE to change the system-resource-access priority for users.

Operands

userid
identifies the virtual machine whose share you are changing.
ABSolute nnn%
specifies that this user is to receive a target minimum of nnn% of the scheduled system resources, which include CPU, storage, and paging capacity; nnn is a decimal real number—no or one decimal place—from 0.1 to 100 (for example, 20.5% or 80%).
RELative nnnnn
specifies that this user is to receive a target minimum relative share of nnnnn. The amount of scheduled system resources available to relative share users is the total of resources available less the amount allocated to absolute share users. The portion that this user receives is nnnnn divided by the sum of the nnnnn's of all relative share users. For example, if one user's relative share is 100 and another user's relative share is 200, then the second user gets twice as much access to system resources as the first. If no share is specified in a user's directory entry, then the share defaults to a relative share of 100. The operand nnnnn ranges from 1 to 10000.
INITial
specifies that this user's share of the system resources is to be reset to that specified in the user's directory entry. In the rare case that this user ID no longer appears in the directory, the user's share of the system resources is set to a relative share of 100.
ABSolute mmm%
specifies that this user is to receive a target maximum of mmm% of the scheduled CPU resource; mmm is a decimal real number—no or one decimal place—from 0.1 to 100 (for example, 20.5% or 80%).

If ABSOLUTE is not specified, the maximum share has the same type as the minimum share. The mmm% must be specified when the minimum is an ABSOLUTE value; mmmmm must be specified when the minimum is a RELATIVE value.

RELative mmmmm
specifies that this user is to receive a target maximum relative share of mmmmm of the scheduled CPU resource. The operand mmmmm ranges from 1 to 10000.

If RELATIVE is not specified, the maximum share has the same type as the minimum share. The mmm% must be specified when the minimum is an ABSolute value; mmmmm must be specified when the minimum is a RELATIVE value.

NOLimit
specifies that a user's share of CPU resource is not limited.
LIMITSoft
specifies that a user's share of CPU resource is limited. However, there are times when LIMITSOFT users will receive more than their limit. This occurs when some users are not using all of their shares (for example, they are waiting for I/O to complete), and there are no NOLIMIT users and no users who have yet to reach their limit and can use additional CPU resource.

If a maximum share value was not specified, the user's minimum share is also its maximum share of the CPU resource.

LIMITHard
specifies that a user's share of CPU resource is limited. When LIMITHARD is specified, a user does not receive more than its maximum share of the CPU resource. If a maximum share is not specified, the minimum share is also the maximum.

If a maximum share value was not specified, the user's minimum share is also its maximum share of the CPU resource.

See the SET SRM LIMITHARD command for details of setting the method that the CP scheduler will use to enforce the limit on the guest's CPU usage.

TYPE
specifies that this change to the user's share setting applies to the specified CPU type and that the share settings for other types are not changed. If TYPE is not specified, or if TYPE ALL is specified, this change applies to all CPU types. The determination of whether this setting has an effect on virtual CPUs depends on the CPU affinity setting for the virtual machine and whether real CPUs of the corresponding type are available in the processor configuration. See Usage Note 8 for further details regarding setting share values by CPU type.

Usage Notes

  1. You can set a user's system-resource-access priority for each processor type with the SET SHARE command, but some of these processor types are not available in certain processor configurations. The share values are still displayed for the unavailable processor types, but they are not used.
  2. Be aware that a user's share denotes priority access to the entire set of system resources, not just CPU. Currently, the following resources are scheduled according to the share specification:
    • CPU
    • Real storage
    • Paging capacity.

    In fact, a bottlenecked resource and a user's requirement for it determine the access priority. For example, if storage is constrained, the user receives access to real storage according to its share. Likewise, if paging is a problem, the user receives paging service according to its share.

  3. An absolute share user is receiving its correct service when the time it would take to complete a task if it were running alone in the system is the inverse of its share percentage. For example, if a user receives 50% (1/2) of the system, it should take no more than twice as long to complete a unit of work as it would if it were running alone. If it gets 25% (1/4) of the system, it should not take more than four times what it would running alone. The gauge of relative share delivery is slightly different. Two relative share users with similar resource requirements can be compared. If the users are limited by the same bottlenecked resource, a RELATIVE SHARE user with twice the SHARE of another should run twice as fast.
  4. The target maximum share is applicable only to the CPU resource.

    If a target maximum share is specified, the user will not necessarily receive that amount of scheduled CPU resource. This is because a user will only receive more than the target minimum share for a resource when other users are not using all of their target minimum shares.

  5. When the limit option is specified alone (that is, without a share and without a maximum share being specified), only that option is changed. The userid retains its previous share and the maximum share is changed (if necessary) to match the new limit option. For example, if NOLIMIT is specified, then the pre-existing maximum share (if any), is reset to zero. Or, if LIMITHARD or LIMITSOFT is specified and there previously was no maximum share, then the maximum share is set equal to the user's minimum share (with the specified 'hard' or 'soft' characteristic).
  6. Due to the dynamics of VM systems and scheduling, the maximum share target is not always met. The actual usage should be within five percent of the system. The accuracy may be affected by the following:
    • running guest as a virtual MP
    • guest use of diagnose X'44' or X'9C'
    • running VM second level or on LPAR
    • low system utilization
  7. When setting SHARE RELATIVE on a userid that has multiple CPUs, the minimum share that the system will assign is one per virtual CPU. For example, if you SET SHARE MAINT RELATIVE 1 and MAINT has five virtual CPUs, the resulting SHARE will be set to five.
  8. When setting the SHARE of a userid that has multiple CPUs in its virtual configuration, there are special considerations. The share for the virtual machine is divided across all of the virtual processors. In the simplest case, if an absolute share of 10% is set for a virtual machine with two shared virtual CPUs, each gets a 5% share of the system's CPU resources. If one of the processors cannot use its 5% share, the other processor does not get more. Each is entitled to 5% of the system individually. If in the above case one of the virtual CPUs has been stopped and the other is started, then the entire 10% share of system resources would be given to the started virtual CPU.

    The user's virtual MP configuration can include more than one type of processor, such as CP, IFL, zIIP, or ICF. In this situation, for scheduling purposes each type of processor is treated as a separate resource. There are two cases depending on whether the virtual machine has CPUAFFINITY ON or CPUAFFINITY OFF. In both cases, assume that all virtual CPUs are started.

    If CPUAFFINITY is OFF, there is only one real resource pool on which these virtual CPUs can be dispatched—the primary CPU type. The virtual machine's share is distributed evenly across all of its virtual CPUs regardless of CPU type.

    If CPUAFFINITY is ON, the virtual machine's share is distributed evenly across each set of virtual CPUs of the same type. As an example, consider a virtual machine with a share of absolute 24% and with two virtual CPUs—one CP and one zIIP. In this case, each virtual CPU will be given a share of 24% of its corresponding type of real processor time. If there are two real CPs and one real zIIP, the virtual CP will be entitled to a 24% share of each CP or 48% of one real CP. The virtual zIIP is entitled to 24% of the zIIP.

    Now consider a virtual machine with a share setting of absolute 24% that has four virtual CPs and two virtual zIIPs, all started. In this example, each virtual CP is given a share of 6% of the real CP resources and each virtual zIIP is given a share of 12% of whatever real zIIP resources exist. However, if there are no real zIIPs, CPUAFFINITY is suppressed for the virtual zIIPs and they are dispatched on the real CPs. In that case, all six virtual CPUs are considered to be sharing the CP resources and each is given a 4% share of the real CP processors.

    There are several consequences of all this which must be considered when assigning a share value to a virtual MP userid.
    1. The examples above use absolute shares as they are the easiest to visualize. However, the same concepts hold true for relative share settings.
    2. Each type of CPU resource must be considered as a separate resource that is controlled by the SHARE setting.
    3. The CPUAFFINITY setting for a virtual machine might have implications for the total CPU time that this virtual machine can receive. This setting can be changed with the SET CPUAFFINITY command, or by varying on a real processor if it is the first of its type, or by varying off a real processor if it is the last of its type.
    4. Changing the number of virtual CPUs in a virtual configuration might change the actual share of real CPU resource a virtual machine is entitled to if a new type is added to the virtual configuration or the last of one type is removed from the configuration.
  9. CP calculates and enforces consumption limits in a different manner than deadline limits. A virtual machine is consumption limited when the following conditions exist:
    • The virtual machine is assigned an ABSOLUTE LIMITHARD share.
    • CONSUMPTION limiting (SET SRM LIMITHARD CONSUMPTION) is in effect on the system.

    For consumption limits, CP always assumes that every logical CPU can run to 100% busy, regardless of the LPAR's entitlement and regardless of the availability of excess power on the CPC. For example, if the system has five shared logical IFL CPUs, CP assumes that the shared IFL CPU resource has a total capacity of 500%. If the virtual machine in this case is assigned an ABSOLUTE LIMITHARD share of 50% for TYPE IFL, the virtual machine will be allowed to consume a CPU capacity of 250% (that is, 2.5 CPUs of power). If PR/SM is limiting the LPAR's five logical IFL CPUs to 280% total capacity, CP will still allow the virtual machine to consume 250%. In that case, CP is really allowing the virtual machine to consume (250/280) = 89% of the IFL CPU resource available to the LPAR. If DEADLINE limiting (SET SRM LIMITHARD DEADLINE) is in effect on the system, the virtual machine will be allowed to consume approximately (50 * 280) = 140% of the IFL CPU capacity, because DEADLINE limiting considers the actual amount of CPU resource available to the LPAR.

  10. When APAR VM65680 is applied and multithreading is enabled, prorated core time is used in the consumption limiting calculation for a virtual machine being consumption limited. When multithreading is not enabled or APAR VM65680 is not applied, raw CPU time is used instead. For an explanation of the different measures of CPU time, see Simultaneous Multithreading (SMT) in z/VM: Performance.
  11. Share settings control access to CPU power on a system-wide, per-processor-type basis, but they have no bearing or influence on how the power associated with a RESPOOL is distributed to its members. When the RESPOOL limit is reached, all members of the pool are put onto the limit list for a while, and then, after a delay sufficient to compensate for any excess use, they are all removed. The scheduler makes no effort to distribute the power of the RESPOOL to its members in accordance with the members' share settings.

Responses

Response 1:


USER userid:  CP    share_type SHARE = value 
                       MAXIMUM SHARE = option share_type value
              IFL   share_type SHARE = value 
                       MAXIMUM SHARE = option share_type value
              ICF   share_type SHARE = value
                       MAXIMUM SHARE = option share_type value
              ZIIP  share_type SHARE = value
                       MAXIMUM SHARE = option share_type value
is issued when the command completes successfully. See QUERY SHARE for field descriptions.

Messages

  • HCP007E Invalid userid - userid
  • HCP020E Userid missing or invalid
  • HCP026E Operand missing or invalid
  • HCP045E userid not logged on