SIT parameters - to the clipbopard - learn how the CICS Explorer gets its data from a CICS regions
JoeWinchester 110000DQA0 Visits (4589)
Quite a lot of my in-box at IBM is from folks asking "Can the CICS Explorer do X for me?". A fair amount of the time I'm able to say "Yes it can my friend - here's the bit of the doc and a scren shot", after which I usually buy myself a well earned lattee and wait for the "Thank you Joe - you're so awesome" e-mail reply. It's a dream job. Cue the picture of me being helpful to users. However... there are times when I have to reply with "Sorry my friend - the CICS Explorer can't do what you're asking". I tend to then still buy myself a coffee but I'm in a grumpy mood for the rest of the day. It's possible that we're already thinking of putting the feature in, or maybe we already have for a future release and not announced it yet, or else it's something new in which case it goes onto what we call a product backlog. Either way the user is going to have to wait for a future release until they get the feature - and often the reason they're asking is because they want it today, or in some cases they want it yesterday !!!! Cue the picture of the angry user that the CICS Explorer doesn't have the feature they're looking for.
If you think the feature is awesome then you have no need to read further - you should open the SIT parm editor to your heart's content and in a spare moment send us a box of chocolates to go with the lattees. Cue the picture of me enjoying some chocolates.
So, back to the fellow who is unhappy because he wants to copy this data to the clipboard and compare the SIT parms from two regions. The idea that occurred to me somewhere between the third lattee and a beer later that evening, was why didn't I just show people how to get at the raw data from the CICS region themselves. The way that the CICS Explorer gets data for a region is by sending an HTTP message to the region (or the WUI server for a CICSplex) - getting a response back - parsing it and shoving it in the user interface. HTTP is text so web browsers can send and receive HTTP (they usually are working with HTML which is designed to be read by a person rather than a machine) but they can work with HTTP just as well, and the API we use is public, so there's really nothing to lose by showing the message we send and receive to do the SIT stuff.
There are three messages that are sent to a CICS region to get the SIT parameters. You might be asking yourself why we use three and not one, and that's a good question that unfortunately I have to answer. Bear with me while I try to explain.
The CICS Explorer doesn't talk to a CICS region by saying "Hey CICS region - give me the data for X" in a single bark. The reason is that there might be a zillion Xs and everything would grind to a halt. Instead what the CICS Explorer does is say "Hey CICS region - I'm interested in X - how many have you got?". The region then comes back and says "I've got 250 (or whatever the number is) and here's a unique number you can now use to reference the Xs that you asked for". The original request could have filters on it as well such as "I need all Xs where the name is C* and the description is D*". The CICS region processes the request to work out how many there are and keeps this around in memory. The requestor - in this case the CICS Explorer - can then get at the data pages at a time. This is how the CICS Explorer is able to show you that you have 6000 tasks for a region, but not actually get all 6000. If you've ever scrolled a view with tasks or something that has a large volume you might have seen that as you move the scroll bar down you get blank pages of data which then fill up with the actual values. This is paging, and what the CICS Explorer is doing is saying "Hey there CICS region - it's mere here - token ABC123 - can I have rows 20 to 40 please", and so forth. When the CICS Explorer is done it can say "Hey there CICS region - I don't need token ABC123 anymore - you can get rid of it".
(If you're feeling bold you'll notice the word COMBINED in the message - this can be changed to be TABLE or JCL or SYSIN or CONSOLE as required just to get back the SIT parms from particular sources - COMBINED gets the SIT parms from all source (which is why it's called combined I guess)
The result of this message is some XML - the screen shot below shows this in a web browser.
The message to get the actual data begins the same way as the last one to get the cachetoken and size - it has the host and port of the CMCI (or CICSplex WUI server), except this time we don't need to pass the plex name or region name. We do need to use the cache token and also the number of rows we want to retrieve. We know the cache token is CB17472B479482 and there are 223 rows, so the message we send is:
http: or https:// hostIPaddress : port / CICS
In the resulting XML we get back the SIT parms in the browser !!!
This is actually very cool. The data is a bit machine readable, rather than human readable, and I'll blab on more about this in a bit - but for a moment just reflect on what's happened. Two http messages have been created and sent in an regular web browser - one to talk to the CICS region and see how many of a particular piece of data exists, in this case SIT, for a region and to get a token which is then used to key back into the CICS region to get all of the data.
The message for the discard is
http: or https: // hostIPaddress : port / CICS
The message to discard the cache token CB1747B479482 is shown belo
Now back to the SIT parms data itself.
If you look at the <records> tag you'll see a bunch of XML tags starting <cic
You can ignore most of the start of the message and just focsu on the portion that starts keyword which is the SIT parameter name, ignore segnum and segtot, the type is the source of the SIT parameter, and the value is the value.
What I've done to process the SIT parms is to copy the XML into a text file, open it in a spreadsheet stating that the delimiter is a space - and then delete the columns I don't want (i.e. just keep keyword, source, and value.
I hope that made sense - it was a bit involved but basically I walked through how to send http requests straight into a CICS region to get the SIT parms and then open these in a spreadsheet. The http stuff was a bit knotty because instead of just one message you have to send one to get the number of rows and a cache token, a 2nd using both of these to get the data, and a 3rd to be a good citizen and release the memory held onto by the cache token. Then the result of the 2nd message is goopy XML which you can open in a spreadsheet, delete the non-user visible portions you don't want, and get the raw data. What you do next is up to you, but you could compare regions together, create reports, pie charts, histograms, and hopefully get what you originally wanted when you asked whether the CICS Explorer could copy SIT parms to the clipboard. The answer was no, but with a few coffees and a beer and a web browser and the CMCI API the answer becomes a "yes if you're willing to be adventurous".
Cue the happy contented user browsing SIT parms in their spreadsheet