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.