1/*
2 * $Id: README.pycli,v 1.3 2008/08/07 18:25:41 tyreld Exp $
3 *
4 * README.pycli
5 *
6 * (C) Copyright IBM Corp. 2002, 2008
7 *
8 * THIS FILE IS PROVIDED UNDER THE TERMS OF THE ECLIPSE PUBLIC LICENSE
9 * ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THIS FILE
10 * CONSTITUTES RECIPIENTS ACCEPTANCE OF THE AGREEMENT.
11 *
12 * You can obtain a current copy of the Eclipse Public License from
13 * http://www.opensource.org/licenses/eclipse-1.0.php
14 *
15 * Author: David Eger <dteger@us.ibm.com>, <eger@cc.gatech.edu>
16 * Contributors:
17 *
18 * Description: Python bindings for WBEMCLI
19 */
20
21
22The WBEMCLI Python Bindings
23===========================
24
25In addition to the 'wbemcli' command line tool, this package includes
26python bindings for accessing CIMOMs such as SNIA-CIMOM or OpenPegasus.
27If you do not use Python, you can safely ignore this.
28
29Files included:
30+ CimXml.py - the low-level C++/Python interface
31+ cimcli.py - some utility functions to make using CimXml easier.
32
33To compile the Python bindings, type:
34
35$ make clipy
36
37
38Using Python to talk to your CIMOMs
39===================================
40
41After this, you can run Python scripts which access CIMOMs, or use
42Python as an interactive shell for talking to CIMOMs.
43
44In Python,
45comments begin with a hash mark (#). The Python prompt is '>>>',
46or when continuing from a previous line '...'. Python code is block
47structured by white space. Further, you can continue the current line
48by putting a slash at the end of your line.
49
50Below is a sample of how you can use Python as a shell interface to
51your CIMOMs:
52
53# BEGIN SAMPLE INTERACTION
54
55$ python
56Python 2.2.3+ (#1, Jul 6 2003, 23:35:56)
57[GCC 3.3.1 20030626 (Debian prerelease)] on linux2
58Type "help", "copyright", "credits" or "license" for more information.
59>>> execfile("cimcli.py") # import utility functions
60>>> machines = getCIMOMs("192.168.64.8","24","PING")
61Portscanning port 5988 on subnet 192.168.64.8/24 for prospective CIMOMs
62IPs found: ['192.168.64.8', '192.168.64.207']
63>>> setmachine("192.168.64.207", locals()) #
64>>> # tell the CLI which machine we want to talk to
65>>> FSs = ei("CIM_FileSystem") #
66>>> # get a list of the filesystems on the box
67>>> len(FSs) # how many did we get?
684
69>>> for i in FSs.ia: # for each filesystem instance... (ia = instance array)
70... print i
71...
72CreationClassName="Linux_Ext3FileSystem",Caption="Ext3 local file system",CSCreationClassName="Linux_ComputerSystem",CSName="dyn324513pok.pok.ibm.com",Name="/dev/sda1",Root="/boot",FileSystemType="ext3",Status="OK",Description="Represents the file store controlled by a ComputerSystem through local means.",ReadOnly=FALSE,BlockSize=1024,FileSystemSize=103515136,AvailableSpace=82735104,MaxFileNameLength=255,PercentageSpaceUse=14,ElementName="/boot",EnabledStatus=2,OtherEnabledStatus="NULL",RequestedStatus=2,EnabledDefault=3
73CreationClassName="Linux_Ext3FileSystem",Caption="Ext3 local file system",CSCreationClassName="Linux_ComputerSystem",CSName="dyn324513pok.pok.ibm.com",Name="/dev/sda2",Root="/home",FileSystemType="ext3",Status="OK",Description="Represents the file store controlled by a ComputerSystem through local means.",ReadOnly=FALSE,BlockSize=4096,FileSystemSize=7270162432,AvailableSpace=6450884608,MaxFileNameLength=255,PercentageSpaceUse=6,ElementName="/home",EnabledStatus=2,OtherEnabledStatus="NULL",RequestedStatus=2,EnabledDefault=3
74CreationClassName="Linux_Ext3FileSystem",Caption="Ext3 local file system",CSCreationClassName="Linux_ComputerSystem",CSName="dyn324513pok.pok.ibm.com",Name="/dev/sdb1",Root="/usr",FileSystemType="ext3",Status="OK",Description="Represents the file store controlled by a ComputerSystem through local means.",ReadOnly=FALSE,BlockSize=4096,FileSystemSize=8427929600,AvailableSpace=6655352832,MaxFileNameLength=255,PercentageSpaceUse=15,ElementName="/usr",EnabledStatus=2,OtherEnabledStatus="NULL",RequestedStatus=2,EnabledDefault=3
75CreationClassName="Linux_Ext3FileSystem",Caption="Ext3 local file system",CSCreationClassName="Linux_ComputerSystem",CSName="dyn324513pok.pok.ibm.com",Name="/dev/sda5",Root="/var",FileSystemType="ext3",Status="OK",Description="Represents the file store controlled by a ComputerSystem through local means.",ReadOnly=FALSE,BlockSize=4096,FileSystemSize=1052434432,AvailableSpace=949731328,MaxFileNameLength=255,PercentageSpaceUse=4,ElementName="/var",EnabledStatus=2,OtherEnabledStatus="NULL",RequestedStatus=2,EnabledDefault=3
76>>> for i in FSs.ia: # that was too much information, let's do it different now.
77... fsprops = i.getProperties()
78... print "Filesystem on %s is %d%% full" % \
79... (fsprops["ElementName"], \
80... 100 - 100 * long(fsprops["AvailableSpace"]) / long(fsprops["FileSystemSize"]))
81...
82Filesystem on /boot is 21% full
83Filesystem on /home is 12% full
84Filesystem on /usr is 22% full
85Filesystem on /var is 10% full
86>>>
87
88# END SAMPLE INTERACTION
89
90
91How it works
92============
93By using the Python Client, you're getting direct access to the
94C++ objects described by CimXml.h. If, instead of saying "print" above,
95we had just typed the name of an object, our interaction would look like
96this:
97
98>>> execfile("cimcli.py")
99>>> setmachine("localhost",locals())
100>>> FSs = ei("CIM_FileSystem")
101>>> FSs
102<C NamedInstancesXml instance at _1015b4b0_p_NamedInstancesXml>
103
104This is the raw C++ object (actually, a raw pointer to a C++ object) of type
105NamedInstancesXml. If you look in CimXml.h, you'll see a description like:
106
107/* from CimXml.h */
108
109class NamedInstancesXml : public RetValXml {
110 public:
111 InstanceArray ia;
112 InstanceNameArray ina;
113 NamedInstancesXml(NamedInstanceXml *n);
114 NamedInstancesXml * clone() { return new NamedInstancesXml(*this);}
115 void add(NamedInstanceXml& n);
116 InstanceNameXml& getName(int n) { return ina.at(n); }
117 InstanceXml& getInst(int n) { return ia.at(n); }
118 int size() { return ina.size(); }
119};
120
121Python doesn't need to know all of these details, just some. We
122use a program called SWIG to automatically generate wrapper code so
123our Python code can talk to our C++ code. We tell SWIG what wrappers
124to generate with a SWIG interface file called "CimXml.i". In that file,
125we find the description:
126
127/* from CimXml.i */
128
129extern
130class NamedInstancesXml : public RetValXml {
131 public:
132 InstanceArray ia;
133 InstanceNameArray ina;
134 NamedInstancesXml(NamedInstanceXml *n);
135 void add(NamedInstanceXml& n);
136 InstanceNameXml& getName(int n);
137 InstanceXml& getInst(int n);
138%rename(__len__) size;
139 int size();
140};
141
142We've included the output of SWIG - CimXml.py and CimXml_wrap.cxx, so
143unless you change the interface file, you don't need to have SWIG.
144
145For each piece of code in the interface file, SWIG makes the glue so
146that handling objects and calling member functions between one OO language
147and another "just works." If your object has a method called add(), and you
148tell SWIG this, then you can call object.add() from your Python code just
149as you would from C++. Sometimes, however, you need to give SWIG some hints.
150Calling len() on a Python array is a natural way to get the array's length.
151Since our C++ code has a different name for this, we use the SWIG directive
152%rename().
153