Tech-Talk Using the PATROL Agent COM Server August 1999 Authored By: Eric Anderson

Transcription

1 Tech-Talk Using the PATROL Agent COM Server August 1999 Authored By: Eric Anderson Introduction Among the many new features of PATROL version 3.3, is support for Microsoft s Component Object Model (COM). The PATROL Agent can now act as a COM server to provide external COM applications with full access to the data PATROL is managing. This feature gives Visual Basic and Visual C++ developers the ability to build robust applications management products on top of PATROL. This paper focuses on the use of the PATROL Agent COM server with Microsoft Visual Basic. To demonstrate how simple it is to build an application using PATROL, we have developed a simple Namespace exploring application. This application connects to a PATROL Agent, gets a list of the applications PATROL is managing, and traverses the namespace of applications, instances and parameters. This paper assumes a basic understanding of PATROL and Visual Basic. If you are not familiar with these applications, visit for information about PATROL and for Microsoft s Visual Basic site. PATROL Agent Server The PATROL Agent for Windows NT is a local COM server. In the COM definition an interface is a group of related functions that are implemented together. The PATROL Agent provides COM functionality through the IPatrolAgent interface. Methods, or functions, are exposed via the IDispatch interface through a technique known as automation. In Visual Basic, an application uses the PATROL Agent s dispatch interface. Using the PATROLAgent object Using the PATROL Agent in a Visual Basic Application requires five basic steps: 1. Installation of PATROL Agent Version Configuration of the PATROL Agent to support COM 3. PATROL Agent object must be known or referenced by Visual Basic 4. PATROL Agent object is instantiated by assigning it to a variable 5. Object s methods are called to connect and get data from the PATROL Agent Each of these steps is covered in detail in the following example application, PatComEx. This application is very simple, but will adequately illustrate the principles. Configuring COM for the PATROL Agent Once you have your PATROL Agent installed you need to configure for use with COM. You configure the machines with PATROL Agents either by setting the PATROL Agent COM configuration variables or by running the Microsoft DCOM configuration utility DCOMCFG.EXE. There are two PATROL Agent configuration variables that must be set. They are:

2 2 ComUserAllowed ComSecurityLevel ComUserAllowed ComUserAllowed controls access to the PATROL Agent COM server. It requires a string, separated by the pipe character ( ), that may include users, members of groups and the user who started the PATROL Agent. To find the PATROL Agent variable, search for /AgentSetup/comUserAllowed. The example below adds three entries to the variable. They are: eanderso to represent the user BMC.COM as a domain Patrol as the default PATROL Agent account "/AgentSetup/comUserAllowed" = { REPLACE="eanderso BMC.COM Patrol" }, ComSecurityLevel The ComSecurityLevel variable controls the level of information provided by the PATROL Agent COM Server. The following values are available: N No DCOM interface allowed (default) R DCOM client can receive data from the server W DCOM client can receive and change data on the server F DCOM client can receive and change data and use pslexecute() to run OS commands To find this variable, scroll up from comuserallowed in config.default or enter the search string "/AgentSetup/comSecurityLevel". To set this variable to F, edit the string as shown below. "/AgentSetup/comSecurityLevel" = { REPLACE="F" }, Restart the PATROL Agent to initialize these settings. Now that the PATROL Agent is configured to support COM, we will configure Visual Basic to use the PATROL Agent object.

3 3 Adding the PATROLAgent object to Visual Basic To use the PATROLAgent object in our example application we must create the PatComEx project. To create the project, start Visual Basic and select File->New. (You may also create the project when you start Visual Basic by selecting a Standard EXE project as shown below.) When opening a Standard EXE project, Visual Basic creates a project named Project1. Select the File->Project->Save As to rename your project to PatComEx. You will also be prompted for a name for Form1, you may use any name you wish. We are now ready to tell Visual Basic about the PATROLAgent object. Note: COM is only supported in the PATROL Agent Version 3.3. This task requires a PATROL 3.3 Agent and the IPA.tlb type library. In Visual Basic, select Project->References

