Running an ITM SOAP Command

by Nick Lansdowne

SOAP calls can be run against the ITM TEMS to query data that is stored either centrally or query a managed system. There is a reference to various XML based SOAP calls here on the Orb Data web-site, but how can you run those calls from the command-line?

ITM ships with the “kshsoap” binary that enables an administrator to execute the soap calls on Windows, UNIX and Linux systems. The basic syntax is:

kshsoap <xml_file> <url_file>

The <xml_file> reference in the above command is the fully-qualified XML file  that includes the SOAP call. The <url_file> reference is the URL of the TEMS in the format “http:<TEMS_hostname>:1920///cms/soap”.

On Windows systems the executable is located in the directory %CANDLE_HOME%/cms. On a Linux/UNIX system it is found in the path $CANDLEHOME/<platform>/ms/bin/. Note that on UNIX/Linux platforms you will need to set-up the TEMS configuration settings prior to running the binary. Execute the following command:

. $CANDLEHOME/config/<hostname>_ms_<temsname>.config

Replace the references to <hostname> and <temsname> with the values of the hostname and TEMS name as relevant to your environment. Failure to set the environment will result in an error similar to “error while loading shared libraries: cannot open shared object file: No such file or directory”.

Linux Example

As an example, to list the status of managed systems running “kshsoap” on a Linux system, create a file including the Agent Status XML from  here and also create a text file to include the TEMS URL details. The following commands detail the steps:

#Change into $CANDLEHOME
> cd /opt/IBM/ITM
#Verify the URL text file
> cat /tmp/soap.url
#Set-up the TEMS environment
> . config/vm60_ms_HUBTEMS01.config
#Run the SOAP call
> ./lx8266/ms/bin/kshsoap /tmp/soap-agentstatus.xml /tmp/soap.url

The output includes the XML request, RAS1 information before the XML return. An extract of the output is below.

=====>>  SoapRequest:  ‘ http://vm60:1920///cms/soap’ l’283
!52172983.0000!========================>  IBM Tivoli RAS1 Service Log  <========================
+52172983.0000      System Name: vm60.orbdata.test           Process ID: 27079
+52172983.0000     Program Name: kshsoap                      User Name: root
+52172983.0000        Task Name: kshsoap                 MAC1_ENV Macro: 0xE316
+52172983.0000       Start Date: 2013/08/23                  Start Time: 10:21:07
+52172983.0000         AS Limit: None                        Core Limit: None
+52172983.0000        CPU Limit: None                        Data Limit: None
+52172983.0000      Fsize Limit: None                      Nofile Limit: 4096
+52172983.0000      Stack Limit: 10M                      Service Point: root.vm60_sh
+52172983.0000   UTC Start Time: 52172983                   ITM Process: vm60_sh
+52172983.0000 Effective User Name: root                
+52172983.0000      System Type: Linux;2.6.32-279.el6.x86_64
+52172983.0000  Executable Name: ./lx8266/ms/bin/kshsoap
+52172983.0000         KBB_RAS1: <not specified>
+52172983.0000      KBB_ENVPATH:
+52172983.0000 ================================================================================
<<=====  SoapResponse: ‘ http://vm60:1920///cms/soap’ l’2194
<?xml version=”1.0″ encoding=”UTF-8″?>
<SOAP-ENV:Envelope   SOAP-ENV:encodingStyle=””> <SOAP-ENV:Body><SOAP-CHK:Success http://soaptest1/soaptest/”> http://soaptest1/soaptest/>” ><TABLE name=”O4SRV.INODESTS”>


Windows Example

Similarly on Windows, this time using the list situations SOAP call detailed here, the command can be run as demonstrated in the figure below.


Note that this commd was run from the directory %CANDLE_HOME%/cms to prevent the error “kshsoap.exe – Unable to Locate Component. This application has failed to start because gsk7ssl.dll was not found.”, as per the figure below.


by Nick Lansdowne