

                            RSX Cover Document                        


                                  FINALLY



     The  long-awaited  (I  hope  you  think it was worth it!) RSX-11M
     version of the LBL software tools  virtual  operating  system  is
     ready.   This  note  describes the system, and in particular, the
     new features added during RSX  developement.   A  companion  note
     describes  the  mass  storage requirements, run-time requirements
     and the installation procedure.

     The following utilities are available in the RSX system:

          ar ....... archive file maintainer 
          args ..... concatenate standard input to arguments for command
          asplit ... salvage garbaged archive files
          cat ...... concatenate and print text files 
          ccnt ..... character count
          cd ....... change working directory
          ch ....... make changes in text files 
          cmp ...... compare two files 
          comm ..... print lines common to two files
          convrt ... convert pip listing files to LIST carriage control
          cpress ... compress input files
          crt ...... copy files to terminal
          crypt .... crypt and decrypt standard input
          date ..... print the date
          dc ....... desk calculator
          detab .... convert tabs to spaces
          dspc ..... display all characters in a file
          echo ..... echo command line arguments 
          ed ....... text editor 
          entab .... convert spaces to tabs and spaces
          expand ... uncompress input files
          fb ....... search blocks of lines for text pattern
          fc ....... fortran compile and task-build image
          fel ...... task to destroy process tree and return to shell
          field .... manipulate fields of data
          find ..... search a file for a pattern 
          form ..... generate form letter
          incl ..... expand included files 
          intro .... list on-line documentation
          kwic ..... make keyword in context index
          lam ...... laminate files
          lcnt ..... line count
          ld ....... task-build image
          ll ....... print line lengths
          ls ....... list contents of directory
          macro .... process macro definitions 
          mail ..... send/receive mail
          man ...... run off section of users manual
          mcol ..... multicolumn formatting
          msg ...... manipulate message files


                                    -1-                               


                            RSX Cover Document                        


          msplit ... salvage lost message files
          mv ....... move (or rename) a file
          os ....... overstrike - convert backspaces into multiple lines
          pl ....... print specified lines/pages in a file
          postmn ... see if user has mail
          pr ....... paginate files to standard output
          pwd ...... print working directory
          rat4 ..... ratfor preprocessor
          rc ....... ratfor compile - preprocess, compile and task-build
          resolve .. resolve mail users
          rev ...... reverse lines
          rm ....... remove files
          roff ..... format text 
          sedit .... stream editor
          sh ....... shell (command line interpreter)
          shl ...... installed version of shell for easy MCR invocation
          sort ..... sort and/or merge text files 
          spell .... find spelling errors
          split .... split a file into pieces
          tail ..... print last lines of a file
          tee ...... copy input to standard output and named files
          tr ....... character transliteration 
          tsort .... topologically sort symbols
          uniq ..... strip adjacent repeated lines from a file
          unrot .... unrotate lines rotated by kwic
          users .... list valid mail users
          wc ....... count lines, words and characters in files
          wcnt ..... (character) word count
          xref ..... make a cross reference of symbols

     Writeups on each of these utilities may be had by  executing  the
     man  command  in  the shell.  The following comments describe new
     features not reflected in the man entries:

      cd: change  working  directory  is  supported.   See   companion
          document  on pathnames for legal input to cd.  Note that the
          synonyms cwd and chdir are not supported.

      ed: ed can handle files up to 750 lines only, due to the  32  kW
          task-image  limit.  Note that ed prompts for input commands,
          with a switch to change this prompt.

