RSX11M-PLUS VERSION 2.0 DOCUMENTATION
                                 THE BERGEN RECORD



          ----------------------------------------------------------------
               SUBJECT:OWN -- new utility to report on UFD ownership
                              AUTHOR: Allen A. Watson
                   LAST REVISION DATE: SUNDAY, NOVEMBER 15, 1982
          ----------------------------------------------------------------


     
     









                                   CHAPTER 1

                               OWN -- UFD utility





         OWN is a new utility to report on UFD ownership or content, and to
         maintain  the  file  that  contains this information.  It bears no
         direct relationship to ACNT.  OWN is written in C.



         1.1  Use of OWN


         OWN has four functions:  to list at the issuing terminal the owner
         of  a UFD or the UFD's belonging to an owner;  to modify the owner
         name of a particular UFD;  to add new  UFD's  and  owners  to  its
         list;  and to delete UFD entries from the list.  

         Modifying, deleting and adding  are  priveleged  functions,  since
         they  involve  writing  to  the  OWN  text file, [1,5]UFDLIST.TXT.
         Non-priveleged  users  may  use  OWN  only  to  list  UFDLIST.TXT;
         however,  if  an  alternate  file is accessed with the "-f" switch
         (see below), access will be governed by  the  user's  file  access
         rights.  

         The file [1,5]UFDLIST.TXT should be created using PIP  or  a  text
         editor  before  attempting  to  use  OWN.  The file can be created
         empty;  then OWN may be used to add entries.



         1.2  Function Switches


         The three function switches -- add (-a), modify (-m),  and  delete
         (-d) -- are mutually exclusive;  that is, only one can be given on
         any OWN command line.  An attempt to use two or more will  produce
         an error message.

         If no function switch is given, OWN assumes you desire a listing.


     OWN -- UFD utility                                            Page 1-2
     


         1.2.1  Listing (no switch)


         OWN may list information in one of  three  ways:   all  UFD's  and
         owners,  the  owner of a particular UFD, or all UFD's belonging to
         one owner.

         Like all C programs, OWN possesses the capability  of  redirecting
         its  output.   The output of OWN may be redirected to a file or to
         LP:  by appending the text ">filespec" or ">LP:"  to  its  command
         line.  Examples are given below.



         1.2.1.1  Listing all UFD's - 

         If OWN is invoked with no command line, it will  simply  list  the
         entire  file  [1,5]UFDLIST.TXT  to  standard  output  (TI:  unless
         redirected).
          
             OWN             --lists all UFD's to TI:
             OWN >filespec   --lists all UFD's to file "filespec"
          



         1.2.1.2  Listing UFD's for one owner - 

         If OWN is given an owner name, it will search [1,5]UFDLIST.TXT and
         list only lines containing that user name:
          
             OWN WATSON      --list all UFD's belonging to WATSON
             OWN BIGTPC      --list UFD containing BIGTPC source
          

         Note that OWN considers the entry a match  if  the  "owner"  given
         occurs  anywhere in the "owner" name on file;  thus OWN WAT or OWN
         SON would match the same as OWN WATSON, and in addition, if  there
         were a CARSON, that would also be listed.

         The "owner" text can be up to 70 characters  long.   This  permits
         entries of the form "SYSTEM-SOURCE-SAVE-BOOT".  OWN will then find
         a match on any of the words in the line, e.g.  OWN SAVE.



         1.2.1.3  Listing owner of a UFD - 

         If OWN is given a UFD specification, which  must  be  enclosed  in
         brackets  to  distinguish  it  from  a user name, it will list the
         owner of that UFD.
          
             OWN [2,31]      --list owner of [2,31]


     OWN -- UFD utility                                            Page 1-3
     


          



         1.2.2  Modifying UFD owner (-m switch)


         A priveleged user may change the owner name for  a  UFD  in  OWN's
         file,   [1,5]UFDLIST.TXT.   Non-priveleged  users  may  modify  an
         alternate index file if they have access to it by using  the  "-f"
         switch.   To modify, a switch (-m) must be given, and then the UFD
         spec.  Example:  
          
             OWN -M [2,31]   --change the owner name for [2,31]
          

         OWN will report that it found the UFD, showing the current  owner,
         and  then  will  prompt  for a new user name.  Only one UFD may be
         modified;  OWN must be re-executed for each modification, and each
         modify produces a new version of UFDLIST.TXT in [1,5].



         1.2.3  Adding entries (-a switch)


         A priveleged user may add entries to OWN's list by  means  of  the
         "-a" switch.  Non-priveleged users may add entries to an alternate
         file by using the "-f" switch.  No other  arguments  are  required
         (they will be ignored if given).  OWN will prompt first for a UFD,
         and then for a user name to be associated with the UFD.  

         When the UFD is entered, OWN checks the UFD's already on file  and
         rejects  duplicate  UFD's.   There  can be only one owner for each
         UFD.  "Owner" does not necessarily have to be an actual user name;
         it  can  be,  for  example,  a  program name (for UFD's containing
         program source) or functional name, such as SYSCMDFILES for [1,5].

         Owner names are limited to 70 characters and  cannot  contain  any
         blanks  (C  will  terminate  input  at the first blank).  To enter
         multi-word  "owner"  lines,   use   hyphens   or   slashes,   e.g.
         SOURCE-FOR-BIGTPC or SOURCE/BIGTPC.

         OWN will continue prompting for UFD's  and  owner  names  until  a
         CNTL/Z is entered in response to the UFD prompt.



         1.2.3.1  Redirecting input for Add - 

         Since OWN is a C program, its standard input (usually TI:) can  be
         redirected  to  a  file using the "<" convention.  For example, if
         the file UFD.NEW contained the following text:


     OWN -- UFD utility                                            Page 1-4
     


          
             [222,3]
             STUDENTA
             [222,4]
             STUDENTB
             [222,5]
             STUDENTC
          
         then the command line
          
             OWN -A <UFD.NEW
          
         would add the three UFD's  to  [1,5]UFDLIST.TXT.   Any  errors  in
         input  (such  as a UFD that already exists on the file) will cause
         OWN to get out of sequence in reading the input file  and  produce
         unpredictable  results.   If  this happens, delete the most recent
         version of the output file (either UFDLIST.TXT or the  file  named
         in  the  "-f"  switch),  fix  the  input file, and rerun OWN.  OWN
         reports each addition to the file at your terminal, so you  should
         be able to pinpoint the error in the input file.



         1.2.3.2  Sorting UFDLIST.TXT - 

         UFDLIST.TXT is not sorted by OWN.  Entries are simply appended  to
         the  file.   It  is advisable after adding new entries to sort the
         file so that  listings  will  be  in  UFD  sequence.   The  delete
         function is also affected by sort order.

         To sort the file, any line-by-line sort utility may be used.   The
         C sort utility, for example, could be invoked by the command:  

         SORTC -O [1,5]UFDLIST.TXT [1,5]UFDLIST.TXT

         -or-
         RUN $SORTC/CMD="SOR -O [1,5]UFDLIST.TXT [1,5]UFDLIST.TXT"

         SORT-11, the LBL tools SORT, or any line-by-line sort program  can
         be used if you do not want to use the C sort.



         1.2.4  Deleting Entries (-d switch)


         The "-d" switch permits entries to be deleted from the file.   The
         delete  switch  is given by itself with no arguments.  To maintain
         an up-to-date UFDLIST, OWN -d should be  run  whenever  a  UFD  is
         deleted from the disk.

         Example:  OWN -D



     OWN -- UFD utility                                            Page 1-5
     


         When -d is specified, OWN prompts for a UFD to delete.  Upon entry
         of  a UFD, OWN searches its file sequentially for the UFD, writing
         out non-matching records as it goes.  When it  finds  a  match  it
         reports  that  the UFD is deleted and prompts for another.  If the
         UFD is not found, OWN reports this, closes the  file,  and  exits.
         Each delete run creates a new version of the file being processed.

         If the file has been sorted, multiple deletes will succeed if  the
         UFD's  to  be  deleted  are  specified  in  sequential order.  OWN
         searches the file sequentially;  it does not  restart  after  each
         deletion.



         1.3  Alternate File Access Switches


         To extend the usefulness  of  OWN,  two  additional  switches  are
         provided.  One, "-u", allows you to access a [1,5]UFDLIST.TXT file
         on a disk other than the system disk.  The  second,  "-f",  allows
         you to specify a completely different file.

         Both "-u" and "-f" must be followed immediately by their arguments
                                             ___________
         with  no  intervening  blanks.   (See  examples  below).   The two
         ____  __  ___________  ______
         switches are mutually exclusive;  only one of them may be used  on
         a command line.



         1.3.1  Accessing disk unit (-u switch)


         The "-u" switch selects an alternate disk unit to be processed  by
         OWN.    The  program  still  reads  [1,5]UFDLIST.TXT  but  from  a
         different disk drive.  The "-u" switch may be placed  anywhere  in
         the  command  line  and  may  be  used  with  any  of the function
         switches.

         Assume you wish to find the owner of [77,77] on DB2:, which  is  a
         mounted disk.  The following commands would both accomplish this:
          
             own -udb2: [77,77]
                     -or-
             own [77,77] -udb2:
          



         1.3.2  Alternate File (-f switch)


         The "-f" switch allows you to direct OWN to search  a  file  other
         than  UFDLIST.TXT.   You  have  complete  control  over  the  file


     OWN -- UFD utility                                            Page 1-6
     


         specification given, including device  name  and  UFD.   Alternate
         file  access  provides  a means of keeping UFD indices on-line for
         dismounted disks or for magnetic tapes, such as the DECUS RSX  SIG
         tapes.   The "-f" switch may take any position in the command line
         and may be used with any of the function switches.

         Examples:

            own bigtpc -f[1,2]RSXS82.DIR
               -- find UFD for BIGTPC in [1,2]RSXS82.DIR
            own -a -fmystuff.dir
               -- add an entry to MYSTUFF.DIR
            own -fVE:[300,1]TAPEINDEX.DIR
               -- list VE:[300,1]TAPEINDEX.DIR
            own -f[1,2]rsxs82.dir -m [300,1]
         -- modify the entry for [300,1] in the file [1,2]RSXS82.DIR.

      This is a good place to re-emphasize that any file  accessed  by  OWN
                                                ___
      must  exist  before  OWN is run to access it.  Thus, [1,5]UFDLIST.TXT
      ____  _____  ______  ___ __ ___ __ ______ __
      should be created (an empty file is sufficient)  by  PIP  or  a  text
      editor before attempting to use OWN to add entries.

      A file, [1,5]RSXS82.DIR, is currently  being  created  to  contain  a
      summary index of the RSX Spring 1982 SIG tape.








                               Table of Contents


         1.0 OWN -- UFD utility . . . . . . . . . 1-1
         1.1 Use of OWN . . . . . . . . . . . . . 1-1
         1.2 Function Switches  . . . . . . . . . 1-1
         1.2.1 Listing (no switch)  . . . . . . . 1-2
         1.2.1.1 Listing all UFD's  . . . . . . . 1-2
         1.2.1.2 Listing UFD's for one owner  . . 1-2
         1.2.1.3 Listing owner of a UFD . . . . . 1-2
         1.2.2 Modifying UFD owner (-m switch)  . 1-3
         1.2.3 Adding entries (-a switch) . . . . 1-3
         1.2.3.1 Redirecting input for Add  . . . 1-3
         1.2.3.2 Sorting UFDLIST.TXT  . . . . . . 1-4
         1.2.4 Deleting Entries (-d switch) . . . 1-4
         1.3 Alternate File Access Switches . . . 1-5
         1.3.1 Accessing disk unit (-u switch)  . 1-5
         1.3.2 Alternate File (-f switch) . . . . 1-5