John Alvord, IBM Corporation
jalvord@us.ibm.com
Draft #3 – 7 June 2016 – Level 0.52000
Inspiration
Recently an ITCAM YN Agent [IBM Tivoli Composite Application Manager Agent for WebSphere Application] upgraded [to 7.1.0.3.8 or 7.2.0.0.5] caused existing custom situations to be unusable. An IBM colleague spent a week on site at one customer to recover access to the situations. I was asked to create a tool for performing that work with less effort. Here is the result. This only needs to be done once since new custom situations will automatically use the new dynamic affinities.The attribute changes are downward compatible. That means if you only update some agents to the new level [including installing the application support] you can update the user objects with confidence with this tool.
At level 0.52000 a new tool was added to update the TEPS KFWQUERY database objects when necessary.
Background – Affinities
Affinities are a part of the ITM design. They are 43 character strings and have three sections.
1) Affinity string proper – 32 characters
2) Version number – 2 characters
3) Feature – 9 characters
When an agent registers at the TEMS, it supplies an affinities string. This is a definitive statement about what the agent is. The Feature section is mostly about the capabilities of the TEMA or Agent Support library.
Agents give access to attribute groups and the attributes within them. Attributes also have affinities. That is critical because an agent at version 2 might have more attributes than at version 1. The new attributes are tagged with version 2 and that lets TEMS and TEPS make sense of it all.
When a situation formula is composed, the attribute affinities are composed into a joint affinity which defines what agents the situation can run on. For example a Situation with a version 2 attribute could not run successfully on a version 1 agent level.
Originally ITM used static affinities which were [get out your calculator] base 64 coding and each byte representing 6 bits. When the Universal Agent was designed a new dynamic affinities scheme was created. Over time most agents have switched to dynamic affinities. One major dividing point is that static affinities could only represent versions 1 to 12. With dynamic affinities the limit is 65K.
Affinities are used everywhere within ITM. One important place is the Portal Client, which represents visually the connections which can be made between agents and situations.
Humorous War Story
Once upon a time in the middle 1990s at Candle Corporation, much of the development was done on OS/2 workstations. The affinities data [and other table details] was kept in a ODI [Object Definition Interface] file. A REXX program CATNIP was used to generate the attribute files, the catalog and the TEMS doc files. That is still true.
One day the development environment was switched to Windows NT. Many workstations were replaced by new workstations. The old workstations were donated to a nearby school district and re-imaged for a new purpose.
A few weeks later someone noticed that REXX ODI processing program stopped working. I was eventually asked to work on the issue. I quickly determined that the error occurred when an REXEC call was made to run a C++ binary program on a workstation at a specific ip address.The REXEC call uses tcp communications to run a command on another machine and return output. That specific workstation belonged to an [apparently] unaware development manager.. The workstations had been replaced, the old workstation had been sent to the school district and that machine had been wiped and reconfigured.
I tracked down the C++ source programs – about 250 Lines of Code. It was doing some 64-base arithmetic – ORing and ANDing the 32 byte attributes. . In a couple hours I redid the work in straight REXX – perhaps 4-5 lines of code. I just had to translate the base 64 characters to 6 bit strings, OR or AND the result, and translate back. That logic replaced the REXEC call and everything started working again. Very low tech but it made everybody happy that a prime component of the development stack was working again.
ITCAM YN Switches to Dynamic Affinities
When the ITCAM YN Agent was upgraded [going to version 13], the user created [custom] situations were left with the original static affinities. As a result, the Portal Client could no longer process them. If you brought them into the Situation Editor, the Distribution tab would have no candidates for distribution. In addition, Portal Client user created queries against the earlier agent levels lost the ability to do Create Another… which was very painful to users that created a lot of ITMCAM YN Agent workspaces.
The current project is designed to cure this issue by updating the situations with original static affinities to the new dynamic affinities. This distribution contains an program for the YN agent. It also includes a program to update the TEPS KFWQUERY. Later project releases will be made as needed for other such agents.
Package Installation
The following assumes ITM was installed in the default directory. The data collection 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 you will need to set an environment variable. If needed, IBM support can do the work for you.
The package is itcamyn.0.52000.It contains
1) Perl program itcamyn.pl.
2) A itcamyn.cmd [Windows] command to run the SQL statements.
3) A itcamyn.tar file which contains Linux/Unix shell command itcamyn.sh file. This avoids problems storing the line endings. Just untar that into the install directory.
4) Perl Program itcamyn_teps.pl.
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. You can of course use any convenient directory.
Linux/Unix: /opt/IBM/IBM/tmp/sql
Windows: c:\IBM\ITM\tmp\sql
Linux and Unix almost always come with the Perl shell installed. For Windows you would install a no cost Community version from Activestate if needed. You could also move the files to another system where Perl is installed.
Running the ITCAMYN Program.
The following work is performed on the system where the TEPS is running and connected to the hub TEMS
1) Linux/Unix
a) cd /opt/IBM/IBM/tmp/sql
b) If not using default install directory specify install directory like this: export CANDLEHOME=/opt/IBM/ITM
c) sh itcamyn.sh
4) perl itcamyn.pl -lst
2) Windows
a) cd c:\IBM\ITM\tmp\sql
b) If not using default install directory specify install directory like this: SET CANDLE_HOME=c:\IBM\ITM
c) itcamyn.cmd
d) perl itcamyn.pl -lst
The data capture captures several QA1*.DB.LST files. The perl program creates three files itcamyn.log and itcamyn.sql and itcamyn.sql.undo,
The itcamyn.log file shows you what is going to be done… the situation names, the old affinities, etc.
The itcamyn.sql file is a file of UPDATE SQL lines to implement the change.
The itcamyn.sql.undo file is a file of UPDATE SQL lines to reverse the change.
*Note: If there is more than one TEPS in the ITM environment, repeat for each TEPS.
Running the ITCAMYN and ITCAMYN_TEPS Programs.
The following work is performed on the system where the TEPS is running and connected to the hub TEMS. The instructions assume the default install directory of [Windows: C:\IBM\IBM and Linux/Unix /opt/IBM/ITM].
1) Get a copy of the current ITCAM YN attribute file
Linux/Unix: /opt/IBM/ITM/tables/<temsnodeid>/ATTRLIB/kyn.atr
Windows: C:\IBM\ITM\cms\ATTRLIB\kyn.atr
z/OS: RKANDATV(KNYATR) copy to workstation and change name to kyn.atr
2) Linux/Unix
a) cd /opt/IBM/IBM/tmp/sql
b) copy the kyn.atr from step 1 to this directory
c) run this command: /opt/IBM/IBM/bin/itmcmd execute cq “runscript.sh migrate-export.sh”
this will create an export of the TEPS database: /opt/IBM/ITM/<arch>/cq/sqllib/saveexport.sql
<arch> depends on the architecture you are running on. If you are uncertain locate it by running that command and then find /opt/IBM/ITM -name saveexport.sql
d) run this command
perl itcamyn_teps.pl /opt/IBM/ITM/<arch>/cq/sqllib/saveexport.sql
3) Windows
a) cd C:\IBM\ITM\tmp\sql
b) copy the kyn.atr from step 1
c) cd C:\IBM\ITM\cnps
d) run this command: migrate-export
this will create an export of the TEPS database: C:\IBM\ITM\cnps\sqllib\savexport.sql
e) cd C:\IBM\ITM\tmp\sql
f) run this command
perl itcamyn_teps.pl C:\IBM\ITM\cnps\sqllib\savexport.sql
The itcamyn_teps.log file shows you what is going to be done… the query id, when last changed and by whom, old and new affinities
The itcamyn_teps.sql file is the UPDATE SQL lines to implement the change.
*Note: The itcamyn_teps.pl has an optional parameter -atr which you can use to specify the fully qualified name of the kyn.atr file. That can be more efficient if the TEMS and TEPS are running on the same system. The default is that the kyn.atr file is in current directory.
Installing the Changes
The following work is performed on the system where the TEPS is running and connected to the hub TEMS. The example commands assume TEPS is installed in the default location. Adjust that if you have installed in another directory.
1) Linux/Unix
a) make the location of the sql files the current directory
cd /opt/IBM/IBM/tmp/sql
b) run the utility to make the changes to TEMS
/opt/IBM/ITM/bin/itmcmd execute cq “KfwSQLClient /v /f itcamyn.sql”
c) run the utility to make the changes to TEPS
/opt/IBM/ITM/bin/itmcmd execute cq “KfwSQLClient /v /d KFW_DSN /f itcamyn_teps.sql”
2) Windows
a) make the location of the sql files the current directory
cd c:\IBM\ITM\tmp\sql
b) run the utility to make the changes
c:\IBM\ITM\cnps\KfwSQLClient /v /f itcamyn.sql
c) run the utility to make the changes to TEPS
c:\IBM\ITM\cnps\KfwSQLClient /v /d KFW_DSN /f itcamyn_teps.sql
After making the changes, recycle the hub TEMS and the TEPS. Then bring up a Portal Client session and verify that things are going normally now.
One Big Change with Dynamic Affinities
Before dynamic affinities, a situation could be distributed to multiple agent attribute groups. That is no longer the case and you will need to write separate situations. This is a necessary side effect of the conversion to dynamic affinities and there are no plans to resurrect the previous behavior.
Summary
These tools will ease the ITCAM YN agent transition process. There are several other agents being worked on that will need the same work later using a revision to this project. If you feel uncomfortable doing this work yourself, IBM Support will work with you.
Sitworld: Table of Contents
History and Earlier versions
If the current version of the ITCAMYN 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.
Add itcamyn_teps.pl – create SQL to update TEPS KFWQUERY database objects
Photo Note: Magic and Miss Tiger – December 2015
The Wonderful World of Situations 