4 4 The References dialog box displays a list of known objects. To add the PATROL Agent object to this list, click Browse and search for the PATROL Agent type library. The type library describes the methods exposed by the PATROL Agent COM Server. Type libraries usually have the file extension.tlb. If you installed PATROL using the defaults, this type library is located in the PATROL3-3/bin directory. The References listbox is updated to add the PATROL Agent type library. Select PatrolAgent 1.0 Type Library by clicking the checkbox, then click OK. Visual Basic now recognizes the PatrolAgent object. To see what it can do, open the Object Browser to view all the methods available. The methods provided by the PatrolAgent object are the same as their counterparts in the PSL reference. Viewing the PatrolAgent Classes and Methods Select View->Object Browser to view the PATROL Agent type library. The following dialog is displayed.

5 5 There are two classes defined in the PatrolAgent 1.0 Type Library. PatrolAgent class represents PATROL Agents that are started as a service. PatrolConsoleAgent class represents agents that are started as console applications. These classes expose the same methods. Select the PATROLAgent class to view these methods. You can use all the objects, methods, and properties listed in the object browser for the PATROL Agent Type Library. Assigning an Object Reference to the PatrolAgent object Now that we know what methods the PatrolAgent object provides, let s see them in action. 1. Choose File->Open to open the example application PatComEx. 2. Create the form to display your output by placing five labels on a form. Fig 1. Form1 for PatComEx Use the example dialog above for naming and locations of the fields.

6 6 3. Add a textbox to display the name of the local PATROL Agent to which we will connect. 4. Add three list boxes to the form as shown in the figure above. With our form completed, we will now add code to initialize the form and make our connection to the PATROL Agent. Instantiating the PatrolAgent object s class The first step to using the PatrolAgent object is to declare an object in a module called globals. 1. To add a module to your project, right-click the Project viewer window over the Project1 text and select Add->Module. 2. In the Properties window, change the module s name to globals. 3. To add or edit code, double-click the globals object in the Project. This is where we ll add our object variable. Insert the following code into your Globals.bas file: LISTING 1.1. Declare the PatrolAgent variable in Globals.bas 'Declare an object variable of the class PatrolAgent Dim opatrolagent As PatrolAgent By declaring the object variable in the module, it becomes globally visible to all functions. When you declare a variable for an object defined in a type library, you specify the name of the class supplied by the type library. The following syntax is used: DIM variable As [New] class The class argument can be composed of two parts:

7 7 component (The choice that is displayed in the project/library list of the object browser. In our case there is none.) class (The part shown in the classes/modules box.) In the object browser there are three classes for the PatrolAgent object. We chose PatrolAgent because we are connecting to a PATROL Agent service. We could have chosen to declare an object of the generic class, however, when you declare a variable with the generic Object Class, ActiveX must use late binding. When you declare an object variable of a specific class, ActiveX uses early binding. Early binding can increase speed to object references. Assigning an Object Reference to a Variable You can assign an object reference to the variable by using the New keyword, CreateObject, or GetObject in a Set statement. Using variables declared with the New keyword could slow your application. Every time a variable is declared using New, it must be tested to see if an object reference has been assigned to it. For this example we have chosen CreateObject. The syntax of CreateObject is as follows: Set objectvariable = CreateObject( progid ) The object variable can be one of your own. The progid argument is usually the fully qualified class name of the object being created. This ID can be the same as the class name or it can be a unique name given to the object and placed in the Windows registry. In the case of the PatrolAgent object, the class ID can be found in the registry at the following location: HKEY_CLASSES_ROOT/CLSID/BMC.PatrolAgent.3.3 The progid is: BMC.PatrolAgent.3.3 The CLSID is: { c039-11d1-ab d5} You can reference the progid either way, however it is easier to remember the proper name. Now we assign the object reference to a variable named opatrolagent in the example application, PatComEx. First, we ll add the reference to the form load procedure for our application by double clicking on the form. This brings up the code editor and automatically creates an event handler for the form load event. Each time the form is loaded into memory this handler is called. LISTING 1.2. Assign the PatrolAgent object to the variable opatrolagent in Form_Load Private Sub Form_Load() Declare variables with types for memory proficiency Dim strhostname As String ' Assign an object reference Set opatrolagent = CreateObject("BMC.PatrolAgent.3.3")

