Materialize Machine Information (MATMIF)

Instruction Syntax

Built-in number for MATMIF is 670.
MATMIF (                                                                        
         receiver                  : address                                   
         materialization_option    : unsigned binary(2)                            
) :   signed binary(4)  /* result */                                               

Warning

The following information is subject to change from release to release. Use it with caution and be prepared to adjust for changes with each new release. The data returned by this instruction is subject to change each and every release. Fields may be added, deleted, reordered, and/or have their unit of measure changed. There will be no attempt made to maintain any compatibility from release to release.

Description:

Information specified by the materialization option operand is materialized into the template addressed by the receiver operand. Upon successful completion, result is set to binary 0.

In the case where the requested data cannot be returned, the EUNKNOWN error number is returned in the result.

The receiver specifies a space that is to receive the materialized information. The space pointer specified must address a 16-byte aligned area. If not, the EFAULT error number is returned in the result.

The materialization option specifies which information is to be materialized. If an invalid value is specified, the EINVAL error number is returned in the result.

A summary of the allowable hex values for materialization option follows.

The receiver template has the following format

The first 4 bytes identify the total number of bytes provided for use by the instruction. This value is supplied as input to the instruction and is not modified by the instruction. A value of less than 8 causes the ENOSPC error number to be returned in the result.

The second 4 bytes identify the total number of bytes available to be materialized. The instruction materializes as many bytes as can be contained in the area specified as the receiver. If the byte area identified by the receiver is greater than that required to contain the information requested, then the excess bytes are unchanged. No error numbers (other than the ENOSPC described previously) are returned if the receiver contains insufficient area for the materialization.

The following information requires receivers of varying lengths. The information that will be materialized and their materialization option values follow. If the system does not support a function, hex zeros will be returned in that field.

