Some uncommonly used features of WTO in z/OS (and maybe z/VSE)

The past few days I have worked on a couple enhancements that exploited some lesser-known WTO features. None of these require APF authorization.

Multiple-line WTOs

So, you ask, why multiple-line WTOs? Why don't I just send lots of WTOs? Well, that sucks up system resources, and if there are any console exits, you're driving them every time. A multple-line WTO can give the console subsystem and your hardcopy log a little breather. There is one drawback – you can only have 71 characters per line…but we're all professionals, that's not a big deal. (A normal single-line WTO can have up to 126 characters.)

Everybody who is a z/OS mainframe programmer has already been exposed to one example - the IEA995A message. This is the one issued when an abend occurs and it has eventually percolated to RTM. You can identify multiple-line WTOs in the JES message log (first SYSOUT data set), JES system messages (third SYSOUT data set), the hardcopy log, or your TSO session as there is no repetition of the date, time, nor the JES job identifier. They are replaced by the three-digit number which appears to the right of the first line of the message. Here's a contrived example (if you don't know, S806-4 means that the load module could not be found in the STEPLIB/JOBLIB/link pack/LPA chain), and I apologize for the small print but since I'm using a basic blogger.com template, this is the only way I could get it to show up without line wrapping:

13.14.51 JOB74042  IEA995I SYMPTOM DUMP OUTPUT  864                                    
   864             SYSTEM COMPLETION CODE=806  REASON CODE=00000004                    
   864              TIME=13.14.51  SEQ=28924  CPU=0000  ASID=0062                      
   864              PSW AT TIME OF ERROR  070C1000   8141F276  ILC 2  INTC 0D          
   864                NO ACTIVE MODULE FOUND                                          
   864                NAME=UNKNOWN                                                    
   864                DATA AT PSW  0141F270 - 8400181E  0A0D18FB  180C181D            
   864                AR/GR 0: 936AF47A/00000000_00001F00   1: 00000000/00000000_84806000
   864                      2: FFFFFFFF/FFFFFFFF_00000000   3: FFFFFFFF/FFFFFFFF_00000000
   864                      4: FFFFFFFF/FFFFFFFF_00000000   5: FFFFFFFF/FFFFFFFF_007E69F8
   864                      6: FFFFFFFF/FFFFFFFF_000000FF   7: FFFFFFFF/FFFFFFFF_00000000
   864                      8: FFFFFFFF/FFFFFFFF_007B5150   9: FFFFFFFF/FFFFFFFF_0141F778
   864                      A: FFFFFFFF/FFFFFFFF_00000000   B: FFFFFFFF/FFFFFFFF_00000000
   864                      C: FFFFFFFF/FFFFFFFF_00000000   D: FFFFFFFF/FFFFFFFF_007B5150
   864                      E: 00000000/00000000_84806000   F: 00000000/00000000_00000004
   864              END OF SYMPTOM DUMP                                                  

There are two variations of how to code the WTO macro to do this. Both utilize the second subparameter of either the first positional parameter (traditional WTO) or the TEXT= operand, and in both cases it is for each multiple subparameter. The first of these is "D", which indicates that the text is part of a multiple-line WTO. The other is your choice - "DE" or "E". "E" indicates that the WTO is fniished; "DE" means that the text supplied on this invocation is the last line. I have found that the easiest way to implement this is to use TEXT= and MF=L/E, something similar to this (only the required stuff shown so not to clutter with DESC= and ROUTCDE=):

         MVC   @WTOD,#WTOD
         MVC   WTOTEXT,MSG1
* put in variable parts of MSG1
         WTO   TEXT=WTOTEXT,MF=(E,@WTOD)
         ST    R1,WTOCONN
         MVC   WTOTEXT,MSG2
* put in variable parts of MSG2
         WTO   TEXT=WTOTEXT,CONNECT=WTOCONN,MF=(E,@WTOD)
         MVC   @WTOE,#WTOE
         WTO   CONNECT=WTOCONN,MF=(E,@WTOE)

#WTOD    WTO   TEXT=(,D),MF=L
#WTOD_L  EQU   *-#WTOD
#WTOE    WTO   TEXT=(,E),MF=L
#WTOE_L  EQU   *-#WTOE