8 8 End Sub strhostname = opatrolagent.get("/hostname") Text1.Text = strhostname In this code we reference the PatrolAgent object by assigning it to the variable opatrolagent. Set opatrolagent = CreateObject("BMC.PatrolAgent.3.3") You must connect to the PATROL Agent in different ways depending if: it was started as a service or it was started as a console application To connect to the PATROL Agent started as a console application, change the CreatObject argument as follows: Set opatrolagent = CreateObject("BMC.PatrolAgent.Console.3.3") Additionally, we have used the get() method of the PatrolAgent interface to get the host name back from the PATROL Agent. Assign the return value to a string as follows. strhostname = opatrolagent.get("/hostname") Then assign the value of the string containing the hostname value to the Text1 control we added to our form. Text1.Text = strhostname A quick way to tell if you have correctly referenced an object is to see if the IntelliSense feature of Visual Basic displays options for the new object. When we instantiated the PatrolAgent object, IntelliSense detected and suggested it as shown below. Using the PatrolAgent object s methods To use the methods of the object you use the object.method syntax.

9 9 In our example, we use the get method to return the current value of a variable. This method has one argument, the name of the variable from which you want the value. We assign the return value to the string strhostname. strhostname = opatrolagent.get("/hostname") /hostname is the variable hostname for the root object in the PATROL namespace. We then assign the value in strhostname to the text property of the Text1 textbox component. When we type the. character after the variable reference, IntelliSense displays a list of the methods for the PatrolAgent object. Finally, to complete the method s arguments, IntelliSense suggests the arguments and types for each argument. Cleaning up after ourselves Before we build the application for the first time, we should cover two important aspects of building robust applications:

10 10 clearing memory error handling Clearing Memory It is good practice to clear our variables that reference objects so the object can be released from memory. To clear an object variable, set it to nothing. Modify the Form_load code so that the opatrolagent variable is set to nothing. LISTING 1.3. Clear the opatrolagent variable Private Sub Form_Load() Declare variables with types for memory proficiency Dim strhostname As String ' Assign an object reference Set opatrolagent = CreateObject("BMC.PatrolAgent.3.3") End Sub strhostname = opatrolagent.get("/hostname") Text1.Text = strhostname Set opatrolagent = Nothing All object variables are cleared when they go out of scope. However, it is good practice to clear them anyway. If you want the variable to retain its value across procedures, use a public or form-level variable or create procedures to return the object. Error Handling You should also include code to handle errors that the ActiveX component generates. There are three conditions to test when working with components. They are: 1. Is the reference to the component valid? 2. Is the component busy? 3. Is there a request pending for the component? Lets look at each of these in more detail before we build and run our application. Testing for Valid Object References You can determine if an object reference is valid by using Is Nothing. Is Nothing only checks to see if a valid reference once existed. To check the error for unavailability you must look at the return code from the component. To validate the object reference assignment to a variable, the syntax looks like this: If variable name Is Nothing Then MsgBox( Invalid Object Reference ) Else Add your object handling code here

11 11 The Component Busy Condition The PATROL component may reject your request because it is processing another request (getting process lists or %dump execution). Visual Basic assumes that the busy condition is temporary and keeps trying the request for a specified timeout interval. When the timeout interval is exceeded, Visual Basic displays a default Component Busy dialog. You can change this dialog to reflect the needs of your program. There are three properties available for customization: OLEServerBusyMsgText OLEServerBusyMsgTitle OleServerBusyTimeout. OLEServerBusyMsgText This property specifies the message text to be displayed when a component busy condition occurs. To set the property, the following syntax is used: Application Object. OleServerBusyMsgText = "text" Where The Application object is a global object accessed with the Application keyword. It determines or specifies information about the application's title, version information, the path and name of its executable file and Help files, and whether or not a previous instance of the application is running OleServerBusyMsgText is the property of the Application object we want to set. Text is the text we want displayed in the dialog when a server busy condition exists. OLEServerBusyMsgTitle This property specifies the caption of the dialog. If you set this property alone, the default dialog will display. The syntax for this property is similar to the OLEServerBusyMsgText property: Application Object. OleServerBusyMsgTitle= "text" Where The Application object is a global object accessed with the Application keyword. It determines or specifies information about the application's title, version information, the path and name of its executable file and Help files, and whether or not a previous instance of the application is running OleServerBusyMsgTitle is the property of the Application object we want to set. Text is the text we want displayed as the dialog caption or title.

