Retrieve Partition Information (dlpar_get_info) API

#include <qpmlpmgt.h>
int dlpar_get_info(void *receiver_variable, int data_format, int receiver_length);

Retrieve Partition Information (dlpar_get_info) API returns information about configuration and CPU utilization of the logical partition where this API was called. The API can return information in one of two formats. Format is specified by Format of data to return parameter.

Format 1 returns information about those partition attributes that are unlikely to change without partition IPL.

Format 2 returns information about partition attributes that can change at any time during partition operation. Data returned by format 2 should be sampled more frequently.

If some fields returned by this API are not supported by the installed version of the hypervisor, these fields will be set to zero.

Authorities and Locks

None.

Parameters

Receiver variable  (receiver_variable)

OUTPUT; CHAR(*)

The variable that is to receive the requested information.

Format of the data to return  (data_format)

INPUT; BINARY(4)

This parameter determines what information is returned in the receiver variable. The supported formats are:

Value	Description
1	Partition information that is unlikely to change without partition IPL
2	Partition information that may change at any time during partition operation

Length of the receiver variable  (receiver_length)

INPUT; BINARY(4)

Number of bytes provided by the caller in the receiver variable. The API will return as much information as fits in the receiver variable. The size of the receiver variable can be smaller than the length of the requested format as long as Length of the receiver variable parameter is specified correctly.

Format 1

The following information is returned for the Format 1. For detailed descriptions of the fields in the table, see Field Descriptions.

Field Descriptions

Defined interactive capacity is the desired amount of interactive capacity that was configured for this partition through the HMC. Partition's interactive capacity is defined as this partition's portion of total interactive capacity of the physical machine (in units of 1/100 of a percent).

Defined memory is the desired amount of memory (in megabytes) that was configured for this partition through the HMC.

Defined processing capacity is the desired amount of processing capacity (in units of 1/100 of a physical processor) that was configured for this partition through the HMC.

Defined variable capacity weight is the desired weighting factor that was configured for this partition through the HMC. Variable capacity weight is used for uncapped partitions when they compete for unused CPU cycles in the shared pool. Variable capacity weight can be in the range of 0 - 255. The larger the weight, the more the chance this partition will get additional CPU cycles from the shared pool.

Defined virtual processors is the desired number of virtual processors that was configured for this partition through the HMC.

Dispatch wheel rotation time 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 some time during this period. The amount of time each virtual processor is able to use a physical processor is determined by partition processing capacity.

LPAR number is the identifier of this partition. It is unique within a physical machine.

LPAR flags indicate whether or not hardware threads are bound in the partition and whether or not the partition uses only dedicated physical processors.

This is a bit field and it contains the combination of the following values:

Use the following table:

Maximum interactive capacity is the maximum portion of the physical machine's interactive capacity (in units of 1/100 of a percent), that can be assigned to this partition.

Maximum memory is the maximum amount of main storage (in units of megabytes) that can be assigned to 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.

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

Maximum virtual processors is the maximum number of virtual processors that can be configured for this partition.

Memory increment is the smallest amount of main storage (in units of megabytes) that can be added to or removed from this partition's memory.

Minimum interactive capacity is the minimum portion of the physical machine's interactive capacity (in units of 1/100 of a percent), that can be assigned to this partition.

Minimum memory is the minimum amount of main storage (in units of megabytes) 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 can be assigned to this partition.

Minimum virtual processors is the minimum number of virtual processors that can be configured for this partition.

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

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

Reserved is a reserved field for alignment purposes.

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

Version is the version of format 1 returned by the API.

Format 2

The following information is returned for Format2. For detailed descriptions of the fields in the table, see Field Descriptions.

Field Descriptions

Dispatch latency is the maximum time between dispatches of this partition on a physical processor (in nanoseconds).

Interactive capacity is this partition's current (usable) portion of the physical machine interactive capacity (in units of 1/100 of a percent). For instance, if the physical machine was allowed to do 2000 units of interactive work per second, and this field was 5000, then this partition would be allowed to perform 1000 units of interactive work per second.

Interactive CPU time is the number of nanoseconds of CPU time used by interactive processes in this partition since partition IPL. An interactive process is any process doing 5250 display device I/O. For additional information on interactive processes, see SC41-0607 iSeries Performance Capabilities Reference which is available in the iSeries Information Center.

Interactive CPU time above threshold is the amount of nanoseconds of CPU time used by interactive processes while exceeding the interactive threshold. This is a total since IPL.

Interactive threshold is the maximum interactive CPU utilization (in units of 1/100 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%. In a partition with no limit on interactive utilization, the value returned will be 10000 (100%).

LPAR flags indicate whether or not hardware multithreading is enabled, whether unused CPU time in a shared pool was returned and whether this is a capped partition.

This is a bit field and it contains the combination of the following values:

Use the following table:

Maximum licensed capacity is the current limit on processing capacity of this partition (in units of 1/100 of a physical processor), imposed by the operating system software license for this partition.

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

Online memory is the current (usable) amount of main storage (in units of megabytes) currently allocated to this partition.

Online virtual processors is the number of virtual processors currently used by this partition.

Partition group ID identifies the LPAR group that this partition is a member of.

Physical processors in the shared pool is the number of physical processors that are allocated to the shared processor pool used by this partition. This field does not apply to dedicated partitions.

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

Processing capacity is the current (usable) amount of processing capacity (in units of 1/100 of a physical processor) available to the partition (also known as partition's entitled capacity).

Reserved is a field reserved for alignment purposes.

Shared processor pool ID identifies the shared processor pool this partition is a member of. 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. This field does not apply to dedicated partitions.

Total CPU time is the number of nanoseconds of CPU time used by this partition since IPL.

Unallocated interactive capacity in a partition group is the amount of interactive capacity in the partition group this partition belongs to, which is not allocated to any partition and is available for allocation. Interactive capacity is defined as portion of total interactive capacity of the physical machine (in units of 1/100 of a percent).

Unallocated processing capacity in a partition group is the amount of processing capacity (in units of 1/100 of a physical processor) in the partition group this partition belongs to, which is not allocated to any partition and is available for allocation.

Unallocated variable capacity weight in a partition group is the amount of capacity weight that is available for allocation to the partition's variable capacity weight.

Unused CPU time in a shared pool is the number of nanoseconds of CPU time that the physical processors in a shared processor pool have been idle since system IPL. This field is only returned if the partition was authorized to retrieve shared pool data (see LPAR flags field). Otherwise, this field is set to 0.

Variable capacity weight is the weighting factor that is used to assign additional unused CPU cycles (from the shared processor pool) to the partition. Variable capacity weight is used for uncapped partitions when they compete for unused CPU cycles in the shared pool. This factor is in the range of 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 current (usable) processing capacity.

Version is the version of format 2 returned by the API.

Return Value

Notes:

1. Firmware level SF230 or later is required to support these fields.