{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Pull Operations Description Notebook" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "<--- Back" ] }, { "cell_type": "markdown", "metadata": { "collapsed": true }, "source": [ "## Table of Contents for this Notebook\n", "\n", "- [Pull Operations Description Notebook](#Pull-Operations-Description-Notebook)\n", "- [Table of Contents for this Notebook](#Table-of-Contents-for-this-Notebook)\n", "- [Pull Operation Concepts](#Pull-Operation-Concepts)\n", "- [Pull Enumerate Instances](#Pull-Enumerate-Instances-Enumeration-Sequence)\n", "- [Pull Enumerate Paths](#Pull-Enumerate-Paths-Enumeration-Sequence)\n", "- [Pull Associator Instances](#Pull-Associator-Instances-Enumeration-Sequence)\n", "- [Pull Associator Paths](#Pull-Associator-Paths-Enumeration-Sequence)\n", "- [Pull Reference Instances](#Pull-Reference-Instances-Enumeration-Sequence)\n", "- [Pull Reference Paths](#Pull-Reference-Paths-Enumeration-Sequence)\n", "- [Pull Query Instances](#Pull-Query-Instances-Enumeration-Sequence)\n", "- [CloseEnumeration Request](#CloseEnumeration-Request-Enumeration-Sequence)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Pull Operation Concepts" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The DMTF CIM/XML Pull operations allow a WBEM client to break the monolithic instance operations for requests that deliver multiple objects (ex. EnumerateInstances) into multiple requests/responses executed as a sequence of requests to limit the size of individual responses.\n", "\n", "The purpose and function and usage of these WBEM operations is defined on the \n", "[pull operations concepts page](https://pywbem.readthedocs.io/en/latest/concepts.html#pull-operations) in the pywbem documentation\n", "\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Pull Enumerate Instances Enumeration Sequence" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The Pull Enumerate Instances request operation sequence differs from the [`EnumerateInstances()`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.WBEMConnection.EnumerateInstances) request in that it consists of multiple of operations, an [`OpenEnumerateInstances()`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.WBEMConnection.OpenEnumerateInstances) operation and corresponding [`PullInstancesWithPath()`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.WBEMConnection.PullInstancesWithPath) operations. The [`OpenEnumerateInstances()`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.WBEMConnection.OpenEnumerateInstances) opens an enumeration sequence and optionally acquires instances from the server determined by the `MaxObjectCount` parameter. It returns a named tuple that defines the sequence, marks, the end of the sequence, and includes instances retrieved by the [`OpenEnumerateInstances()`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.WBEMConnection.OpenEnumerateInstances) operation.\n", "\n", "Subsequent [`PullEnumerateInstancesWithPath()`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.WBEMConnection.PullInstancesWithPath) operations retrieve more instances as defined by the `MaxObjectCount` parameter of the call until the end-of-sequence flag (result.eos) is received.\n", "\n", "The [`OpenEnumerateInstances()`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.WBEMConnection.OpenEnumerateInstances) method returns a Python named tuple with the components as defined in the concepts documentation:\n", "\n", "* `eos` - End-Of-Sequence Boolean flag indicating whether the server has more to instances/paths to deliver.\n", "* `context` - Opaque string that provides context between open, pull and close operations within a single enumeration sequence.\n", "* `instances` - A list of [`pywbem.CIMInstance`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.CIMInstance) objects for each CIM instance of a particular CIM class (and its subclasses). The CIM instance path is part of the returned instance objects and can be accessed via their `path` attribute returned for this request operation. The instances may be a partial or complete response depending on the result.eos flag.\n", "\n", "The [`PullEnumerateInstancesWithPath()`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.WBEMConnection.PullInstancesWithPath) method returns a named tuple containing the same named elements as the [`OpenEnumerateInstances()`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.WBEMConnection.OpenEnumerateInstances) above (eos, context, instances). Note that while the MaxObjectCount parameter is an option with the open request (the default is zero) it is a required parameter with the pull request.\n", "\n", "The following code enumerates the instances of the specified CIM class with an open and subsequent pull requests and prints their instance paths in WBEM URI format (see [`pywbem.CIMInstanceName.__str__()`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.CIMInstanceName.__str__)), and the instance itself in MOF format (see [`pywbem.CIMInstance.tomof()`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.CIMInstance.tomof)) when all have been retrieved.\n", "\n", "The example sets the maximum number of instances that will be retrieved for each request including the open (MaxObjectCount) at 100. Each response may return 100 or fewer instances.\n", "\n", "In this code, the received results are accumulated into the `insts` list. They could also be processed directly after each response is received. The only caution is that if they are processed immediatly, the client must understand that the response sequence could end early and incomplete if an exception is received and the client must account for this incomplete response in its processing.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": true }, "outputs": [], "source": [ "import pywbem\n", "\n", "# Global variables used by all examples:\n", "server = 'http://localhost'\n", "username = 'user'\n", "password = 'password'\n", "namespace = 'root/cimv2'\n", "\n", "classname = 'PyWBEM_Person'\n", "max_obj_cnt = 100\n", "\n", "conn = pywbem.WBEMConnection(server, (username, password),\n", " default_namespace=namespace,\n", " no_verification=True)\n", "\n", "try:\n", " result = conn.OpenEnumerateInstances(classname,\n", " MaxObjectCount=max_obj_cnt)\n", " insts = result.instances\n", " while not result.eos:\n", " result = conn.PullInstancesWithPath(result.context, max_obj_cnt)\n", " insts.extend(result.instances)\n", "except pywbem.Error as exc:\n", " print('Operation failed: %s' % exc)\n", "else:\n", " print('Retrieved %s instances' % (len(insts)))\n", " for inst in insts:\n", " print('path=%s' % inst.path)\n", " print(inst.tomof())" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "In this example, the connection has a default namespace set. This allows us to omit the namespace from the subsequent [`OpenEnumerateInstances()`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.WBEMConnection.OpenEnumerateInstances) method.\n", "\n", "This example also shows exception handling with pywbem: Pywbem wraps any exceptions that are considered runtime errors, and raises them as subclasses of [`pywbem.Error`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.Error). Any other exceptions are considered programming errors. Therefore, the code above only needs to catch [`pywbem.Error`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.Error).\n", "\n", "Note that the creation of the [`pywbem.WBEMConnection`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.WBEMConnection) object in the code above does not need to be protected by exception handling; its initialization code does not raise any pywbem runtime errors.\n" ] }, { "cell_type": "markdown", "metadata": { "collapsed": true }, "source": [ "## Pull Enumerate Paths Enumeration Sequence" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The Pull Enumerate Paths operation parallels the Pull Enumerate Instances sequence except that it returns instance paths instead of instances.\n", "\n", "The Pull Enumerate Paths request operation sequence differs from the [`EnumerateInstanceNames()`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.WBEMConnection.EnumerateInstanceNames) request in that its consists of multiple of operations, an [`OpenEnumerateInstancePaths()`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.WBEMConnection.OpenEnumerateInstancePaths) operation and corresponding [`PullEnumerateInstancesPaths()`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.WBEMConnection.PullInstancePaths) operations. The [`OpenEnumerateInstances()`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.WBEMConnection.EnumerateInstances) opens an enumeration sequence and optionally acquires instance paths from the server determined by the `MaxObjectCount` parameter. It returns a named tuple that defines the sequence, marks, the end of the sequence, and includes instance paths retrieved by the [`OpenEnumerateInstancePaths()`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.WBEMConnection.OpenEnumerateInstancePaths) operation.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": true }, "outputs": [], "source": [ "# Global variables from first example are used\n", "\n", "max_obj_cnt = 100\n", "\n", "conn = pywbem.WBEMConnection(server, (username, password),\n", " default_namespace=namespace,\n", " no_verification=True)\n", "\n", "try:\n", " result = conn.OpenEnumerateInstancePaths(classname,\n", " MaxObjectCount=max_obj_cnt)\n", " paths = result.paths\n", " while not result.eos:\n", " result = conn.PullInstancesPaths(result.context, max_obj_cnt)\n", " insts.extend(result.paths)\n", "except pywbem.Error as exc:\n", " print('Operation failed: %s' % exc)\n", "else:\n", " print('Retrieved %s instances' % (len(paths)))\n", " for path in paths:\n", " print('path=%s' % path)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Pull Associator Instances Enumeration Sequence" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The Pull Associator Instances sequence is opened with an\n", "[`OpenAssociatorInstances()`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.WBEMConnection.OpenAssociatorInstances)\n", "operation and corresponding [`PullInstancesWithPath()`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.WBEMConnection.PullInstancesWithPath)\n", "\n", "The example below first gets instance names from a class that is part of an association and then uses one of those\n", "instances to execute the OpenAssociatorInstances operation. Normally the code should always include the full pattern of\n", "the Open followed by the Pull loop because the client cannot be certain how many objects will be returned in the\n", "response to the open request (the specification only requires that no more than MaxObjectCount be returned). In fact,\n", "some WBEM server implementations recommend that the client delay slightly between a response and subsequent pull to insure\n", "the server has more objects prepared to send.\n", "\n", "The extra print statements in the example below record the the responses received." ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": true }, "outputs": [], "source": [ "# Global variables from first example are used\n", "\n", "max_obj_cnt = 100\n", "\n", "conn = pywbem.WBEMConnection(server, (username, password),\n", " default_namespace=namespace,\n", " no_verification=True)\n", "\n", "try:\n", " # Find an instance path for the source end of an association.\n", " source_paths = conn.EnumerateInstanceNames(classname)\n", " if source_paths:\n", " result = conn.OpenAssociatorInstances(source_paths[0],\n", " MaxObjectCount=max_obj_cnt)\n", " insts = result.instances\n", " while not result.eos:\n", " result = conn.PullInstancesWithPath(result.context, max_obj_cnt)\n", " insts.extend(result.instances)\n", " else:\n", " print('%s class has no instances and therefore no associations' %\n", " classname)\n", "except pywbem.Error as exc:\n", " print('Operation failed: %s' % exc)\n", "else:\n", " print('Retrieved %s instance(s)' % (len(insts)))\n", " for inst in insts:\n", " print('path=%s' % inst.path)\n", " print(inst.tomof())" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Pull Associator Paths Enumeration Sequence" ] }, { "cell_type": "markdown", "metadata": { "collapsed": true }, "source": [ "The Pull Associator Paths sequence is opened with an\n", "[`OpenAssociatorInstancePaths()`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.WBEMConnection.OpenAssociatorInstancePaths)\n", "operation and corresponding [`PullInstancesPaths()`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.WBEMConnection.PullInstancesPath)\n", "\n", "The example below first gets instance names from a class that is part of an association and then uses one of those\n", "instances to execute the OpenReferenceInstances operation. Normally the code should always include the full pattern of\n", "the Open followed by the Pull loop because the client cannot be certain how many objects will be returned in the\n", "response to the open request (the specification only requires that no more than MaxObjectCount be returned). In fact,\n", "some WBEM server implementations recommend that the client delay slightly between a response and subsequent pull to insure the server has more objects prepared to send.\n", "\n", "The extra print statements in the example below record the the responses received." ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": true }, "outputs": [], "source": [ "# Global variables from first example are used\n", "\n", "max_obj_cnt = 100\n", "\n", "conn = pywbem.WBEMConnection(server, (username, password),\n", " default_namespace=namespace,\n", " no_verification=True)\n", "\n", "try:\n", " # Find an instance path for the source end of an association.\n", " source_paths = conn.EnumerateInstanceNames(classname)\n", " if source_paths:\n", " result = conn.OpenAssociatorInstancePaths(source_paths[0],\n", " MaxObjectCount=max_obj_cnt)\n", " paths = result.paths\n", " while not result.eos:\n", " result = conn.PullInstancePaths(result.context, max_obj_cnt)\n", " insts.extend(result.paths)\n", " else:\n", " print('%s class has no paths and therefore no associations' %\n", " classname)\n", "except pywbem.Error as exc:\n", " print('Operation failed: %s' % exc)\n", "else:\n", " print('Retrieved %s paths' % (len(paths)))\n", " for path in paths:\n", " print('path=%s' % path)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Pull Reference Instances Enumeration Sequence" ] }, { "cell_type": "markdown", "metadata": { "collapsed": true }, "source": [ "The Pull ReferenceInstances sequence is opened with an\n", "[`OpenReferenceInstances()`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.WBEMConnection.OpenreferenceInstances)\n", "operation and corresponding [`PullInstancesWithPath()`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.WBEMConnection.PullInstancesWithPath)\n", "\n", "The example below first gets instance names from a class that is part of an association and then uses one of those\n", "instances to execute the OpenReferenceInstances operation. Normally the code should always include the full pattern of\n", "the Open followed by the Pull loop because the client cannot be certain how many objects will be returned in the\n", "response to the open request (the specification only requires that no more than MaxObjectCount be returned). In fact,\n", "some WBEM server implementations recommend that the client delay slightly between a response and subsequent pull to insure\n", "the server has more objects prepared to send.\n", "\n", "The extra print statements in the example below record the the responses received." ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": true }, "outputs": [], "source": [ "# Global variables from first example are used\n", "\n", "max_obj_cnt = 100\n", "\n", "conn = pywbem.WBEMConnection(server, (username, password),\n", " default_namespace=namespace,\n", " no_verification=True)\n", "\n", "try:\n", " # Find an instance path for the source end of an association.\n", " source_paths = conn.EnumerateInstanceNames(classname)\n", " if source_paths:\n", " result = conn.OpenReferenceInstances(source_paths[0],\n", " MaxObjectCount=max_obj_cnt)\n", " insts = result.instances\n", " while not result.eos:\n", " result = conn.PullInstancesWithPath(result.context, max_obj_cnt)\n", " insts.extend(result.instances)\n", " else:\n", " print('%s class has no instances and therefore no associations' %\n", " classname)\n", "except pywbem.Error as exc:\n", " print('Operation failed: %s' % exc)\n", "else:\n", " print('Retrieved %s instances\\n' % (len(insts)))\n", " for inst in insts:\n", " print('path=%s\\n' % inst.path)\n", " print(inst.tomof())" ] }, { "cell_type": "markdown", "metadata": { "collapsed": true }, "source": [ "## Pull Reference Paths Enumeration Sequence" ] }, { "cell_type": "markdown", "metadata": { "collapsed": true }, "source": [ "The Pull Reference Paths sequence is opened with an\n", "[`OpenReferenceInstancePaths()`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.WBEMConnection.OpenreferenceInstancePaths)\n", "operation and corresponding [`PullInstancesPaths()`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.WBEMConnection.PullInstancesPath)\n", "\n", "The example below first gets instance names from a class that is part of an association and then uses one of those\n", "instances to execute the OpenReferenceInstances operation. Normally the code should always include the full pattern of\n", "the Open followed by the Pull loop because the client cannot be certain how many objects will be returned in the\n", "response to the open request (the specification only requires that no more than MaxObjectCount be returned). In fact,\n", "some WBEM server implementations recommend that the client delay slightly between a response and subsequent pull to insure\n", "the server has more objects prepared to send.\n", "\n", "The extra print statements in the example below record the the responses received.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": true }, "outputs": [], "source": [ "# Global variables from first example are used\n", "\n", "max_open_cnt = 0 # no instance paths returned on open\n", "max_pull_cnt = 1 # zero or one instance path returned for each pull\n", "\n", "conn = pywbem.WBEMConnection(server, (username, password),\n", " default_namespace=namespace,\n", " no_verification=True)\n", "\n", "try:\n", " # Find an instance path for the source end of an association.\n", " source_paths = conn.EnumerateInstanceNames(classname)\n", " if source_paths:\n", " result = conn.OpenReferenceInstancePaths(source_paths[0],\n", " MaxObjectCount=max_open_cnt)\n", " paths = result.paths\n", " print('Open eos=%s, context=%s, path count %s' %\n", " (result.eos, result.context, len(result.paths)))\n", " while not result.eos:\n", " result = conn.PullInstancePaths(result.context, max_pull_cnt)\n", " print('Pull eos=%s, context=%s, path count %s' %\n", " (result.eos, result.context, len(result.paths)))\n", " paths.extend(result.paths)\n", " else:\n", " print('%s class has no paths and therefore no associations', classname)\n", "except pywbem.Error as exc:\n", " print('Operation failed: %s' % exc)\n", "else:\n", " print('Retrieved %s paths' % (len(paths)))\n", " for path in paths:\n", " print('path=%s' % path)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Pull Query Instances Enumeration Sequence" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": true }, "outputs": [], "source": [ "The Pull Query Instances sequence is a parallel to the traditional ExecQuery operation. It requests that the\n", "server execute a query defined by the query parameter and the query language parameters. These are NOT the same query\n", "and query language as the other pull operations. The query language is normally WQL or the DMTF CQL.\n", "\n", "The [`OpenQueryInstances()`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.WBEMConnection.OpenQueryInstances)\n", "defines the query language and query required parameters.\n", "\n", "This enumeration sequence uses the [`PullInstances()`](https://pywbem.readthedocs.io/en/latest/client.html#pywbem.WBEMConnection.PullInstances)\n", "operation because the query function returns instances without paths.\n", "\n", "The following example execute a query on the class Pywbem_Person with no where clause. This should return all \n", "instances of this class and its subclasses.\n", " \n", "The maximum instances that can be returned from each request is 10 (see max_object_cnt) although this is\n", "lower that normally recommended for MaxObjectCnt.\n", " " ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": true }, "outputs": [], "source": [ "# Global variables from first example are used\n", "\n", "classname = 'Pywbem_Person'\n", "max_object_cnt = 10\n", "\n", "query_language = \"DMTF:CQL\"\n", "query = 'Select * from Pywbem_Person'\n", "\n", "conn = pywbem.WBEMConnection(server, (username, password),\n", " default_namespace=namespace,\n", " no_verification=True)\n", "\n", "try:\n", " result = conn.OpenQueryInstances(query_language, query,\n", " MaxObjectCount=max_object_cnt)\n", " insts = result.instances\n", " while not result.eos:\n", " result = conn.PullInstances(result.context, max_object_cnt)\n", " insts.extend(result.instances)\n", "except pywbem.Error as exc:\n", " print('Operation failed: %s' % exc)" ] }, { "cell_type": "markdown", "metadata": { "collapsed": true }, "source": [ "## CloseEnumeration Request" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The following is an example of using the CloseEnumeration request to terminate an enumeration sequence before it has completed. It requests zero responses from the open and terminates before the first pull. In this example, since the MaxObjectCount for the open is zero, no instances should be processed before the close is issued.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": true }, "outputs": [], "source": [ "# Global variables from first example are used\n", "\n", "classname = 'CIM_ComputerSystem'\n", "\n", "conn = pywbem.WBEMConnection(server, (username, password),\n", " default_namespace=namespace,\n", " no_verification=True)\n", "\n", "try:\n", " result = conn.OpenEnumerateInstances(classname, MaxObjectCount=0)\n", " if result.eos:\n", " result = conn.CloseEnumeration(result.context)\n", " print('instance count = %s' % len(result.instances))\n", "except pywbem.Error as exc:\n", " print('Operation failed: %s' % exc)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "<--- Back" ] } ], "metadata": { "kernelspec": { "display_name": "Python 2", "language": "python", "name": "python2" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 2 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython2", "version": "2.7.6" } }, "nbformat": 4, "nbformat_minor": 1 }