• Hex 0001 = Option 0001 information

  Offset
  Dec	Hex	Field Name	Data Type and Length
  8	8	Maximum memory	UBin(8)
  16	10	Minimum memory	UBin(8)
  24	18	Dispatch wheel rotation period	UBin(8)
  32	20	Partition ID	UBin(4)
  36	24	Indicators	Char(4)
  36	24	Reserved (binary 0)	Bits 0-28
  36	24	Scaled processor time indicator 0 = Processor time may not be scaled during the current IPL. 1 = Processor time may be scaled during the current IPL.	Bit 29
  36	24	Bound hardware threads indicator 0 = Hardware threads are not bound 1 = Hardware threads are bound	Bit 30
  36	24	Dedicated processors indicator 0 = Partition shares processors 1 = Partition has dedicated processors	Bit 31
  40	28	Maximum processors in the physical machine	UBin(4)
  44	2C	Minimum virtual processors	UBin(4)
  48	30	Maximum virtual processors	UBin(4)
  52	34	Minimum processing capacity	UBin(4)
  56	38	Maximum processing capacity	UBin(4)
  60	3C	Processing capacity delta	UBin(4)
  64	40	Minimum interactive capacity percentage	UBin(4)
  68	44	Maximum interactive capacity percentage	UBin(4)
  72	48	Hardware threads per processor	UBin(2)
  74	4A	Partition name	Char(256)
  330	14A	Reserved (binary 0)	Char(5)
  335	14F	5250 measurement type	UBin(1)
  336	150	Memory delta	UBin(8)
  344	158	Configured virtual processors	UBin(4)
  348	15C	Configured processing capacity	UBin(4)
  352	160	Configured interactive capacity percentage	UBin(4)
  356	164	Configured variable processing capacity weight	UBin(4)
  360	168	Configured memory	UBin(8)
  368	170	Minimum 5250 online transaction processing (OLTP) user authorizations	Bin(4)
  372	174	Maximum 5250 online transaction processing (OLTP) user authorizations	Bin(4)
  376	178	Configured 5250 online transaction processing (OLTP) user authorizations	Bin(4)
  380	17C	--- End ---

  Minimum memory is the minimum amount of memory (in units of megabytes) that is needed in this partition.

  Maximum memory is the maximum amount of memory (in units of megabytes) that can be assigned to this partition.

  Dispatch wheel rotation period is the number of nanoseconds in the hypervisor's scheduling window. Each virtual processor will be given the opportunity to execute on a physical processor sometime during this period. The amount of time each virtual processor is able to use in the hypervisor's scheduling window on a physical processor corresponds to the partition's processing capacity. The value of processing capacity is returned in option hex 0002 of this instruction.

  Partition ID is the identifier of this partition. It is unique within a physical machine.

  Bound hardware threads indicator indicates whether or not hardware threads are bound. Hardware threads are not bound indicates that the system can not assume that a set of hardware threads will always be dispatched together on a physical processor. Hardware threads are bound indicates that a set of hardware threads will always be dispatched together on a physical processor. This allows an operating system to make scheduling decisions based on cache affinity and work load.

  Dedicated processors indicator indicates whether or not the partition uses only dedicated physical processors. Partition has dedicated processors indicates that this partition uses only dedicated physical processors. This means that each virtual processor in the partition has a corresponding entire physical processor. Partition shares processors indicates that this partition uses physical processors from a shared pool of physical processors. The number of virtual processors represents the maximum number of concurrent units of execution that can be active in the partition at any point in time. Each virtual processor has the processing capacity of some fraction of a physical processor. One or more partitions may be executing on the physical processors in the shared processor pool at any given point in time.

  The scaled processor time indicator indicates whether processor time may or may not be scaled during the current IPL. If the scaled processor time indicator is 0, then materialized values of scaled and unscaled processor times are equivalent during the current IPL. If the scaled processor time indicator is 1, then materialized values of scaled and unscaled processor times are not equivalent during the current IPL.

  Over any interval, the average relative processor speed (i.e. processor speed relative to nominal) is indicated by the ratio of scaled processor time to unscaled processor time elapsed during the interval. When the scaled processor time indicator is 0, scaled and unscaled processor times are equivalent, and their ratio over any interval is 1:1, indicating that the processor's relative speed is 1X nominal. When the scaled processor time indicator is 1, scaled and unscaled processor times are not equivalent, and the ratio of their elapsed values over any interval indicates the processor's average relative speed over the interval.

  For example, consider MATRMD hex 26 data is available at the start and end of an interval. The ratio of the elapsed scaled processor utilized time to elapsed processor utilized time indicates the average relative processor speed while the processor was being utilized during the interval. The same analysis is applicable to all categories of processor time accumulated during an interval (i.e. processor interrupted time, processor stolen time, processor donated time, processor idle time, and process/thread time) -- the ratio of the scaled to unscaled time indicates the relative processor speed for the accumulated time category. Note that when the scaled processor time indicator is 0, the ratio of scaled to unscaled processor times is always 1:1.

  Maximum processors in the physical machine is the maximum number of physical processors that can be active in this physical machine without physically installing additional processors. This field includes currently active processors and any standby processors that are present in the physical machine.

  Minimum virtual processors is the minimum number of virtual processors that are needed in this partition.

  Maximum virtual processors is the maximum number of virtual processors that can be assigned to this partition.

  Minimum processing capacity is the minimum amount of processing capacity (in units of 1/100 of a physical processor) that is needed in this partition.

  Maximum processing capacity is the maximum amount of processing capacity (in units of 1/100 of a physical processor) that can be assigned to this partition.

  Processing capacity delta is the delta (in units of 1/100 of a physical processor) that can be added to or removed from this partition's processing capacity.

  Minimum interactive capacity percentage is the minimum value that can be set for this partition's interactive capacity percentage. If the 5250 measurement type is not 0, this field will return binary 0.

  Maximum interactive capacity percentage is the maximum value that can be set for this partition's interactive capacity percentage. If 5250 measurement type is not 0, this field will return binary 0.

  Hardware threads per processor is the number of hardware threads per processor when hardware multi-threading is enabled.

  Partition name is the name that has been assigned to this partition. This field is a null-terminated ASCII character string.

  5250 measurement type returns the indicator of the 5250 type of measurement of the physical machine. The value of 0 indicates that the physical machine authorizes the use of 5250 OLTP in units of 5250 CPW. The value of 1 indicates that the physical machine authorizes the use of 5250 OLTP in units of 5250 users.

  Memory delta is the delta (in units of megabytes) that can be added to or removed from this partition's memory.

  Configured virtual processors is the number of virtual processors that are configured for this partition. It does not include the standby (on demand) processors.

  Configured processing capacity is the processing capacity (in units of 1/100 of a physical processor) that is configured for this partition.

  Configured interactive capacity percentage is the interactive processing capacity that is configured for this partition. If the 5250 measurement type is not 0, this field will return binary 0.

  Configured variable processing capacity weight is the variable processing capacity weight that is configured for this partition.

  Configured memory is the physical memory size (in units of megabytes) that is configured for this partition. It does not include the standby (on demand) memory.

  Minimum 5250 online transaction processing (OLTP) user authorizations is the minimum value that are needed for this partition. If minimum number of 5250 OLTP user authorizations was set to no maximum, this field will return binary -2. If the 5250 measurement type is not 1, this field will return binary 0.

  Maximum 5250 online transaction processing (OLTP) user authorizations is the maximum value that can set for this partition. If the number of maximum number of 5250 OLTP user authorizations was set to no maximum, this field will return binary -2. If the 5250 measurement type is not 1, this field will return binary 0.

  Configured 5250 online transaction processing (OLTP) user authorizations is the value configured for this partition from HMC. If the number of configured 5250 OLTP user authorizations was set to no maximum, this field will return binary -2. If the 5250 measurement type is not 1, this field will return binary 0.

