9. Appendix¶

This section contains information that is referenced from other sections, and that does not really need to be read in sequence.

9.1. Base classes for resources¶

Base definitions for resource manager classes.

Resource manager classes exist for each resource type and are helper classes that provide functionality common for the resource type.

Resource manager objects are not necessarily singleton objects, because they have a scope of a certain set of resource objects. For example, the resource manager object for LPARs exists once for each CPC managed by the HMC, and the resource object scope of each LPAR manager object is the set of LPARs in that CPC.

class zhmcclient.BaseManager(resource_class, class_name, session, parent, base_uri, oid_prop, uri_prop, name_prop, query_props, list_has_name=True)[source]¶

Abstract base class for manager classes (e.g. CpcManager).

It defines the interface for the derived manager classes, and implements methods that have a common implementation for the derived manager classes.

Objects of derived manager classes should not be created by users of this package by simply instantiating them. Instead, such objects are created by this package as instance variables of Client and other resource objects, e.g. cpcs. For this reason, the __init__() method of this class and of its derived manager classes are considered internal interfaces and their parameters are not documented and may change incompatibly.

__repr__()[source]¶: Return a string with the state of this manager object, for debug purposes.

invalidate_cache()[source]¶

Invalidate the Name-URI cache of this manager.

The zhmcclient maintains a Name-URI cache in each manager object, which caches the mappings between resource URIs and resource names, to speed up certain zhmcclient methods.

The Name-URI cache is properly updated during changes on the resource name (e.g. via update_properties()) or changes on the resource URI (e.g. via resource creation or deletion), if these changes are performed through the same Python manager object.

However, changes performed through a different manager object (e.g. because a different session, client or parent resource object was used), or changes performed in a different Python process, or changes performed via other means than the zhmcclient library (e.g. directly on the HMC) will not automatically update the Name-URI cache of this manager.

In cases where the resource name or resource URI are effected by such changes, the Name-URI cache can be manually invalidated by the user, using this method.

Note that the Name-URI cache automatically invalidates itself after a certain time since the last invalidation. That auto invalidation time can be configured using the name_uri_cache_timetolive attribute of the RetryTimeoutConfig class.

resource_class¶: The Python class of the parent resource of this manager.

class_name¶: The resource class name

session¶

Session with the HMC.

Type:	`Session`

parent¶

Parent resource defining the scope for this manager.

None, if the manager has no parent, i.e. when it manages top-level resources.

Type:	Subclass of `BaseResource`

resource_object(uri_or_oid, props=None)[source]¶

Return a minimalistic Python resource object for this resource class, that is scoped to this manager.

This method is an internal helper function and is not normally called by users.

The returned resource object will have the following minimal set of properties set automatically:

object-uri

object-id

parent

class

Additional properties for the Python resource object can be specified by the caller.

Parameters:	uri_or_oid (string) – object-uri or object-id of the resource. props (dict) – Property values in addition to the minimal list of properties that are set automatically (see above).
Returns:	A Python resource object for this resource class.
Return type:	Subclass of `BaseResource`

findall(**filter_args)[source]¶

Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g. for CPCs, a list of Cpc objects is returned).

Any resource property may be specified in a filter argument. For details about filter arguments, see Filtering.

The zhmcclient implementation handles the specified properties in an optimized way: Properties that can be filtered on the HMC are actually filtered there (this varies by resource type), and the remaining properties are filtered on the client side.

If the “name” property is specified as the only filter argument, an optimized lookup is performed that uses a name-to-URI cache in this manager object. This this optimized lookup uses the specified match value for exact matching and is not interpreted as a regular expression.

Authorization requirements:

see the list() method in the derived classes.

Parameters:	**filter_args – All keyword arguments are used as filter arguments. Specifying no keyword arguments causes no filtering to happen. See the examples for usage details.
Returns:	List of resource objects in scope of this manager object that match the filter arguments. These resource objects have a minimal set of properties.
Raises:	Exceptions raised by the list() methods in derived resource manager classes (see Reference: Resources).