12 12 OleServerBusyTimeout You can also set how long Visual Basic tries to request the object before the dialog is displayed. The time is measured in milliseconds. The syntax for the OleServerBusyTimeout property is: Application Object. OleServerBusyTimeout= time Where The Application object is a global object accessed with the Application keyword. It determines or specifies information about the application's title, version information, the path and name of its executable file and Help files, and whether or not a previous instance of the application is running OleServerBusyTimeout is the property of the Application object we want to set. Time is the time in milliseconds before the server busy dialog is displayed. The default value is milliseconds (10 seconds). The Request Pending Condition Once the PATROL component is accepted, your application must wait for a response. If the request exceeds the time allowed, a dialog displays. Visual Basic displays a default Component Request Pending dialog. You can change this dialog to reflect the needs of your program There are three properties available for customization: OLERequestPendingMsgText OLERequestPendingMsgTitle OleRequestPendingTimeout OLERequestPendingMsgText This property specifies the message text to be displayed when a component busy condition occurs. To set the property, the following syntax is used: Application Object. OleRequestPendingMsgText = "text" Where The Application object is a global object accessed with the Application keyword. It determines or specifies information about the application's title, version information, the path and name of its executable file and Help files, and whether or not a previous instance of the application is running OleRequwstPendingMsgText is the property of the Application object we want to set. Text is the text we want displayed in the dialog when a server busy condition exists. OLERequestPendingMsgTitle This property specifies the caption of the dialog. If you set this property alone, the default dialog will display.

13 13 The syntax for this property is similar to the OLERequestPendingMsgText property: Application Object. OleRequestPendingMsgTitle= "text" Where The Application object is a global object accessed with the Application keyword. It determines or specifies information about the application's title, version information, the path and name of its executable file and Help files, and whether or not a previous instance of the application is running OleRequestPendingMsgTitle is the property of the Application object we want to set. Text is the text we want displayed as the dialog caption or title. OleRequestPendingTimeout You can also set how long Visual Basic will wait for the response from the object before the dialog is displayed. The time is measure in milliseconds. The syntax for the OleRequestPendingTimeout property is: Application Object. OleRequestPendingTimeout= time Where The Application object is a global object accessed with the Application keyword. It determines or specifies information about the application's title, version information, the path and name of its executable file and Help files, and whether or not a previous instance of the application is running OleRequestPendingTimeout is the property of the Application object we want to set. Time is the time in milliseconds before the server busy dialog is displayed. The default value is 5000 milliseconds (5 seconds). Finally, we ll add error handling to our application. We will then build it to see what we ve created. LISTING 1.4. Connection with error handling Private Sub Form_Load() Declare variables with types for memory proficiency Dim strhostname As String On Error GoTo LongTransaction _Error ' Set busy to 4 seconds pending to 2 seconds App.OleRequestPendingTimeout = 2000 App.OleServerBusyTimeout = 4000 ' Window Titles App.OleServerBusyMsgTitle = "Component Busy" App.OleRequestPendingMsgTitle = "Request Pending"

