





















     NN       NN     EEEEEEEEEEE     WW          WW        SSSSSS
     NNN      NN     EE              WW          WW      SS      SS
     NNNN     NN     EE              WW          WW     SS
     NN NN    NN     EE              WW          WW      SSS
     NN  NN   NN     EEEEEEEEEE      WW          WW        SSSSS
     NN   NN  NN     EE              WW    WW    WW            SSS
     NN    NN NN     EE              WW   WWWW   WW               SS
     NN     NNNN     EE              WW  WW  WW  WW               SS
     NN      NNN     EE               WWWW    WWWW      SS      SS
     NN       NN     EEEEEEEEEEE       WW      WW         SSSSSS






















                    ROCKWELL INTERNATIONAL CAE NEWS UTILITY

                             By: J. F. Lawrence

                    Copyright 1986, Rockwell International
                             All rights reserved





OVERVIEW..................................................................Page 1

COMMANDS..................................................................Page 1

PROTECTION................................................................Page 3

ORGANIZATION..............................................................Page 4

NEWS FILES................................................................Page 5

INSTALLATION..............................................................Page 7

                      Rockwell International NEWS Utility              Page 1



OVERVIEW


NEWS is a general purpose utility which resembles the VAX MAIL utility.  It is
intended for the use of the poor overworked system manager who  just  got  the
twenty  third call asking about the status of the new disk drive installation.
I originally used a public MAIL file to post messages to the user community as
a NEWS feature but was never very satisfied with it for lots of reasons:

    1. Only one user at a time could read the MAIL file.

    2. Anyone could delete the messages since MAIL insists on  read and  write
       access  to a file before it will let you read it.  Items were regularly
       dissapearing, and I had to keep two copies of the MAIL file, one public
       and one secure.  Fortunately, no one found out that they could edit the
       various messages.

    3. MAIL was really a mild pain in the wherever to use because the commands
       were close to what was needed but weren't quite right.  New users  took
       quite  a  while to get the hang of using the commands,  so there I was,
       back to answering the phone.


The utility is primarily intended for general topics of interest to the entire
user community.  On my system,  I have a large subset of users developing code
in  Ada  for a target processor not built by DEC.  Therefore,  I added a topic
feature to NEWS.  To get general news items, users enter the command NEWS.  To
read the latest about Ada, users enter NEWS ADA. The installation section will
show you how to implement this feature.


COMMANDS


NEWS has the following commands all of which can be abbreviated to their first
character:

    CANCEL -

        A manager's command that allows you to delete any news item  prior  to
        it's expiration date.  Manager's commands are invisible to your users.
        They can't enter them, nor will they show up in the help messages.

    DIRECTORY -

        Displays  a  list  of  all  available  news  items.  Unread  items are
        highlighted in the display.  NEWS automatically displays  a  directory
        when first entered.

    EXIT -

        Gets you out of news.  You can accomplish the same thing by repeatedly
        entering <CTRL Z> until you get the DCL prompt.



                      Rockwell International NEWS Utility              Page 2



    HELP -

        Invokes  NEWS  help  via  the  system  HELP  utility.  Managers  get a
        different help  file  than  users. Managers  help  includes  the three
        manager commands CANCEL, LIST, and PROLONG.

    LIST -

        A manager's command that will display a list of all the users who have
        invoked NEWS along with some statistics about them.

    PROLONG -

        A  manager's  command that allows you to extend the expiration date of
        an existing NEWS item. (Incidentally, can anyone think  of  a  command
        name that means  the same thing and doesn't start with  C, D, E, H, L,
        P, R, S, or T?)

    READ -

        What NEWS is all about.  If you enter READ or hit the <RETURN> key  at
        a NEWS> prompt, NEWS will do one of two things; 1) If there are unread
        NEWS items, NEWS will start reading the first unread one, or 2) if all
        news has been previously read,  NEWS will start reading the first news
        item. To start reading at a specific item, simply enter:

            READ item-number

        or

            item-number

    SUBMIT -

        Lets the system manager and, optionally,  users submit news items.  It
        has  a  couple  of  useful  features.  You  can  simply invoke SUBMIT.
        Whereupon NEWS will; 1) prompt for the retention period in days from 1
        to 90, 2) ask for a subject title, and 3) go into line entry mode just
        like MAIL.  If you don't care to enter a long news item this way,  you
        can  invoke  your favorite editor as part of the SUBMIT command or you
        can pre-edit a file and submit it directly.  You can even combine both
        features and edit an existing file.  To invoke  an  editor  enter  the
        command as follows:

            SUBMIT/editcommand/options

        Where  editcommand can be a command like EDIT,  EVE,  or whatever.  If
        your edit command uses options (eg.  TPU/SEC=MYSECFILE),  simply enter
        the  slash  and follow it with the command as you normally enter it at
        the DCL level:

            SUBMIT/TPU/SEC=MYSECFILE.

        NEWS will treat everything after the first slash  (/)  as  a  complete
        command.

                      Rockwell International NEWS Utility              Page 3



        To specify an existing file use the indirect (@) symbol. For example:

            SUBMIT @MYNEWS.TXT

        will  submit  a  file in your default directory named MYNEWS.TXT.  You
        can use any legal filename except wildcards which are not supported.

        To combine both of the above, enter a command such as:

            SUBMIT /TPU/SEC=MYSECFILE @MYNEWS.ITEM.

        Incidently,  spaces are ignored completely after  the  SUBMIT  command
        verb. So you could enter /EVE as / E V E.

    TOPIC -

        Lets you select a specific news topic. There are two entry formats: 

            TOPIC topic-name

        or

            TOPIC

        The first command will switch you to the specified topic directly.  The 
        second  format  will  display a list of the available topics and prompt 
        for selection of one of the available topics.  Pressing the RETURN  key 
        will select the default topic NEWS.  


