AUTHORS: Karl Schopmeyer
Last Update 2/8/2002 5:03 AM
Revision Status: Draft – Thinking through the issues.
File: DefinitionofCommandLineClient.htm
|
Revision |
Date |
Author(s) |
Reason |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
We have long discussed a number of client tools including clients that would support scripting including clients in TCL, command-line functions, etc. In general, the concept was to design an equivalent to the existing Pegasus client API so that command like getclass, enumerateclass, etc. would be the primitives of this new interface.
The command line has both appeal and problems in the support of these interfaces. The positive is that it provides tools that will support direct access to CIM functionality from scripts, console programs, etc. The negative is that it is not easy to support real CIM based programming and CIM objects with a commandline set of tools. For example, it is not easy to support manipulation of a cim instance or cim class with command line concepts and tools.
However, this can be a useful set of tools so we propose as a background task to start to produce them.
I propose that we produce the CL CIM Operation tools as a set of independent executables, one for each command with a common support library. Thus there would be a separate executable for each CIM Operation defined (getclass, deleteclass, etc.). The common functions for support of the programming would be defined in a common DLL available to all of these tools and possibly in the future to other tools and applications.
Note that the alternative is to produce this as a single executable where one of the parameters is the CIM Operation to be executed but since this is a background task hopfully to be done by a number of people, the separate executables is a more modular approach.
We have already defined a directory called clitestclients under \src\clients and will have a directory for each command and for the common utility module under this structure.
Each executable will process a single CIM Operation taking input information from a combination of command line parameters, environment variables and possibly a config file, and producing one of several possible types of output (Ascii text as lists and either XML or MOF as the form for object representations).
Thus, for example, the enumrateclassnames function has exactly the same set of definitions as the CIM operation as input:
· Namespace
· Classname
· Deepinheritance (true or false)
It is expected that, at least for this first version, each command would make its connection, execute and disconnect from the server.
I see two usage models here:
A lot of the rules and tools for programming these functions will be developed off of the first couple we do. However here is a starting point.
1. Common tool for input parameter analysis so that the decision process is common to all of the functions and done only once. Initially, I was looking at using the tools existing in the CIMSever (the original options manager) but we may want to modify that for ourselves. Note that this code is no longer used by CIMServer but it is still used by a lot of the client things so we would be free to move it, extend it, etc.
2. Want to keep each one of these things simple and largely do one function.
3. Input and output ascii generally with structure applied through mechanisms for lists, MOF, XML, etc.
This is probably the characteristic that is going to make or break this whole thing and which we need to put some thought before we jump into programming.
The goals for this are:
· Completeness to specify everything we want.
· Easy programming support since we are doing 30 different definitions.
· Easy of entry for the console operator since we do not want something where the operator has to enter 30 lines of text to put in a single command.
It seems that we want more than simply putting all the parameters on the command line for each command. Therefore we need for parameters to be objtained from a hierarchy of sources as follows:
· Highest priority is the command line. Any input parameter on the command line overrides the equivalent defintion in either an environment variable or a config file.
· Second priority is probably environment variables
· Third priority would be a config file
Therefore, I suggest that we work toward the following:
· Some parameters required and defined by position and some optional and defined by a keyword=parm structure. .
· The optional parameters would have a default based on the default defined in the CIM Operations documentation. Thus, for example, deepinheritance is optional. It would have the same default as the
· Source of parameters would be in priority: 1 command line, 2. environment variable, 3, config file. Thus, for example, namespace could be supplied with each command or could be defined as an environment variable once and then used for subsequent commands or could be in a config file with the same result as the environment variable.
· There would be a final default on the major parameters of local system so that simple one word commands would generate some result.
Thus, returning to the enumerateClassNames command:
Enumerateclassnames - With no parameters and no env variables defined would enumerate from the localhost:5988 CIMV2 namepace, top level and deepinhertance = false. It would return the result as a list of classnames one name per line.
Next question: how to we organize the conceopts of required, optional, etc parameters to make this thing as flexible as possible.
We appear to have: several possibilities here for setting parameters:
· Option tag (-) with keyword (ex getclass –n namespace –c CIM_Door)
· field=value where fields are all represented by fieldname=value ( thus, as an example, getclass namespace=CIMV2 name=CIMV2)
· string where string can represent string,integer, etc. and the position of the strings is fixed. ( Thus getclass CIMV2 CIM_Door. If there is only one parameter it would be the class and the namespace would be assumed)
· Boolean keyword (deepinheritance means deepinheritanc=true)
Today the optionmanager supports the following today:
1. sort out all option tag parameters defined by the option table defined. These may be of several types including string, integer, Boolean, etc.
2. Then return all remaining parameters as a new command line string for the application to sort out.
Lets go with the definitions in the option manager
Thus the get class options becomes, for example
· -namespace namespace
· -host host-name
· -port port-number
· -class Classname
· -output output type (we could use the keywordoption so it could be –output XML or –output MOF
· -localonly
· -includeclassorigin
· -includequalifiers
· -property
For each of the above we can include a short form one letter equivalent to make life simpler for the inputter as follows:
· -N namespace
· -P port-number
· -L for localonly
·
· etc.
This leaves us with NO nonoption parameters at all since all parameters are covered by the -… parameter options and all are therefore optional. We could modify this so that the class name could be considered a non-option parameter thus the command could be entered
Getclass CIM_Door
Or
GetClass –C CIM_Door
Of course, we can probably do both so that it can be entered either way.
Note that further, we probably have a problem with the property list in that it is not one parameter but a list and we need to develop something to support that form of input and do not think that the option manager covers this today.
We must determine the host for each command input with some sort of option so that set once, the same host is repeated for all successive commands until changed. There are a couple of alternatives here.
Not sure which to apply. I suggest that the easiest might be to do both in such a way that the parameters are optional so that the user could:
Since all would be optional with proper defaults except that there has to be a CIM_Door from somewhere, the user can have his choice.
All output has to be either to file or ascii manageable in some way by scripting tools.
I propose the following options on output:
Commands that return lists – return the results as a list. We can make the list mechanism more flexible by allowing the specification of list separator and possible header and trailer on the list. The default separator could then be CRLF and the default header and trailers empty. The headers and trailers could be modified by input parameters (cmdline, envvar, configfile).
Commands that return objects – We need a way to represent these objects. The two most obvious forms are: XML and MOF, both of which are largely supported in existing functions in the base object system with functions like toXML and toMof. I think that we can use these functions directly to provide output. I suggest that we provide a parameter that would allow the selection of one of the several output forms.
Other commands – There are probably some other output forms that we have not thought out yet. In particular, we may have to do something special with getproperty, invoke method, etc. This we can attack as it arrives.
It appears obvious that we will have to also create some extra commands above and beyond the existing basic CIM Operations. The following list comes to mind initially:
Handling the error return – What should we do? Think that the choices are to do an error return from the code itself or something distinctive in the output that the user can recognize. The error return with a set of codes sounds logical at first glance.
virtual CIMClass
getClass(
const
String& nameSpace,
const
String& className,
Boolean
localOnly = true,
Boolean
includeQualifiers = true,
Boolean
includeClassOrigin = false,
const CIMPropertyList& propertyList =CIMPropertyList());
Namespace(String)
ClassName(String)
LocalOnly(Boolean)
IncludeQualifiers(Boolean)
IncludeClassOrigin(Boolean)
PropertyList(definitely optional)
Returns either error on the Class information. Here we can chose to output it in either MOF or XML form
---END OF DOCUMENT--