14 14 ' Message texts specific to this request. App.OleServerBusyMsgText = "Your PatrolAgent seems to be busy." & vbcrlf _ & "Continue trying to initialize the connection" App.OleRequestPendingMsgText = "Your request " _ & "is still executing. " & vbcrlf _ & "Call your PATROL Administrator to verify that the " _ & " Patrol Agent is running, or to report problems." ' Assign an object reference Set opatrolagent = CreateObject("BMC.PatrolAgent.3.3") If opatrolagent Is Nothing Then MsgBox( Invalid Object Reference ) Else Get the PATROL Agent hostname variable value strhostname = opatrolagent.get("/hostname") Text1.Text = strhostname Set opatrolagent = Nothing LongTransaction _Cleanup: Set opatrolagent = Nothing Exit Sub LongTransaction_Error: If Err.Number = &H Then MsgBox("Connection Request cancelled") Else MsgBox("Connection With Agent Failed ) Resume LongTransaction _Cleanup End Sub We added an Error handler to the application by assigning our error handler. Visual Basic provides a general On Error function that returns numeric error codes, which handles errors by your defined error handlers. On Error GoTo LongTransaction _Error This line tells Visual Basic to use the LongTransaction_Error handler to determine what to do with the error. The handler determines if the error code is &H This code indicates that the connection request was cancelled. We look for this code and generate an appropriate message or we provide an alternative message to indicate another error type. LongTransaction_Error: If Err.Number = &H Then MsgBox("Connection Request cancelled") Else MsgBox("Connection With Agent Failed )

15 15 The final statement in the error handler directs the application to another function to free memory and to exit the Form_Load() procedure. Resume LongTransaction _Cleanup LongTransaction _Cleanup: Set opatrolagent = Nothing Exit Sub We set the timeout values and customized the dialog text and titles for the OleServerBusyMsg and OleRequestPendingMsg to reflect our application. ' Set busy to 4 seconds pending to 2 seconds App.OleRequestPendingTimeout = 2000 App.OleServerBusyTimeout = 4000 ' Window Titles App.OleServerBusyMsgTitle = "Component Busy" App.OleRequestPendingMsgTitle = "Request Pending" ' Message texts specific to this request. App.OleServerBusyMsgText = "Your PatrolAgent seems to be busy." & vbcrlf _ & "Continue trying to initialize the connection" App.OleRequestPendingMsgText = "Your request " _ & "is still executing. " & vbcrlf _ & "Call your PATROL Administrator to verify that the " _ & " Patrol Agent is running, or to report problems." We also test the opatrolagent reference to determine if it is valid. If it is not valid the following occurs: Is Nothing returns true and we display a message. We drop out of the If statement We set the opatrolagent to Nothing to be sure memory is deallocated and We exit the procedure. If opatrolagent Is Nothing Then MsgBox( Invalid Object Reference ) Else Get the PATROL Agent hostname variable value strhostname = opatrolagent.get("/hostname") Text1.Text = strhostname If the Is Nothing returns false, we have a valid object reference and can use the PatrolAgent object methods to get the hostname and display it in the Text1 textbox. Building the Application Build and run the PatComEx project by selecting Run->Start or by clicking Start on the toolbar. At this point, the hostname textbox (Text1) is now filled with the name of your host. (in this example, eanderson). The application should now look like this.

16 16 With an understanding of how to reference the PATROL Agent Object and what its methods do, we are now ready to fill out the rest of our application. Filling in the Application list To add the application list from the PATROL Agent to our listbox we must get a list of the agent variables using the get_vars() function. The return from this function is a string with carriage return characters. We split this string up and for each entry use the get() method to check the _type_ variable. This will return the type APPLICATION if the object is an application. We then add the application names to the listbox using its additem method. Modify the code in the Form_Load handler to get the application list as follows: LISTING 1.5. Get the application list using the get_vars() and get() functions Private Sub Form_Load() Declare variables with types for memory proficiency Dim strhostname As String On Error GoTo LongTransaction _Error ' Set busy to 4 seconds pending to 2 seconds App.OleRequestPendingTimeout = 2000 App.OleServerBusyTimeout = 4000 ' Window Titles App.OleServerBusyMsgTitle = "Component Busy" App.OleRequestPendingMsgTitle = "Request Pending" ' Message texts specific to this request. App.OleServerBusyMsgText = "Your PatrolAgent seems to be busy." & vbcrlf _ & "Continue trying to initialize the connection" App.OleRequestPendingMsgText = "Your request " _