• Hex 0002 = Option 0002 information

  Offset
  Dec	Hex	Field Name	Data Type and Length
  8	8	Usable memory	UBin(8)
  16	10	CPU time since IPL	UBin(8)
  24	18	Interactive time since IPL	UBin(8)
  32	20	Excess interactive time since IPL	UBin(8)
  40	28	Shared processor pool idle time since IPL	UBin(8)
  48	30	Indicators	Char(4)
  48	30	Reserved (binary 0)	Bits 0-26
  48	30	Scaled processor time indicator 0 = Processor time may not be scaled during the current IPL. 1 = Processor time may be scaled during the current IPL.	Bit 27
  48	30	Service aggregation point indicator 0 = This partition has a service aggregation point 1 = Another partition or HMC has a service aggregation point	Bit 28
  48	30	Capped partition indicator 0 = Uncapped partition 1 = Capped partition	Bit 29
  48	30	Hardware multi-threading indicator 0 = Hardware multi-threading is not enabled 1 = Hardware multi-threading is enabled	Bit 30
  48	30	Shared processor pool idle time since IPL indicator 0 = Shared processor pool idle time since IPL was not materialized 1 = Shared processor pool idle time since IPL was materialized	Bit 31
  52	34	Processors in the physical machine	UBin(4)
  56	38	Usable virtual processors	UBin(4)
  60	3C	Physical processors in the shared processor pool	UBin(4)
  64	40	Unallocated processor capacity in the partition group	UBin(4)
  68	44	Usable processing capacity	UBin(4)
  72	48	Usable variable processing capacity weight	UBin(4)
  76	4C	Unallocated variable processing capacity weight	UBin(4)
  80	50	Minimum required processing capacity	UBin(4)
  84	54	Interactive capacity percentage	UBin(4)
  88	58	Partition group ID	UBin(2)
  90	5A	Shared processor pool ID	UBin(2)
  92	5C	Interactive threshold	UBin(2)
  94	5E	Reserved (binary 0)	Char(1)
  95	5F	5250 measurement type	UBin(1)
  96	60	Unallocated interactive processor capacity in the partition group	Bin(4)
  100	64	Scaled CPU time since IPL	UBin(8)
  108	6C	Reserved (binary 0)	Char(4)
  112	70	Usable 5250 online transaction processing (OLTP) user authorization	Bin(4)
  116	74	Unallocated 5250 online transaction processing (OLTP) user authorization in partition group	Bin(4)
  120	78	Active 5250 users	Bin(8)
  128	80	--- End ---

  Usable memory is the amount of usable memory (in units of megabytes) currently allocated to this partition.

  CPU time since IPL is the number of nanoseconds of processor time used since IPL.

  Interactive time since IPL is the number of nanoseconds of processor time used by interactive processes since IPL.

  An interactive process is any process doing 5250 display device I/O. For additional information on interactive processes, see manual SC41-0607 IBM i Performance Capabilities Reference manual which is available in the IBM i Information Center.

  Excess interactive time since IPL is the number of nanoseconds of processor time used by interactive processes since IPL, that exceeded interactive capacity. If the 5250 measurement type is 1, it is the CPU time used by 5250 OLTP threads that don't hold 5250 OLTP user authorization.

  Shared processor pool idle time since IPL is the number of nanoseconds of processor time that the shared processor pool has been idle since IPL, when shared processor pool idle time since IPL was materialized.

  Service aggregation point indicator indicates whether or not this partition has a service aggregation point. A service aggregation point is used by the operating system to report problems to HMC.

  Capped partition indicator indicates whether or not the partition is allowed to use more than its processing capacity. An uncapped partition is allowed to use more than its processing capacity if processing capacity is available in the shared processor pool. A capped partition is not allowed to use more than its processing capacity even if the partition has work to do and there is processing capacity available in the shared processor pool.

  Hardware multi-threading indicator indicates whether or not hardware multi-threading is enabled. Hardware multi-threading is enabled indicates that hardware multi-threading is active. Hardware multi-threading is not enabled indicates that hardware multi-threading is inactive. Hardware multi-threading refers to the ability of a processor to be multi-threaded. When a processor is multi-threaded, multiple tasks of execution can be loaded into the same processor. Each task of execution is referred to as a hardware thread. When hardware multi-threading is enabled, hardware threads per processor indicates the number of hardware threads each processor has.

  The scaled processor time indicator indicates whether processor time may or may not be scaled during the current IPL. If the scaled processor time indicator is 0, then materialized values of scaled and unscaled processor times are equivalent during the current IPL. If the scaled processor time indicator is 1, then materialized values of scaled and unscaled processor times are not equivalent during the current IPL.

  Over any interval, the average relative processor speed (i.e. processor speed relative to nominal) is indicated by the ratio of scaled processor time to unscaled processor time elapsed during the interval. When the scaled processor time indicator is 0, scaled and unscaled processor times are equivalent, and their ratio over any interval is 1:1, indicating that the processor's relative speed is 1X nominal. When the scaled processor time indicator is 1, scaled and unscaled processor times are not equivalent, and the ratio of their elapsed values over any interval indicates the processor's average relative speed over the interval.

  For example, consider MATRMD hex 26 data is available at the start and end of an interval. The ratio of the elapsed scaled processor utilized time to elapsed processor utilized time indicates the average relative processor speed while the processor was being utilized during the interval. The same analysis is applicable to all categories of processor time accumulated during an interval (i.e. processor interrupted time, processor stolen time, processor donated time, processor idle time, and process/thread time) -- the ratio of the scaled to unscaled time indicates the relative processor speed for the accumulated time category. Note that when the scaled processor time indicator is 0, the ratio of scaled to unscaled processor times is always 1:1.

  Shared processor pool idle time since IPL indicator indicates whether or not the shared processor pool idle time since IPL was successfully materialized. Shared processor pool idle time since IPL was materialized indicates that the shared processor pool idle time since IPL was successfully materialized and contains valid information. Shared processor pool idle time since IPL was not materialized indicates that the shared processor pool idle time since IPL was not materialized (the partition is not authorized to retrieve this information) and should not be used.

  Processors in the physical machine is the number of physical processors in this physical machine that are available for customer use. This does not include temporary processors on demand that have not been turned on.

  Usable virtual processors is the number of usable virtual processors in this partition.

  Physical processors in the shared processor pool is the number of physical processors that are allocated to the shared processor pool in which this partition is executing.

  Unallocated processing capacity in the partition group is the amount of processing capacity (in units of 1/100 of a physical processor) in this partition's group that is available to be allocated to processing capacity.

  Usable processing capacity is the amount of processing capacity (in units of 1/100 of a physical processor) currently available to the partition. For a partition using dedicated processors this value represents the number of virtual processors currently active in the partition. For a partition using shared processors this value represents this partition's share of processors from its shared processor pool.

  Usable variable processing capacity weight is the weighting factor that is used to assign additional unused CPU cycles (from the shared processor pool) to the partition. Variable processing capacity weight is used for uncapped partitions when they compete for unused CPU cycles in the shared pool. This factor is ranged from 0 - 255. The larger the weight, the more the chance this partition will get additional CPU cycles from the pool. A value of 0 effectively caps this partition at its processing capacity.

  Unallocated variable processing capacity weight is the amount of capacity weight that is available for allocation to the variable processing capacity weight.

  Minimum required processing capacity is the amount of processing capacity (in units of 1/100 of a physical processor) that the operating system requires in this partition.

  Interactive capacity percentage is this partition's portion (in hundredths of a percent) of the physical machine's interactive capacity. For example, if the physical machine was allowed to do 2000 units of interactive work per second, and this field was 5000 (50%), then this partition would be allowed to perform 1000 units of interactive work per second. If the 5250 measurement type is not 0, this field will return binary 0.

  Partition group ID identifies the LPAR group that this partition is a member of. A LPAR group (aka partition group) is a set of partitions on a physical machine that a Work Load Manager (WLM) will manage to achieve its goals. WLM manages the partitions by moving resources from one partition in the group to another partition in the group.

  Shared processor pool ID identifies the shared processor pool this partition is a member of. This field should only be used when partition shares processors. A shared processor pool is a set of physical processors on the physical machine that is used to run a set of shared processor partitions that exist on this physical machine.

  Interactive threshold is the maximum interactive processor utilization (in hundredths of a percent) which can be sustained in this partition, without causing a disproportionate increase in system overhead. For example, a value of 2379 means that the threshold is 23.79%. On a machine with no limit on interactive utilization, the value returned will be 10000 (100%). If the 5250 measurement type is not 0, this field will return 10000 (100%).

  5250 measurement type returns the indicator of the 5250 type of measurement of the physical machine. The value of 0 indicates that the physical machine authorizes the use of 5250 OLTP in units of 5250 CPW. The value of 1 indicates that the physical machine authorizes the use of 5250 OLTP in units of 5250 users.

  Unallocated interactive capacity percentage in the partition group is the portion (in hundredths of percent) of the physical machine's interactive capacity that is available to be allocated to interactive capacity percentage of partitions in this partition's group. 0 will be returned if this instruction is issued on a system with firmware level hex 00 , or if the 5250 measurement type is not 0. -1 will be returned if this instruction is issued on a system with firmware level hex 10 and the release level of that firmware does not support this function.

  Usable 5250 online transaction processing (OLTP) user authorizations is the number of 5250 OLTP user authorizations that the partition has allocated from the total 5250 OLTP user authorizations in the physical machine. If the 5250 measurement type is not 1, this field will return binary 0. If the usable 5250 OLTP user authorizations was set to no maximum, this field will return binary -2.

  Unallocated 5250 online transaction processing (OLTP) user authorizations in partition group is the number of 5250 OLTP user authorizations in the physical machine that is available to be allocated to the usable 5250 OLTP user authorizations of partitions in the partition's group. If this instruction is issued on a system with firmware level hex 00, or the 5250 measurement type is not 1, this field will return binary 0. If the unallocated 5250 OLTP user authorizations in partition group is no maximum, this field will return binary -2.

  Active 5250 users is the number of 5250 users currently active.

  Note that if the 5250 measurement type is 1, the value returned in this field is the number of 5250 OLTP user authorizations needed for the current workload. It can exceed the number of 5250 OLTP user authorizations allocated to this partition.

  Scaled CPU time since IPL is the number of nonoseconds of scaled processor utilized time used since IPL.

  If scaled processor time indicator is 0, the scaled CPU time since IPL will equal the CPU time since IPL. If scaled processor time indicator is 1, the partition's processors may operate at different speeds during the current IPL, and the scaled CPU time since IPL and CPU time since IPL unscaled may differ. The ratio between scaled and unscaled utilized times over any interval is indicative of the processor's speed, relative to nominal, while being used productively during the interval.