Examples:

The following example finds partitions in a CPC by status. Because the ‘status’ resource property is also a valid Python variable name, there are two ways for the caller to specify the filter arguments for this method:

As named parameters:
```
run_states = ['active', 'degraded']
run_parts = cpc.partitions.find(status=run_states)
```
As a parameter dictionary:
```
run_parts = cpc.partitions.find(**{'status': run_states})
```
The following example finds adapters of the OSA family in a CPC with an active status. Because the resource property for the adapter family is named ‘adapter-family’, it is not suitable as a Python variable name. Therefore, the caller can specify the filter argument only as a parameter dictionary:
```
filter_args = {'adapter-family': 'osa', 'status': 'active'}
active_osa_adapters = cpc.adapters.findall(**filter_args)
```

find(**filter_args)[source]¶

Find exactly one resource in scope of this manager, by matching resource properties against the specified filter arguments, and return its Python resource object (e.g. for a CPC, a Cpc object is returned).

Any resource property may be specified in a filter argument. For details about filter arguments, see Filtering.

The zhmcclient implementation handles the specified properties in an optimized way: Properties that can be filtered on the HMC are actually filtered there (this varies by resource type), and the remaining properties are filtered on the client side.

If the “name” property is specified as the only filter argument, an optimized lookup is performed that uses a name-to-URI cache in this manager object. This this optimized lookup uses the specified match value for exact matching and is not interpreted as a regular expression.

Authorization requirements:

see the list() method in the derived classes.

Parameters:	**filter_args – All keyword arguments are used as filter arguments. Specifying no keyword arguments causes no filtering to happen. See the examples for usage details.
Returns:	Resource object in scope of this manager object that matches the filter arguments. This resource object has a minimal set of properties.
Raises:	`NotFound` – No matching resource found. `NoUniqueMatch` – More than one matching resource found. Exceptions raised by the list() methods in derived resource manager classes (see Reference: Resources).

Examples:

The following example finds a CPC by its name. Because the ‘name’ resource property is also a valid Python variable name, there are two ways for the caller to specify the filter arguments for this method:

As named parameters:
```
cpc = client.cpcs.find(name='CPC001')
```
As a parameter dictionary:
```
filter_args = {'name': 'CPC0001'}
cpc = client.cpcs.find(**filter_args)
```
The following example finds a CPC by its object ID. Because the ‘object-id’ resource property is not a valid Python variable name, the caller can specify the filter argument only as a parameter dictionary:
```
filter_args = {'object-id': '12345-abc...de-12345'}
cpc = client.cpcs.find(**filter_args)
```

list(full_properties=False, filter_args=None)[source]¶

Find zero or more resources in scope of this manager, by matching resource properties against the specified filter arguments, and return a list of their Python resource objects (e.g. for CPCs, a list of Cpc objects is returned).

Any resource property may be specified in a filter argument. For details about filter arguments, see Filtering.

The zhmcclient implementation handles the specified properties in an optimized way: Properties that can be filtered on the HMC are actually filtered there (this varies by resource type), and the remaining properties are filtered on the client side.

At the level of the BaseManager class, this method defines the interface for the list() methods implemented in the derived resource classes.

Authorization requirements:

see the list() method in the derived classes.

Parameters:	full_properties (bool) – Controls whether the full set of resource properties should be retrieved, vs. only a minimal set as returned by the list operation. filter_args (dict) – Filter arguments. None causes no filtering to happen. See the examples for usage details.
Returns:	List of resource objects in scope of this manager object that match the filter arguments. These resource objects have a set of properties according to the full_properties parameter.
Raises:	Exceptions raised by the list() methods in derived resource manager classes (see Reference: Resources).

Examples:

The following example finds those OSA adapters in cage ‘1234’ of a given CPC, whose state is ‘stand-by’, ‘reserved’, or ‘unknown’:

