Sitworld: Situation Distribution Report


John Alvord, IBM Corporation

Draft #15 – 8 January 2021 – Level 0.80000

Follow on twitter


I am often asked how to discover what agents a situation is distributed to. I’ve been tinkering with this issue. I finally made a first draft.

At Version 0.68000 I added a report section listing Managed System lists that were unused in any situation distribution either directly or indirectly by situation groups.

At Version 0.75000 I cloned the into and altered to not include the json output. The new does not require CPAN packages.

At Version 0.80000 I have a good output with Persist and Description added.


Situations get distributed through four logical mechanisms:

1) Direct distribution to a Managed system [Agent]

2) Direct distribution by Managed System List that includes an agent.

3) Indirect distribution from Situation Group to a Managed system [Agent]

4) Indirect distribution from Situation Group to a Managed System List

There can be multiple MSLs or Situation Groups involved – maybe 10 different reasons why the situation will be distributed, It will only be distributed once.

Side Note for Extra Credit – There will NOT be a Test!!

A situation can take on multiple roles. For example it might be running on its own but also used in an Until situation or in a *SIT test or in a Workflow policy. In this case the situation only runs once on the agent but the results are multiplied at the TEMS so each usage gets the data needed. Sometimes you see situations start more then once on an agent. An Action command will show that result. It will also been if there are invisible sub-situations caused when multiple attribute groups are present. If you see a situation starting dozens of times, that is the likely issue.  See the Mixed Up Situations blog post for scary details.

Development notes

I had originally planned to use Perl/SOAP for this work. However some problems were encountered. The alternative was to run the needed SQL dumps using the KfwSQLClient program which is part of TEMS. This is rapid and simple to use – since it uses a preexisting connection. The output is a little rougher to parse but the benefits are huge.

Package Installation

The following  assumes the default install directory. The work is done on the system which runs the TEPS.  You can certainly do this any number of ways. For example you could capture the data at the TEPS and then copy the files somewhere else to process. If you are using a non-default install directory then then shell files will need to be modified. The choice of where to store the program objects is arbitrary – pick whatever you want.

The package is sitinfo.0.80000. It contains

1) Perl program – standing for Situation Information

2) Perl program – which adds a json output.

3) A  sitinfo.cmd [Windows] shell command to run the SQL statements.

3) A sitinfo.tar file which contains Linux/Unix versions of the SQL capture shell command This avoids problems with the line endings. Just untar that into the install  directory.

I suggest these all be placed in a single directory. For Windows you need to create the tmp directory and the sql subdirectory. For Linux/Unix create the sql directory.

Linux/Unix:  /opt/IBM/IBM/tmp/sql

Windows: c:\IBM\ITM\tmp\sql

Please note: In some environments installing CPAN packages is a major problem. Internet access may not be available or Perl may be a shared resource which you do not have the right to change. Changing such packages could negatively affect other programs.

To manage this case please see the CPAN Library for Perl Projects which has a package which can eliminate changing the installed Perl libraries.

Running the Program

The command line assumes you are running the the CPAN include library above.

1) Linux/Unix

a) cd /opt/IBM/IBM/tmp/sql

b) If not using default install directory run specify like this:

c) sh

4) perl -Iinc -lst

5) On AIX platform you may need to run this command if he tables are large and you get outputs that show Unknown Exception

export LDR_CNTRL=MAXDATA=0x80000000

2) Windows

a) c:\IBM\ITM\tmp\sql

b) If not using default install directory run specify like this:

c) sitinfo.cmd

d) perl -Iinc -lst


Two files are created:

A comma separated file [sitinfo.csv] which names the situation, the count of agents, the list of agents and the predicate. This can be unwieldy if there are thousands of agents.

If you use a JSON file [sitinfo.json] which tells  why the distribution occurred. JSON files are good for portable lists of highly structured data. There are many libraries to process these types of files.

The -onerow Option

If you specify the -onerow option the output puts each agent and each situation on a separate line. The ip address of the agent is included. This report is useful for some specialized data input applications. At 0.70000 a “why” column is added that lists the direct [agent and MSLs] and indirect via Situation Groups [Agent and MSLs],

Screen shots

First is a view of the CSV file from Symphony


Next is a view of the JSON file from a web online editor – actually this is a section of the screen.


When there is a Situation Group indirect distribution you will see  a GA or GM, the agent name or MSL name and third the situation group name involved.


The Situation Distribution tool was derived from ITM Agent Health Survey.

Sitworld: Table of Contents

Feedback Please!!

I am new to this JSON world and you have any suggestions you will find a willing ear.

History and Earlier versions

If the current version of the Situation Distribution  tool does not work, you can try previous published binary object zip files. At the same time please contact me to resolve the issues.  If you discover an issue try intermediate levels to isolate where the problem was introduced.

Correct sitinfo.cmd and

Correct Description logic in -onerow output

Add Situation Description to -onerow output
Show FULLNAME along with SITNAME when different

Add Situation Persist to -onerow output

correct sitinfo.cmd data collection – missing TNAME table



Add knowledge of distribution for TCALENDAR, TOVERRIDE and POLICY

Photo Note: The Road to Big Sur has many strange sights – watch out for wild boars!!

2 thoughts on “Sitworld: Situation Distribution Report

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: