Using the IBM Tivoli Monitoring SOAP Interface with a
Tivoli Enterprise Monitoring Server on z/OS: An Example
Mike Bonett
IBM Corporation
Advanced Technical Support, Gaithersburg, MD
bonett@us.ibm.com
This technote provides an example of using Simple Object Access Protocol (SOAP)
Methods to retrieve information from the IBM Tivoli Monitoring (ITM) 6.1 environment
helpful when the Hub Tivoli Enterprise Monitoring Server (TEMS) on z/OS is the target
for the SOAP request. Review the following information in other publications to best
understand and use the information in this technote:
•
•
•
IBM Tivoli Monitoring 6.1 Administrators Guide, located online in the IBM
Tivoli Monitoring Information Center at
http://publib.boulder.ibm.com/infocenter/tivihelp/v15r1/index.jsp?toc=/com.ibm.i
tm.doc/toc.xml . Appendix C describes the IBM Tivoli Monitoring Web Services
and SOAP methods.
Using IBM Tivoli Monitoring 6.1 SOAP Services - available at the IBM Tivoli
Open Process Automation Library (OPAL) website.
(http://catalog.lotus.com/wps/portal/topal).
IBM Tivoli Monitoring Version 6.1: Using the CT_Get SOAP Method in Tivoli
Enterprise Monitoring Services – available at the IBM Tivoli Open Process
Automation Library website (http://catalog.lotus.com/wps/portal/topal) as part of
the IBM Tivoli Monitoring 6.1 Tivoli Enterprise Monitoring Server Web
Services/SOAP documentation and samples. This paper provides details on the
CT_Get SOAP method.
A z/OS® TEMS is enabled to act as a SOAP Server via the Installation and
Configuration Assistance Tool (ICAT). When configuring IBM Tivoli Monitoring
Services in ICAT, Option 3 (Specify Communications protocols) allows the SOAP
Server to be enabled. Either IP.PIPE or IP.UDP must be used:
© 2007, IBM Advanced Technical Support Techdocs
Version 11/27/2007
Page 1 of 8
http://www.ibm.com/support/Techdocs
Using the IBM Tivoli Monitoring SOAP Interface with a Tivoli Enterprise Monitoring Server on z/OS: An Example
.
. . . . . . . . . . . . . . . . . . . . . . .
--------------- SPECIFY IP.PIPE COMMUNICATION PROTOCOL --------------COMMAND ===>
Specify the IP.PIPE communication values for this TEMS.
* Hostname
==> SYSHL125
* Address
==> 10.1.1.2
Started task
==> *
Network interface list:
==>
(Recommended default = *)
(If applicable)
Specify IP.PIPE and Web Services SOAP Server configuration.
Port number
==> 1918 (IP.PIPE)
Port number
==>
(IP.PIPE for IPV6)
Port number
==>
(Secure IP.PIPE)
Port number
==>
(Secure IP.PIPE for IPV6)
HTTP server port number ==> 1920
Access TEMS list via SOAP Server?
==> N (Y, N)
Address translation
==> N
(Y, N)
Partition name
==>
Set the Access TEMS list via SOAP Server? option to Y to create the initial
KSHXHUBS member (in the RTE RKANPARU partitioned data set) required for SOAP
Server operation. The contents of this member will appear as follows:
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="hubdef.xsl" ?>
<ENTERPRISE>
<HUB>
<CMS_Name>
IP.PIPE:SYSH125Ý1918¨
</CMS_Name>
<Service_Name>SOAP</Service_Name>
<Alias>SOAP</Alias>
</HUB>
</ENTERPRISE>
The symbols around the port number in KSHXHUBS are actually brackets, but do not
display as such when translated to EBCDIC. The port in KSHXHUBS is the port used for
TEMS<->agent or TEMS<->TEMS communications. It is *not* the port used for SOAP
queries – this is the HTTP server port number option in ICAT (1920 in the above
example).
Validate the SOAP Server is active by accessing the provided client at
http://<host>:<HTTP server port number>///cms/soap/kshhsoap.htm:
© 2007, IBM Advanced Technical Support Techdocs
Version 11/27/2007
Page 2 of 8
http://www.ibm.com/support/Techdocs
Using the IBM Tivoli Monitoring SOAP Interface with a Tivoli Enterprise Monitoring Server on z/OS: An Example
You can use this client to test and execute the available SOAP methods.
OMEGAMON® and other product agents that report to a TEMS provide data organized
into attribute tables. These tables are defined to the Hub TEMS via the agent catalog and
attribute files. On z/OS the catalog and attribute definitions are stored as members in the
runtime environment (RTE) RKANDATV partitioned dataset. The catalog members are
named KppCAT, and the attribute members are named KppATR, where pp is the two
digit product code.
Data from the same agent types (e.g. all OMEGAMON XE on z/OS agents) are logically
stored in a single set of tables. This makes it possible use the SOAP methods to access
information from multiple monitored systems, across image/sysplex boundaries, at the
same time. Details on specific attribute tables are provided in the product-specific
documentation and in Tivoli Enterprise Portal online help.
The CT_Get SOAP method retrieves information from the TEMS. Data queries using
CT_Get are essentially retrieving rows from a table. The desired data attributes are the
table columns, and data filtering sets criteria to control the number of rows returned.
The following tags for the CT_Get method determine the data to be retrieved:
•
<object> or <table> - defines the table against which the data will be retrieved.
If the <object> tag is used, the value is the first component (the string before the
period) portion of the name attribute in the KppATR member. If the <table> tag
© 2007, IBM Advanced Technical Support Techdocs
Version 11/27/2007
Page 3 of 8
http://www.ibm.com/support/Techdocs
Using the IBM Tivoli Monitoring SOAP Interface with a Tivoli Enterprise Monitoring Server on z/OS: An Example
is used, then the value is the table name prefix (more on that later) concatenated
with a period and the value of the tabl attribute on the KppATR member.
•
<attribute> or <column> - defines the columns of the table which data will be
retrieved. If these tags are not used, data from all columns will be returned. If the
tags are used, only the data in the corresponding table columns will be returned.
If the <attribute> tag is used the value is the second component (the string after
the period) portion of the name attribute in the KppATR member. If the
<column> tag is used, then the value is the column name defined by the value of
the colu attribute in the KppATR member.
•
<afilter> or <filter> - filtering criteria to determine which rows will be returned.
The format is
name;operation;value
If <afilter> is used, name = the column name as defined for the <column> tag. If
<filter> is used, name = the attribute name as defined for the <attribute> tag.
For the <table> tag, the prefix is usually Kpp , where pp is the 2 letter product code.
However, this is not always the case. To determine the proper prefix, scan the KppCAT
file for the name of the table. The first item on the line will have the format C<vvv>; the
<vvv> is the prefix to use in the SOAP <table> tag for the table name.
For example, the product code for OMEGAMON XE for CICS® on z/OS is C5.
Scanning KC5CAT file for the table CICSROV, the following lines are found:
COMCICS
COMCICS
COMCICS
COMCICS
COMCICS
COMCICS
COMCICS
COMCICS
COMCICS
CICSROV
CICSROV
CICSROV
CICSROV
CICSROV
CICSROV
CICSROV
CICSROV
CICSROV
AIDS
CICSAPPL
CICSGAPL
CICSNAME
CICSTODB
CPUUTIL
ENQWAIT
ICES
IORATE
KCPI4
KCPS8
KCPS8
KCPS8
KCPI4
KCPI2
KCPI4
KCPI4
KCPI4
VSE1EMT1KCP11
VSE1EMT1KCP11
VSE1EMT1KCP11
VSE1EMT1KCP11
VSE1EMT1KCP11
VSE1EMT1KCP11
VSE1EMT1KCP11
VSE1EMT1KCP11
VSE1EMT1KCP11
From these results, the prefix for CICS tables is OMCICS . This is the correct value to
use as part of the <table> tag value:
<table>OMCICS.CICSROV</table>
It can be tedious to manually scan through the ATR and CAT members to find the
information needed for a SOAP method request. However, the files are very structured,
and programming can be used to read the files and summarize the information in the
following manner:
© 2007, IBM Advanced Technical Support Techdocs
Version 11/27/2007
Page 4 of 8
http://www.ibm.com/support/Techdocs
Using the IBM Tivoli Monitoring SOAP Interface with a Tivoli Enterprise Monitoring Server on z/OS: An Example
1. From the ATR file, find the name statements and parse the values for the object
and attribute tags.
2. From the ATR file, find the colu statements and parse the value for the columns
tag.
3. From the ATR find, find the tabl statements and parse the value. This value
corresponds to the preceding object value found – that is, they refer to the same
table.
4. Lookup the value from the tabl statement in the corresponding CAT file to locate
its prefix, to create the value for the table tag.
For example, a 65 line (including comments) REXX program was created to perform the
above steps. It produced this output when run against the OMEGAMON XE on z/OS
catalog and attribute files:
<table>;<object>;<column>;<attribute>
KM5.ASCPUUTIL;Address_Space_CPU_Utilization;ORIGINNODE;Managed_System
KM5.ASCPUUTIL;Address_Space_CPU_Utilization;JOBNAME;Job_Name
KM5.ASCPUUTIL;Address_Space_CPU_Utilization;CPUPCT;CPU_Percent
KM5.ASCPUUTIL;Address_Space_CPU_Utilization;TCBPCT;TCB_Percent
KM5.ASCPUUTIL;Address_Space_CPU_Utilization;SRBPCT;SRB_Percent
KM5.ASCPUUTIL;Address_Space_CPU_Utilization;STEPNAME;Step_Name
KM5.ASCPUUTIL;Address_Space_CPU_Utilization;PROCSTEP;Proc_Step
KM5.ASCPUUTIL;Address_Space_CPU_Utilization;SVCCLASS;SvcClass
KM5.ASCPUUTIL;Address_Space_CPU_Utilization;SVCCLASP;SvcClasP
KM5.ASCPUUTIL;Address_Space_CPU_Utilization;ASID;ASID
KM5.ASCPUUTIL;Address_Space_CPU_Utilization;JESJOBID;JESJOBID
…
From this type of summary, determining the values to use for a CT_Get method call is
much easier. Using the above information, the following SOAP envelope will retrieve
the job name, JES job ID, and CPU percent from the OMEGAMON XE on z/OS agent,
for address spaces with CPU percent greater than zero:
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:mrns0="urn:xmethods-delayed-quotes"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soap:Body
soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<CT_Get>
<userid>user</userid><password>password</password>
<object>Address_Space_CPU_Utilization</object>
<attribute>Job_Name</attribute>
<attribute>JESJOBID</attribute>
<attribute>CPU_Percent</attribute>
<afilter>CPU_Percent ;GT;0</afilter>
</CT_Get>
© 2007, IBM Advanced Technical Support Techdocs
Version 11/27/2007
Page 5 of 8
http://www.ibm.com/support/Techdocs
Using the IBM Tivoli Monitoring SOAP Interface with a Tivoli Enterprise Monitoring Server on z/OS: An Example
The SOAP envelope returned contains the following information:
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV=”http://schemas.xmlsoap.org/soap/envelope/”
SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<SOAP-CHK:Success xmlns:SOAP-CHK = "http://soaptest1/soaptest/"
xmlns="urn:candle-soap:attributes">
<TABLE name="KM5.ASCPUUTIL">
<OBJECT>Address_Space_CPU_Utilization</OBJECT>
<DATA>
<ROW>
<Job_Name>R41AYNSA</Job_Name>
<JESJOBID>STC09808</JESJOBID>
<CPU_Percent dt="number">27.3</CPU_Percent>
</ROW>
<ROW>
<Job_Name>TWSE</Job_Name>
<JESJOBID>STC02804</JESJOBID>
<CPU_Percent dt="number">0.4</CPU_Percent>
</ROW>
<ROW>
<Job_Name>V5S1</Job_Name>
<JESJOBID>STC04827</JESJOBID>
<CPU_Percent dt="number">24.7</CPU_Percent>
</ROW>
<ROW>
<Job_Name>V5S1S</Job_Name>
<JESJOBID>STC04844</JESJOBID>
<CPU_Percent dt="number">21.3</CPU_Percent>
</ROW>
<ROW>
<Job_Name>RMFGAT</Job_Name>
<JESJOBID>STC04878</JESJOBID>
<CPU_Percent dt="number">0.4</CPU_Percent>
</ROW>
<ROW>
<Job_Name>R41BDSST</Job_Name>
<JESJOBID>STC09930</JESJOBID>
<CPU_Percent dt="number">0.4</CPU_Percent>
</ROW>
</DATA>
</TABLE>
</SOAP-CHK:Success></SOAP-ENV:Body></SOAP-ENV:Envelope>
Each row of returned data is contained within the <ROW> tag. This makes it easy to
parse the information into the desired format. Using programming language containing
an XML parser makes it even easier to extract and format the information as desired.
WebITM is a browser application, available on the IBM Tivoli OPAL website, which
demonstrates using the SOAP methods to retrieve information via a custom interface.
Here it shows the managed systems for a z/OS Hub TEMS:
© 2007, IBM Advanced Technical Support Techdocs
Version 11/27/2007
Page 6 of 8
http://www.ibm.com/support/Techdocs
Using the IBM Tivoli Monitoring SOAP Interface with a Tivoli Enterprise Monitoring Server on z/OS: An Example
Selecting a z/OS LPAR then allows a list of preconfigured queries to display:
Selecting the Address Space CPU Utilization where CPU Percent GT 5.0% - Bar
Graph query results in this view:
© 2007, IBM Advanced Technical Support Techdocs
Version 11/27/2007
Page 7 of 8
http://www.ibm.com/support/Techdocs
Using the IBM Tivoli Monitoring SOAP Interface with a Tivoli Enterprise Monitoring Server on z/OS: An Example
Further details and examples of the use of the SOAP interface can be found in these
items on the IBM Tivoli OPAL website.
•
•
•
Using IBM Tivoli Monitoring V6.1 SOAP Services
(http://catalog.lotus.com/topal?NavCode=1TW10TM4M)
WebITM - A Web Based Demonstration Application using IBM Tivoli
Monitoring V6.1 SOAP Services
(http://catalog.lotus.com/topal?NavCode=1TW10TM52)
IBM Tivoli Monitoring 6.1 Tivoli Enterprise Monitoring Server Web
Services/SOAP documentation and samples
http://catalog.lotus.com/topal?NavCode=1TW10TM1R
© 2007, IBM Advanced Technical Support Techdocs
Version 11/27/2007
Page 8 of 8
http://www.ibm.com/support/Techdocs
Using the IBM Tivoli Monitoring SOAP Interface with a Tivoli Enterprise Monitoring Server on z/OS: An Example