fc,ld,rc: are  available  in  RSX-11M.    The   manual   entries   are
          essentially up-to-date. More information on fc and ld may be
          found  farther  on  in  the  section  entitled  "Tools  Disk
          Structure".

   intro: displays a list of available tools on STDOUT.

      ls: lists structure-level-1  directories.   ls  understands  the
          regular  expressions  of find,change and ed, thus permitting
          such examples as



                                    -2-                               


                            RSX Cover Document                        


          ls %a ......... lists all files starting with the  letter  a
          in the current working directory
          ls tst  .........  lists  all  files with the characters tst
          anywhere in the file name
          ls ";1$" ....... lists all files with version number 1

     man: is a real utility now, as opposed to being  a  script  file.
          If  no  arguments are present, man displays the writeups for
          all of the utilities (those listed in intro).  If  arguments
          are  specified,  then  the  writeups for those utilities are
          displayed.

    rat4: the string declaration has been added.  The  rules  for  its
          use are:

            1. All  string  declarations  in  a module must be grouped
               together.
            2. The group of string declarations must appear after  all
               other   declaration  statements  and  before  any  data
               statements.
            3. The format of the string declaration is

               string name "abcdefghij"

               name is the name of the character array declared.   The
               value   of  name  may  be  delimited  by  single(')  or
               double(")  quotes.   name  may  be  used   anywhere   a
               character variable array can be used.

      sh: A bare input line of ? directs the user to help in using the
          system.  Command  lines  starting with # indicate a comment,
          thus allowing scripts to be commented. BACKGROUND  PROCESSES
          ARE  ONLY IMPLEMENTED ON RSX11M. Several commands internal to the
          shell have been added:

           home set current directory to home directory
            xon equivalent to -x switch
           xoff inverse of xon
            von equivalent to -v switch
           voff inverse of von

          The standard  search  path  for  the  shell  when  resolving
          commands is as follows:

            1. current directory
            2. home directory
            3. usr directory [105,2]
            4. bin directory [105,1]

          In each directory, the routine loccom (the source code is on
          osprim.w/osprim.r)  attempts  to  find  a  file  with a null
          extension (shell script files) and  a  file  with  a  .  tsk
          extension.  If a file is found in this search path, its type


                                    -3-                               


                            RSX Cover Document                        


          (character  or  binary)  is  determined  and the appropriate
          action is taken; otherwise, the command is handed to MCR for
          execution as is.  A command may be explicitly given  to  MCR
          through the use of the "x" command as
          
          % x help
          
          for example.  The auto-dropthrough feature may be turned off
          by specifying the -d switch when invoking the shell.














































                                    -4-                               


                            Files and Pathnames                       


     The following are legal file specifications to any tool requiring
     one:

               file.ext;version
               [ggg,mmm]file.ext;version
               ddnn:[ggg,mmm]file.ext;version
               /ggg,mmm/file.ext;version
               /ddnn/ggg,mmm/file.ext;version

     Note that ddnn:file.ext;version is not legal.

     Valid   inputs   to   cd  are  the  last  four  above,  with  the
     file.ext;version removed.  Again note that ddnn: is not valid.

     None of the utilities assume a default extension, so  a  filename
     typed  without a period is assumed to have a null extension.  The
     semicolon is a special character to the  shell,  so  it  must  be
     escaped  with  an  @  when  a  file  version number is explicitly
     specified in a command line typed to the shell.

     When a file is opened at WRITE access, the most recent version of
     the file is overwritten.  In particular, the following command is
     to be eschewed, since it may garbage up your file:

               tool <file >file






























                                    -5-                               


                           Tools Disk Structure                       


                    On disk structure of the Tools VOS


     As currently implemented, the  Tools  VOS  uses  six  consecutive
     members  of  one  group on the disk where it resides (ST0:).  The
     system built at LBL uses group 105 - i.e. [105,*],  but  this  is
     something that can be tailored during installation.  Assuming the
     group used is 105, the current assignment of UIC's is as follows:

     [105,1] main  tools  directory; all system task images as well as
             script files reside here
     [105,2] site-dependent tools and scripts go here.  This directory
             is part of the normal search path for the shell  (current
             working directory; ST0:[105,1]; ST0:[105,2])
     [105,3] scratch files created by the tools go here.
     [105,4] files formatted by lpr go here (not yet implemented)
     [105,5] mail directory: the mail data-base is kept here.
     [105,6] the directory where man entries reside.

     The  bare minimum on [105,1] for a working tools system is *.tsk,
     dict., intro., mymail., mymail.bld, summary.,  rlib.olb,  spell.,
     msgprim.,  msgtest.,  msgprm.  and  symbols.   This  set of files
     occupy ~6100 disk blocks.  [105,6] is also essential for the  man
     command.

     The tools do their own I/O with FCS calls, with the only reliance
     upon  Fortran being the use of the $FCHNL entry point to retrieve
     the FDB address for a lun.  (Note:  if you are running F4P  v.3.0
     with  the  RMS  library,  you  will have to edit gtfdb.mac before
     doing the system generation.) The runtime system provides  for  6
     concurrent  open  files,  using luns 1-6.  Lun 7 is a scratch lun
     used by the runtime system, and lun 8 is always assigned to  TI:.
     Each tool attaches TI:, so that ^O works correctly.
     
     The ld tool generates an indirect command file for TKB and spawns
     TKB  to  build  the resulting task image.  Given that the current
     working directory is dk0:[101,1] and the following ratfor  source
     file called hello.r:

          subroutine main
          
          call remark("Hello world.")
          
          return
          end
     
     An  rc  command  line of "rc -c hello.r" will generate hello.obj,
     and an ld command line of "ld hello" will generate a TKB  command
     file in the following sequence:
     
       1. ld generates the following lines on the file (assuming F4P)
          dk0:[101,1]hello.tsk;1/fp/cp=
          dk0:[101,1]hello


                                    -6-                               


                           Tools Disk Structure                       


          ST0:[105,1]rlib/lb:.main.
          ST0:[105,1]rlib/lb
       2. ld then appends the file st0:[105,1]tools.tkb to the command
          file.   The  version  of  this  file  delivered  on the tape
          consists of:
          /
          units=8
          actfil=6
          //
     
     If the site supports an FCS resident library, or wishes  to  link
     to  a  modified  Fortran  library  for the tools, the appropriate
     changes may be made to the tools.tkb file.   In  particular,  the
     following one is used by the author:
     
          /
          units=8
          actfil=6
          libr=fcsres:ro
          //
     
     In   order   to   assure   correct   linkage   with  the  FCSRES,
     lb:[1,1]fcsres.stb was patched so  that  word  26(octal)  is  the
     characters  ESK  in rad50 instead of ESL. (FCSRES was built as it
     comes on the distribution.)  One of  the  tools  (ls)  needs  the
     ".XQIO"  entry  point  from  the resident library, and this patch
     assures that any globals not in  the  resident  library  will  be
     linked in correctly.

                    Structure of the Distribution Tape


     The  distribution  tape, unless specifically requested otherwise,
     is a 9-track, 800 bpi, DOS-format tape created  with  FLX.   Four
     UIC's are represented:

     [307,30] command  file to install the tools, this document, and a
              working task image for FFL, the fast filex utility
     [307,31] the fortran and macro sources for building  the  system,
              along  with all script files necessary for the system to
              run.
     [307,32] the  pre-roffed  manual  entries  for  use  by  the  man
              command.
     [307,33] ratfor source code for the system, as well as roff input
              files for various documentation on the tools.










                                    -7-                               


                    Run-time Requirements of Tools VOS                


     One  global  logical device name must exist - ST0:.  As one might
     expect,  this  merely  points  to  the  disk  where   the   tools
     directories reside.

     For  ease  of  use,  it  is suggested that the task sh.tsk on the
     tools directory be installed with the name "...SHL".

     The task fel.tsk on the tools directory must  be  installed  with
     the  taskname "...FEL".  FEL allows the user to kill all subtasks
     created by the shell invoked from MCR.  The way to do this is:

       1. Type ^C and wait for the MCR> prompt.
       2. Type FEL and wait for  the  termination  messages  from  the
          subtasks.

     If  your  terminal is currently operating in half-duplex, and the
     bottom task in the tree is reading your terminal, you may have to
     type a carriage return in order to get the  termination  messages
     onto  your screen.  You should see a shell prompt (%) when all is
     done.  If you do not wish to see an extra MCR  prompt  (>),  then
     terminate  the  FEL  line  with an ESCAPE. (The name fel[l] is to
     depict the felling of the process tree  hanging  from  the  login
     shell.)  Fell acts by sending a message to the task named $Tnn.1,
     which is the name given to the login shell's  child.   This  task
     propagates  the chain of messages, and each task in the tree will
     die, printing a message on the user's terminal.

     Due to the large task images of the tools, and the way that shell
     scripts are performed (a copy of the shell is spawned reading the
     file as its standard input), the checkpoint  file[s]  is  heavily
     used.   In particular, it must be quite large.  A reasonably safe
     assumption is 500 blocks per simultaneously active tools user.  I
     realize that this may be a hardship for some  installations,  but
     little can be done to alleviate the problem. (Moral: one pays for
     portable code and functionality!)




















                                    -8-                               


                            Installation Guide                        


     The  installation command file ([307,30]kitbld.cmd) normally uses
     FLX on the distribution tape.  If your system  does  not  have  a
     9-track  tape  drive,  it will be necessary to copy the necessary
     UIC's from the tape onto some compatible  disk  medium  (RK05  or
     larger) at another site.  To do so, perform the following steps:

     1. Login under a priveleged account
     2. Mount your disk pack to copy onto
     3. Allocate the drive, initialize pack (if necessary), and mount it
     4. Ready distribution tape on tape unit (following assumes MM0:)
     5. Set /uic=[?,?] for copying FFL (fast filex)
     6. FLX /RS/BL:35.=MM0:[307,30]FFL.TSK/DO
     7. INS FFL
     8. If the target disk(DDn:) is larger than an RK05
     8a. FFL DDn:/UF/FO=MM0:[307,*]*.*
     9. If the target disk(DKn:) is an RK05
     9a. FFL DKn:/UF/FO=MM0:[307,30]*.*,[307,31]*.*,[307,32]*.*
     9b. PIP DKn:[307,*]*.*;*/TR
     9c. FFL DKn:/UF/FO=MM0:[307,33]*.*




































                                    -9-                               


                          Installation Procedure                      


       1. Login under a priveleged account
       2. Ready tape or disk with the distribution on it
       3. Select UIC to copy kitbld.cmd to
       4. if (distribution on disk)
               PIP *.*=DISK:[307,30]KITBLD.CMD
          else
               FLX /RS=TAPE:[307,30]KITBLD.CMD/DO
       5. Make sure target volume is initialized and mounted
       6. @KITBLD
       7. Answer all questions
       8. Peruse   the  ST0:[GRP,MEM]TOOLS.CMD  file  which  has  been
          displayed  on  the   console.    This   is   the   suggested
          tools-specific  startup file.  The following comments are in
          order:

          a. The GBL logical name assignment is essential
          b. Installation of shl is suggested
          c. Installation of fel is essential
          d. Running of  shl  -c  "addr  |  sort  >st0:[105,1]address"
             assures  that  the  mail  database is current with ACNT's
             database.

       9. If you are satisfied with the tools.cmd file as is, or after
          removing offending, non-essential parts, the following  four
          steps are necessary:

          a. >SET /UIC=[1,2]
          b. >PIP *.*=ST0:[GRP,MEM]TOOLS.CMD
          c. >@TOOLS
          d. >using  your  favorite  editor,  place the following line
             somewhere in [1,2]startup.cmd before  the  terminals  are
             enabled for users to use:

             @LB0:[1,2]TOOLS

      10. Now you are finished



















                                   -10-                               


                           What is KITBLD doing?                      


       1. Determines
          a. Target  device  and  unit  (LB0 is suggested, if there is
             room)
          b. Tools group number (default is 105)
          c. Member number for tools binary directory (default is 1)
          d. If building from tape or disk, and input device and unit
          e. If F4P will be used
          f. If the OTS for the compiler is in LB:[1,1]SYSLIB.OLB
          g. If not, file specification for  the  OTS  library  -  eg.
             LB0:[1,1]FOROTS.OLB
          h. If not using F4P, should the tasks be built /FP
          i. If  the  tasks  should  be  linked  with  an FCS resident
             library (see comments on page 6).
          j. If so, the name of the resident library (FCSRES).
          k. Should fortran and  macro  files  be  deleted  after  use
             (saves ~1100 blocks on target disk)
          l. Should  object  files  be  deleted after use (saves ~1600
             blocks on target disk)
       2. Copies the necessary files from the distribution
       3. Assures contiguousness of . tsk files from the distribution
       4. If the binary directory is not [105,1], uses chs and rt4  to
          modify the site-dependent primitive functions in sitepr.r.
       5. Uses  lss  and  chs to generate an indirect command file for
          the assembler to assemble all of the . mac files.
       6. Fortran compiles the primitive functions written in ratfor
       7. Creates the ratfor library, RLIB.OLB
       8. Builds all of the tasks
       9. Builds the manual directory from the distribution medium
      10. Builds the mail database
      11. Creates  each  account's  mymail.  file  with  the   correct
          protection.
      12. Displays the site's tools.cmd file

      On   a   non-loaded   system,   the   system   generation  takes
      approximately 90 minutes.




















                                   -11-                               


                           Source File Structure                      


            (How to rebuild the damn thing if I don't like it!)


      The source code for each tool is contained  on  the  tape  under
      [307,33]tool.w.  This  file  is all the environment necessary to
      rebuild the tool, provided that the tools  VOS  is  running,  of
      course.   The tool.w file (except for ed, msg, rat4 and sh - see
      below) is an archive containing:

        1. All files included in the rat4 source file
        2. The rat4 source file, tool.r

      Suppose that you wish  to  change  the  subroutine  "module"  in
      "tool".  The suggested scenario is as follows:

      >shl
      % flx /rs=mm0:[307,33]tool.w/do
      % ar xv tool.w
      % ar xv tool.r module
      % ed module
      (make changes and write file)
      % ar uv tool.r module
      % rc -v tool.r
      % test out new version of tool.  Repeat the last three steps
      until satisfied
      % ar uv tool.w
      % pip [105,2]tool.tsk=tool.tsk
      % cat tool.w >/105,2/tool.w

      Placing  the  tool in [105,2] means that the shell will now find
      your version of the tool in  [105,2],  the  site-dependent  tool
      directory.   It  is  a  good idea to keep the modified source in
      [105,2] also, since you may need it to track down a bug found by
      your local bugfinder person.

      Rat4, msg, sh and ed are a little  trickier,  since  the  source
      code  is  so  large  as to cause the archiver to overflow if the
      previous tool.w structure is attempted.  For  these  tools,  the
      ".w" archive contains:

        1. toolcbl - an archive of the included files
        2. each individual source module for tool

      In  the main tools directory [105,1], a file bigbld is available
      to automatically build the  tool  from  this  type  of  archive.
      Suppose you wish to modify the shell. Then

      % flx /rs=mm0:[307,33]sh.w/do
      % ar xv sh.w module
      % ed module
      % ar uv sh.w module
      % bigbld sh
      % pip [105,2]sh.tsk=sh.tsk


                                   -12-                               


                           Source File Structure                      


      % cat sh.w >/105,2/sh.w


                     Source Differences for FOR vs. F4P

      The  source  code for the system is identical for both compilers
      with two exceptions - fc and ld.  The fc utility,  which  spawns
      the  compiler  as  a subtask, comes in two flavors on the source
      uic [307,33]: fcfor.w and fcf4p.w
      
      FCF4P generates the following command line for F4P

      F4P A,A=A.F/NOTR

      All of the tools primitives and  utility  source  code  will  be
      compiled  with  the  NOTR  option.   If  a  different default is
      desired, modify the source code for the routine fortrn in  fc.w,
      after copying fcf4p.w into fc.w.
      
      FCFOR generates the following command line for FOR

      FOR A,A=A.F/NOSN/NOVA/NOLO

      If  this  is  undesirable, then follow the same procedure as for
      F4P except copying fcfor.w to fc.w
      
      The ld utility, which builds a tool task image,  also  comes  in
      two varieties on the source uic: ldfp.w and ldnofp.w.
      
      LDFP  places  a  /fp switch after the task image name in the TKB
      indirect command file.
      
      LDNOFP places a /-fp switch after the task image name.   If  you
      are  building  a FOR system, but using the FPP or FIS libraries,
      simply answer the kitbld question "DO YOU WANT THE  TASKS  BUILT
      /FP?" in the affirmative when building the system.
      
      The  task  images  on  [307,31]  have  been  compiled  with  FOR
      generating threaded code and linked with the EIS library,  since
      it  was  felt  that  these  images would then run on all systems
      building the tools.














                                   -13-                               


                        Adding On-line Documentation                  


      A sample scenario for modifying existing  on-line  documentation
      follows.

      The  archive  /st0/105,1/docu  contains  the  roff input for the
      manual  entry  for  each  tool.   If  you  are   preparing   new
      documentation,  one  of  these  archive entries can be used as a
      template.  The subsets  are  given  the  name  of  the  utility.
      Suppose  you  wish  to  modify the writeup for ar.  The steps to
      take are:

         % ar xv /105,1/docu ar
         % ed ar
         % cat /105,1/pagel >pagel
         % roff pagel ar
         % do this until you are satisfied with the writeup
         % /105,1/ar uv /105,1/docu ar
         % roff pagel ar >/105,6/ar
         % rm ar

      The first invocation of ar is to extract the  roff  source  from
      the  documentation  archive.   The  editor is used to modify the
      writeup.  The file pagel is used merely to set the  page  length
      to  62.  The modified writeup source is then roffed to see if it
      is OK.  Once it is ok, it is placed back in  the  archive.   The
      reason  that  /105,1/ar  is  explicitly specified, is due to the
      fact that just typing ar will cause the shell to find  the  file
      name  ar.  in  your  current  working directory, and will try to
      execute it as a script file.  The roffed writeup is then  placed
      in  the  directory  for  manual entries, /105,6.  The file ar is
      then removed from the current working directory.

























                                   -14-                               


                           Running tools from MCR                     


      Each tool is built to retrieve its arguments from MCR if it  was
      installed  with  a  "...XXX"  name.  To make "tool" available as
      "...TOL" from MCR, simply type the following MCR command:

      >INS ST0:[105,1]TOOL/TASK=...TOL

      If a tool is invoked by the following MCR command

      >RUN ST0:[105,1]TOOL

      the tool will prompt for its arguments with an asterisk

      *

      before continuing.








































                                   -15-                               