PROTECTION

Since NEWS is a world accessible utility,  any directories  where  news  items
will be stored must have world execute access, which allows any user to access
a file provided they specify the file without  the  use  of  wildcards.  (NEWS
maintains  the  complete  file  specification  for each news item internally.)
World read is NOT required,  since that  allows  users  to  access  files  via
wildcards, in effect letting them browse.


The  news  item  files  are  first  stored  in  the  submittors SYS$LOGIN root
directory then moved to the appropriate NEWS topic subdirectory by a batch job
that  runs  at  midnight.  If you want to let your users submit news items but
don't permit them to access each other's directories for security reasons, you
can  create a special directory with world execute and write access.  You will
then have to edit NEWS.COM and change  the  references  to  SYS$LOGIN  to  the
directory  you  have created.  If only system privileged staff members will be
making news submittals, you can simply change all SYS$LOGIN references to NEWS
in NEWS.COM.







                      Rockwell International NEWS Utility              Page 4



You must also insure that the world has write access to the data files in  the
topic   subdirectories.   NEWS  will  create  these  files  with  the  correct
protection,  so just make sure that you don't change their  protection  masks.
The files in question are; NEWSDIR.DAT, USERLOG.DAT, and LASTNEWS.DATE. Do NOT
set the world access protection to write for the various NEWS directories. The
recommended   protection  mask  for  all  NEWS  directories  is;   SYSTEM:RWE,
OWNER:RWE, GROUP:RWE, WORLD:E.
 


ORGANIZATION


The NEWS utility consists of four command and three help files.  It is written
in  DCL  so  you  can  easily modify it to any special requirements.  It has a
simple debugging feature that requires SYSNAM and SYSPRV  privileges  to  use.
You will also need SYSPRV to use the management commands.


The debugging aid is simply a controlled way to turn on the verify mode.  NEWS
first  turns  off  verify  and  then  attempts  to  translate the logical name
NEWSDEBUG at the executive mode level.  The logical name can be in any  table;
Job, Process, Group, or System and it can have any value.  Since the privilege
SYSNAM  is  required to make logical name entries at the executive mode level,
the casual user is prevented from turning on the debug feature.


A similar means is used to enable/disable submital of news items by users. The
logical name NEWSENABLE must be entered in the system logical  name  table  at
executive mode level to enable NEWS item submitals by users.


The manager commands CANCEL,  LIST,  and PROLONG can only be invoked by a user
with SYSPRV privilege.  This privilege will also override the submital lockout
described above and it will bypass the maximum retention period check,  so the
manager can submit items which are retained for months or even years.  For  my
facility,  I  created  an  introduction to NEWS outlining its use and rules of
conduct which expires in 1999 (I entered 4748 for the retention period).


The news command and help files must reside in a directory which is equated to
the  logical name NEWS.  The data files and NEWS item files for each topic are
kept in a subdirectory which must  have  the  same  name  as  the  topic  (eg.
subdirectory  [.ADA] will be required for ADA NEWS).  The subdirectory [.NEWS]
is mandatory,  since it is the default NEWS subdirectory.  To add new  topics,
simply  create a subdirectory with the same name as the topic,  and then enter
the command:

    $ NEWS topic