@WTOD    DS    CL(#WTOD_L)
         ORG   @WTOD
@WTOE    DS    CL(#WTOE_L)
         ORG   ,

(Now, yes, I could have mapped the WTO parm list and manipulated things directly for the E invocation, but I believe this explains the concept better.)

The "D" and "E" invocations are tied together via the CONNECT parameter. The CONNECT token is returned in GPR1 if a multiple-line WTO is started. It is then referenced in subsequent WTO invocations. (In the old days, before CONNECT, you put it in GPR0 before the call, and you can still do this if you don't use TEXT=.) The WTO is not issued until you make the "E" invocation.

You can use the field where you save the CONNECT token as a switch in a loop. If it is zero, it's the first time, so you invoke the WTO without CONNECT and store the token, and with subsequent iterations you invoke the WTO with CONNECT.

But remember – you need that "E" call, otherwise your partially built WTO will be discarded after a few seconds, which is eons to a 5.5Ghz model 2827 (zEC12) CPU.

Non-authorized callers are limited to 10 lines maximum, but authorized callers can have up to 255 lines, and that's a whole lotta lines.

Command response WTO

Have you entered an operator command via "/" in SDSF and wonder how it was able to (usually) display the response from the command? It is not an "ancient Chinese secret," if you are old enough to remember that USA commercial from the 1970s. One crucial piece of information is required: the command-and-response token (CART).

When your task that processes operator MODIFY or STOP commands (or if you're really fancy, from the START command, or through operator command or subsystem interface exits) retrieves the command, the CART is located in both the CIBX (addressable by adding CIBXOFF to the CIB address), the CSCB, or the aforementioned exits. (Modern processing uses the CIB.) Once you have this piece of information, you can specify it via the CART= operand on the WTO. This identifies this WTO as a command response, and certain processes that use the console subsystem can retrieve just these WTOs and tie them to the originating command. This is how SDSF does it, and it becomes useful for the next section…

Limiting a command response WTO to the console where the command was issued

When using the console subsystem for issuing operator commands and retrieving WTOs, such as IBM's NetView or Software AG's Entire System Server, it is nice to only send the WTO command response to the originating console, rather than to every console (hardware and subsystem) in the LPAR. You limit this by specifying the console ID on the WTO through either CONSID=. The console ID is available in the CIBX, the CSCB, and the aforementioned exits. It is also possible to put a console ID that was obtained elsewhere, if you have an environment that has well-defined consoles. If you know the console name, you can use CONSNAME=. (CONSNAME and CONSID are mutually exclusive, however.)

The IEZWPL DSECT

If you are feeling adventurous, you can build your own parameter list to SVC 35 using the IEZWPL DSECT (found in SYS1.MODGEN). However, you really need to be careful in building this list, because a mistake can lead to an SD23 abend, incomplete WTO, or pure garbage and messages incorrectly flagged as critical.

If you want to try this, I recommend that you do some sample assemblies with various expansions of the WTO macro to see how it builds the parameter list. I also recommend you talk to your systems programmer, and if you are nice maybe s/he will allow you to try this on a sandbox system.

WTOs and commands in z/VSE

In the late 1990s, the OS/390 console support was ported to VSE/ESA., retaining many of the same design concepts. Therefore, many of the concepts above apply as well, however I have to admit that I have not done a multiple-line or a specific command-response WTO in a z/VSE task as a response to the MSG console command. If there is interest, I'll get our z/VSE expert Martin to elaborate.

My high school is no more

Some sad news crossed my path the other day. My high school alma mater, Montclair College Preparatory School, shut down a month ago, a victim of the economy. They'd been around for 56 years.

The founder and operator, Dr. Vernon E. Simpson, passed away about 4 years ago. Apparently since, the school had had difficulty getting endowments and drawing students. I'm sure the economy had a lot to do with this, as well as the passing of the visible presence of the school to parents and the community. Last year, they had cut all sports programs, which is never a good sign. 

Montclair is where I learned all about computers. Up until the last semester of my senior year, I had absolutely no clue as to what I wanted to do. Then, that Christmas, I received a TI-58 programmable calculator. I started playing with the programming, and it was like the proverbial light bulb. Then a computer class became available, and I started working on a TRS-80 Model 1. Within a month I was working on the school's PDP-8, and the rest, as is said, is history. And here I am today.

On the auditorium stage when I got up to receive my diploma (actually a rolled-up piece of paper because the original diplomas had the school's name misspelled by the printer), Dr. Simpson whispered to me "and honors in computers", as he knew that I spent lots of time after school hours working on the PDP-8, just writing programs.

Now that part of my life really only exists in memories. No longer can I drive on Sepulveda Blvd. heading to Western Bagel and look at the school, and remember that's where I got the kick in the tushie that pointed me to what I am today. But I do have good friendships with several of my classmates, and I've seen a few of them in the past month. Our 35th reunion is coming up in a couple of years. I helped get people together via Facebook for our 30th, and social networking will help us again. And Montclair Prep will live on in our collective memories.

Thank you, Montclair. You may have had your problems off and on over the years, but you taught me a lot about life, and got me into a career field I love. 

Sometimes being a pack rat works out well, sometimes you wind up on "Hoarders"

This past weekend was dedicated to a big rearrangement and purge of my office (although my wife says I still need to purge more, and I actually agree with this sentiment). The catalyst was the receipt of a recent woot.com deal of a combination of two HP 22" monitors with a dual stand. I rearranged the work areas so that my day job workspace is much bigger, and I cleared enough to put my Mac Mini, my Windows 2003 Server server, and two laptops destined to become Linux/BSD machines in one corner.

The wired keyboard and mouse I was using for the Mac were a pain, so I decided to use one of a pair of Microsoft wireless keyboard/mice I had bought a while ago from woot.com. I opened the package, and started to work on it. I saw all of these dire warnings about "install software first!" (exclamation points included), and went about this. That's when I remembered something - the Mac Mini does not have an optical drive. No big deal, I'll just copy the contents of the CD to a USB drive and use Sneakernet. But when I loaded the CD into my laptop, I noticed something - no .dmg files (the format used by Apple OS for installation). I didn't dig further, but I realized that this was a dual-format CD, and Windows would not acknowledge the OS partition.

Then I remembered something - I had an ancient external CD writer. Purchased around the turn of the century, we used it to back up an old Sony VAIO laptop used extensively during our eBay selling days. It was temperamental with writing CDs, but, hey, who cares, I'm reading, not writing. It was also early USB technology, probably 1.1. Off to one of my two junk boxes; I tore through the contents, and found it and its power supply. I grabbed a USB cable, plugged it in (both places), and inserted the CD. Surprisingly, OS X Lion recognized it, and, even better, it recognized the CD! I then clicked through Finder and started the dmg package, and it installed. There were a couple of dire warning messages, but after the restart, I was able to plug in the remote receiver and my wireless keyboard and mouse are working perfectly.

Moral of the story: Don't throw anything out, you might need it. Wait, revised moral: You can get rid of some things, for example, the 10Mb network switches and the parallel and serial mechanical A/B switches.

(A victim of the purge is my dearly loved IBM P96 flat-screen CRT monitor, made by Sony, with Trinitron innards. It is unique because it was an early dual-input device, and drives an incredible-for-its-time 1600x1200 (but I swear I drove it harder than that at 1920x1440). I call it the boat anchor, because it's pretty darned heavy, and is really not conducive to relocation. It suffers from a little tic in that when it warms up the display is a bit cut off; all you have to do, though, is power-off and -on and it clears up. The reason why I am digressing is that despite its little glitch, it is still a great monitor, and I hate to send it to the recycling facility. If you're in the Sacramento area, drop me a note via my web site, and it's yours for free.)

Getting the CPU-Measurement Facility to work in z/VSE

At long last - the promised guest blog entry from Martin Trübner! Vielen dank!

Let me first introduce myself

My name is Martin Trübner. I am German and work from here, but did (when being on site was vital) gigs all over Europe and the US. I was educated and did my first job in z/OS predecessors but did my first sysgen on DOS/VS R31. During my activities I do run into z/OS and it is a wonderful environment. You can do everything and everything can be avoided and/or forbidden (through real measures), but not so in DOS/VS. Today I am bit-wise active in z/VSE and CICS/TS, and as an application person (with enough background to be dangerous) in z/OS. 

First Encounter

With the announcement of the z196 I stumbled over the CPU-Measurement Facility (CPU-MF). I was delighted to read that it is available on the z10 as well. The various counters did not really interest me, but the sampling was something for which I could imagine a very rewarding use case. If you want details of what is collected, here is a picture with mouseover explanations. But I read that it is only available for native operating systems. Since most of the z/VSE shops do run with z/VM on top, there was no point for me to investigate further. 

During a presentation at the end of June 2012, I was alerted by a single sentence that read: 

New z/VM CPU MF COUNTERS support – APAR VM64961

I thought to myself: “Now this is good news. Let's dive into the details”. 

Preliminary checks

I Googled for it and found a few presentations, the book that documents the instructions and structures used for it, and some bits and pieces about it; I must also not forget documentation regarding Hardware Instrumentation Services (HIS) for z/OS (thanks to "E."). Here are my findings:

• For sampling, it needs a setting in the SE/HWC
• For VM it needs the above PTF
• z/OS has HIS that explores it and makes lots of extra information  available
• z/HISR from Phoenix has software that uses the z/OS HIS data.
• The CPU-MF "POP-equivalent" manual, Load-Program-Parameter and the Set-Program-Parameter and CPU-Measurement Facilities (IBM manual SA23-2260-02) says that this facility is a prerequisite for the CPU-measurement sampling facility.
• The structures for sampling are very clever and suitable for any number of samples
• There is even provision for emptying buffers while sampling is active  
• There is even extra space for extension (as it was when TRAP–ping was introduced, shortly before 64-bit was introduced).

Setup in z/VSE / Problems

Nothing is a show-stopper, so I decided to go for it and write a POC with only 1–minute sampling at every 2 milliseconds (just one SDB (sampling data buffer) at 1MB), and here is what happened…

(Please do not forget- this is all occuring in z/VSE 5.1, which is the first version of VSE that supports 64-bits virtual.)

• My hardware does not have it. Okay, there are customers with a z10/z196/z114 that willing to help but the switching on via the SE/HWC is not an everyday activity. So here we have a delay.
• It needs IARV64 – my first chance to use it – one more reason to go for it.
• For debugging I would like to display what I “prepared for the HW”/”got back from HW”. 
• Ah…well, SDUMPX does support areas above the bar–but how do I get an address space STOKEN. I know what it is but heck – should I really go for control blocks to get it? Thanks to "I.", who showed me an undocumented operand of ALESERV. So now we can display these areas even without the famous 0C3 or my debugger (TRAPPER, which does understand 64-bit storage).(Ray adds: I know of this operand. It can also be used to access other partitions via access registers.)
• IARV64 REQUEST=PAGEFIX,RANGLIST=RLIST_PTR,NUMRANGE=1 abends with a ABEND 2C5 reason 0598 which reads: “0598 IARV64: Parameter list or range list must be in 31-bit storage”. How can I guarantee 31 bit storage? I can do 24, below the bar, and any boundary- but 31? With the help of "I." it was identified as typo (meaning “not 64”) and a coding-error on my side.
• I have yet to find a place where my program needs to use LPP. I am not part of the operating system, and have no way to transport (and complement later) any specific information via these 8 bytes (as opposed to z/VM or z/OS which certainly do utilize the 3 fields (basic, logical, virtual) and would certainly produce confusing results with a program injecting its own 8 bytes).

The END

I coded it, commented out the QSI and LSCTL instructions, created entries as I expect the HW to do it, tested it, and removed the testcode…and then I learned that I have not read the fine print of the PTF (thanks to "E.", saving me hours of frustration in front of a z196) . Here is the fine print: 

Support for the CPU-Measurement Sampling Facility and ... interfaces for guest use are not provided.

So I can put this to a rest and wait. Maybe one day support for guests will show up.

Next

Next time I get a chance, I will write about CICS/TS and coding a simple TRUE and a GLUE.