Authorization Required

• None

Lock Enforcement

• None

Error Conditions

The result will be set to one of the following:

EFAULT

3408 - The address used for an argument was not correct.

EINVAL

3021 - The value specified for the argument is not correct.

ENOSPC

3404 - No space available.

EUNKNOWN

3474 - Unknown system state.

Exceptions

• 06 Addressing
  • 0601 Space Addressing Violation
  • 0602 Boundary Alignment
  • 0603 Range
• 08 Argument/Parameter
  • 0801 Parameter Reference Violation
• 10 Damage Encountered
  • 1004 System Object Damage State
  • 1005 Authority Verification Terminated Due to Damaged Object
  • 1044 Partial System Object Damage
• 1A Lock State
  • 1A01 Invalid Lock State
• 1C Machine-Dependent
  • 1C03 Machine Storage Limit Exceeded
• 20 Machine Support
  • 2002 Machine Check
  • 2003 Function Check
• 22 Object Access
  • 2202 Object Destroyed
  • 2203 Object Suspended
  • 2207 Authority Verification Terminated Due to Destroyed Object
  • 220B Object Not Available
• 24 Pointer Specification
  • 2401 Pointer Does Not Exist
  • 2402 Pointer Type Invalid
• 2E Resource Control Limit
  • 2E01 User Profile Storage Limit Exceeded
• 32 Scalar Specification
  • 3203 Scalar Value Invalid
• 36 Space Management
  • 3601 Space Extension/Truncation
• 44 Protection Violation
  • 4401 Object Domain or Hardware Storage Protection Violation
  • 4402 Literal Values Cannot Be Changed