and  NEWS  will  do  the  rest.  But  don't  enter this command until you have
completed the basic NEWS installation covered further on.  You'll  get  a  DCL
error and the command won't do anything.



                      Rockwell International NEWS Utility              Page 5



NEWS FILES



NEWS  is  supplied  as a set of command and help files.  To simplify it's use,
NEWS was designed to install itself and create the remaining files  the  first
time you run it.


The command and help files are:


    NEWS.COM -

        The  main  NEWS utility invoked by both average Joe User and you,  the
        system manager.


    CHECKNEWS.COM -

        A suplementary command file that can be invoked  in  individual  login
        command  procedures or the site login command procedure,  depending on
        your  preference.  It  checks  if a user has read all the current NEWS
        items and,  if they have not,  displays a message informing them  that
        there is fresh news.  This procedure  uses  the  VT100/VT200  graphics
        character  set,  so if your facility uses brand X terminals that can't
        display these characters,  then you will have  to  edit  the  file  to
        display something readable.


    SUBMITNEWS.COM -

        A command file which submits the batch file SUBMITNEWS.SUB  (described
        next)  at  midnight  to  the  SYS$BATCH  queue.  I  use  the  trick of
        submitting a batch file from a command file a lot.  It  allows  me  to
        submit  jobs  that  run at special times or on specific queues or that
        have other requirements that I usually forget and  have  to  look  up.
        Also,  the  command  file  can be invoked by the batch job to resubmit
        itself.  I usually give the two files the same  name  and  distinguish
        them with the types .COM and .SUB.

        You will have to  edit  this  file  to  specify  a  queue  other  than
        SYS$BATCH or to change the submittal time.


    SUBMITNEWS.SUB -

        A batch file that runs at midnight each day and then resubmits  itself
        as  described  above.  It  purges expired news items and,  if the user
        submital feature is enabled,  moves any user  news  files  from  their
        SYS$LOGIN  root directory or the alternate submittal directory (if you
        take that option) to the appropriate NEWS subdirectory.




                      Rockwell International NEWS Utility              Page 6



        A  caveat  about the purge operation.  The NEWS item file being purged
        is deleted from the system.  If you don't want this to happen for some
        reason,  you will have to edit out the line in this file  that  starts
        with:

            $ DELETE/LOG

        Another  way  to  accomplish  the  same  thing is to pre-edit any NEWS
        items, and use the @file-name option on the SUBMIT command.  That way,
        you will have a copy of your submittals under meaningful  file  names.
        You might also want to create a specific directory for these items, so
        that they can be easily found.


    SYSNEWS.HLP -

        A help file that can be installed in the system help file.  NEWS  will
        optionally  install  this  file for you.  See the installation section
        for details on how to do this.


    MANAGERHELP.HLP -

        The help file for system managers. It contains the same information as
        the  general  help  file  described  below  plus information about the
        manager specific commands CANCEL, LIST, and PROLONG.


    NEWSHELP.HLP -

        The help file invoked by NEWS when users enter the  HELP  command.  It
        invokes  the  system  help  command  via  the logical name SYS$HELPLIB
        defined in user mode.



For each topic, NEWS keeps track of;  1) the time each user reads the news all
the way through, 2) the last time a news item was submitted, 3) a directory of
the news items in submittal order,  and 4) the  individual  news  item  files.
This information is kept in a set of files maintained in  each  of  the  topic
subdirectories.  These files are:


    USERLOG.DAT -

        An indexed sequential file indexed by username.  User information such
        as 1) the last time and date NEWS was read,  2) the  number  of  times
        NEWS was invoked, 3) the date and time of the last news submittal, and
        4)  the  number  of  news  submittals  made  are  stored  here.   This
        information  is  used to determine which news items have been read and
        also provide you with some data about the usage of NEWS.





                      Rockwell International NEWS Utility              Page 7



    NEWS.DIR -

        An  indexed  sequential  file  indexed  by  submittal date.  NEWS item
        information such as 1) the item's submittal and expiration  dates,  2)
        the  subject  title,  3)  the  submittor's  name,  and 4) the complete
        filename are kept in this file.


    LASTNEWS.DATE -

        The date and time of the latest news item submittal is kept here. This
        is compared to the date and time that the user invoking NEWS last read
        an item and used to flag unread news items.


    NEWSnnnnnnnnnn.NWS -

        There  will be several of these.  They are the actual NEWS text files.
        The nnnnnnnnnnn corresponds to the submittal date and time.