filter_args = {
    'adapter-family': 'osa',
    'card-location': '1234-.*',
    'state': ['stand-by', 'reserved', 'unknown'],
}
osa_adapters = cpc.adapters.list(full_properties=True,
                                 filter_args=filter_args)

The returned resource objects will have the full set of properties.

find_by_name(name)[source]¶

Find a resource by name (i.e. value of its ‘name’ resource property) and return its Python resource object (e.g. for a CPC, a Cpc object is returned).

This method performs an optimized lookup that uses a name-to-URI mapping cached in this manager object.

This method is automatically used by the find() and findall() methods, so it does not normally need to be used directly by users.

Authorization requirements:

see the list() method in the derived classes.

Parameters:	name (string) – Name of the resource (value of its ‘name’ resource property). Regular expression matching is not supported for the name for this optimized lookup.
Returns:	Resource object in scope of this manager object that matches the filter arguments. This resource object has a minimal set of properties.
Raises:	`NotFound` – No matching resource found. Exceptions raised by the list() methods in derived resource manager classes (see Reference: Resources).

Examples:

The following example finds a CPC by its name:
```
cpc = client.cpcs.find_by_name('CPC001')
```

flush()[source]¶

Invalidate the Name-URI cache of this manager.

Deprecated: This method is deprecated and using it will cause a exceptions.DeprecationWarning to be issued. Use invalidate_cache() instead.

Base definitions for resource classes.

Resource objects represent the real manageable resources in the systems managed by the HMC.

class zhmcclient.BaseResource(manager, uri, name, properties)[source]¶

Abstract base class for resource classes (e.g. Cpc) representing manageable resources.

It defines the interface for the derived resource classes, and implements methods that have a common implementation for the derived resource classes.

Objects of derived resource classes are representations of the actual manageable resources in the HMC or in systems managed by the HMC.

Objects of derived resource classes should not be created by users of this package by simply instantiating the derived resource classes. Instead, such objects are created by this package and are returned to the user as a result of methods such as find() or list(). For this reason, the __init__() method of this class and of its derived resource classes are considered internal interfaces and their parameters are not documented and may change incompatibly.

properties¶

The properties of this resource that are currently present in this Python object. Will not be None.

Key: Name of the property.

Value: Value of the property.

See the respective ‘Data model’ sections in the HMC API book for a description of the resources along with their properties.

The dictionary contains either the full set of resource properties, or a subset thereof, or can be empty in some cases.

Because the presence of properties in this dictionary depends on the situation, the purpose of this dictionary is only for iterating through the resource properties that are currently present.

Specific resource properties should be accessed via:

The resource name, via the name attribute.

The resource URI, via the uri attribute.

Any resource property, via the get_property() or prop() methods.

The properties in this dictionary are mutable. However, the properties of the actual manageable resources may or may not be mutable. Mutability for each resource property is indicated with the ‘w’ qualifier in its data model in the HMC API book.

Type:	dict

uri¶

The canonical URI path of the resource. Will not be None.

Example: /api/cpcs/12345

Type:	string

name¶

The name of the resource. Will not be None.

The resource name is unique across its sibling resources of the same type and with the same parent resource.

Accessing this property will cause the properties of this resource object to be updated from the HMC, if it does not yet contain the property for the resource name.

Type:	string

manager¶

Manager object for this resource (and for all resources of the same type in the scope of that manager). Will not be None.

Type:	Subclass of `BaseManager`

full_properties¶

A boolean indicating whether or not the resource properties in this object are the full set of resource properties.

Note that listing resources and creating new resources produces objects that have less than the full set of properties.

properties_timestamp¶: The point in time of the last update of the resource properties cached in this object, as Unix time (an integer that is the number of seconds since the Unix epoch).

pull_full_properties()[source]¶

Retrieve the full set of resource properties and cache them in this object.

Authorization requirements:

Object-access permission to this resource.

Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

get_property(name)[source]¶

Return the value of a resource property.

If the resource property is not cached in this object yet, the full set of resource properties is retrieved and cached in this object, and the resource property is again attempted to be returned.

