MVS TOOLS AND TRICKS OF THE TRADE SEPTMBER 2004 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. ADMINISTERING SYS1.BRODCAST Today I'd like to talk about a frequently neglected part of the MVS operating system, which need be neglected no more. This is the part of the system which IBM designed (many long years ago) to convey messages between programmers using TSO, and which is now mostly used to tell the programmer how well a job has executed. I'm referring to the broadcast facility of MVS. The broadcast facility uses a dataset called SYS1.BRODCAST. (The first A has been left out to get its name down to 8 characters.) SYS1.BRODCAST technically "belongs" to TSO, but it is a necessary part of MVS itself. You can't have an MVS operating system which doesn't contain the SYS1.BRODCAST dataset. As necessary as SYS1.BRODCAST seems to be, IBM certainly hasn't provided any normal and convenient set of tools for the system administrator to use in taking care of it. I can supply a few excuses for IBM's neglect in that regard, but I've also "put my money where my mouth is" and I've written many of these tools that will fill the void which IBM has left. If you set up and use these tools, which don't cost a penny, then just about all of the administration problems regarding SYS1.BRODCAST will be gotten rid of. Before telling you about my tools, we have to know something about how SYS1.BRODCAST works, and how IBM's commands, SEND and LISTBC, as well as the ACCOUNT and SYNC administrator commands, interact with it. SYS1.BRODCAST is a Direct Access dataset (DSORG=DA) whose records (KEYLEN=1,LRECL=129) are accessed by means of a relative record number of 6 hex digits, which starts with (hex) 000000. SYS1.BRODCAST currently has six (really seven) different types of records. Each type has its own purpose and its own layout. The macros describing all the SYS1.BRODCAST record types have now (finally) been placed in SYS1.MACLIB instead of in the Optional Materials, and they have names IKJZT301 thru IKJZT306. Two TSO commands access SYS1.BRODCAST on a regular basis. They are: SEND, which writes messages to SYS1.BRODCAST, and LISTBC, which reads messages from SYS1.BRODCAST, and which (in the case of user messages) deletes them after they have been read. The SEND and LISTBC commands have to be APF authorized, because they are usually invoked on behalf of TSO users who don't have write access to the SYS1.BRODCAST dataset. LISTBC is automatically invoked by TSO every time you LOGON. That's why you see your notification messages at LOGON time. For your information, enqueues on the SYS1.BRODCAST dataset have a QNAME of SYSIKJBC, and an RNAME of the hexadecimal 6-digit relative record number that is being accessed. An ENQ is usually also placed on the header record of SYS1.BRODCAST, whose relative record address is 000000, so the RNAME for header record access is X'000000'. This extra ENQ is done to "lock up" the header record in any case. That's because most programs which access SYS1.BRODCAST, have to start by looking up information that is stored in the header record. There are two basic types of broadcast messages which are stored and forwarded by means of the SYS1.BRODCAST dataset. These are: global notification messages, and user messages. Global notification messages go out to all TSO users whenever they LOGON (and the LISTBC program is automatically invoked). These are the messages which the system administrators put out, such as: "System A will be down all next Tuesday. Please only use System B on Tuesday." These are the messages which all users have to see. And then there are the user messages which go only to one userid. If one TSO user issues a SEND command to send a message to another TSO user, then (if TSO userlogs are not in effect, or if the particular user doesn't have a userlog allocated, and if the user isn't currently logged on) that message is stored as a user message in SYS1.BRODCAST. When a job, which had NOTIFY=userid coded in the JOB card, finishes, then a SEND command is also issued by the system, to notify the TSO user mentioned, that the job has finished. These "NOTIFY" messages are the most frequently found user messages on MVS systems nowadays. Since SYS1.BRODCAST is a Direct Access dataset, it has a fixed number of "slots" for records, and therefore it can fill up. When SYS1.BRODCAST fills up, TSO users who are not logged on, cannot receive messages unless TSO userlogs are in effect and they have a TSO userlog. Many MVS systems operate with SYS1.BRODCAST completely filled up. That's because IBM doesn't give you a good way to administer its contents. This doesn't have to happen. WE HAVE THE TOOLS! When SYS1.BRODCAST fills up and the user whose messages have filled it up, does not LOGON (for example, if he has left the company), then IBM has provided only one solution to delete THAT USER's messages: Wipe out EVERYBODY's messages, no matter how important they may be. IBM allows the administrator to do this, with the ACCOUNT and SYNC commands. These commands check which users are defined both to SYS1.UADS and the security system, and the SYNC command then completely initializes SYS1.BRODCAST so it is completely blank. Talk about blowing up the barn to kill a skunk that's inside it! On File 247 of the CBT Tape collection, which is free to everyone, there is a very capable package of SYS1.BRODCAST administration tools. These tools are collectively called the "Broadcast Manager" package, and as I've said, they are free. Using the package's BCMISPF interface, which takes 5 minutes to set up for each MVS instance in your shop, you can: List, Print and Delete all outstanding messages for any user. And also, you can even List, Print or Delete only SOME of the messages and leave the rest, for any user, even if it is not you. NO OTHER PACKAGE currently gives you this power in SYS1.BRODCAST, and there is plenty more besides that, which you can do. Here are some further examples. You can create a copy of SYS1.BRODCAST which contains your old messages after an ACCOUNT SYNC of the real SYS1.BRODCAST has wiped them out. And you can List, Print, and Delete (all or some) messages from the copy as well. In addition, the BCMSEND command allows you to write new messages to either SYS1.BRODCAST itself, or to the copy. If this has aroused your curiosity, please read on, and I'll show you some more of the wonders contained in the "Broadcast Manager" package from CBT Tape File 247. BASIC SETUP OF THE BCM PACKAGE To find out about the CBT Tape collection of software, do a www.google.com search for "CBT Tape". Then follow your nose. The Broadcast Manager package is on File 247 of the CBT collection, and once you've created its partitioned dataset on your MVS system, you're ready to start. For quick setup, there is a LOADMODS member, which is really an XMIT-unloaded load library containing all the relevant load modules. Just do a TSO RECEIVE INDS(this.pds(member)) and create the load library. Then copy all the members to a load library which your TSO session can get to. You won't need APF authorization, except to run the BCMDEL and BCMDEL1 programs, because they temporarily change the userid and then invoke LISTBC. But since you'll probably be running BCMDEL2 to delete messages, and BCMDEL2 accesses the SYS1.BRODCAST dataset directly, no authorization is required. If you want to assemble your own modules, see sample JCL members $$BCMASM and/or $ASMSING. And also, your TSO id should have at least UPDATE or ALTER access to the SYS1.BRODCAST dataset. This eliminates the amateurs, and doesn't let them play. Once you have access to the load modules, you'll want to set up the BCMISPF interface (written by Vinh Vu), which takes about two minutes. First either create the ISPF materials pds by running job $LOADSPF, or by doing a TSO RECEIVE INDS(file247.pds(BCMISPF)). Copy the BCMUTIL member of that pds to a CLIST or REXX library (SYSPROC or SYSEXEC concatenation) and the rest of the members to an ISPF panel library (ISPPLIB). Then from TSO, just execute TSO BCMUTIL, and you should be ready to go. A panel showing all users with outstanding SYS1.BRODCAST messages will appear. You just type an S (to display) D (to delete) or P (to print) next to any user whose messages you want to deal with. The SKIP(mm) and MSGS(nn) keywords will always allow you to skip the first mm messages and then display, print, or delete the next nn messages. ADVANCED FACILITIES OF THE BCM PACKAGE The BCM (Broadcast Manager) package is a very complete set of utilities for dealing with the "user message" part of SYS1.BRODCAST, and for dealing with the SYS1.BRODCAST dataset as a whole. For example, the BCMDUMP program allows you to create an FB-130 sequential dataset from SYS1.BRODCAST, including everything in it, and you can send that dataset anywhere--you can even zip it or unzip it. Then, with programs BCMREST (restore the backup to the old size) or BCMEXPND (which allows you to make it bigger and add more user records), you can create a new copy of SYS1.BRODCAST from this FB-130 (non-DA) backup, which can be used later, as a new version of SYS1.BRODCAST on the system. The BCMSEND TSO command can send new user messages to the copy, or to the original SYS1.BRODCAST dataset. And the BCMLIST and BCMDEL2 programs can list or delete (respectively) user messages from either the original SYS1.BRODCAST, or from a copy. The BCMUTIL REXX exec also has the capacity to access both the working SYS1.BRODCAST dataset or a copy. You can control which SYS1.BRODCAST format dataset is addressed by any of the BCM**** programs, by allocating the BRODCAST DD name to either SYS1.BRODCAST or to a copy of it. The BCMSEND TSO command will send messages to either SYS1.BRODCAST or to a copy, in this way. Also, since BCMSEND (unlike IBM's SEND) command, does not use IBM's IKJPARS TSO command parser, but it takes all characters that are one space after the TSO userid, you can send characters to SYS1.BRODCAST messages that are not "legal" by TSO standards. So you can make messages out of hex characters and be very creative, if you want to be. The BCMUSADD and BCMUSDEL TSO commands use IBM's IKJIFRIF interface to the "userid" records of SYS1.BRODCAST, to either add, or delete, a new userid from SYS1.BRODCAST (or from a copy). This has nothing to do with RACF or UADS. You can add a phony id like XXXXXX. When you add the new userid to SYS1.BRODCAST in this way, you can then SEND messages to that "userid" or use the NOTIFY=XXXXXX keyword in a job card, and the messages will go into the chain of messages that are connected to userid XXXXXX in SYS1.BRODCAST, even if that userid does not exist anywhere else on the system. This is a "SYS1.BRODCAST" thing, only. Of course, you'll need the BCM package to display or delete userid XXXXXX's messages too, but the BCMUTIL interface will do it. Of course, you'll want to do this carefully, so that SYS1.BRODCAST won't get filled up with your new id's messages. A practical use for this type of thing would be if you want to track a job for a couple of days. Just do a BCMUSADD for XXXXXX, and send NOTIFY=XXXXXX messages to the runs of that job. Use the BCMUTIL interface to track the resulting messages for as long as you need them. Then, after you don't need the id anymore, just BCMUSDEL XXXXXX and all of the messages for that userid on SYS1.BRODCAST will be cleared out, in addition to the userid itself being cleared out. Of course, when you run IBM's ACCOUNT and SYNC against SYS1.BRODCAST, all the new id's you've created in this way will be cleaned out, because SYNC checks all userids against both SYS1.UADS and the RACF (or other security system) database, and SYS1.BRODCAST userid records for only valid userids will be created. Most of the BCM package's functionality deals with the "user messages" part of SYS1.BRODCAST. But there is some "global notification" message support there, too. The BCEDIT REXX, and the other BCED*** REXX members in File 247 were supplied by Paul Lemons, and they allow you to ISPF EDIT your "global notification" messages from SYS1.BRODCAST and replace them with new ones. To do this, you need TSO CONSOLE authority, so you'll have to get at least READ access to the TSOAUTH CONSOLE resource from RACF for your TSO userid. But as an administrator, you should be able to get permission for this access. In the area of the "global notification" messages in SYS1.BRODCAST, I've made one attempt to write a program that displays these notification messages, and that is the TSO command, BCMNLIST. In the future, I hope to possibly create my own "notification message" delete and send commands, but I haven't done so as yet. Creating such commands would allow me to write and delete notification messages to a copy of SYS1.BRODCAST, as well as to SYS1.BRODCAST itself. There is another little thing that I've done in the SYS1.BRODCAST area. That is my program called BCMCLEAN. If you've ever browsed your SYS1.BRODCAST dataset, it might seem full of messages, even though a program like BCMSCAN, or the BCMUTIL package says that it is practically empty. That is because when LISTBC deletes a user broadcast message, it doesn't wipe out all the message text. When LISTBC deletes a user message, it only changes the first two bytes of it. The first byte of the message, the "key" byte, has to be X'FF' for a "deleted message". But there's also another condition. For a user message in SYS1.BRODCAST to be considered "deleted", the first data byte (the one after the key) has to equal the "R" (record number on the track) of the CCHHR or TTR record location on DASD. Therefore, LISTBC just sets the first byte of the message record to X'FF' and the second byte to the R of the CCHHR. The rest of the message is still there, and if you're browsing, it looks as if there's a real message in that slot. So the function of BCMCLEAN is to go through all the user messages in SYS1.BRODCAST and find the ones that are actually deleted messages. Then BCMCLEAN replaces the text part of the old message with hex zeroes. This makes it easier to spot deleted messages in SYS1.BRODCAST if you are BROWSE-ing it with ISPF (not a good practice, because you lose the last byte) or you're REVIEW-ing it with the REVIEW TSO command from CBT Tape File 134. REVIEW shows the key byte and data bytes clearly, and it differentiates between them. CONCLUSION This month, I've tried to open your eyes to a (usually) very neglected part of MVS administration, taking care of the SYS1.BRODCAST dataset. This subject actually has many fine points, as I've tried to either show directly, or hint at indirectly. The "broadcast manager" administration package from CBT Tape File 247, which is free, will greatly help you clean out garbage messages in SYS1.BRODCAST, and will actually make it possible to manage and administer SYS1.BRODCAST effectively. Best of luck to all of you, and I'm hoping to see you here again next month.