This section covers the following topics:
Sun Management Center software users can run the agent in the interactive mode. In this environment, they can communicate with the agent using Tcl/TOE commands. Any commands available in the agent can be executed in interactive mode dependent on the context in which they are executed.
Running the agent in the interactive mode allows users to debug their agents at runtime, which allows the users to perform the following tasks:
- Navigate the object tree interactively.
- Create or destroy objects.
- Define, lookup, or display certain object attributes.
- Invoke an operation in a particular object context.
- Set a group of object attributes from a file or export the object information to a file.
- Generate SNMP MIB from a module.
This chapter includes examples with relation to working within the agent interactive mode.
|
To Work Within the Agent Interactive Mode
|
 |
Start the agent in the interactive mode:
|
_
|
To Exit the Environment
|
This section describes a set of commands available to all nodes. These commands allow users to create or destroy objects in the agents, apply object interaction, apply dictionary operation, navigate object tree, import data from a file to the agent, export agent to an file and load classes or packages at runtime.
Object Creation
The following commands can be used to create a new TOE object and destroy an existing TOE object.
toe_create [PARENT ...][-superior SUPERIOR]
|
Creates a new TOE object. An optional list of the parent object can be specified to define the objects inheritance tree. The optional superior object can be used to specify the object's superior in the sense of an object tree. This permits trees of objects to be created where the objects' ancestry is independent from the organizational tree structure.
Destroys the specified OBJECT(s).
Object Relationship
These commands allow users to trace or establish the relationship among objects.
toe_parents [PARENT PARENT ...]
|
With no arguments, this command lists the parents of the current TOE object. If any parent objects are specified, then the parent list of the object is changed to the new object list. This is useful for adding or removing class relationships dynamically, but should be used with extreme caution.
With no argument, this command returns the superior object of the current TOE object. If SUPERIOR is specified as the argument, the superior object of the current object is set to SUPERIOR. As with toe_parents, users must use caution when changing the superior state of an object after it has been fully constructed.
Establishes OBJECT as inferior of the current TOE object. This essentially does three things:
- Sets OBJECT's name to NAME.
- Sets OBJECT to be a subobject of the current object.
- Sets the superior of OBJECT to be the current object.
This is the primary means of establishing tree relationships.
locate NAME [-noscope] [-create PARENTS]
|
Locates an object in the object tree by name and returns its TOE identification. If
-noscope is specified, the search does not traverse up the object tree. If PARENTS are specified using the -create option, the object are created if it does not already exist, and its parents are set accordingly.
Adds the specified OBJECT(s) to the parent list of the current TOE object. This is similar to toe_parents, except the inherit command is implicitly safer as it cannot remove parents.
Object Interaction
The following commands allow operation apply to a certain object context instead of the current one:
Sets the current TOE object context to OBJECT. The interpreter maintains a stack of object contexts, and this pushes the specified object onto the context stack. The current object is the base for all command and data references.
Pops the current object off the context stack and reestablishes the previous context.
Returns the TOE identification of the current TOE object context.
Evaluates COMMAND in the context of OBJECT. This is equivalent to beginning the object (using toe_begin), evaluating the command (using eval), and ending the object (using toe_end).
toe_csend VAR OBJECT COMMAND
|
Performs a catch send function, which is identical to a combination of toe_send and the Tcl catch command. Any results or error messages from COMMAND are placed in the variable named VAR, and the entire command returns 0 for success, 1 for error.
toe_supersend OBJECT COMMAND
|
The supersend operation invokes the method of another object (usually a class) in the context of the current object. This is usually used within object constructors, to perform an initialization operation defined in a particular class on the current instance.
toe_recurse pre|post COMMAND
|
Traverses the object tree below the current object and runs COMMAND on each object. Whether the COMMAND is run before or after the subtrees are traversed depends on whether "pre" or "post" is specified.
Returns the tree-based name of the specified TOE object. If no OBJECT is specified then the name of the current object is returned. If the -full option is used then the object's full name, in absolute terms from the root of the object tree, is returned.
Outputs the parents, superior, methods and data keys of the specified object. If no object is specified, the current object is dumped.
Dictionary Operations
These commands provide capability to allow users to apply operations on a certain entry, in the current object, such as define/undefined an entry, find the value of an entry or copy the value of a certain entry to a new entry.
define SLICE KEY VALUE [-t TYPE]
|
Creates a new dictionary entry in the current TOE object. A dictionary entry is identified by two names, SLICE and KEY. The slice is the category or general type of information, and the key is the specific name. This allows an object's data space to be partitioned into logical groups (for example, runtime data versus static configuration information).
The optional TYPE can be used to associate a data type to the key. The most commonly used data types are "string", "int" and "float". The default data type is "string". Data types are usually used for type checking data.
Removed a dictionary entry named KEY from SLICE. If no KEY is specified, then all entries in the specified slice are removed.
With no arguments, this returns all slices in the current TOE object. If a SLICE is specified, then all the keys in that slice are returned.
Reports whether a particular dictionary entry exists, returning 1 for true, 0 for false.
lookup [-d DEFAULT][-t TYPE] SLICE KEY
|
Returns the value of the dictionary entry named by SLICE and KEY. An error results if the dictionary entry does not exist in the current object or its inherited parents. This error is suppressed if the optional DEFAULT is provided, in which case the DEFAULT is returned. If a TYPE is specified then the value is converted to that type. Failure to convert the data type results in an error.
ilookup {SLICES} KEY [DEFAULT]
|
The instance lookup command is the same as the standard lookup command except only the current TOE object is referenced. This is more efficient than lookup and can be used in cases where the parent classes of the object need not be referenced (for example, looking up runtime data or state information).
slookup {SLICES} KEY [DEFAULT]
|
The "scoped lookup" is like the standard lookup except that it also reference superior objects and their parents. This allows data to be retrieved from higher levels of the object tree in a manner similar to variable scoping in programming languages such as C. This is useful for accessing resource information pertinent to an entire tree of objects, but is the least efficient of the three lookup commands (lookup, iloopup, and slookup).
Dumps all the key/value pairs associated with the specified slice to stdout.
Promotes the value of the dictionary entry named by SLICE and KEY into the current TOE object. This is used to pull dictionary values from parent classes into the instance before modifying them. This is equivalent to:
define SLICE KEY [lookup SLICE KEY]
slicelength SLICE
|
Returns the number of keys defined in SLICE in the current TOE object.
Copies all keys from SLICE1 to SLICE2 in the current TOE object.
Compares two dictionary slices (in the current object) and returns three lists: added keys, removed keys and changed keys.
Object/Dictionary I/O
These two commands allow user to import and export the agent's data from and to a file or a certain source.
import string|interface SLICE SPEC [-class PARENTS][-exact]
|
Reads a configuration file and imports its contents into the current TOE object. For string imports, SPEC is the body of the configuration file. For interface imports, SPEC is the interface specification (usually the file name). The SLICE specification indicates that any keys in the configuration file not qualified by a slice name should be placed in SLICE.
If the configuration file contains hierarchical object specifications, these objects is created as inferiors of the current object (that is, a tree of objects is constructed below the current object). If PARENTS are specified then all new objects inherit from this object. If the -exact option is specified, then any subobjects in the configuration file specification must exactly match the existing object tree structure. Otherwise, it results in an error .
export string|interface SLICE SPEC [-minimal][-dot]
|
Exports the pertinent dictionary information from the current TOE object and any of its inferiors. The SLICE specification indicates which slice(s) are to be exported, and a blank slice specification causes all slices to be exported. Any subobjects are represented by a curly-brace-enclosed block in the resulting configuration file. The -minimal option suppresses as the output of subobjects not containing any pertinent dictionary entries (that is, empty config blocks). The -dot switch causes any subobject dictionary keys to be output in dot notation, which does not use curly braces.
Interactive Object Tree Navigation
These command enable users to interactively navigate the object tree. They are similar to UNIX shell commands for file system navigation.
Mimics the UNIX shell cd command when interactively navigating the TOE object tree. Navigating the TOE object tree is similar to UNIX shell cd. The functionality is actually more like the C shell pushd command since an object context stack is maintained. The special name ``..'' is used to pop the stack and return to the previous object. The ``*'' can be used as a shortcut to an unique object in the TOE object tree.
Returns the full name of the current object.
Lists the names of the subobjects under the current object. The -a option shows what (objects or data) and who (name) are under this object. The -l option outputs detailed information about each object, such as the object's TOE identification. If names are specified, the subobject names (or detail information) are listed for each named subobjects; otherwise, it means to look into all subobjects.
Class Definition
These commands can be used to define class, create class, or destroy a class at runtime. They are not so useful in terms of debugging.
newclass name {parent classes} {body}
|
Creates a new class definition called name. The new class is subclassed from the parent classes (using multiple inheritance), and base classes can be created with empty set of parent classes. The body specification is a block of code, which defines the methods and the data of the new class, and is evaluated in the context of the class at the time of class creation.
Extends the definition of a class. This command can be used to add methods or data to an existing class, and is useful for splitting large class definitions over multiple places.
method name {args} {body}
|
Creates a new method called name in the current class. The method command is identical to the Tcl "proc" command, but it also creates an association between the method and the class it is defined in.
Creates a new instance object of class. A new object is created which inherits from the class definition object, and the constructor is invoked on the new object.
Destroys the object instance. Before removing the object, any inferior objects in the object scope tree are uninstantiated, and the object's destructor is invoked.
Class/Package Loading
These commands allow users to load classes or binary packages to an agent at runtime.
Indicates to the interpreter that a particular class is required. The interpreter loads the class if it has not been loaded, and it automatically pulls in the entire ancestor hierarchy of the named class.
.class.name
requires package name
|
Indicates to the interpreter that a particular binary package is required. The interpreter loads the package if it has not been loaded, and it automatically loads in all packages the are required by the named package.
This loads an X file as a template and makes it available as a reference tree. This is useful for loading tree specifications that are used by multiple other object trees. Reference tree can be inherited to produce usable object tree.
The loaded template is placed in the object tree at:
This section includes the following procedures:
Note - Since the agent interactive mode is basically used for debugging, you can define new object attributes and introduce new modules. However, anything done in this mode is permanent.
|
To Define a Module
|
The rest of this chapter uses a hypothetical example consisting of three files: hellosunmc-v01-m.x, hellosunmc-v01-d.x and hellosunmc-v01-d.prc. The contents of the files are given below:
hellosunmc-v01-m.x:
.........
# Location of the module
param:location =
.iso.org.dod.internet.private.enterprises.sun.prod.sunsymon\
.agent.modules.demo.HelloSunMCV01
param:oid = 1.3.6.1.4.1.42.2.12.2.2.1000.2
..........
hellosunmc-v01-d.x:
[ load hellosunmc-v01-m.x ]
HelloSunManagedObject = { [ use templates.hellosunmc-v01-models\
-d.HelloWorldManagedObject ]
[ source hellosunmc-v01-d.prc ]
type = active
refreshMode = sync
refreshService = _internal
refreshCommand = getHS2String
initInterval = 2
refreshInterval = 300
}
hellosunmc-v01-d.prc:
proc getHS2String { } {
set count [lookup -d "0" visitCount count]
incr count
define visitCount count $count
return "Hello World! This data is updated $count time(s)"
}
|
|
To Find the Attribute Value of a Certain Object
|
|
|
If the TOE object is HelloSunManagedObject, its location is specified in the hellosunmc-v01-m.x file. To find its attribute: |
|
1. |
Navigate to the specific object. |
|
a. |
Determine the current object:
|
|
|
This displays the current TOE object id:
|
|
b. |
Determine the objects directly under this object:
|
|
|
This lists all objects under the current object, for example:
classes templates _config config services iso shadow contexts rules
|
|
|
c. |
Determine the current object:
|
|
|
This gives you the full name of the objects. |
|
d. |
Go to the specified object:
|
- To go to a certain object directly under the current object:
- For a short cut to an object whose name is unique in the current context:
agent:ios> cd *modules
.iso.org.dod.internet.private.enterprises.sun.prod.sunsymon.\
agent.modules
agent:modules> cd *HelloSunMCV01
.iso.org.dod.internet.private.enterprises.sun.prod.sunsymon\
.agent.modules.demo.HelloSunMCV01
agent:HelloSunMCV01> ls
availability enabled HelloSunManagedObject
agent:HelloSunMCV01> cd HelloSunManagedObject
.iso.org.dod.internet.private.enterprises.sun.prod.sunsymon\
.agent.modules.demo.HelloSunMCV01.HelloSunManagedObject
|
|
|
Using the cd command, several times, takes you beyond the top object. If this happens, you can use the following command:
|
|
|
This brings you back to the node you need to enter. |
|
2. |
View all slices (logic groups) in the current object:
agent:HelloSunManagedObject> entries
|
|
|
|
This lists all slices in this object. |
|
3. |
Enter the following to view the attribute value in a certain slice:
internal object peer timer timer-timer timer-attribute\
-timer target oid service serviceparam visitCount
agent:HelloSunManagedObject> sdump visitCount
|
|
|
|
This lists all key attributes/value pair in this slice:
|
|
To View the Result of an Operation on a Certain Object
|
|
1. |
Invoke the method on the object: |
|
a. |
Go to the object domain where the method has been defined:
agent> cd *HelloSunManagedObject
|
|
|
|
The results are as follows:
.iso.org.dod.internet.private.enterprises.sun.prod.sunsymon\
.agent.modules.demo.HelloSunMCV01.HelloSunManagedObject
|
|
|
b. |
View current value of an attribute:
agent:HelloSunManagedObject> sdump visitCount
|
|
|
|
The results are as follows:
|
|
c. |
Invoke the method:
agent:HelloWorldManagedObjec> getHS2String
|
|
|
|
The results are as follows:
Hello World! This data is updated 26 time(s)
|
|
|
d. |
View a certain attribute if it is set as a result:
agent:HelloSunManagedObject> lookup visitCount count
|
|
|
|
This returns the value of the set attribute, for example:
|
|
2. |
Apply the method on the object: |
|
a. |
Apply operation on a certain object directly:
agent:modules> toe_send [locate *HelloSunManagedObject]
getHS2String
|
|
|
|
This applies the getHS2String() method to the specified object context and return the result:
Hello World! This data is updated 26 time(s)
|
|
|
b. |
View certain attributes if it is set as results:
|
|
i. |
Go to the specified object context:
agent:modules> cd *HelloSunManagedObject
|
|
|
ii. |
View the attribute values:
agent:HelloSunManagedObject> sdump visitCount
count: 26
|
|
|
To Import and Export a Set of Object Attributes
|
To import and export a set of object attributes to and from a certain TOE object, do the following:
|
1. |
Write all attributes (key/value pair) of a file in .x file format:
shell% cat helloworld_v03_update.x
initValue = 10
status = "OK"
|
|
|
2. |
Go to the target object:
agent> cd *HelloSunManagedObject
.iso.org.dod.internet.private.enterprises.sun.prod.sunsymon\
.agent.modules.demo.HelloSunMCV01.HelloSunManagedObject
|
|
|
3. |
View the current value of an attribute:
agent:HelloSunManagedObject> sdump visitCount
count: 28
|
|
|
4. |
Input data under this object to slice visitCount:
agent:HelloSunManagedObject> import interface visitCount \
helloworld_v03_update.x
|
|
|
5. |
View the attributes generated:
agent:HelloSunManagedObject> sdump visitCount
count:28
initValue:10
status:OK
|
|
|
6. |
Define a new attribute in this slice (or apply a certain operation):
agent:HelloSunManagedObject> define visitCount time 16:23:10
16:23:10
|
agent:HelloSunManagedObject> sdump visitCount
count:28
initValue:10
status:OK
time:16:23:10
|
|
|
7. |
Export these attributes to a file:
agent> export interface visitCount helloworld_v03_update_out.x
|
|
|
8. |
View the output file:
shell% cat helloworld_v03_update_out.x
|
|
|
|
This command provides the following result:
count=28
initValue=10
status=OK
time=16:23:10
HelloSunMCMessage = {
}
|
|
|
To Generate SNMP MIB From a Module
|
|
1. |
Go to the destination module. |
|
|
As defined in hellosunmc-v01-m.x, when this HelloWorld module is loaded, its location is:
.iso.org.dod.internet.private.enterprises.sun.prod.sunsymon\
.agent.modules.demo.HelloSunMCV01
agent> cd *HelloSunMCV01
.iso.org.dod.internet.private.enterprises.sun.prod.sunsymon\
.agent.modules.demo.HelloSunMCV01
agent:HelloSunMCV01> ls
availability enabled HelloSunManagedObject
|
|
|
2. |
Generate SNMP MIB for these modules:
agent:HelloSunMCV01> mibExport
|
|
|
3. |
View the SNMP MIB files. |
- The mib files are located under the directory $VAROPTDIR, which is defined in the following: $INSTALL_DIR/sbin/sm_setup_mib2.sh. You can locate the hellosunmc-v01-mib.txt file at: the following location:
Copyright © 2000 Sun Microsystems, Inc. All Rights Reserved.