Authorization requirements:

Object-access permission to this resource.

Parameters:	name (string) – Name of the resource property, using the names defined in the respective ‘Data model’ sections in the HMC API book.
Returns:	The value of the resource property.
Raises:	`KeyError` – The resource property could not be found (also not in the full set of resource properties). `HTTPError` `ParseError` `AuthError` `ConnectionError`

prop(name, default=None)[source]¶

Return the value of a resource property, applying a default if it does not exist.

If the resource property is not cached in this object yet, the full set of resource properties is retrieved and cached in this object, and the resource property is again attempted to be returned.

Authorization requirements:

Object-access permission to this resource.

Parameters:	name (string) – Name of the resource property, using the names defined in the respective ‘Data model’ sections in the HMC API book. default – Default value to be used, if the resource property does not exist.
Returns:	The value of the resource property.
Raises:	`HTTPError` `ParseError` `AuthError` `ConnectionError`

__str__()[source]¶

Return a human readable string representation of this resource.

Example result:

Cpc(name=P0000S12,
    object-uri=/api/cpcs/f1bc49af-f71a-3467-8def-3c186b5d9352,
    status=service-required)

__repr__()[source]¶

Return a string with the state of this resource, for debug purposes.

Note that the derived resource classes that have child resources have their own __repr__() methods, because only they know which child resources they have.

9.2. Glossary¶

This documentation uses a few special terms:

HMC

Hardware Management Console; the node the zhmcclient talks to.

session-id

an opaque string returned by the HMC as the result of a successful logon, for use by subsequent operations instead of credential data. The HMC gives each newly created session-id a lifetime of 10 hours, and expires it after that.

fulfillment

The act of satisfying requests for creation, modification, or deletion of storage volumes in a storage subsystem (i.e. of the actual storage backing a storage volume object).

Storage volume objects have a fulfillment state indicating whether the volume is fulfilled, which means that the request for creation or modification has been carried out and the state of the backing volume is now in sync with the storage volume object.

Storage group objects also have a fulfillment state indicating whether all of its storage volumes are fulfilled.

9.3. Special type names¶

This documentation uses a few special terms to refer to Python types:

string

a unicode string or a byte string

unicode string

a Unicode string type (unicode in Python 2, and str in Python 3)

byte string

a byte string type (str in Python 2, and bytes in Python 3). Unless otherwise indicated, byte strings in this package are always UTF-8 encoded.

number

one of the number types int, long (Python 2 only), or float.

integer

one of the integer types int or long (Python 2 only).

timestamp

a Timestamp-typed value as used in the HMC API. This is a non-negative integer value representing a point in time as milliseconds since the UNIX epoch (1970-01-01 00:00:00 UTC), or the value -1 to indicate special treatment of the value.

json object

a dict object that is a Python representation of a valid JSON object. See py-to-json-table for details.

header dict

a dict object that specifies HTTP header fields, as follows:

key (string): Name of the header field, in any lexical case. Dictionary key lookup is case sensitive, however.

value (string): Value of the header field.

callable

a type for callable objects (e.g. a function, calling a class returns a new instance, instances are callable if they have a __call__() method).

DeprecationWarning

a standard Python warning that indicates the use of deprecated functionality. See section Deprecations for details.

HMC API version

an HMC API version, as a tuple of (api_major_version, api_minor_version), where:

api_major_version (integer): The numeric major version of the HMC API.
api_minor_version (integer): The numeric minor version of the HMC API.

9.4. Resource model¶

This section lists the resources that are available at the HMC API.

The term resource in this documentation is used to denote a managed object in the system. The result of retrieving a resource through the HMC API is termed a resource representation. Python classes for resources are termed to represent a resource.

For resources within a CPC, this section covers CPCs in DPM mode and classic mode, but omits any resources that are available only in ensemble mode. See section CPCs for a definition of the CPC modes.

Some of the items in this section are qualified as short terms. They are not separate types of resources, but specific usages of resources. For example, “storage adapter” is a short term for the resource “adapter” when used for attaching storage.

