[cura-tools] master: update man page (8bdffb8)
by phatina@fedoraproject.org
Repository : http://git.fedorahosted.org/cgit/cura-tools.git
On branch : master
>---------------------------------------------------------------
commit 8bdffb88f6ca169fbe3cdc401b0ed31fa7ffa82e
Author: Peter Hatina <phatina(a)redhat.com>
Date: Tue Jul 30 18:22:53 2013 +0200
update man page
>---------------------------------------------------------------
man/lmishell.1 | 120 ++++++++++++++++++++++++++++++++++---------------------
1 files changed, 74 insertions(+), 46 deletions(-)
diff --git a/man/lmishell.1 b/man/lmishell.1
index edc5495..c0b4eb5 100644
--- a/man/lmishell.1
+++ b/man/lmishell.1
@@ -108,6 +108,7 @@ of the classes, run this:
> c.root.cimv2.print_classes()
...
> classes_lst = c.root.cimv2.classes()
+ >
.SH CLASSES
Each class in LMIShell represents a class provided by a CIMOM. You can get a
list of its properties, methods, instances, instance names and ValueMap
@@ -116,24 +117,22 @@ instance or new instance name.
.SS GET A CLASS OBJECT
To get a class which is provided by a broker, you can do following:
- > lmi_service_class = c.root.cimv2.LMI_Service
+ > cls = c.root.cimv2.ClassName
>
.SS METHODS
A class object can return a list of its methods, properties and valuemap
properties. Following example covers methods' retrieval:
- > lmi_service_class = c.root.cimv2.LMI_Service
- > lmi_service_class.print_methods()
+ > cls.print_methods()
...
- > lmi_service_class_methods = lmi_service_class.methods()
+ > cls_method_lst = cls.methods()
>
.SS PROPERTIES
To get a list of properties of a specific object, run following code:
- > lmi_service_class = c.root.cimv2.LMI_Service
- > lmi_service_class.print_properties()
+ > cls.print_properties()
...
- > service_properties_lst = lmi_service_class.properties()
+ > cls_property_lst = cls.properties()
>
.SS VALUEMAP PROPERTIES
A CIM class may contain ValueMap properties (aliases for constant values) in
@@ -141,25 +140,26 @@ its MOF definition. These properties contain constant values, which can be
useful, when calling a method, or checking a returned value. To work with the
ValueMap properties, see following code:
- > c.root.cimv2.CIM_ConcreteJob.print_valuemap_properties()
+ > cls.print_valuemap_properties()
...
- > lmi_valuemap_properties = c.root.cimv2.CIM_ConcreteJob.valuemap_properties()
+ > valuemap_properties = cls.valuemap_properties()
>
.SS GET VALUEMAP PROPERTY VALUE
By using a ValueMap properties, you can retrieve a constant value defined in
the MOF file. To get a list of all available constants, their values, use the
following code:
- > cim_concrete_job = c.root.cimv2.CIM_ConcreteJob
- > cim_concrete_job.JobStateValues.print_values()
+ > cls.PropertyValues.print_values()
...
>
+\fBNOTE:\fR The suffix "`Values`" privides a way, hot to access ValueMap properties.
+
To retrieve a constant value, see the next example:
- > constant_value_names_lst = cim_concrete_job.values()
- > cim_concrete_job.JobStateValues.Completed
- 7
+ > constant_value_names_lst = cls.PropertyValues.values()
+ > cls.PropertyValues.ConstantValueName
+ ConstantValue
>
.SS GET INSTANCES
Using a class object, you can access its instances. You can easily get a list
@@ -168,48 +168,48 @@ input dictionary, if present, where the dictionary keys represent the instance
properties and the dictionary values represent your desired instance property
values. See following example:
- > inst = c.root.cimv2.LMI_Service.first_instance()
- > inst_lst = c.root.cimv2.LMI_Service.instances()
+ > inst = cls.first_instance()
+ > inst_lst = cls.instances()
>
.SS GET INSTANCE NAMES
The CIMInstanceName objects clearly identify CIMInstance objects. The shell
can retrieve wrapped CIMInstanceNames objects, by calling following:
- > inst_name = c.root.cimv2.LMI_Service.first_instance_name()
- > inst_names_lst = c.root.cimv2.LMI_Service.instance_names()
+ > inst_name = cls.first_instance_name()
+ > inst_names_lst = cls.instance_names()
>
.SS FILTERING
Both methods `.instances()` or `.instance_names()` can filter returned objects
by their keys/values. The filtering is achieved by passing a dictionary of
`{property : value`} to the corresponding method. See following example:
- > inst_lst = c.root.cimv2.LMI_Service.instances({"Name" : "sshd.service"})
- > inst_names_lst = c.root.cimv2.LMI_Service.instance_names({"Name" : "sshd.service"})
+ > inst_lst = cls.instances({"FilterProperty" : "FilterValue"})
+ > inst_names_lst = cls.instance_names({"FilterProperty" : "FilterValue"})
>
.SS NEW INSTANCE NAME
LMIShell is able to create a new wrapped CIMInstanceName, if you know all the
primary keys of a remote object. This instance name object can be then used to
retrieve the whole instance object. See the next example:
- > inst_name = c.root.cimv2.LMI_SoftwareIdentity({InstanceID : "LMI:LMI_SoftwareIdentity:sblim-sfcb-0:1.3.16-3.fc19.x86_64"})
+ > inst_name = cls({Property1 : Value1, Property2 : Value2, ...})
> inst = inst_name.to_instance()
>
.SS CLASS NAME
Every class object can return a string of the CIM class, see following:
- > c.root.cimv2.LMI_Service.classname
- LMI_Service
+ > cls.classname
+ ClassName
.SS NAMESPACE
Every class belongs to certain namespace, to get a string containing the
corresponding namespace for each class, run following:
- > c.root.cimv2.LMI_Service.namespace
- root/cimv2
+ > cls.namespace
+ NamespaceOfClassName
>
.SS DOCUMENTATION
To see a class documentation (based on MOF definitions), run:
- > c.root.cimv2.LMI_Service.doc()
+ > cls.doc()
... pretty verbose output displayed in a pages (can be modified by setting environment variable PAGER) ...
>
.SS CREATE A NEW INSTANCE
@@ -217,19 +217,16 @@ LMIShell is able to create an object of specific class, if the provider
support this operation. The next example shows, how to add a specific user
account to the desired group.
- > group = c.root.cimv2.LMI_Group.first_instance({"Name" : "groupname"})
- > identity = c.root.cimv2.LMI_Identity.first_instance({"ElementName" : "user"})
- > member_of_group_class = c.root.cimv2.LMI_MemberOfGroup
- > # add user to the group
- > member_of_group_class.create_instance({"Collection" : group, "Member" : identity})
+ > cls.create_instance({"Property1" : Value1, "Property2" : Value2})
>
+
+\fBNOTE:\fR `Value` can be a LMIInstance object, as well. LMIShell will auto-cast such object.
.SS FETCHING A CIMCLASS
Objects of LMIClass use lazy fetching method of CIMClass, because some methods
do not need the CIMClass object. To manually fetch the CIMClass object, call
following:
- > service_class = c.root.cimv2.LMI_Service
- > service_class.fetch()
+ > cls.fetch()
>
The methods, which need the CIMClass object to be fetched from CIMOM, do this
@@ -242,16 +239,14 @@ object to CIMOM or delete a single instance from the CIMOM.
.SS METHODS
To get a list of methods, run following:
- > sshd = c.root.cimv2.LMI_Service.first_instance({"Name" : "sshd.service"})
- > sshd.print_methods()
+ > instance.print_methods()
...
- > sshd_methods = sshd.methods()
+ > method_lst = sshd.methods()
>
To execute a method within an object, run this:
- > sshd = c.root.cimv2.LMI_Service.first_instance({"Name" : "sshd.service"})
- > sshd.RestartService()
+ > instance.Method(Param1=value1, Param2=value2, ...)
https://host: ok (0)
>
@@ -259,20 +254,53 @@ See the result string after a method was executed. This kind of "display
sugar" is used only in the interactive mode. It displays a hostname, on which
the object method was executed and its return value "ok" or "fail" (it also
includes a return value in the parenthesis).
+
+To get the result from a method call, see following:
+
+ > (rval, rparams, errorstr) = instance.Method(Param1=value1, Param2=value2, ...)
+ >
+
+The tuple in the previous example will contain retun value of the method call
+(`rval`), returned parameters (`rparams`) and possible error string
+(`errorstr`).
+
+The LMIShell can perform synchronous method call, which means, that the
+LMIShell is able to synchronously wait for a Job object to change its state to
+"finished" state and then return the job's return parameters. LMIShell can
+perform the synchrous method call, if the given method returns a object of
+following classes:
+
+ * `LMI_StorageJob`
+ * `LMI_SoftwareInstallationJob`
+ * `LMI_NetworkJob`
+
+LMIShell first tries to use indications as the waiting method, but if it
+fails, then it uses polling method instead.
+
+Following example illustrates, how to perform a synchronous method call:
+
+ > (rval, rparams, errorstr) = instance.SyncMethod(Param1=value1, Param2=value2, ...)
+ ...
+ >
+
+\fBNOTE:\fR See the prefix `Sync` in front of a `Method` name.
+
+When a synchronous method call is done:
+
+ * `rval` will contain the job's return value
+ * `rparams` will contain the job's return parameters
.SS PROPERTIES
You can also access an instance object properties. To get a property, see the
following example.
- > root_account = c.root.cimv2.LMI_Account.first_instance()
- > root_account.LoginShell
- /bin/bash
+ > instance.Property
+ PropertyValue
>
To modify a property, execute following:
- > root_account = c.root.cimv2.LMI_Account.first_instance()
- > root_account.LoginShell = "/usr/bin/zsh"
- > root_account.push()
+ > instance.Property = NewPropertyValue
+ > instance.push()
https://host: ok (0)
>
@@ -301,8 +329,8 @@ To get a string of the namespace name, run following:
To retrieve a unique identification object for an instance, CIMNamespaceName,
execute following:
- > sshd_instance.path
- root/cimv2:LMI_Service.CreationClassName="LMI_Service",SystemName="localhost.localdomain",Name="sshd",SystemCreationClassName="Linux_ComputerSystem"
+ > instance.path
+ namespace:ClassName.CreationClassName="CreationClassName",SystemName="SystemName",Name="InstanceName",SystemCreationClassName="SystemCreationClassName"
>
.SS DOCUMENTATION
For an instance object, you can also use a documentation method, which will