17 17 & "is still executing. " & vbcrlf _ & "Call your PATROL Administrator to verify that the " _ & " Patrol Agent is running, or to report problems." ' Assign an object reference Set opatrolagent = CreateObject("BMC.PatrolAgent.3.3") If opatrolagent Is Nothing Then MsgBox( Invalid Object Reference ) Else Get the PATROL Agent hostname variable value strhostname = opatrolagent.get("/hostname") Text1.Text = strhostname ' Get the list of agent variables for the host Dim NodePath, ApplicationPath, strtype As String NodePath = "/" Applications = opatrolagent.get_vars(nodepath, "nodes") 'Split the list up or you will get one lone string with 'carriage returns embedded For Each Application In Split(Applications, vblf) ApplicationPath = NodePath & Application strtype = opatrolagent.get(applicationpath & "/ type ") ' Only put it in the list if it is of type APPLICATION If strtype = "APPLICATION" Then List1.AddItem (Application) Next Set opatrolagent = Nothing LongTransaction _Cleanup: Set opatrolagent = Nothing Exit Sub LongTransaction_Error: If Err.Number = &H Then MsgBox("Connection Request cancelled") Else MsgBox("Connection With Agent Failed ) Resume LongTransaction _Cleanup End Sub We begin by adding three new variables: NodePath (hard coded to point to the root of the PATROL namespace) ApplicationPath strtype ' Get the list of agent variables for the host Dim NodePath, ApplicationPath, strtype As String

18 18 NodePath = "/" The applications variable contains the list of applications returned by the get_vars() method of the PatrolAgent object. The get_vars() method is the same as the PSL get_vars() function and uses the same arguments. The first argument is the object whose variables are wanted, the second variable is a keyword that specifies the information to be returned. We only want nodes however you can return subnodes, leaves or all. Applications = opatrolagent.get_vars(nodepath, "nodes") In order to determine if we have an application object (which we want) or an agent variable, we need to test the object s type variable. We do this by first assigning the Nodepath value / and an entry in the application variable string. We iterate through the application string in the same manner as collections for Visual Basic. We use a for each loop and the Visual Basic split function to get the object name separated by the line feed character. You can look up the split function by pressing F1 and searching for split. For Each Application In Split(Applications, vblf) ApplicationPath = NodePath & Application We use the PatrolAgent get method to return the object s type. If the type is an application we add it to the List1 component using its AddItem method. Otherwise, we discard it and iterate to the next item in the application list. strtype = opatrolagent.get(applicationpath & "/ type ") ' Only put it in the list if it is of type APPLICATION If strtype = "APPLICATION" Then List1.AddItem (Application) Next The get method, like the get_vars method are equivalent to the corresponding PSL functions get() and get_vars() functions. Refer to the PATROL Script Language Reference Manual for details on these functions. Building the Application Build and run the PatComEx project by selecting Run->Start or by clicking Start on the toolbar. The Application List is filled with the applications that PATROL is currently managing.

19 19 Filling in the Application Instance list Filling in the application instance list is similar to filling in the applications list. We ll fill in the instance list based on the application that is selected in the application list. We recommend a singular function to build the PATROL namespace and populate the lists from that function, however for simplicity, we have placed most of the code in the List1_Click event handler and left out the error handling. To create the event handler for the Application List, double-click the List1 listbox in the form editor. Add the following code to the List1_Click procedure. LISTING 1.6. Get the application Instance list using the get_vars() and get() functions Private Sub List1_Click() ' Assign an object reference Set opatrolagent = CreateObject("BMC.PatrolAgent.3.3") List2.Clear List3.Clear ' Get the list of agent variables for the host Dim NodePath, ApplicationPath, strtype As String NodePath = "/" & List1.List(List1.ListIndex) Label5.Caption = NodePath Applications = opatrolagent.get_vars(nodepath, "nodes") 'Split the list up or you will get one lone string with 'carrage returns embedded For Each Application In Split(Applications, vblf) ApplicationPath = NodePath & "/" & Application strtype = opatrolagent.get(applicationpath & "/ type ") ' Only put it in the list if it is of type APPLICATION Instance If strtype = "APP_INSTANCE" Then List2.AddItem (Application) Next Set opatrolagent = Nothing

20 20 End Sub In the Form_Load procedure we clear the PatrolAgent assignment. To get the application instance list, we must recreate the opatrolagent variable. Set opatrolagent = CreateObject("BMC.PatrolAgent.3.3") Clear List2 and List3 using the Clear method to prevent the duplication of entries in the controls. List2.Clear List3.Clear Like in the applications example, we declare three variables to handle the complete path of the agent name space and to test the object s type. Dim NodePath, ApplicationPath, strtype As String List1.List returns the ascii string value of the item selected in the list. We add this value to the agent root ( / ) to complete the object path in the PATROL namespace. We assign the NodePath value to Label5 s caption method to create a simple status bar message indicating where the user has selected in the PATROL namespace. NodePath = "/" & List1.List(List1.ListIndex) Label5.Caption = NodePath We use the get_vars method again to get a list of the objects under the selected application. We iterate through the list using almost the same method as we used in the applications. We append a / character to the node path to separate the object paths, similar to directories. A complete path for the NT_CPU application instance would read: /NT_CPU/NT_CPU We test the type variable in the same way as the application, however we compare to the string APP_INSTANCE. Applications = opatrolagent.get_vars(nodepath, "nodes") For Each Application In Split(Applications, vblf) ApplicationPath = NodePath & "/" & Application strtype = opatrolagent.get(applicationpath & "/ type ") ' Only put it in the list if it is of type APPLICATION Instance If strtype = "APP_INSTANCE" Then List2.AddItem (Application) Next Building the Application Build and run the PatComEx project by selecting Run->Start or by clicking Start on the toolbar. You can select an item in the Application List and its instance will be displayed in the Instance List.

21 21 Some application classes do not have instances. In this case the Instance List will be empty. Filling in the Parameter list To conclude our example application, we add two event handlers: one displays the parameter list when an instance is selected in the Instance List one displays the current value of the parameter selected in the Parameter List Both of these handlers are similar to the application and application instance code. We use one more method of the PatrolAgent class to get the value of the parameter. To create the event handler for the Instance List, double-click the List2 listbox in the form editor. Add the following code to the List2_Click procedure. LISTING 1.7. Get the parameter list using the get_vars() and get() functions Private Sub List2_Click() ' Assign an object reference Set opatrolagent = CreateObject("BMC.PatrolAgent.3.3") List3.Clear ' Get the list of agent variables for the host Dim NodePath, ApplicationPath, strtype As String NodePath = "/" & List1.List(List1.ListIndex) & "/" & List2.List(List2.ListIndex) Label5.Caption = NodePath Applications = opatrolagent.get_vars(nodepath, "nodes") 'Split the list up or you will get one lone string with 'carrage returns embedded For Each Application In Split(Applications, vblf) ApplicationPath = NodePath & "/" & Application strtype = opatrolagent.get(applicationpath & "/ type ") ' Only put it in the list if it is of type APPLICATION Instance If strtype = "PARAM_INSTANCE" Then List3.AddItem (Application)

22 22 Next Set opatrolagent = Nothing End Sub The only difference between this procedure and the List1_Click procedure is the definition of NodePath and comparison of strtype. To create the full path to the application instance, we define NodePath, root /, the string value of List1, the slash separator (/) and the string value of the List2 component. NodePath = "/" & List1.List(List1.ListIndex) & "/" & List2.List(List2.ListIndex) To fill Parameter List with parameters we compare strtype to PARAM_INSTANCE. If strtype contains the string PARAM_INSTANCE then the parameter name is added to the listbox. If strtype = "PARAM_INSTANCE" Then List3.AddItem (Application) Next Displaying the Value of a Parameter To display the value of the parameter, we build the full path to the parameter based on the application, application instance and parameter selected in the listboxes. We call the get method of the PatrolAgent class with the full path name and append the value agent variable name. We use the Visual Basic MsgBox method to display the value of the parameter to the user. To create the event handler for the Parameter List, double-click the List3 listbox in the form editor. Add the following code to the List3_Click procedure. LISTING 1.8. Get the parameter value using the get_vars() and get() functions Private Sub List3_Click() ' Assign an object reference Set opatrolagent = CreateObject("BMC.PatrolAgent.3.3") Dim strfullpath, strvalue As String Dim mbresult As Integer strfullpath = "/" & List1.List(List1.ListIndex) & "/" & List2.List(List2.ListIndex) & "/" & List3.List(List3.ListIndex) Label5.Caption = strfullpath strvalue = opatrolagent.get(strfullpath & "/value") If strvalue <> "" Then