9.4.1. Resources scoped to the HMC¶

Console

The HMC itself.

Group

TBD - Not yet supported.

Hardware Message

TBD - Not yet supported.

Also scoped to CPCs in any mode.

Job

The execution of an asynchronous HMC operation.

LDAP Server Definition

The information in an HMC about an LDAP server that may be used for HMC user authorization purposes.

Metrics Context

A user-created definition of metrics that can be retrieved.

Password Rule

A rule which HMC users need to follow when creating a HMC logon password.

Session

A session between a client of the HMC API and the HMC.

Task

An action that an HMC user with appropriate authority can perform.

User

An HMC user.

User Pattern

A pattern for HMC user IDs that are not defined on the HMC as users but can be verified by an LDAP server for user authentication.

User Role

An authority role which can be assigned to one or more HMC users.

9.4.2. Resources scoped to CPCs in any mode¶

Capacity Record

TBD - Not yet supported.

CPC

Central Processor Complex, a physical IBM Z or LinuxONE computer.

For details, see section CPCs.

9.4.3. Resources scoped to CPCs in DPM mode¶

Accelerator Adapter

Short term for an Adapter providing accelerator functions (e.g. the z Systems Enterprise Data Compression (zEDC) adapter for data compression).

Adapter

A physical adapter card (e.g. OSA-Express adapter, Crypto adapter) or a logical adapter (e.g. HiperSockets switch).

For details, see section Adapters.

Adapter Port

Synonym for Port.

Capacity Group

TBD - Not yet supported.

Crypto Adapter

Short term for an Adapter providing cryptographic functions.

FCP Adapter

Short term for a Storage Adapter supporting FCP (Fibre Channel Protocol).

FCP Port

Short term for a Port of an FCP Adapter.

HBA

A logical entity that provides a Partition with access to external storage area networks (SANs) through an FCP Adapter.

For details, see section HBAs.

HBA resource objects only exist when the “dpm-storage-management” feature is not enabled. See section Storage Groups for details.

Network Adapter

Short term for an Adapter for attaching networks (e.g. OSA-Express adapter).

Network Port

Short term for a Port of a Network Adapter.

NIC

Network Interface Card, a logical entity that provides a Partition with access to external communication networks through a Network Adapter.

For details, see section NICs.

Partition

A subset of the hardware resources of a CPC in DPM mode, virtualized as a separate computer.

For details, see section Partitions.

Port

The physical connector port (jack) of an Adapter.

For details, see section Ports.

Storage Adapter

Short term for an Adapter for attaching storage.

Storage Group

A grouping entity for a set of FCP or ECKD (=FICON) storage volumes. A storage group can be attached to a partition which will cause its storage volumes to be attached to the partition.

Storage Group objects exist only when the “dpm-storage-management” feature is enabled on the CPC. For details, see section Storage Groups.

Storage Group Template

A template for Storage Groups.

Storage Port

Short term for a Port of a Storage Adapter.

Storage Volume

An FCP or ECKD (=FICON) storage volume defined in context of a storage group. The life cycle of a storage volume includes being defined but not fulfilled, being fulfilled but not attached, and finally being attached to a partition.

Storage Volume objects exist only when the “dpm-storage-management” feature is enabled on the CPC. For details, see section Storage Groups.

Storage Volume Template

A template for Storage Volumes.

vHBA

Synonym for HBA. In this resource model, HBAs are always virtualized because they belong to a Partition. Therefore, the terms vHBA and HBA can be used interchangeably.

Virtual Function

A logical entity that provides a Partition with access to an Accelerator Adapter.

For details, see section Virtual Functions.

Virtual Storage Resource

A representation of a storage-related z/Architecture device in a partition. For FCP type storage volumes, a Virtual Storage Resource object represents an HBA through which the attached storage volume is accessed. For FICON (ECKD) type storage volumes, a Virtual Storage Resource object represents the attached storage volume itself.

