Using IBM Tivoli Monitoring V6.1 SOAP Services

Transcription

1 A technical discussion of IBM Tivoli Monitoring V6.1 SOAP Services May 2007 Using IBM Tivoli Monitoring V6.1 SOAP Services (With an emphasis on Tivoli Monitoring V6.1 z/os products) David Ellis May 2007 Copyright International Business Machines Corporation All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Using IBM Tivoli Monitoring V6.1 SOAP Services 1

2 Introduction Names such as XML, SOAP, XSL, HTTP, DOM, AJAX and JavaScript form the basis of what are roughly known as Web services. For the mainframe specialist that grew up in the days when all you needed to know was assembler, some Cobol, JCL, and how to write CICS or IMS applications, all this Web-based terminology can be overwhelming. Where should you start? What do you need to know? What can you ignore and how do you put any of it together to interact with IBM Tivoli Monitoring V6.1 in a way that will let you do something of value? This article guides you through the terminology and technology, and helps you to understand how to build your own Web-based applications to enhance your use of Tivoli Monitoring 6.1 when managing your z/os systems. Important: You must implement only the listed configurations. Over time, these configurations might be changed or expanded, however, you must use the services of certified IBM Tivoli Monitoring architects, services personnel, or IBM Business Partners to implement scenarios other than as described in this paper. The examples used in this document have been tested with Internet Explorer 6, Internet Explorer 7, FireFox 1.5 on Windows 2000, and Windows XP systems. While every effort has been made to ensure that the information and code examples contained herein are correct, it is based on personal experiences of the author and is therefore provided in the presently existing condition without modification. Using IBM Tivoli Monitoring 6.1 Web Services Page - 1 -

3 Description of Tivoli Monitoring Web Services Basically, Tivoli Monitoring V6.1 is equipped with an HTTP server (the same server that serves up Web pages the world over) that can handle SOAP (Simple Object Access Protocol) requests. The HTTP server can accept, act upon, and return XML documents that describe, in a structured form, the request and response to that request. When XML documents are referred, there is no physical document (like a text document on a hard drive). Rather these documents are virtual in that they exist in memory as objects within the processing language environment. Here s an example of a simple XML document: <myxml> <firstname>dave</firstname> <lastname>ellis</lastname> </myxml> Basically it s a hierarchical structure that can be represented like this: You can continue that level of hierarchical nesting down as far as you need. Each of the strings within the angled brackets such as <firstname> is a tag and the matching closing tag contains the same name but is preceded with a forward slash like this </firstname>. The two matching tags form a node and the data between the two matching tags is the data for that node (the tag name) but it does not have to be data, it can be more tags, extending the hierarchy down as far as your requirements dictate. For example the previous document can be extended to resemble this: <myxml> <firstname>dave</firstname> <lastname>ellis</lastname> <address> <street>123 Somewhere Drive</street> <city>raleigh</city> <state>nc</state> </address> </myxml> In this case the address node does not have any textual data of its own, rather it has child nodes that contain further data. Each of the legs of the hierarchy is known as a node and the nodes that form the document have a parent/child/sibling type of relationship that you use to extract the data from the document. Using IBM Tivoli Monitoring 6.1 Web Services Page - 2 -

4 One of the terms that you might come across is the DOM. DOM means Document Object Model, which is a way of describing the node structure used within your XML (or any other XML-like) document. For example, the HTML tags and data that make up a Web page source have a hierarchical structure just like an XML document and therefore have a Document Object Model of their own. The implication of documents having a DOM, as discussed later, is that you can use a variety of services to navigate though the document and extract data from it, but in a standard way. So basically what works for one document works for most any document that follows the same model. Creating a request XML document to perform a task The format of the request XML document depends on what the SOAP server accepted. For example: <request> <action>getaddress</action> <parm>dave Ellis</parm> </request> This example says do something (whatever getaddress represents on the SOAP server, such as retrieving a mailing address) and then passes it one parameter, the value of which in this case is Dave Ellis. Next you need to send the request XML document to the SOAP server using HTTP. When you type a Web site address in a browser, the address always starts with which is how you tell the browser and target site that you want communicate using HTTP over the TCP/IP connection between your browser and the target sites servers. HTTP is a way of exchanging data and responses between a client (typically your browser) and the server. It s a protocol. For example, I say this and you reply with that. There are two ways to send an XML document using HTTP. The first is called GET, which encodes the document parameters as part of the URL (that you see in the browser address bar). You ve probably seen text in the browser address bar that resembles this: This text is called URL encoding. The whole string is sent to the server when you press Enter and all the characters following the question mark are the parameters, coded as name and value pairs separated by ampersands. The %20 is how the browser encodes a space, so the value for the name parameter is xx yy. The problem with this method is that there is a limit to the length of data that you can include in a URL like this so it is restricted to fairly short requests. The second method is called POST and this method sends the data as an attachment to the main request, which implies that there is no limit to how big the request can be. Traditionally GET is used for requests that do not result in updates on the server while POST is used for updating requests, but this is not a strict rule and is becoming more blurred as Web pages send ever bigger request strings back to their servers. Using IBM Tivoli Monitoring 6.1 Web Services Page - 3 -

5 Returns made by the SOAP server If you are talking to a Web site, such as when you type a Web site name in a browser, the Web server returns an HTML document that the browser can interpret and render on the screen as a Web page. In the same way, a SOAP server returns an XML document. The XML document has the same sort of hierarchical structure as the request document but obviously contains the response data. For example, in response to the previous request, you might get back a document that resembles this: <data> <name>dave Ellis></name> <street>123 Somewhere Drive</street> <city>raleigh</city> <state>nc</state> </data> Basically, the HTTP request returns a typical US mailing address. In addition, the HTTP request returns information back to the client in status fields relating to the request. This information is not part of the response document but part of the HTTP interface process between the requesting client and the server. For example, you ve probably seen the 404 code on a Web site for page not found. The 404 code is a standard HTTP response code that indicates the requested resource was not found. A code of 200 means Ok, and there are many more, which are all documented on the W3C Web site (the governing body for Web protocols). So all you have to do in the application is send the request, get the response and returned data, take it apart, and do whatever you want with the application. Using IBM Tivoli Monitoring 6.1 Web Services Page - 4 -

6 Communicating with a SOAP server In this section, basic mechanisms and techniques are discussed for creating an application that communicates with a SOAP server, makes requests, and processes the returned data that can be used in a JavaScript environment, such as might be used by a Web page, to make requests to a SOAP server and process the returned documents. Remember that the same techniques discussed here can be used to build other applications in other environments using other languages and tools, for example Java, Perl, and even REXX. This section explains at a basic level how to communicate with the Tivoli Monitoring Web services and how to understand and process the data that is returned. JavaScript and the XMLHttpRequest Object There are many books and articles on the Web about JavaScript, but if you can write in REXX or Perl or any similar scripting type language you can understand how to use JavaScript. JavaScript is used within our Web page to communicate with the Tivoli Monitoring SOAP Server indirectly. To accomplish this type of communication, create an XMLHttpRequest object and then use the values and methods associated with that object to send the request to the SOAP server and get the response back. Description of an XMLHttpRequest object An XMLHttpRequest object is an object in the application environment (JavaScript in this case) that knows how to talk HTTP to a Web server to send and receive XML documents between the two. It also provides a variety of functions (methods) that you can use to process the returned document. Creating the XMLHttpRequest object Internet Explorer has a specific way of handling HTTP requests so you need to use something like the following code fragment in your script to create the object depending on the execution environment: var xmlhttp; // global var for xmlhttp object function CreateXMLHttpRequest() { if (window.activexobject) { // Internet Explorer xmlhttp = new ActiveXObject("Microsoft.XMLHTTP"); } else if (window.xmlhttprequest) { // The rest of the world xmlhttp = new XMLHttpRequest(); } } This example defines a global variable (because it is outside of any function) within the JavaScript environment, called xmlhttp, and then creates an XMLHttpRequest object and assigns it to the variable so that you can reference the properties and methods of that environment. Properties are the values assigned to the global variable or that you can assign, and methods are functional routines you can invoke to get the variable to do something. Using IBM Tivoli Monitoring 6.1 Web Services Page - 5 -

7 Sending the request to the SOAP server Next you need to create the request as a simple XML-formatted string in a variable and send it to the SOAP server using the XMLHttpRequest object you just created, as shown in the following example of code and as described previously: 1. var query = <request><action>getaddress</action><parm>dave Ellis</parm></request> 2. var url = " 3. xmlhttp.onreadystatechange = handleresponses; 4. xmlhttp.open("post",url,true); // true=process request asynchronously. 5. Set Parameters for Tivoli Monitoring SOAP CT_Get call: xmlhttp.setrequestheader("methodname", "CT_Get"); xmlhttp.setrequestheader("interfacename", "CT_SOAP"); xmlhttp.setrequestheader("messagetype", "Call"); xmlhttp.setrequestheader("content-type", "text/xml"); 6. xmlhttp.send(query); And that s how the request is sent. The following numbered items correspond to the line numbers in the previous script section: 1. Defines a variable called query and assigns the XML document text to it as a string. Typically, you obtain the data used in the request tags from input data fields from the hosting application such as a Web page. 2. Defines a variable called url and assigns the address of the SOAP server you want to communicate with, including the prefix, again as a simple text string. 3. Sets the name of a function that is called as the XMLHttpRequest object processes the request. 4. Opens the connection to the target server. Because the last parameter is true the request is processed asynchronously so that the JavaScript can continue to execute while the SOAP server is processing the request and returning the response. 5. Set these HTTP header parameters when making calls to the Tivoli Monitoring SOAP server, which are not typically required when making calls to standard SOAP servers unless the SOAP server requires them. 6. Sends the request XML to the server. Obtaining the response document. In step 3 above, we assigned the name of a JavaScript function to the XMLHttpRequest object attribute onreadystatechange. What that does is tell the request object to call a function in our JavaScript called handleresponses every time the request object receives a response from the SOAP server. It s important NOT to include brackets on the name of the function when doing the assignment to the XML request object, otherwise JavaScript will call the function instead of assigning a reference to it to the request object. So this is WRONG: Using IBM Tivoli Monitoring 6.1 Web Services Page - 6 -

8 xmlhttp.onreadystatechange = handleresponses(); Processing responses The request object has a property called readystate, and the request to the server is complete when readystate is equal to the value 4. The status property of the request object contains the response code from the server. For example, a response code of 200 means OK, 404 means not found, and so on. These codes are the same response codes illustrated previously for the HTTP request (because basically that s what you are using as the protocol for this conversation with the server). You need a JavaScript function to test for readystate being 4 (request complete) and status being 200 (OK). After you have those conditions you know that the request completed and it completed successfully (at least as far as the HTTP part of the server is concerned). The following JavaScript function is the handler you previously assigned: Function handleresponses() { if (xmlhttp.readystate == 4) // complete when readystate // equals four { if else (xmlhttp.status == 200) // status 200 means OK { doresults(); // call this function to // process the // response document. } { // Do request failed processing (status not = 200) } } } // end of function The request object invokes the previous function every time it receives a response or state change from the server (testing shows that it might be invoked several times with the same readystate value during a request). After the request has completed successfully, it calls another function called doresults to process the response document returned by the XML request object. Processing the response document The XML request object has two properties of interest. These properties include the responsetext and the responsexml. The responsetext property is the XML response document as a text string that you can display using a JavaScript alert function as follows: alert(xmlhttp.responsetext); Where xmlhttp is the variable you created previously to contain the XMLHttpRequest object. Using IBM Tivoli Monitoring 6.1 Web Services Page - 7 -

9 The responsexml property contains the response text in a structured form (the DOM for the response document) that you can navigate through using a variety of methods that are built into the XML request object. Assign the responsexml property to a variable to make it easier to work with, and because the previous response handler calls a function called doresults, when the request to the server completes, embed it in a function of that name, as in the following example: function doresults() { var xmldoc = xmlhttp.responsexml; // assign response doc to var : // code to process the : // document elements } Basically this defines a variable called xmldoc within the function (the variable names used can be anything of your own choosing; you don t have to use the names used here) and assigns the responsexml object to it from the xmlhttp request object. So now you have the response document in a variable that you can process. To get at the data within the document s DOM structure, you use the getelementsbytagname; method of the XML response document, as in the following example: var namenode = xmldoc.getelementsbytagname( name ); What that says is get all the elements in the document that have the name tag. Notice that you don t have to start with the top-level node name. This function returns another object that you must process as an array because there can be multiple nodes with the same name. Of course it is not as simple as referring to the entry in the array to get its value because that entry can be another collection of child nodes instead of data as in our case. To get at the data for the node, you have to use the following example code: var myname = namenode[0].childnodes[0].nodevalue; Note that you have had to refer to the element in the array that you want to process (namenode[0] is the first (or only) element) and also the first child node (element zero) because the node you are referring to might also have child nodes. Finally you can get the data value using the nodevalue attribute. If you know that there might be multiple name nodes in the XML response document and you want only the first one, you can use code similar to the following: var namenode = xmldoc.getelementsbytagname( name )[0]; Notice the [0] index identifier at the end. Because you identified the entry you want, the function returns the specific node object you requested, rather than an array and so the statement to get the data value from the entry becomes: Using IBM Tivoli Monitoring 6.1 Web Services Page - 8 -

10 var myname = namenode.childnodes[0].nodevalue; There is no [0] index indicator this time for the namenode variable name because namenode contains a specific element, rather than an array of elements. To process all the elements in an array of elements you can use code like this: var namenode = xmldoc.getelementsbytagname( name ); for (var i ; i < namenode.length ; i++) { var myname = namenode[i].childnodes[0].nodevalue; alert( name tag data value is < + myname + > ); } This example gets all the name elements in the response document and then loops through the elements and displays the value contained within the each. Of course in our simple example there is only one element so this is a bit of overkill but it does illustrate the process. Using IBM Tivoli Monitoring 6.1 Web Services Page - 9 -

11 Attributes and attribute data in XML tags As well as enclosing data, the tags within an XML document can also contain attributes within the tag boundaries. These attributes are not part of the data but can be using in conjunction with it and typically tell you something more about the data. For example they might indicate the type of data such as text or numeric, or tell you something else about the data without having to code additional tags within the XML document. For example an XML document might look like this: <employees> <employee hired= 4/1/2000 age= 43 >Fred Flintstones</employee> <employee hired= 6/17/2001 age= 23 >Barney Rubble</employee> </employees> In this example each <employee> tag defines not only the employee s name but also additional information about the employee, in this case the employee s hire date and age. The additional data are attributes of the <employee> tag. You can refer to these attributes in a number of ways, for example: var myattrs = xmldoc.getelementbytagname( employee )[0].attributes; This returns an array of attributes for the first <employee> tag. You can then refer to each attribute and its data, for example alert(myattrs.name[0]); displays the name of the first attribute which is hired in this case, whilst alert(myattrs.value[0]); displays the value for the first attribute which is 4/1/2000. Alternatively, you can use the getattribute() function to extract the data for known attributes, for example: xmldoc.getelementbytagname( employee )[0].getAttribute( hired ) returns the data for the hired attribute of the first <employee> tag. The only attribute/value pair that is used in the data tags within an XML response document returned from the Tivoli Monitoring SOAP server is the dt= number setting, for example: <CPU_Percent dt= number >10</CPU_Percent> There does not appear to be a corresponding value for the dt attribute when the data is textual. It also seems possible that you can see a numeric value as the data for a tag without the dt= number attribute specified. In such cases it might be possible for that data element to contain textual data, for example n/a even though the data being returned for the element in a particular row appears to be numeric. Using IBM Tivoli Monitoring 6.1 Web Services Page

12 The JavaScript sandbox and its impact on security Before a discussion about building Web-based application in JavaScript that communicate with a SOAP server, you need to be aware of the restrictions that exist on JavaScript applications executing within a browser or similar environment. The JavaScript environment enforces a sandbox around any running scripts. What that means is that, unless you tell the browser otherwise, the script can communicate only back to the domain that it was loaded from. So, if you load the Web page containing the script from your local PC hard drive, by default it can communicate only with services running on your PC. The practical effects of that restriction as applied to the development of SOAP client scripts are: You must have the Tivoli Monitoring SOAP server, which implies all the Tivoli Monitoring services as well, running on your local PC and have agents that connect to it for the products that you are developing your scripts for; or. You have to load your Web page and scripts from the Tivoli Monitoring SOAP server, which implies that you have access to it so that you can update them on that system. However all is not lost and as always there are ways around this limitation so that it becomes practical to load your scripts locally and still have them collect data from a remote SOAP server. Using IBM Tivoli Monitoring 6.1 Web Services Page

13 Internet Explorer For Internet Explorer you accept the warnings that are displayed when the Web page is loaded by rightclicking on the warning message and selecting Allow Blocked Content. Using IBM Tivoli Monitoring 6.1 Web Services Page

14 Then accept the Security Warning by clicking Yes: Using IBM Tivoli Monitoring 6.1 Web Services Page

15 Firefox browser For Firefox and similar browsers you need to include the following line inside any function that uses restricted services (the best way of determining which services within the script are restricted seems to be best done by experimentation at this point). try { netscape.security.privilegemanager.enableprivilege ('UniversalBrowserRead'); } catch(e) {} You also need to tell your browser to accept this by typing the following in the address bar: about:config Find the line signed.applets.codebase_principal_support and set it to true by double-clicking it. When you load your Web page or script, the browser issues a security warning that you must accept. You can also select Remember this option so that you do not have to accept the security warning every time you load the page. Using IBM Tivoli Monitoring 6.1 Web Services Page

16 Obtaining data from the Tivoli Monitoring SOAP server The CT_Get Request The Tivoli Monitoring SOAP server can respond to several different request types in the XML document that you send it. One of these request types is called CT_Get. CT_Get is the enclosing tag name in the requesting XML document that you send to the Tivoli Monitoring SOAP server. The Tivoli Monitoring SOAP server performs the action described by the tags and data enclosed within the CT_Get request and typically results in data being returned to the requestor in the response XML document. However it is interesting to note that it is also possible to initiate updates to the Tivoli Monitoring data tables the using the CT_Get method call. A simple CT_Get request XML document might look like this: <CT_Get> <userid>sysadmin</userid> <password>abcdefg</password> <object>managedsystem</object> <target>managedsystemname</target> </CT_Get> The data element tags within the CT_Get envelope (the enclosing CT_Get tags) are the parameters that the Tivoli Monitoring SOAP server uses to determine what the sender of the request wants to do and what security information to use to determine if the sender is authorized to perform that operation. In this case the security information is supplied in the <userid> and <password> tags. All tag names are case-sensitive and for the Tivoli Monitoring SOAP server, data contained within the tags is for the most part also case-sensitive since it is being processed directly by the Tivoli Monitoring SOAP server. Data that is passed to the managed system agent, may or may not be case-sensitive, depending on the agent code used to collect the data from the target system. The <object> tag tells the Tivoli Monitoring SOAP server the name of the attribute group that you want to obtain data from. In this case you are querying the ManagedSystem attribute group. This attribute group contains information about all the products and the managed systems registered at the hub for those products. The <target> tag tells the Tivoli Monitoring SOAP server where to direct the request. This particular request must be valid within the context of the Tivoli Monitoring architecture and again, it is casesensitive so basically code it as shown when accessing this table. Using IBM Tivoli Monitoring 6.1 Web Services Page

17 The ResponseXML document The ManagedSystem request described previously returns a XML response document that looks similar to this: <?xml version="1.0" encoding="utf-8"?> <SOAP-ENV:Envelope xmlns:soap-env=" SOAP-ENV:encodingStyle=" ENV:Body> <SOAP-CHK:Success xmlns:soap-chk = " xmlns="urn:candle-soap:attributes"> <TABLE name="o4srv.inodests"> <OBJECT>ManagedSystem</OBJECT> <DATA> <ROW> <Timestamp> </Timestamp> <Name>PRODPLEX:SYS:MVSSYS</Name> <Managing_System>TEST:CMS</Managing_System> <ORIGINNODE>PRODPLEX:SYS:MVSSYS </ORIGINNODE> <Reason></Reason> <Status>*ONLINE</Status> <Product>M5</Product> <Version> </Version> <Type>V</Type> <HLOCFLAG></HLOCFLAG> <HHOSTINFO>z/OS~ </HHOSTINFO> <HHOSTLOC></HHOSTLOC> <Host_Address></Host_Address> </ROW> </DATA> </TABLE> </SOAP-CHK:Success> </SOAP-ENV:Body> </SOAP-ENV:Envelope> <SOAP- Using IBM Tivoli Monitoring 6.1 Web Services Page

18 The response document has the following structure: The header information consists of all the SOAP-ENV and SOAP-CHK parts. The SOAP-CHK information can be used to determine if the request was accepted and processed normally or not. If the request fails for any reason the response document contains a <faultstring> tag that describes the reason for the failure and possibly a <detail> tag that contains further information. You can use the existence or absence of these tags to determine if the request was successful. If the request was processed and returned any data, then the document contains one <DATA> element. If the agent returns no data there is no <DATA> element within the returned document, but since you don t need the <DATA> element to process the response data, it is not too important. Within the <DATA> element there are from one to n <ROW> elements. Each <ROW> element represents the data from one row in the attribute group identified by the <object> tag in the requesting document. Within each <ROW> element there is a series of tags that correspond to the column names of the requested attribute group. Each <ROW> element contains the same tags although obviously the data contained within the tags changes from row to row. Note that there are no elements within the response document that define the attribute names returned for each <ROW> element, other than the tag names themselves within each <ROW> element. This means that to programmatically discover the column names contained within the <ROW> elements you need to process the DOM (Document Object Model) of the response XML document. But this task is not that hard to do, at least not to get to the information you need. In addition, by default the data rows seem to be returned in the order they occur within the selected table. So far as has been determined for the purposes of this paper, there is no mechanism to allow you to specify sort parameters on this basic SOAP request although you can do that, and much more when you get into the more advanced functions later on. Using IBM Tivoli Monitoring 6.1 Web Services Page

19 Requesting the managed systems list in JavaScript Before you can request any data from a managed system such as a z/os LPAR or a CICS region, you need to know which managed systems are registered to the Tivoli Monitoring environment that you are using. You can obviously look at the Tivoli Monitoring Client application and get the names from there but if you want to discover the managed system names programmatically, then here is one way to do it. Sending the Request First of all, you need to send a CT_GET request to the Tivoli Monitoring SOAP server to request the managed system names. This request was described earlier so here it is again: <CT_Get> <userid>sysadmin</userid> <password>abcdefg</password> <object>managedsystem</object> <target>managedsystemname</target> </CT_Get> The JavaScript code to send this request resembles this: var xmlhttp; var url = " + myipaddress + ":" + myport + "///cms/soap"; var query = "<CT_Get><userid>" + myuserid + "</userid><password>" + mypassword + "</password>"; query = query + "<object>managedsystem</object><target>managedsystemname</target>"; query = query + "<attribute>originnode</attribute>"; query = query + "<attribute>product</attribute>"; query = query + "<attribute>status</attribute>"; query = query + "<attribute>managing_system</attribute>"; query = query + "</CT_Get>" CreateXMLHttpRequest(); xmlhttp.onreadystatechange = checkcall; // set call back function name xmlhttp.open("post",url,true); // true=process request asynchronously. xmlhttp.setrequestheader("methodname", "CT_Get"); xmlhttp.setrequestheader("interfacename", "CT_SOAP"); xmlhttp.setrequestheader("messagetype", "Call"); xmlhttp.setrequestheader("content-type", "text/xml"); xmlhttp.send(query); Using IBM Tivoli Monitoring 6.1 Web Services Page

20 The previous code defines a variable to hold the request object and some variables to hold the URL of the Tivoli Monitoring SOAP server as well as the query string. Note that in this example the IP Address and port are variables, as are the user ID and password used for the request, which can be obtained from the invoking Web page or some other source. You can of course also hard-code the values if you wanted to. The query string specifies the attribute names that you want. In this example you are requesting the following attributes (columns): ORIGINNODE name, which is the managed system name as registered with Tivoli Monitoring. You will need this later to direct queries to the appropriate managed system. Product identifies the product, for example, M5 for OMEGAMON XE on z/os. Status is *ONLINE or *OFFLINE and defines the managed systems status. Obviously you cannot sent requests for data to a managed system that is offline Managing_System is the name of the Tivoli Enterprise Monitoring Server (monitoring server) that the managing system is running on. This server typically has a name of the form temsname:cms. You will need this later to direct queries to the appropriate monitoring server. The code then calls a function called CreateXMLHttpRequest, which is not shown here, that creates the XMLHttpRequest object and stores it in the xmlhttp variable. See the earlier description of how to create the request object. The code then sets the name of a function to be called as the request is processed (checkcall). Finally it opens the connection to the Tivoli Monitoring SOAP server, sets the request header parameters, and sends the query string to the server. That completes the sending of the request. Using IBM Tivoli Monitoring 6.1 Web Services Page

21 Processing the request response Each time the status of the request changes, the xmlhttp object you created invokes the specified callback function. In this case you specified a function call checkcall. The checkcall function looks like this: function checkcall() { if (xmlhttp.readystate == 4) // 4 = request complete { if (xmlhttp.status == 200) // 200 = request ok { doresults(); // process data rows } } A readystate of 4 from the request to the Tivoli Monitoring SOAP server means that the request is complete. A status of 200 means the http request was processed normally. The request itself can of course have failed but the 200 means that as far as the HTTP protocol is concerned, everything is working correctly. After you see a readystate of 4 (request complete) and a status of 200, the code calls the doresults function to process the returned data. You can add extra code to handle the situation where the status code is not 200. Using IBM Tivoli Monitoring 6.1 Web Services Page

22 Processing the request response data The first thing you need to do is check that the Tivoli Monitoring SOAP server processed your request successfully. For example you might have mistyped a tag name or the data within a tag of the request document. The following code snippet can be used to look for the faultstring tag in the response document and extract any error data: xmldoc = xmlhttp.responsexml; // save response xml object var faultstring = xmldoc.getelementsbytagname('faultstring')[0]; if (faultstring!= null) // something was wrong { var msg = "Unable to obtain Managed System list for reason '" + faultstring.childnodes[0].nodevalue + "'" alert(msg); } If there is no fault string then you can assume all is well and continue. The response data to the request is contained in one or more <ROW> elements within the XML document returned by the Tivoli Monitoring SOAP server. There is a single <DATA> element that encloses these but you don t need to worry about that unless you want to refer to all the data rows as a single element. The following statement creates an array of ROW elements from the response document. var xmlrows = xmldoc.getelementsbytagname('row'); To process the array of <ROW> elements and extract the information from each one, you can use a loop like this one: var msg= ; for (var i=0 ; i< xmlrows.length ; i++) { var myoriginnode = xmlrows[i].getelementsbytagname('originnode'); var myms = xmlrows[i].getelementsbytagname('managing_system'); var mystatus = xmlrows[i].getelementsbytagname('status'); var myproduct = xmlrows[i].getelementsbytagname('product'); msg += Product= +myproduct; msg += ORIGINNODE= +myoriginnode; msg += Status= +mystatus; msg += Managing_system= +myms+ \n ; } alert(msg); Using IBM Tivoli Monitoring 6.1 Web Services Page

23 The previous code extracts the data for the specified tags from each row and appends them to a message that is displayed in an alert dialog box when the loop completes. Important: To make subsequent requests for data for a particular product to the managed systems, you need to remember the values from the <ORIGINNODE> tag and the <Managing_System> tags from this data, as you need to plug those values into the requests to tell the SOAP server where to process the request and which managed systems you want the request to go to. Using IBM Tivoli Monitoring 6.1 Web Services Page

24 Obtaining data from a managed system Now that you know how to make requests to the Tivoli Monitoring SOAP server and process the response you get back from it, the process of obtaining real live monitoring data from it is straightforward. First you need to understand how the data is organized within the Tivoli Monitoring product and how to find out what to specify in a Tivoli Monitoring SOAP request to obtain specific data from a managed system. Tables All the data in Tivoli Monitoring 6.1 is organized into tables, just like a relational database table. These tables are known as Attribute Groups and each attribute is a column of the table. Unlike a database table though, when you request data for an attribute group, the request is sent to agent code on the target managed system, or sometimes on the hub monitoring server and collected in real time. Any data is returned to the requestor as one or more rows. Each row contains the same columns although obviously the data can be different for each row. For example, each row can represent an address space on a z/os system and the columns (attributes) are the information about that address space, such as job name executing within it, start time, CPU time used, and so on. Finding the attribute group for a workspace view The standard Tivoli Monitoring 6.1 client organizes the data into a series of workspaces that you can access either from the navigation tree or by using links from other workspaces. Each workspace is split into one or more views and each view displays data from an agent table. Within a workspace, multiple views can obtain data from a single table and present different attributes within each view. Use the following steps to determine the name of the attribute group for the data that you want to obtain using the Tivoli Monitoring SOAP service: Determine which workspace and view the data is contained in. Determine the query name associated with the workspace view. Determine the attribute group name associated with the query. Convert the attribute group name to the format required by the Tivoli Monitoring SOAP service. Using IBM Tivoli Monitoring 6.1 Web Services Page

25 Finding the workspace and view the data is contained in The first step involves looking at the data in the workspace views of the Tivoli Monitoring client and deciding which one you want to get data from using the Tivoli Monitoring SOAP service. For example, the following window shows the Address Space CPU Utilization workspace, the lower view of which is also called Address Space CPU Utilization and contains information about each address space on the selected managed system that is executing a job, edrunning a startedyou task, and so on: To obtain this data from the Tivoli Monitoring SOAP server, you need to determine the name of the attribute group associated with that lower view. To do this you must first determine the query associated with the view. Using IBM Tivoli Monitoring 6.1 Web Services Page

26 Determining the query associated with a view Right-click the data part of the lower view and select Properties, which brings up the properties dialog panel for the workspace view: You can see the name of the query in the Name field of the Description section. Using IBM Tivoli Monitoring 6.1 Web Services Page

27 Click the button marked Click here to assign a query that brings up the query editor for the current query: Also while you are here, make a note of the column name above the column with the ==$NODE$ text in it, which is the pretty version of the attribute name that contains the managed system name. You need this name later to ensure your query goes to the correct managed system. Using IBM Tivoli Monitoring 6.1 Web Services Page

28 Determine the attribute group name associated with the query The final step is to click the Add Attributes button. You are not going to change anything; you are just using this to obtain the name of the attribute group. The following Select attribute window is displayed: The Attribute Group name in the left panel of the window is the name of the attribute group that you want. Convert the attribute group name to the format required by the SOAP service In this final step, replace any spaces in the attribute group name with underscore characters. In this case, the attribute group name becomes Address_Space_CPU_Utilization. Note that these names are case-sensitive so you must code the name as shown in the window, replacing the space characters with underscores of course. Using IBM Tivoli Monitoring 6.1 Web Services Page

29 Requesting attribute group data To request data for a managed system you need three pieces of information that you now have: The formatted attribute group name, such as Address_Space_CPU_Utilization The Managed System name (ORIGINNODE), such as PRODPLEX:SYS:MVSSYS for a z/os LPAR The managed system name of the monitoring server system for that Managed System, such as TEST:CMS The following example shows the XML structure required to request all attributes and data rows for the Address_Space_CPU_Utilization attribute group from a specific managed system: <CT_Get> <userid>sysadmin</userid> <password>password</password> <object>address_space_cpu_utilization</object> <target>test:cms</target> <afilter>managed_system;eq;prodplex:sys:mvssys</afilter> </CT_Get> The <object> tag specifies the name of the attribute group collection you want to obtain. The <target> tag specifies the name of the monitoring server Managed System that hosts the agent that obtains the data. The <afilter> tag you have not seen before but basically it is a filter that is applied to the request when it is processed to limit the returned data to that specified by the predicate. In this case you are limiting the data to only that from the Managed_System names PRODPLEX:SYS:MVSSYS (remember that you obtained that earlier from the ORIGINNODE column when you queried the list of managed systems). You can specify multiple <afilter> tags to further limit the returned data, for example all address spaces where CPU % greater than 75%, but you can only logically AND the filters together at this level. There s no way to use this mechanism to logically OR the predicates together for example. The default action for this type of query is to return all rows of data containing all the attributes for the attribute group. Depending upon the attribute group being queried, the amount of data returned by such a query can be quite large. A later discussion explains how to limit the query to specific attributes and rows. Using IBM Tivoli Monitoring 6.1 Web Services Page

30 The data for the <afilter> tag used to select the managed system that the query is to go to has the form attribute_name;test;value, which requires you to know the attribute name. However the attribute name used by the Tivoli Monitoring SOAP server for the managed system column name (ORIGGINNODE) is assigned on a product-by-product basis. The column with the ==$NODE$ text in the query editor shown earlier contains the pretty attribute name, replace the spaces with underscore characters to obtain the name you must code in the afilter tag, but for now the following table shows the names used for some of the z/os products: Product Product ID Attribute Name z/os M5 Managed_System CICS CP Origin_Node Mainframe Networks N3 Origin_Node IMS IP Originating_System_Identifier DB2 PE/PM DP ORIGINNODE Storage S3 ORIGINNODE Management Console HL Managed_System Processing the attribute group response document As described earlier, if there is any data to be returned, then it is returned in the response document by the Tivoli Monitoring SOAP server and consists of from one to n <ROW> elements. Assume for now that the request returned the following <ROW> elements as the data part of the response document: <ROW> <Job_Name>PRODJOB1</Job_Name> <JESJOBID>JOB12345</JESJOBID> </ROW> <ROW> <Job_Name>CICSPROD</Job_Name> <JESJOBID>STC00352</JESJOBID> </ROW> There are many other tags surrounding these tags in the response document and this is a very cut-down example showing the <ROW> elements to keep things simple. In this example each <ROW> element has two child elements called Job_Name and JESJOBID. These contain the job/task name and the JES job or started task number associated with the job. If you know that this is what this particular request always returned, you can hard-code the column names in the processing code to extract the data and display it in an alert, or on a Web page possibly, a technique that was shown earlier in the section Processing the Request Response Data. Using IBM Tivoli Monitoring 6.1 Web Services Page

31 Extracting the tag names Another and slightly more flexible method of processing the response document, especially when you don t know what attributes will be returned, is to step through the Document Object Model (DOM) for the response document. A variation on this is to step through the DOM for one row of data and extract the attribute names from the row s child tags. When you have the tag names, you can use them as the header text for a table of the output data in your Web page, as well as use them to extract the data from subsequent rows using the getelementsbytagname function that you have seen previously. The one disadvantage to this method is that you must have at least one row of data returned by the query to extract the tag names. There are a couple of reasons why you need to discover the attribute names returned by the Tivoli Monitoring SOAP server: The names displayed by the Add Attributes dialog box that you used to discover the Attribute Group name are based on descriptive text taken from the attribute definitions in the attribute group rather than the actual attribute name. In fact, if you have a language pack installed you may not even see the English text used here because those names are installation-specific. The tag names returned by the Tivoli Monitoring SOAP server are the same names the server requires in its input request document, so discovering them from a row of a response document ensures that you have the correct attribute names to use in your subsequent requests. The following code shows how to process a single <ROW> element of the response document to extract the tag names from it and store them in an array. var objrow = xmldoc.getelementsbytagname('row')[0]; var tagnames = new Array(); // array to hold list of // attrib name var x = objrow.childnodes; // x = array of childnodes for (var i=0;i<x.length;i++) // loop through nodes { if (x[i].nodetype == 1) // text node { tagnames[tagnames.length] = x[i].tagname; // store tag name // in array } } The first line gets the first <ROW> element and stores it in a variable. You then create an array to hold the results (the tag names that you extract). Then you create an array of childnodes from the <ROW> element and step through that array looking for text nodes. Each text node is a tag name so you add it to the tagnames array that you created earlier. Now that you have all the attribute names in the tagnames array, you can step through every <ROW> element of the response document and for each row, extract the data for each attribute in the row since all the rows have the same attributes. Using IBM Tivoli Monitoring 6.1 Web Services Page

32 How you process that data after that is of course up to you. The following JavaScript example shows how you can obtain the attribute names and then step through the <ROW> elements, processing each one in turn to obtain the data for each attribute: function doresults() { var objrows = gblxmldoc.getelementsbytagname('row'); var tagnames = new Array(); // array to hold list of // attrib names tagnames = gettagnames(objrows[0]); // pass one row element // now go through all row elements and extract the attribute data // for eac for (var i=0;i < objrows.length; i++) // do all rows { for (var j=0;j < tagnames.length; j++) { var elm = // do all tags // in row objrows[i].getelementsbytagname(tagnames[j]); var elmdata=" ; // in case nodevalue is null! try {y = elm[0].childnodes[0].nodevalue;} catch(e) {elmdata= } // *** Attribute data in elmdata, // do something with it here *** } // tagnames loop } // rows loop } // doresults function function gettagnames(objrow) { // Function to extract attribute names from a single row element // and return them to the caller as an array object } var x = objrow.childnodes; var tagnames = new Array(); for (var i=0;i<x.length;i++) { if (x[i].nodetype == 1) } return tagnames; // x = array of childnodes // array to hold tag names // loop through nodes // text node { names[names.length] = x[i].tagname; // store tag name // in array } // return array of tag names to caller Using IBM Tivoli Monitoring 6.1 Web Services Page

33 Specifying which attributes to obtain in a request Instead of letting the request default to every attribute for an attribute group it is useful in many cases to limit the data returned by a request to specific attributes. Limiting the data returned has the benefit of making your code execute faster and also reduces the amount of data being processed by the Tivoli Monitoring servers as well as passing over the network. Limit the data returned by using the <attribute> tag within your request document. You add one or more attribute tags to your XML request. Each tag, which must be matched by a closing </attribute> tag, contains the name of an attribute that belongs to the attribute group that you are requesting data for. Your request for data from the Address_Space_CPU_Utilization attribute group might now look like this: <CT_Get> <userid>sysadmin</userid> <password>password</password> <object>address_space_cpu_utilization</object> <target>test:cms</target> <afilter>managed_system;eq;prodplex:sys:mvssys</afilter> <attribute>job_name</attribute> <attribute>jesjobid</attribute> <attribute>cpu_percent</attribute> </CT_Get> You must code the <attribute> tag exactly as shown with all lowercase letters. You must code the attribute name with the correct case. For example there is no attribute called JESJobId in the Address_Space_CPU_Utilization attribute group. There is an attribute called JESJOBID. Notice that the only difference is the case used for the attribute name. The Tivoli Monitoring SOAP server is casesensitive. If you code an incorrect attribute name the Tivoli Monitoring SOAP server returns an error message in the response document and the request fails. This is why it is useful to initially extract all the tag names for an attribute group from a default response document and programmatically extract the attribute names. Note that if you code the same attribute name more than once in the request, the Tivoli Monitoring SOAP server returns only one instance of the attribute name in each row of the response document. Using IBM Tivoli Monitoring 6.1 Web Services Page

34 Filtering the data returned by a request You have already seen an example of the <afilter> tag. Basically the <afilter> tag allows you to specify one or more predicates that are used to select specific rows of data to be returned to the requestor. The limitation of the <afilter> tag is that they can be only ANDED together. That is, you can specify only if this is true AND that is true, and you cannot say, if this is true OR that is true to select rows of data. Each predicate is enclosed within the <afilter> tag and the matching closing </afilter> tag, and has the form: <afilter>attribute_name;test;value</afilter> You can code only one predicate within each <afilter> tag. Again the attribute name is case-sensitive so you must specify it correctly. In case the previous code is hard to reada semi-colons are used to separate the three fields of the predicate. You can use the following relational operators: EQ NE GT LT GE LE Equal Not equal Greater Than Less Than Greater Than or Equal Less Than or Equal For example: <afilter>job_name;eq;cicsprod</afilter> or <afilter>cpu_percent;gt;80</afilter> Thus a request to return selected attributes for all address spaces with CPU usage percentage greater than 80% might look like this: <CT_Get> <userid>sysadmin</userid> <password>password</password> <object>address_space_cpu_utilization</object> <target>test:cms</target> <afilter>managed_system;eq;prodplex:sys:mvssys</afilter> <afilter>cpu_percent;gt;80</afilter> <attribute>job_name</attribute> <attribute>jesjobid</attribute> <attribute>cpu_percent</attribute> </CT_Get> Using IBM Tivoli Monitoring 6.1 Web Services Page

35 Be aware of how the data is returned by the agent to correctly use the afilter attribute to test numeric values. For example a numeric value can be displayed as 29.4 on the client workspace and is returned in the same form by a query to the SOAP server. Internally the data is processed as an integer with a value of 294. When returning such data the SOAP server and the client GUI use the formatting information contained in the products configuration files to correctly present the data. However the reverse is not true for the SOAP interface. You must supply the predicate value based on the manner in which the data is stored, not how it is presented. Thus, in the previous example, if CPU_Percent is displayed as an integer with no decimal places the previous test is correct. However if it displayed as 29.4 for example, then you must code the afilter predicate like this to test for a value greater than 80.0: <afilter>cpu_percent;gt;800</afilter> In many workspaces a single table provides data for multiple views within the workspace. In such situations the agent is invoked only once and filtering is used to select the data for each view. You can determine the filters used for a view by clicking the Filters tab on the properties window of the workspace view: In this example you can see that the data is limited to rows where CPU Percent is greater than 0.0. You can transfer the same filtering criteria to your Tivoli Monitoring SOAP query by coding an <afilter> tag like this: <afilter>cpu_percent;gt;0<aflter> Using IBM Tivoli Monitoring 6.1 Web Services Page

36 Passing parameters to agents Many of the agent modules accept parameters when called and can return different sets of data depending on the input parameters. For example, an agent can return information about all address spaces when called with no parameters or about a single address space when called with an address space ID. Other agents may only function when passed the required parameters. So how do you find out the parameters an agent accepts, and how do you pass those parameters to the agent? The second part of that question is the easiest to answer since you have already seen the solution. You use the <afilter> tag. For example, to pass an address space ID to an agent, you might code something like this in your query: <aflter>asid;eq;123</afilter> Even if you pass other parameters in <afilter> tags to the agent, if the agent does nothing with them they are ignored by the agent. They are however used to filter the returned data, as previously shown. Finding the parameters that an agent accepts The easiest way to determine which parameters an agent accepts using the Tivoli Monitoring client is to look at the query associated with the workspace view that you want to use as the basis for your request. For example, you want to obtain Address Space CPU usage details for a specific address space. This data is contained in the following lower view of the Address space CPU Usage Details workspace: Right-click the lower view and select properties to open the properties window for the view, like this: Using IBM Tivoli Monitoring 6.1 Web Services Page

37 In the Formula section you can see the parameters passed to the agent. You have already seen how the Managed System parameter is used, but this query also includes an additional parameter of ASID == $LINKASID$. The value to the left of the == symbol is the attribute name that you need to code in your <afilter> tag to pass the value you specify to the agent. The symbol to the right, $LINKASID$ in this case, is used by the link wizard. As before, when determining attribute names, if the attribute name contains spaces, replace them with underscore characters and allow for decimal places in the formatted output, for example: <afilter>cpu_percent;gt;80</afilter> This tests for the value being greater than 8, not 80 since the value displays with one decimal place in the client. Using IBM Tivoli Monitoring 6.1 Web Services Page

38 Issuing native SQL So far you have seen how to issue basic queries to the Tivoli Monitoring SOAP server to retrieve data from the various agents using the built in facilities of the CT_Get function. In this section the ability of the Tivoli Monitoring SOAP server to process native Tivoli Monitoring SQL statements is discussed. Instead of specifying all the parameters for the request as tags in the request XML document, you can also code the SQL directly within the request document by using the <sql> tag, for example: <CT_Get> <userid>sysadmin</userid> <password>password</password> <table>o4srv.utctime</table> <sql> SELECT ASCPUUTIL.JOBNAME, ASCPUUTIL.CPUPCT, ASCPUUTIL.IORATE FROM KM5.ASCPUUTIL AT('TEST:CMS') WHERE (ASCPUUTIL.ORIGINNODE = "PRODPLEX:SYS:MVSSYS" AND (ASCPUUTIL.CPUPCT > 0.0 OR ASCPUUTIL.IORATE > 0.0)) ORDER BY ASCPUUTIL.CPUPCT DESC </sql> </CT_Get> In this request you are now coding a table name in the table tag instead of the attribute group name that you used previously within the <object> tag. The Tivoli Monitoring SOAP server returns the attribute group name in the <object> tag of the response document. You can code any valid table name for this parameter since the table names used for the query come from the embedded SQL. This entry keeps the Tivoli Monitoring SOAP server happy, however if you don t want to code a product table name here you can use any common platform table name such as O4SRV.UTCTIME, which is the Universal_Time attribute group table. The SQL for the request is enclosed within the <sql> and </sql> tags. The AT( TEST:CMS ) operand replaces the <target>test:cms</target> tag of the original CT_Get request. The ASCPUUTIL.ORIGINNODE = "PRODPLEX:SYS:MVSSYS" part of the WHERE clause replaces the <afilter>managed_system;eq;prodplex:sys:mvssys</afilter> tag of the original CT_Get request that you used to ensure that you obtain only the data from a specific managed system. As you can see, you can code additional predicates within the WHERE clause, in this case you want only those rows returned where the value in the CPUPCT column is greater than zero or the value in the IORATE column is greater than zero. The SELECT statement specifies the table and column names that you want to retrieve while the FROM statement specifies the application name (KM5 in this case) and table name that you are querying. The other elements to notice about this query are: Using IBM Tivoli Monitoring 6.1 Web Services Page

39 The WHERE clause can contain both AND and OR predicates, thus allowing more complex queries than can be issued using the standard CT_Get interface. You can sort the returned output on one or more columns in both descending and ascending order. In this case you are sorting in descending order on the CPUPCT column. The FROM operand specifies the application, KM5 in this case, and the internal table name that the data is to be selected from which is ASCPUUTIL in this example. You are no longer using the attribute group name for the table or the attribute names for the data that you want to obtain. Instead you are using the internal product names for the table and columns. The most important part to note when using SQL like this is that you have to use the internal names for the table and columns being queried. When you refer to attribute groups and attribute group attributes (as opposed to attributes of an XML tag) you are referring to the original method that was discussed earlier to obtain data from the Tivoli Monitoring SOAP server. When you are referring to tables and columns you are referring to the names that you must use to issue SQL requests natively. Basically, Attribute Group = Table and Attribute Group Attribute = Column. Note also that you cannot mix the two techniques; you can either issue native Sre used to QL as shown here or the method shown earlier using the request tags to specify the request parameters. Using IBM Tivoli Monitoring 6.1 Web Services Page

40 Determining the Application and Table Name to use Using the Tivoli Monitoring SOAP Server The easiest way to do this is to use the mechanism that you have already seen and this is to issue a basic CT_Get request using the attribute group name as the object name, for example: <CT_Get> <userid>sysadmin</userid> <password>password</password> <object>address_space_cpu_utilization</object> <target>test:cms</target> <afilter>managed_system;eq;prodplex:sys:mvssys</afilter> </CT_Get> This returns: <?xml version="1.0" encoding="utf-8"?> <SOAP-ENV:Envelope xmlns:soap-env=" SOAP-ENV:encodingStyle=" <SOAP-ENV:Body> <SOAP-CHK:Success xmlns:soap-chk = " xmlns="urn:candle-soap:attributes"> <TABLE name="km5.ascpuutil"> <OBJECT>Address_Space_CPU_Utilization</OBJECT> <DATA> : : etc; In the response you can see the <table> tag has an attribute associated with it of name and the value of this attribute is KM5.ASCPUUTIL. This is the application and table name that you need to code within your SQL statement. Using IBM Tivoli Monitoring 6.1 Web Services Page

41 Using the product DOC file Another way to obtain the table name to use, and this is probably the better way since you need this file for the rest of our information as well, is to obtain the product DOC file. For example, for the KM5 product, the doc file is called DOCKM5 on the distributed platform and KM5DOC on the host platform. On the distributed platform, the DOC files are located in the CNPS subdirectory of the C:\IBM\ITM directory, which is the default Tivoli Monitoring home directory. On the host platform you can find the DOC files in the RKANDATV library allocated to the monitoring server address space. If you browse this file you see something like this for each table: *OBJECT: *TABLE: *OCCURS: *SAMPLE: *LOCATOR: *DLL: *SHARE: *INDEX: *INDEX: etc; Address_Space_CPU_Utilization ASCPUUTIL M O KRACXLOC KRANDREG Y IRAKEY1 ORIGINNODE IRAKEY1 JOBNAME The *OBJECT entry specifies the attribute group name, whist the *TABLE: entry specifies the internal table name. Using IBM Tivoli Monitoring 6.1 Web Services Page

42 Finding the column names you can use for a table Unfortunately it appears that there is no way to query the Tivoli Monitoring SOAP server to obtain the actual internal column names for a table as there was when using the Attribute Group name. Recall that if you just coded the Attribute Group name in a CT_Get request, the Tivoli Monitoring SOAP server returns all attributes associated with the attribute group you specified, assuming there is any data in that attribute group of course. When using native SQL, there is no way to issue something like this: SELECT * FROM KM5.ASCPUUTIL etc And have it return all columns for the specified table. So to issue native SQL, you need to know the column names for a table so that you can code them in the SELECT statement. To do that you need to look further into the product DOC file. If you look further down the KM5 product s DOC file under the ASCPUUTIL table for example you will see entries like this: *ATTR: *CAPTION: *COLUMN: Managed\System Managed\System ORIGINNODE *ATTR specifies the attribute name. This name is displayed in the Tivoli Monitoring portal client displays unless a *CAPTION entry is also specified, in which case that is used. In these entries a backslash indicates a line break while an underscore character is displayed as a space character. The *COLUMN entry defines the internal column name and is the name that you need to code in your SQL statement. So for example the CPU Percent attribute entry looks like this: *ATTR: *CAPTION: *COLUMN: CPU\Percent CPU\Percent CPUPCT This example shows that the internal column name for the CPU Percent attribute is CPUPCT. These names are typically derived, more or less, from the attribute name and so they make some sort of sense, at least to English speakers. Now that you know where to obtain attribute group and attribute names from for a product, you can also use this method to obtain the values to plug into the original CT_Get requests you looked at originally that used attribute group and attribute names. Using IBM Tivoli Monitoring 6.1 Web Services Page

43 Coding column names in SELECT statements Column names are always be uppercase. There are two ways that you can code the column names within a SELECT statement, these are: tablename.columnname columnname For example: SELECT ASCPUUTIL.JOBNAME, ASCPUUTIL.CPUPCT FROM or SELECT JOBNAME, CPUPCT FROM Both of the above are valid but deciding to use one code one over the other depends on the table or tables that you specify in the FROM part of the SELECT clause. If you code only a single table name to obtain data for, then either form is valid since there is only one table to get the data from. However, when extracting data from multiple tables you must specify which table each column is to be extracted from, therefore you must code the first form of the statement and prefix each column name with the table name where it is found. For example, to extract data from columns in the ASCPUUTIL and ASGNWAIT tables with a single select statement, you might code something like this: SELECT ASCPUUTIL.JOBNAME, ASCPUUTIL.CPUPCT, ASCPUUTIL.IORATE, ASGNWAIT.ASNAME FROM KM5.ASCPUUTIL, KM5.ASGNWAIT WHERE etc In this example, because you are extracting data from multiple tables, you must prefix the column names with the table name that the column belongs to. Using IBM Tivoli Monitoring 6.1 Web Services Page

44 Joins As far as is known by this author, the Tivoli Monitoring SOAP server SQL processor does not support joins. Thus, as shown in the example in the previous section, while it is possible to extract data from multiple tables with a single select statement, there is no mechanism to relate rows in one table to rows in another. For example, the ASNAME column of the ASGNWAIT table contains the name of the job or started task running in an address space. The JOBNAME column of the ASCPUUTIL table contains the same data. If you code a single select statement like the following statement to select both of these columns, both columns are returned for each row but the data returned for each column of each row is based on the order of data received from the agent. SELECT ASCPUUTIL.JOBNAME, ASGNWAIT.ASNAME FROM KM5.ASCPUUTIL, KM5.ASGNWAIT WHERE etc Because these two tables have different organizations, the data for each row ends up being mixed, rather than aligned based on a common key, for example: <ROW> <JOBNAME>PCAUTH</JOBNAME> <ASNAME>*MASTER*</ASNAME> </ROW> <ROW> <JOBNAME>PCAUTH</JOBNAME> <ASNAME>PCAUTH</ASNAME> </ROW> <ROW> <JOBNAME>PCAUTH</JOBNAME> <ASNAME>RASP</ASNAME> </ROW> <ROW> <JOBNAME>PCAUTH</JOBNAME> <ASNAME>TRACE</ASNAME> </ROW> etc As you can see from the above sample result set, the data for each table column is returned in the order it was received from each agent. If you attempt to use a WHERE clause to relate columns in one table to columns in another like this for example: WHERE ASCPUUTIL.JOBNAME =ASGNWAIT.ASNAME Then, all that happens is that the WHERE clause is applied to the result set and only those rows where both columns contain the same name are returned. In the previous example data, that is the PCAUTH column only. Using IBM Tivoli Monitoring 6.1 Web Services Page

45 Built-in functions for SELECT statements The Tivoli Monitoring SOAP server SQL processing includes the following built-in functions that you can use to summarize data returned by an SQL query: COUNT() SUM() MAX() MIN() AVG() Returns count of specified column in result set Sums value of specified column from result set Returns max value of specified column from result set Returns min value of specified column from result set Returns average value of specified column from result set For example: SELECT COUNT(JOBNAME) FROM etc Returns the number of occurrences of the JOBNAME column that were returned by the query. Note that in this case, even though a column such as JOBNAME typically contains string data, the SQL processor assigns the dt= number attribute to the column s tag to indicate that the data contained by the tag is numeric. You can apply the functions MAX and MIN to string data. In such cases the function returns the last or first entry from the result set based on the collating sequence of the character set. For example MIN(JOBNAME) might return AP1 (a job name of AP1) while MAX(JOBNAME) might return ZFS (a job name of ZFS). If you code other columns in the same SQL statement, there is no guarantee that the data returned is from matching rows, for example SELECT CPUPCT, MAX(JOBNAME) FROM etc Might return data like this: <ROW> <CPUPCT dt="number">0</cpupct> <JOBNAME>ZFS</JOBNAME> </ROW> You cannot assume that the CPUPCT data value is actually for the JOBNAME that was returned. After you start using functions to manipulate the data returned by a query, each column, even within a single row, is unique and might not have any relationship to other columns of data within that row. Using IBM Tivoli Monitoring 6.1 Web Services Page

46 Similarly: SELECT AVG(CPUPCT), JOBNAME FROM etc Might return: <ROW> <CPUPCT dt="number">1</cpupct> <JOBNAME>*MASTER*</JOBNAME> </ROW> Again, you cannot assume that the average CPUPCT value returned has anything to do with the JOBNAME value that was returned. What you have done is taken the average CPUPCT value for all data rows returned by the agent, which has then been returned in a single row, along with the first row of normal data containing the JOBNAME column. In effect you are mixing summarized data with regular tabular data and as you can see, this does not work too well. Another interesting thing to note about the SQL function processor is that if you code an incorrect function name, the processor simply ignores it and returns the data exactly as if you had not coded a function name at all. For example, you might code this to ensure that job names are always uppercase: SELECT UPPER(JOBNAME) FROM etc Because there is no UPPER function, the SQL processor ignores it and returns the job name unaltered. Because job names are always uppercase anyway you might assume the function is working as expected when it is being ignored. Using IBM Tivoli Monitoring 6.1 Web Services Page

47 Sorting the selected data You can sort the returned data in both ascending and descending order on multiple columns by using the ORDER BY statement on the request SQL. For example: <CT_Get> <userid>sysadmin</userid> <password>password</password> <table>o4srv.utctime</table> <sql> SELECT ASCPUUTIL.JOBNAME, ASCPUUTIL.CPUPCT, ASCPUUTIL.JOBNAME, ASCPUUTIL.IORATE FROM KM5.ASCPUUTIL AT('TEST:CMS') WHERE (ASCPUUTIL.ORIGINNODE = "PRODPLEX:SYS:MVSSYS" AND (ASCPUUTIL.CPUPCT > 0.0 OR ASCPUUTIL.IORATE > 0.0)) ORDER BY ASCPUUTIL.CPUPCT DESC, ASCPUUTIL.IORATE ASC </sql> </CT_Get> In this example the returned data is sorted in ascending order on the CPUPCT column and then in descending order on the IORATE column. This sorting gives you the highest CPUPCT values first and then where rows have the same CPUPCT value they are returned in increasing IORATE order. Here s part of the output from this request: <ROW> <JOBNAME>WLM</JOBNAME> <CPUPCT dt="number">21</cpupct> <IORATE dt="number">0</iorate> </ROW> <ROW> <JOBNAME>*MASTER*</JOBNAME> <CPUPCT dt="number">21</cpupct> <IORATE dt="number">26</iorate> </ROW> <ROW> <JOBNAME>SMFGDMP</JOBNAME> <CPUPCT dt="number">21</cpupct> < IORATE dt="number">3483</iorate> </ROW> You can also sort on textual data in the same way, such as the JOBNAME column, to obtain a result set in alphabetical order. Note: The ORDER BY does not work when the HAVING or GROUP BY clause are also specified (see later). Using IBM Tivoli Monitoring 6.1 Web Services Page

48 Grouping data returned by functions When using functions such as SUM, AVG, and so on to summarize data, you can group the resultant data based on another column by using the GROUP BY operand. Note that you cannot use the GROUP BY function unless you are using a valid function on one of the selected columns (when tried with an incorrect function, the browser became unresponsive). For example, the z/os product table for orphaned common storage by address space (KM5.ASCSUNOW) contains JOBNAME, AREA and SIZE columns, and might contain data as shown in the following table: JOBNAME AREA SIZE JOB1 CSA 1000 JOB1 ECSA JOB1 SQA 400 JOB2 SQA 500 JOB3 SQA 400 The SQL might then look like the following: SELECT JOBNAME, SUM(SIZE) FROM KM5.ASCSUNOW AT('TEST:CMS') WHERE (ASCSUNOW.ORIGINNODE = "PRODPLEX:SYS:MVSSYS" AND AREA=1) GROUP BY JOBNAME In this example you are using the SUM function to calculate the sum of all SIZE columns for each job name. So the returned data looks like this: JOBNAME SUM(SIZE) JOB JOB2 500 JOB3 400 Using IBM Tivoli Monitoring 6.1 Web Services Page

49 Now you are probably asking, what is that AREA=1 operand in the WHERE clause? If you look at the AREA entry for the ASCSUNOW table in the KM5 product DOC file you see the following values: *ENUM: *ENUM: *ENUM: *ENUM: CSA=1 ECSA=2 SQA=3 ESQA=4 These are enumerated values. Each number corresponds to the associated text string. The agent code returns a number as the data for the column that the Tivoli Monitoring portal client then converts and displays as a textual string. Because you are using raw SQL here you must do that conversion yourself, hence the use of the numeric value in the WHERE clause, rather than the textual string. Thus in the previous example you are only summarizing orphaned CSA for each job name returned. If you displayed the AREA column in the result set, you also see the data returned as a numeric value, rather than the interpreted string. For example: SELECT JOBNAME, AREA, SIZE FROM KM5.ASCSUNOW AT('DCUT13:CMS') WHERE (ASCSUNOW.ORIGINNODE = "LPAR400J:SYS:MVSSYS" AND AREA=1) Returns: <ROW> <JOBNAME>AFOG018</JOBNAME> <AREA dt="number">1</area> <SIZE dt="number">1440</size> </ROW> etc Using IBM Tivoli Monitoring 6.1 Web Services Page

50 Filtering grouped data: the HAVING clause When grouping data as shown previously, you cannot use the WHERE clause to filter the summarized and grouped data. Instead you must use the HAVING clause, although you must still have a WHERE clause to specify the correct managed system name and to pass any parameters to the agent. For example, to select only summarized rows (jobs) from the previous example with a total orphaned CSA size of more than 1000, you can code something like this: SELECT JOBNAME, SUM(SIZE) FROM KM5.ASCSUNOW AT('TEST:CMS') WHERE (ASCSUNOW.ORIGINNODE = "PRODPLEX:SYS:MVSSYS" AND AREA=1) GROUP BY JOBNAME HAVING SUM(SIZE) > 1000 This example returns only the summarized row for JOB1 in this instance. The format of the HAVING clause is: HAVING function(column) test value However, you need to be careful when coding the test operand. In the previous example the greater than symbol > works correctly, however if you code a less than symbol < you receive an XML parsing error from the Tivoli Monitoring SOAP server. This parsing error occurs because the SQL is embedded within the XML document tags and the parser treats the less than symbol as the start of an XML tag, which it obviously isn t. To overcome this, you can code entity names instead of the symbols for the test operand: To specify a test of: Code this: Equal = Greater than > or > Less than < Not equal <> Greater than or equal >= Less than or equal <= Thus the previous example becomes: SELECT JOBNAME, SUM(ALLOC) FROM KM5.SOMETABLE WHERE etc GROUP BY JOBNAME HAVING SUM(ALLOC) > 1000 You must code the entity names as lowercase as shown and remember to include the trailing semi-colon. Using IBM Tivoli Monitoring 6.1 Web Services Page

51 Passing parameters to agents in SQL You saw earlier how to use the <afilter> tag to pass parameters to agents when you re not using native SQL. If you ve not already guessed, the <afilter> tag becomes part of the WHERE clause that the Tivoli Monitoring SOAP server generates from your input tags. Thus the process of passing parameters to agents when using SQL is the same as specifying filtering criteria in your SQL statement. For example, if an agent accepts an input value in the ASID column of the request then you might code something like this: SELECT etc WHERE ASID=123 AND etc etc Using IBM Tivoli Monitoring 6.1 Web Services Page

52 XSL transformations If you process XML documents, then at some point you come across XSL and XSL Transformations. XSL stands for extensible Stylesheet Language and XSL Transformations, also known by the abbreviation XSLT, are mechanisms that can be used to transform an XML document into a different form of XML document such as, for example, an HTML Web page. Now you might ask why you need to bother with yet another technology when you can do everything you need in JavaScript. The fact is though, that as the result set grows in size it takes longer to process it using pure JavaScript. So much so that your browser might appear to stop, or the browser might issue an alert because it determines that the script might be looping. Neither option is a very friendly event for your user. XSLT transformations have the advantage of executing much more quickly than JavaScript to accomplish the same thing. This advantage also means that you can embed the conversion of the XML response data to HTML into a separate file from the main line JavaScript, thus making it easier to maintain. Loading and applying the XSL document Assume you have a pre-written XSL transformation document that you want to apply to your Tivoli Monitoring SOAP response document to convert the response document <ROW> elements into an HTML fragment. The first step is to load the XSL document into your JavaScript. The following JavaScript function loads the passed file name and returns it to the caller of the function: function loadfile(file) { var reqobj = new Object(); if (document.implementation && document.implementation.createdocument) { } reqobj = document.implementation.createdocument("", "", null); reqobj.async=false; // mozilla 1.4 and up support //synchronous load reqobj.load(file); } else if (window.activexobject) // IE { reqobj= new ActiveXObject("Msxml2.FreeThreadedDOMDocument"); reqobj.async = false; reqobj.load(file); } return reqobj; So to call this function to load an XSL file called row2table.xsl for example, you can use something like this: var xsl=loadfile("rows2table.xsl"); After you have loaded your XSL transformation document, you need to apply it to the XML response document that was returned by the Tivoli Monitoring SOAP server. The following example JavaScript Using IBM Tivoli Monitoring 6.1 Web Services Page

53 function applies the passed xsl object to the passed XML object and returns the resultant fragment to the caller: function Transform(myXML,myXSL) { if (document.implementation.createdocument) { myxslproc = new XSLTProcessor(); myxslproc.importstylesheet(myxsl); // Mozilla else } var fragment = myxslproc.transformtofragment(myxml, document); return fragment; } { // IE var xslt = new ActiveXObject("Msxml2.XSLTemplate.3.0"); xslt.stylesheet = myxsl; xslproc = xslt.createprocessor(); xslproc.input = myxml; xslproc.transform(); return xslproc.output; } As you can see from the example there are different ways to do this for Internet Explorer and Mozillabased browsers. To call this function you can use something like this, which assumes the XSL object is in a variable called xsl and the XML response document is in a variable called xmldoc : var myhtml=transform(xmldoc,xsl); The returned transformed document object is returned by the function and saved in a variable called myhtml. Using IBM Tivoli Monitoring 6.1 Web Services Page

54 After you have the returned HTML fragment, you can insert it into the hosting Web page for display, or process it further using JavaScript or even another XSL transform. For example the following code fragment places the returned HTML into an area of the hosting Web page with an ID of testarea. if (window.activexobject) { // IE document.getelementbyid("testarea").innerhtml=""; document.getelementbyid("testarea").innerhtml=myhtml; } else // Mozilla etc { document.getelementbyid("testarea").innerhtml=""; document.getelementbyid("testarea").appendchild(myhtml); } testarea can be an empty DIV on the hosting HTML page, for example: <div id="testarea"></div> Using IBM Tivoli Monitoring 6.1 Web Services Page

55 XSL document structure XSL transformation documents are also XML documents. That means that they have the same sort of tag structure that any other XML document has with each opening tag matched to a corresponding closing tag. The transformation is achieved through one or more templates that are applied to the source XML document, along with XSL processing instructions and non- XSL statements that are written out as is. The following example shows the actual XSL transformation document used previously to convert the <row> elements of the Tivoli Monitoring SOAP server response document to an HTML fragment: <?xml version="1.0" encoding="iso "?> <xsl:stylesheet version="1.0" xmlns:xsl= xmlns:itm="urn:candle-soap:attributes"> <xsl:output method="html"/> <xsl:template match="/"> <html> <body> <table border="1"> <xsl:for-each select="//itm:data/itm:row"> <tr> <xsl:for-each select="*"> <xsl:choose> <xsl:when test="@dt='number'"> <td align="right"><xsl:value-of select="."/></td> </xsl:when> <xsl:otherwise> <td align="left"><xsl:value-of select="."/></td> </xsl:otherwise> </xsl:choose> </xsl:for-each> </tr> </xsl:for-each> </table> </body> </html> </xsl:template> </xsl:stylesheet> Using IBM Tivoli Monitoring 6.1 Web Services Page

56 The output from the above XSL transformation when applied to a sample XML response document that contains two columns of data for each row, job name, and CPU percentage usage, for example, looks like this: JOB JOB2 5.2 JOB3 87 JOB4 0.0 JOB4 2.1 JOB JOB7 2.3 So how does this XSL transformation document work? The initial lines are standard and are coded as shown, the first line of interest to you is this one: <xsl:output method="html"/> This tells the XSL transform to generate HTML rather than simple text. The next line : <xsl:template match="/"> Starts the transformation template and tells the template to select the entire document. Following this are some, probably familiar, HTML tags that define the start of the HTML fragment that is generated. Because these are defined within the XSL transformation document, the transformation simply outputs them as they are coded. In this case they define the start of the HTML page and the table that contains the data rows and columns. Next up is this line: <xsl:for-each select="//itm:data/itm:row"> This line tells the transformation to process each <ROW> element that is defined immediately under a <DATA> element (and you know there is only one of those). The // characters before the DATA name tell the transformation that the DATA element can exist anywhere within the response document. This is important since the DATA element exists within other tags so using the double-slash prefix in this way avoids the need to specify the exact path from the root element down to the data element. Following the select is a <TR> element that is invoked every time a <ROW> element is processed in the XML response document. As a result, an HTML table row element is generated for every <ROW> element tag in the response document. There is a corresponding closing HTML table row element just before the closing xsl:for-each statement that closes the table row as the HTML is generated. Following the <TR> element that defines the start of a HTML table row comes this statement: <xsl:for-each select="*"> Using IBM Tivoli Monitoring 6.1 Web Services Page

57 This line selects each child node within the current selected <ROW> element (node). As you know, these are the attribute tags that contain the data for the current row. The asterisk matches any tag (attribute) name. Within the column (attribute) select are the following statements: <xsl:choose> <xsl:when <td align="right"><xsl:value-of select="."/></td> </xsl:when> <xsl:otherwise> <td align="left"><xsl:value-of select="."/></td> </xsl:otherwise> </xsl:choose> This is essentially a basic selector type of structure common in other languages that generates one of two HTML table data (column) elements depending on presence or absence of the dt attribute with the number value in the current node. As you may recall, the Tivoli Monitoring SOAP server adds this attribute name and value to columns that are defined as numeric to Tivoli Monitoring. The previous XSL transformation statements generate a right-aligned table data element when the source XML element is defined as numeric, and a normal left-aligned textual element when that attribute is absent from the source XML element. Using IBM Tivoli Monitoring 6.1 Web Services Page

58 Adding column headings to the generated output In the previous JavaScript, you looked at how it was possible to extract the attribute names from the source XML document by processing the document DOM. You can then use the attribute names as column headers for example. While you can still do that to generate column headers while using an XSL transformation to format the data, it is better to also use the XSL transformation to generate the column headings. The following highlighted changes to the template achieves this: <xsl:template match="/"> <html> <body> <table border="1"> <tr bgcolor="#9acd32"> <xsl:for-each select="//itm:data/itm:row[1]"> <xsl:for-each select="*"> <th align="left"> <xsl:value-of select="local-name()"/> </th> </xsl:for-each> </xsl:for-each> </tr> <xsl:for-each select="data/row"> <tr> etc; The template now generates a table row header with a background color, selects a single row, and then selects every column from that row using the following statements: <xsl:for-each select="//data/row[1]"> <xsl:for-each select="*"> Following that, the following line generates a table header column using the tag name extracted by the local-name() function. <th align="left"><xsl:value-of select="local-name()"/></th> Using IBM Tivoli Monitoring 6.1 Web Services Page

59 This is what the resultant output looks like now using the same input document as before: Jobname CPU_Percent JOB JOB2 5.2 JOB3 87 JOB4 0.0 JOB4 2.1 JOB JOB7 2.3 You can make the column headings more readable by replacing the underscore characters used as part of the attribute tag names with space characters. You can do this by using the XSL translate function like this: <th align="left"> <xsl:value-of select="translate(local-name(),'_',' ')"/> </th> The resultant output now looks like this with the underscore character of the CPU_Percent title replaced by a space: Jobname CPU Percent JOB JOB2 5.2 JOB3 87 JOB4 0.0 JOB4 2.1 JOB JOB7 2.3 Using IBM Tivoli Monitoring 6.1 Web Services Page

60 Using parameters with XSL transformations In this section you learn how to pass parameters from JavaScript into an XSL transformation document, and also how you can use those parameters within the XSL document to control its processing. Parameters are defined within the XSL transformation document by using the xsl:param tag like this: <xsl:param name="title" select="'default Title'" /> <xsl:param name="style" select="'normal'" /> These tags define two parameters, one named title and one named style. The select attribute defines a default value for the parameter name that is used unless the parameter value is changed. You can insert the current value of a parameter within the transformed output by including a tag within your XSL transformation document like this: <h2><xsl:value-of select="$title" /></h2> In this example the value of the title parameter is substituted between the <h2> tags to form a heading within the generated HTML. To refer to the parameter value you prefix the parameter name with a dollar sign as shown. You can also use parameter values to control the processing flow of the XSL transformation. For example: <xsl:choose> <xsl:when test="$style='pretty'"> <th align="left"> <xsl:value-of select="translate(local-name(),'_',' ')"/> </th> </xsl:when> <xsl:otherwise> <th align="left"> <xsl:value-of select="local-name()"/> </th> </xsl:otherwise> </xsl:choose> In this example the value of the parameter named style is used to control which table header HTML element is generated, either a normal one or the pretty one with underscore characters replaced by spaces. Using IBM Tivoli Monitoring 6.1 Web Services Page

61 You can set the value to be used for a parameter name both internally, that is within the xsl processing, and externally such as through the JavaScript interface. Only the JavaScript interface is described here. The following example shows the Transform function you looked at earlier that has been modified to accept two additional parameters, style and title, and the relevant processing statements needed for Mozilla and IE environments to pass those parameters to the XSL transformation: function Transform(myXML,myXSL,title,style) { if (document.implementation.createdocument) { myxslproc = new XSLTProcessor(); // Mozilla myxslproc.importstylesheet(myxsl); myxslproc.setparameter(null, "title", title); myxslproc.setparameter(null, "style", style); else } var fragment = myxslproc.transformtofragment(myxml, document); return fragment; } { // IE var xslt = new ActiveXObject("Msxml2.XSLTemplate.3.0"); xslt.stylesheet = myxsl; xslproc = xslt.createprocessor(); xslproc.input = myxml; xslproc.addparameter("title", title); xslproc.addparameter("style", style); xslproc.transform(); return xslproc.output; } Using IBM Tivoli Monitoring 6.1 Web Services Page

62 XSL name spaces Name spaces are important because they isolate the structures of XML documents and prevent collisions when different XML structures use the same tag names. In the Tivoli Monitoring SOAP server XML response document shown earlier you may have noticed the following item: <?xml version="1.0" encoding="utf-8"?> <SOAP-ENV:Envelope xmlns:soap-env=" SOAP-ENV:encodingStyle=" ENV:Body> <SOAP-CHK:Success xmlns:soap-chk = " xmlns="urn:candle-soap:attributes"> <TABLE name="o4srv.inodests"> <OBJECT>ManagedSystem</OBJECT> <SOAP- What this tells the XML environment is that the following tags, unless otherwise specified, belong to this name space and that you must reference the tags within the context of this name space to process them. There are two steps to doing this within the XSL transformation document. This first is to define the name space string and assign it to an identifier. In this case itm is used as the identifier. <?xml version="1.0" encoding="iso "?> <xsl:stylesheet version="1.0" xmlns:xsl= xmlns:itm="urn:candle-soap:attributes"> This identifies the name space that the attributes of the XML document returned by the Tivoli Monitoring SOAP server belong and associates the itm identifier to it. Lines such as this one: <xsl:for-each select="//itm:data/itm:row"> Use the itm identifier previously specified to identify the name space that the tag belongs to. Without this you cannot extract any data from the full Tivoli Monitoring SOAP server response document. Using IBM Tivoli Monitoring 6.1 Web Services Page

63 You can avoid the need to use name spaces in this manner in the bulk of your XSL processing by extracting the <DATA> node and all its child nodes from the Tivoli Monitoring SOAP server response document within your code and then applying the XSL transformation to that fragment only. Because there is now no name space information within the extracted fragment of the response document, there is no need to specify or use any name space information within the XSL transform. Using IBM Tivoli Monitoring 6.1 Web Services Page

64 Security When Tivoli Monitoring is initially installed, security is turned off. This means that even though you need to enter a user ID on the client sign on screen, it only has to be a user ID defined to Tivoli Monitoring and you don t need to enter a password. For a CT_Get request to the SOAP server you don t even need to supply the userid or password tags, or if you do, it does not matter what you enter in them. However with security enabled, the user ID and password that you enter is validated using the security mechanism of the system hosting the monitoring server. Thus if the monitoring server is on a Windows computer, all user IDs must be defined to that Windows computer. If the monitoring server is on a z/os system, then the user IDs and passwords must be defined to RACF (Resource Access Control Facility). Controlling security From the Manage Tivoli Enterprise Monitoring Services window, right-click the monitoring server entry and select Reconfigure. Using IBM Tivoli Monitoring 6.1 Web Services Page

65 Select or clear the Security: Validate User check box to turn security checking on or off: Click OK. You don t need to change anything else. Tivoli Monitoring then stops your monitoring server so you must restart it by right-clicking- it in the Manage Tivoli Enterprise Monitoring Services window and selecting Start. Using IBM Tivoli Monitoring 6.1 Web Services Page

66 Using IBM Tivoli Monitoring 6.1 Web Services Page

67 Copyright IBM Corporation 2007 IBM United States of America Produced in the United States of America All Rights Reserved DB2, IBM, the IBM logo, Tivoli, the Tivoli logo, Tivoli Enterprise, z/os, and zseries are trademarks of International Business Machines Corporation in the United States, other countries or both. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. Other company, product and service names may be trademarks or service marks of others. This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user s responsibility to evaluate and verify the operation of any non-ibm product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome, Minato-ku Tokyo 106, Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON- INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement might not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-ibm Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:ibm Corporation 2Z4A/ Burnet Road Austin, TX U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases payment of a fee. The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us. Using IBM Tivoli Monitoring 6.1 Web Services Page