Sitworld: A Situation By Any Other Name…
John Alvord, IBM Corporation
A customer was attempting to verify a new situation was working as expected. The situations were not complex and he was reviewing the TEMS and Agent operation logs to see that situations were starting and were firing as expected. The operation logs were not showing what he expected.
Situations have a one or more names depending on the context where they are viewed. The simplest case is when a situation name is composed under the short name rules - which everyone should memorize.
- 31 characters or less
- Alphanumeric or underline
- First character Alpha
- Last character not underline
If you are a regular expression geek, rules 2/3/4 would be expressed as
Before ITM 6.2, the rules were almost the same except (1) was 32 characters or less. That was the only choice for situation names.
If you create a situation under shortname rules and never rename a situation by over-typing in the Situation Editor then that is the name you will see in most circumstances. This is preserved in the TSITDESC table and is the SITNAME column.
From ITM 6.2 [14 November 2007] a new situation feature was introduced called a FULLNAME. This allowed you to have names up to 256 characters and to violate rules 2/3/4. For example the name can be up to 256 characters and have dashes or embedded blanks. To implement this new logic, the TNAME table was introduced with two columns
FULLNAME name up to 256 characters
ID index name
The ID column follows the short name rules. The TSITDESC.SITNAME column is always the same as the TNAME.ID field.
To display this table see Do It Yourself TEMS Table Display. The needed SQL is
When FULLNAME is seen and not seen
The FULLNAME is always seen in the Situation Editor. If it is blank or missing the SITNAME is used,
Both SITNAME and FULLNAME are seen in the tacmd viewsit and tacmd bulkexport outputs. In simple cases, FULLNAME will be blank.
In the TEMS operations log and in the Agent operations log, the SITNAME column is the only one ever seen.
Important note: If you need to validate cases where there is a FULLNAME and an index SITNAME, you will need to get the TNAME data to translate.
The Rename Horror Show
When you have an existing situation and rename it in the Situation Editor by overtyping the name and pressing Apply, the TSITDESC.SITNAME is never!! ever!! changed and a TNAME entry is created with the new name in FULLNAME and the old name as the ID.
Before case looks like this
TNAME [no corresponding ID field
After a rename looks like this
By doing a series of creates and renames like that you can wind up with
In this worst case scenario the Situation name seen in the TEMS and Agent operations logs would be the opposite of the ones see in the Situation Editor. That is an prime source for confusion.
If you must rename a situation but want to avoid this confusion, do a Create Another... and type in the desired name. Later delete the old name.
Typical SITNAME Index Names.
If you enter a long name in the situation editor and the first 31 characters match rules 2/3/4 then the SITNAME index will be just the first 31 characters. If there is a situation with the same SITNAME index already a Z name is created as described next.
If the SITNAME index needs to be created, it typically has the form Z and 30 numeric characters. The exact one chosen is somewhat random since the first one chosen might already exist.
FULLNAME and tacmd createsit
Some people do a tacmd viewsit -s sitname -e sitname.xml. Then they manipulate the xml file and reload it with a tacmd createsit -i sitname.xml. As you can see from the above logic, it is very important to use the Shortname rules or to keep the SITNAME and FULLNAME entries unchanged. The tacmd createsit process does not create new valid SITNAME index values.
The _Z_ Situation Names
TEMS implements a feature called Super Duper Situations. In this usage, existing situations are merged into a _Z_ type situation. That situation is run, the results are returned to the TEMS and the TEMS creates results for the original situations. In the operations log what you see is the somewhat mysterious _Z_ names. See this post Sitworld: Mixed Up Situations for a fuller explanation including how to disable that logic… which can be very useful for debugging some problem situation cases.
The client deleted the problem situations and created them again following the shortname rules. Then he could validate the situations were working as expected.
This document discusses the complexity of situation names in various contexts.