Virtual Storage Resource objects exist only when the “dpm-storage-management” feature is enabled on the CPC. For details, see section Storage Groups.

Virtual Switch

A virtualized networking switch connecting NICs with a Network Port.

For details, see section Virtual Switches.

vNIC

Synonym for NIC. In this resource model, NICs are always virtualized because they belong to a Partition. Therefore, the terms vNIC and NIC can be used interchangeably.

9.4.4. Resources scoped to CPCs in classic (and ensemble) mode¶

Activation Profile

A general term for specific types of activation profiles:

Reset Activation Profile
Image Activation Profile
Load Activation Profile

Group Profile

TBD

Image Activation Profile

A specific Activation Profile that defines characteristics of an LPAR.

Load Activation Profile

A specific Activation Profile that defines an operating system image that can be loaded (booted) into an LPAR.

Logical Partition

LPAR

A subset of the hardware resources of a CPC in classic mode (or ensemble mode), virtualized as a separate computer.

For details, see section LPARs.

Reset Activation Profile

A specific Activation Profile that defines characteristics of a CPC.

9.5. Bibliography¶

X.509: ITU-T X.509, Information technology - Open Systems Interconnection - The Directory: Public-key and attribute certificate frameworks
RFC2616: IETF RFC2616, Hypertext Transfer Protocol - HTTP/1.1, June 1999
RFC2617: IETF RFC2617, HTTP Authentication: Basic and Digest Access Authentication, June 1999
RFC3986: IETF RFC3986, Uniform Resource Identifier (URI): Generic Syntax, January 2005
RFC6874: IETF RFC6874, Representing IPv6 Zone Identifiers in Address Literals and Uniform Resource Identifiers, February 2013
HMC API: The Web Services API of the z Systems Hardware Management Console, described in the following books:
HMC API 2.11.1: IBM SC27-2616, System z Hardware Management Console Web Services API (Version 2.11.1)
HMC API 2.12.0: IBM SC27-2617, System z Hardware Management Console Web Services API (Version 2.12.0)
HMC API 2.12.1: IBM SC27-2626, System z Hardware Management Console Web Services API (Version 2.12.1)
HMC API 2.13.0: IBM SC27-2627, z Systems Hardware Management Console Web Services API (Version 2.13.0)
HMC API 2.13.1: IBM SC27-2634, z Systems Hardware Management Console Web Services API (Version 2.13.1)
HMC API 2.14.0: IBM SC27-2636, IBM Z Hardware Management Console Web Services API (Version 2.14.0)
HMC API 2.14.1: IBM SC27-2637, IBM Z Hardware Management Console Web Services API (Version 2.14.1)
HMC API 2.15.0: IBM SC27-2638, IBM Z Hardware Management Console Web Services API (Version 2.15.0) (covers both GA1 and GA2)
HMC Operations Guide: The operations guide of the z Systems Hardware Management Console, in the following books (subset):
HMC Operations Guide 2.11.1: IBM SC28-6905, System z Hardware Management Console Operations Guide (Version 2.11.1)
HMC Operations Guide 2.12.1: System z Hardware Management Console Operations Guide (Version 2.12.1)
HMC Operations Guide 2.13.1: z Systems Hardware Management Console Operations Guide (Version 2.13.1)
HMC Operations Guide 2.14.1: Hardware Management Console Operations Guide (Version 2.14.1)
HMC Operations Guide 2.15.0: Hardware Management Console Operations Guide (Version 2.15.0) (covers both GA1 and GA2)

9. Appendix¶

9.1. Base classes for resources¶

9.2. Glossary¶

9.3. Special type names¶

9.4. Resource model¶

9.4.1. Resources scoped to the HMC¶

9.4.2. Resources scoped to CPCs in any mode¶

9.4.3. Resources scoped to CPCs in DPM mode¶

9.4.4. Resources scoped to CPCs in classic (and ensemble) mode¶

9.5. Bibliography¶

9.6. Related projects¶