23 23 mbresult = MsgBox("The current value of " & strfullpath & " is: " & strvalue, 0, "Parameter Value") Else mbresult = MsgBox("There is no value for this parameter", 0, "Parameter Value") Set opatrolagent = Nothing End Sub Concatenating the string values of each of the listboxes list methods creates the full path to the parameter. We inserted the slash characters (/) between each string item to create a properly delineated path. strfullpath = "/" & List1.List(List1.ListIndex) & "/" & List2.List(List2.ListIndex) & "/" & List3.List(List3.ListIndex) In PATROL there are three types of parameters: Standard Collector Consumer In general, a collector parameter contains values to be used by consumer parameters. Therefore, if the user selects a collector parameter, a null string will be returned and no value will be displayed. Since we did not filter out collector parameters, we must handle the null string. If strvalue <> "" Then mbresult = MsgBox("The current value of " & strfullpath & " is: " & strvalue, 0, "Parameter Value") Else mbresult = MsgBox("There is no value for this parameter", 0, "Parameter Value") This simple if statement checks for the null string and displays a dialog indicating that There is no value for this parameter. The other arguments determine the type of icon that is displayed in the dialog and its title. Building the Application Build the application one more time to complete the form. Click on each of the list boxes, application instances, parameters and parameter values to display their values.

24 24 Click on any parameter and the following is displayed. Summary Building a Visual Basic application based on the PatrolAgent object is simple and very powerful. You can build anything from the most simple application status indicator to a full complex console. You can download the source code for this example as well as an additional application, PATROL Explorer that demonstrates most of the methods available to you through the PatrolAgent object from the BMC Software Developer Connection web site at devcon.bmc.com in the freeware area. PATROL Explorer is a PATROL Console written entirely in Visual Basic using the PatrolAgent COM object. PATROL Explorer demonstrates using the pslexecute method to create an event browser. Additionally, PATROL Explorer demonstrates using the psl %dump commands, profiling tools, the process list, and many PATROL Agent variables. The introduction of COM support to the PATROL Agent has opened unlimited possibilities to extend PATROL in the Windows NT environment.

25 25 Appendix A PATROLAgent Object Methods The PATROL Agent Object The following table defines the methods available to you from the PATROL Agent object. Function annotate(bstrname As String, [bstrformat As String], [pvardata]) As String Function annotate_get(bstrname As String, [bstrtimestamp As String]) As String Function blackout([bstrinst As String], [bstrperiod As String]) As String Function change_state(bstrname As String, bstrstate As String, [bstrdescr As String]) As String Function create(bstrname As String, [bstrlabel As String], [bstrstate As String], [bstrdescr As String], [bstrparent As String]) As String Function destroy(bstrname As String, [bstrdescr As String]) As String Function exists(bstrname As String, [bstrinherit As String]) As String Function get(bstrname As String) As String Function get_psl_errno() As Long Function get_ranges([bstrname As String], [bstrstatus As String]) As String Function get_vars([bstrobj As String], [bstrkeyword As String]) As String Function getenv(bstrname As String) As String Function history([bstritem As String], [bstrformat As String], [bstrcount As String]) As String Function is_var(bstrname As String) As String Function pdr(v1, v2) Sub print(message As String) Sub psh_done(pslprocid As Long, psh_errno As Long) Function PslExecute(bstrName As String, bstrscript As String, [pbstrerrlist As String], [pbstrwarnlist As String]) As String Sub set(bstritem As String, bstrvalue As String) Function set_alarm_ranges(bstralarmrangevalue As String, bstrglobalparamclassname As String, [bstrapplname As String], [bstrparamoid As String], [bstrparamfullpath As String]) As String Function set_psl_errno(psl_errno As Long) As Long Function set_psl_procid(pslprocid As Long, flag As Long) As <Unsupported variant type> Function unset(bstrname As String) As String