INSTALLATION


Installation is done in two phases; a manual setup and a final installation. I
haven't provided a fully automatic installation for several  reasons;  1)  the
initial  setup  isn't  very  complicated,  2)  I  have  no idea what your site
requirements  are  and  developing  a  command  procedure  to  allow  for  all
possibilities  might  result in a procedure more complex than the NEWS utility
itself, and 3) I believe that a system manager should know what is going on in
his system and should manage it rather than the other way around.


You should read this section  completely  to  familiarize  yourself  with  the
proceedure.  Once the manual setup is completed,  you then run NEWS which will
complete the installation by creating all the files it needs.  If  you  choose
to set up additional topics,  you will have to create an appropriate directory
and run NEWS for each topic.
















                     Rockwell International NEWS Utility               Page 8



The NEWS distribution kit consists of the following files:

    NEWS.DOC        - This file

    NEWS.COM        - The main utility

    CHECKNEWS.COM   - Checks for any new NEWS and notifies users

    SUBMITNEWS.COM  - Submits the SUBMITNEWS.SUB file to batch

    SUBMITNEWS.SUB  - Batch housekeeping utility

    MANAGERHELP.HLP - Help for system managers

    NEWSHELP.HLP    - Help for users

    SYSNEWS.HLP     - Help to be placed in the system help library


First;

    Create a directory for NEWS and set up the required  system-level  logical
    names:

        $ CREATE/DIRECTORY dev:[dir]
        $ DEFINE/SYSTEM/EXEC  NEWS dev:[dir]
        $ DEFINE/SYSTEM/EXEC/TRANS=(CONCEAL,TERMINAL) NEWSROOT dev:[dir.]

    Dev:[dir] can be anything you want to make  them,  as  long  as  they  are
    allowed by VMS.  I used something like DRA0:[NEWS].  You should also place
    the  last  two  commands  somewhere  in  your  site  startup command file,
    SYS$MANAGER:SYSTARTUP.COM,  since NEWS uses these logical names.  Be  sure
    that  the period between the directory name and the closing bracket (]) is
    present in the last command.


Second;

    Copy  all  of  the  above listed files to the just-created directory using
    either BACKUP or COPY. These files are most likely already in a directory.


Third,

    Set your default to the NEWS directory and create a  sub-directory  called
    NEWS. This is the default subdirectory for general news items.

        $ SET DEFAULT  NEWS:
        $ CREATE/DIRECTORY  [.NEWS]







                     Rockwell International NEWS Utility               Page 9



Fourth,

    Make  sure  you have SYSPRV privilege (a system UIC isn't good enough) and
    run NEWS.  You can do this by entering either of  the  following  sets  of
    commands:

        $ @NEWS

    or

        $ NEWS :== @NEWS:NEWS
        $ NEWS

    NEWS will display several messages as it runs,  informing  you  that  file
    so-and-so  can't  be  found  and is being created.  NEWS creates all files
    automatically except for the system HELP.  If you want a brief description
    of NEWS to appear in the system HELP,  answer YES or Y when NEWS  asks  if
    you  want  to  add NEWS to the system wide HELP.  If not,  answer NO or N.
    NEWS will insist on either a yes or no answer.


Fifth,

    Locate your site login procedure. It's usually SYS$MANAGER:SYLOGIN.COM but
    yours may be different.  To find out exactly, use the command SHOW LOGICAL
    SYS$SYLOGIN. Edit the procedure to include the following commands:

    $ NEWS :== @NEWS:NEWS
    $ @NEWS:CHECKNEWS

    You can leave out the second line if you don't want to notify  your  users
    when a new NEWS item appears. If you have captive accounts, you might want
    to  leave  out  both  commands  and  simply invoke a call to NEWS in their
    LOGIN.COM files.


Sixth and last, (This is optional)

    You might want to submit an initial news item,  outlining the use of  news
    and  any  rules  of conduct.  This will trigger CHECKNEWS.COM to display a
    message to users when they login,  telling them that  NEWS  is  available,
    providing that you included the call in the appropriate login command file
    or files.

    Incidentally,  NEWS  will  substitute  the name "Staff" for any privileged
    username as the submittors name.  If you wish to change this,  comment out
    or  delete  the  lines  that  substitute  the name "Staff" in place of the
    username in the NEWS.COM file.

