MVS TOOLS AND TRICKS OF THE TRADE AUGUST 2007 Sam Golob MVS Systems Programmer P.O. Box 906 Tallman, New York 10982 Sam Golob is a Senior Systems Programmer. He also participates in library tours and book signings with his wife, author Courtney Taylor. Sam can be contacted at sbgolob@cbttape.org. Information about the CBT MVS Tapes can be found on the web, at http://www.cbttape.org. THE STRUCTURE OF THE BROADCAST DATASET - PART 3 Last month, we talked about many of the details concerning the internal structure of the TSO Broadcast Dataset, which used to be known exclusively as SYS1.BRODCAST. In former times (at the z/OS 1.2 Release level and before, you had to have a dataset (of the proper format) called SYS1.BRODCAST, cataloged in the master catalog, in order to even IPL MVS, and certainly, SYS1.BRODCAST had to be present, to enable the TSO/E messaging facility. After TSO/E Release 3 came out, with z/OS 1.3, it became possible to name the TSO/E Broadcast Dataset with any name, and it even could be uncataloged, with its volume serial specified. So now it is possible to talk about multiple copies of the TSO/E Broadcast Dataset, and we have a need to determine which copy is the active copy, and which copies are not. The active copy of the TSO/E Broadcast Dataset is determined by a PARMLIB member named IKJTSOxx. Since the active copy of the TSO/E Broadcast Dataset is determined by a PARMLIB member, we must mention that from z/OS 1.3 and afterwards, it is possible to switch the active Broadcast Dataset, by means of names supplied in another PARMLIB member. Let's show how. At IPL time, if the IEASYSxx member points to an IKJTSOxx member of PARMLIB, then the IKJTSOxx member with the proper suffix is honored. If a name other than SYS1.BRODCAST is mentioned by the BROADCAST (DATASET(data-set-name) VOLUME(volume-name)) subparameters of the SEND parameter in the IKJTSOxx member, then that name and volser are honored. But after IPL also, there are two means of switching the active IKJTSOxx PARMLIB member, to include a possible change in Broadcast Dataset name or location. These are: The PARMLIB UPDATE(xx) TSO command, and the SET IKJTSO=xx console operator command. Both of these commands have the same net effect, that of changing the TSO/E internal control blocks according to ALL of the specifications and instructions mentioned in that PARMLIB member, including a possibly new name, and possibly a new disk location, for the TSO/E Broadcast Dataset. This month, we're going to talk about tools which you can use, to administer the Broadcast Dataset. And we'll start by mentioning a free tool that I wrote, which shows you all of the current Broadcast Dataset information. THE EESCB TOOL If you want to know what is going on with all the TSO/E control blocks that have to do with the Broadcast Dataset, I have written a TSO command which shows this information. The command is called EESCB, and you can find it (source and all) in the CBT Tape collection at www.cbttape.org, on File 731 (on the Updates page, most likely). I have written the EESCB command to be backward compatible, all the way back to the TSO/E 2.4 level (ESA 5.2.2), even though the relevant control blocks have changed very considerably since then. Of course, the EESCB command works all the way up to the present system levels, z/OS 1.8 and TSO/E 3.8.0, at the time of this writing. Please look at Figure 1 for an illustration of the output of the EESCB command. When I wrote the EESCB command, I tried to show just about every possible field in the appropriate TSO/E control blocks that has to do with the Broadcast Dataset. There are a very few fields that I left out, but all of the stuff which was coded in the active PARMLIB IKJTSOxx member, appears in the output of the EESCB command, in control block form. In other words, using the EESCB command, you can see how the contents of the PARMLIB IKJTSOxx member is reflected in the actual control blocks that are in storage. These results are very interesting, and if you don't happen to have access to the PARMLIB datasets at the current moment, or to a console where you can execute the D IKJTSO command, the EESCB command, (which DOES NOT have to be authorized) will show you all the relevant information. Since the EESCB TSO command uses the TSO PUTLINE interface to show its output, all of the output can be SYSOUTTRAP-ped and displayed in ISPF EDIT, ISPF BROWSE, ISPF VIEW, or TSO REVIEW (CBT Tape File 134) fullscreen format. CBT Tape File 434 contains REXX execs from Mark Zelden called TSOE, TSOB, TSOV, and TSOR, which do the SYSOUTTRAP-ping. When these are executed with the EESCB command by saying TSO TSOE EESCB, TSO TSOB EESCB, and so forth, they will display all of the EESCB output in fullscreen, scrollable form. MANAGING USERIDS AND USER MESSAGES The usual problem that we normally have with the Broadcast Dataset is that is has filled up, or it is threatening to fill up. It usually fills up with user messages that are attached to userids. When this condition happens, and several userids are accumulating a large quantity of user messages without deleting them (by means of the user logging on to TSO and thereby issuing the LISTBC command), IBM is not particularly helpful. IBM's "remedy" for a filled-up Broadcast Dataset is to issue the SYNC subcommand of the ACCOUNT TSO command, which will effectively wipe out EVERYBODY's user messages, instead of just looking at the ones belonging to the worst "offending" userids. In other words, IBM is telling us that when a skunk goes into the barn, you have to burn down the entire barn and rebuild it over again, just to get rid of the skunk. Putting it another way, IBM does not provide services which an administrator can use, to intelligently manage which Userids are accumulating an inordinately large number of messages without having deleted them. At this point, I have to point out one other fact. All of IBM's tools which are intended to access the Broadcast Dataset, are geared to only accessing the copy of the Broadcast Dataset which is currently in use by the system. In other words, this is the copy of the Broadcast Dataset which is being pointed to by the IKJEESCB control block. Or in older systems, this is the cataloged copy of the dataset named SYS1.BRODCAST. What if you have another copy of the Broadcast Dataset which is not currently in use? Are there any tools to display ITS messages, or to delete THEM? I wrote two packages of tools to address both of these issues. One of them is free, and it can be found on File 247 of the CBT Tape collection of free MVS tools. (Go to www.cbttape.org.) The other one is a commercial package with more extensive capabilities, which I intend to release soon. Most of the programs in my free package, and ALL of the programs in my commercial package, can access any copy of the Broadcast Dataset, whether in use by the system, or not. They do this by our allocating the BRODCAST DD name to the Broadcast Dataset copy that we want to point to. As far as micro-managing user messages that are attached to userids, my packages contain three programs which perform the actual administration: BCMUSERS, BCMLIST, and BCMDEL2 in my free package, and BDMUSERS, BDMLIST, and BDMDEL in my commercial package. These are interfaced to a nice ISPF-based dialog from my friend Vinh Vu, called BCMUTIL in the free package and BDMUTIL in the commercial package. (Using the program names from the free package) I'll explain their functionality. BCMUSERS will show all userids in the target Broadcast Dataset which have messages attached to them, and it will say how many messages are attached to each userid. BCMLIST will list all messages attached to one userid, or to all of them. (If you list the special userid name ALL$#@ you will get all messages for all userids in that Broadcast Dataset. And finally, BCMDEL2 will delete all (or some) of the messages attached to one userid. BCMUTIL provides an interface to all three of these programs, to show all the userids with messages, and then to provide an opportunity to display, print, or delete (all or some of) them. Please see Figure 2, to show what the BCMUTIL utility looks like. Unlike other tools which list or delete user messages from the Broadcast Dataset, BCMLIST and BCMDEL2 (as well as their commercial counterparts BDMLIST and BDMDEL) can list or delete SOME of the user messages belonging to a userid, without listing or deleting all of them. This is accomplished with two keywords: SKIP(mm) and MSGS(nn), where mm and nn are numeric integers. SKIP(mm) means to skip the first mm messages before performing the list or delete operation. And MSGS(nn) means to list or delete the next nn messages after the skip, if SKIP is coded, or nn messages from the first message, if SKIP is not coded. If you think about this arrangement, you'll see that it gives you COMPLETE CONTROL, which messages to list, or to delete, or to keep. In addition to these three utilities, the BCMSEND command will send a user message to any copy of the Broadcast Dataset. But the free version BCMSEND is quite slow, being adequate for a few messages, but it cannot efficiently be used to load messages in bulk. In the commercial package, I rewrote the BDMSEND command to be about 80 times more efficient than the free BCMSEND version. Syntax of the command is: BCMSEND userid text-of-message. UTILITIES FOR USERIDS AND GLOBAL NOTICES The utility programs mentioned above are only intended to manage the "user message" part of the Broadcast Dataset, but the Userid part and the Global Notification messages part are equally as important to administer. Userids are added or deleted, one at a time, by my BCMUSADD and BCMUSDEL free utilities. But these two programs use an IBM interface to the Userid portion of the Broadcast Dataset, and that interface does not easily allow access to an arbitrary copy of Broadcast which is not in current use by the system. In the commercial package, I completely rewrote BDMUSADD and BDMUSDEL from scratch, to eliminate the IBM interface. BDMUSADD and BDMUSDEL are easily able to add Userids to any copy of the Broadcast Dataset, or to delete a Userid. In addition, the reports from BDMUSADD and BDMUSDEL are far more informative about what was actually done, than those in their free counterparts. Global Notification messages, the ones that go to all users of the system at LOGON time (or whenever LISTBC is invoked), are managed with three programs in the free package, and with their counterparts, and also some other programs in addition, in the commercial package. The three programs are BCMNLIST, BCMNOTFY, and BCMNUPD. Also in the free package is the BDMNCLEN TSO command, whose functionality is absorbed in the BDMCLEAN TSO command in the commercial package. BCMNLIST will list all active messages in the Broadcast Dataset. This is accomplished by reading the Broadcast Dataset (that is currently being pointed to by the BRODCAST DD name) directly. Its format is similar to that of the SEND LIST subcommand of OPER which IBM provides. But (as I explained in a previous article in this series), LISTBC will not read the Broadcast Dataset directly, but an incore copy of it. BCMNOTFY can change any active message in the Broadcast Dataset copy that is being pointed to. BCMNOTFY is wholly driven by "message number" and it will either place a Global message in that number slot, place a blank message there, or delete the message that was there before. Its syntax is: BCMNOTFY nn followed by either: message text, -BLAnks, or -DELete. BCMNUPD is an authorized TSO command which sets a bit, to tell the system that the Global Notices section of the currently active Broadcast Dataset has to be reread, and that the incore copy of the Global Notices has to be replaced. When this bit is set on, one invocation of LISTBC anywhere in the system will trigger the "incore notice table" update. But that happens only with TSO/E Release 3 (z/OS 1.3) or later. Before TSO/E Release 3, you needed an OPER SEND command which updated the Broadcast Dataset, to also update the incore Notices table when the bit is set on. OTHER UTILITIES You may want to make a copy of the Broadcast Dataset on the same device type or on a different DASD device type. The free package has a BCMDUMP and BCMREST "dump-restore" combination. BCMDUMP makes an FB-130 format dataset out of the direct access format Broadcast Dataset, and BCMREST will reload a newly allocated Broadcast Dataset with all the data from the dumped dataset. An extra program called BCMEXPND not only will reload a new Broadcast Dataset from the FB-130 BCMDUMP dataset, but it will additionally fill any larger "first extent" allocation for the target dataset, with extra blank userid message datasets (format X'FF'). Both BCMREST and BCMEXPND can reload the Broadcast Dataset to a different DASD device type, because they fill in the correct first data byte value (the R of the CCHHR or TTR of the record) no matter what type of DASD the target device type is. The commercial package contains more than a few amazing additional utilities. Its BDMINIT program will initialize a new Broadcast Dataset of any size, based on SYSIN keyword parameter data. For example, if you want the new Broadcast Dataset to have capacity for 400 Global Notification messages, you need merely code NOTIFY=400 in SYSIN, rather than having to zap an IBM module that is in the link list. The BDMINIT program is preceded by a BDMCALC program, which helps you calculate all the sizes, track and cylinder capacities for the target DASD device type, before actually creating the new dataset by running the BDMINIT program using the same parameters. I created working Broadcast Datasets using BDMINIT, as large as over 1000 cylinders, and as small as only one track. Once the BDMINIT program has been created according to your specs, you have to load it with Notices, Userids, and Messages. These are done using newly written Bulk Dumper and Bulk Loader programs for all of these three categories. So you can allocate and format any size new Broadcast Dataset with BDMINIT, and load it using a batch JCL stream, in a very short period of time. On my development system, loading a 13000 record Broadcast Dataset from a fully loaded old Broadcast Dataset, took considerably less than one minute, clock time. Last but not least, I have to mention the BDMSCAN program. This commercial program came from the BCMSCAN program in my free package, which in turn, was an improvement over the old user-written BRODSCAN program. Both programs give you a summary of how many records of each type, are in the Broadcast Dataset, and which userids have (how many) messages deferred. But BDMSCAN (the commercial version) also will format (using an optional DD name) all of that Broadcast Dataset's records, interpreting all the field values for all the record types. If you look at File 247 of the CBT Tape, you'll see a load module of an early version of BDMSCAN that I allow everybody to use, with JCL to run it, and then you'll taste why my commercial package is so much better than my free package. You can find out about my commercial package (called Broadcast Master) by looking at www.brodmstr.com or by emailing me directly. I expect the price for my commercial Broadcast Master package to be REMARKABLY affordable. SUMMARY In the first two installments of this series, I explained many details about the internal structure of a Broadcast Dataset. Today, I described two sets of tools that I've written, to administer (any copy of) a Broadcast Dataset, in detail. The free set of programs is available on File 247 of the free CBT Tape collection (see the Updates page of www.cbttape.org). The commercial package is about to be released in beta, and inquiries about it, can be made on www.brodmstr.com, or by emailing me directly. Best of luck to all of you. And I'm looking forward to seeing you here again next month. * * * * * * * * * * * * * * * * * * * * * * * Figure 1. A sample of output from the free TSO command EESCB at the z/OS 1.8 level (TSO/E Release 3.8.0). Current PARMLIB BRODCAST information - IKJEESCB ------- ------- -------- ----------- -------- The EESCB TSO command displays information concerning the TSO SEND and LISTBC command options. Information is obtained from the IKJEESCB and TPVT TSO control blocks, which are chained off the TSO Vector Table IKJTSVT. BROADCAST dataset switching is only available from IKJEESCB version 03 or later. --------------------------------------------- Parmlib member IKJTSOxx can be invoked: A - At IPL Time B - Under TSO using PARMLIB UPDATE(xx) C - Using Operator command SET IKJTSO=xx --------------------------------------------- Source of EESCB messages: --------------------------------------------- IKJEESCB - General SEND and LISTBC defaults from the IKJEESCB control block. PARMLIB - TPVT control block BRODCAST - BRODCAST section of IKJEESCB which is only present from IKJEESCB version 03 or later. --------------------------------------------- IKJEESCB Address : 119C30D8 IKJEESCB Version : 03 IKJEESCB Flags : E8800000 IKJEESCB Opersend: On IKJEESCB Usersend: On IKJEESCB Save : On IKJEESCB Chkbrod : Off IKJEESCB Usebrod : On IKJEESCB Msgprot : Off IKJEESCB Sysplxshr Off IKJEESCB Spxshrxcf Off IKJEESCB Oprsewait On IKJEESCB Spxshrini Off IKJEESCB Lognmspec Off PARMLIB Dataset : ADCD.Z18.PARMLIB PARMLIB Volser : Z8RES1 PARMLIB Member : IKJTSO06 PARMLIB Activator SBGOLOB PARMLIB Swt Date: 2007-07-17 PARMLIB Swt Time: 08:03:41 PARMLIB System : ADCD PARMLIB CPUID : 0192 PARMLIB CPU Model 1247 This system does not write to TSO Userlogs. BRODCAST Dataset : SYS1.BRODCAST BRODCAST Volser : Z8SYS1 BRODCAST Unit Name SYSALLDA BRODCAST Flags : 24 BRODCAST Timeout : 005 Seconds BRODCAST Operator: Prompt The BRODCAST dataset name is the default. BRODCAST Dataset volser not specified in IKJTSO06 BRODCAST Dataset name was set by PARMLIB TSO command BRODCAST Dataset switch required? No BRODCAST Dataset Name is an ALIAS? No * * * * * * * * * * * * * * * * * * * * * * * Figure 2. Illustration of Vinh Vu's BCMUTIL ISPF interface for administrating User Messages connected to Userids in the Broadcast Dataset. Sort Exit ------------------------------------------------------------------------------ 2007/07/31 --------------- SYS1.BRODCAST Utility -------- Row 1 to 17 of 48 Cmd input ===> Scroll ===> PAGE (SORTID, SORTTOT) CPU Type: 1247 CPs: 1 SU/Sec: 1483.5 Real: 512M Exp: 0M Active SMF id: SYS1 Number of Active TSUs: 1 Broadcast DSN: IBMUSER.NEW.BRODCAST Volume: WORK04 Unit: 3390 Creation Date: 2007/105 Dsorg: DA Recfm: F Keyl: 1 Lrecl: 129 Blksize: 129 Action SKIP MSGS ID Number Of TSO ID (S/D/P) (nn) (nn) Messages Status ------------------------------------------------------------------------------ _ USER001 1875 _ USER002 256 _ USER003 4 _ USER004 5 _ USER005 1 _ USER017 17 _ USER021 28 _ USER045 38 _ USER057 6