
     
     


          












                       RSX11M-PLUS VERSION 2.0 DOCUMENTATION
                                 THE BERGEN RECORD



          ----------------------------------------------------------------
                      SUBJECT:COMMAND RECOGNITION UNDER RSX11
                              AUTHOR: Allen A. Watson
                  LAST REVISION DATE: WEDNESDAY, DECEMBER 1, 1982
          ----------------------------------------------------------------

     
     









                                   CHAPTER 1

                              COMMAND RECOGNITION







         1.1  TYPES OF SYSTEM COMMANDS


         Under RSX11M-Plus Version 2.0 (as implemented at THE RECORD) there
         are many ways a symbol can be defined to be recognized as a system
         command.

         Because there are so many ways to define a command it is important
         that  programmers  understand  what  they are and the priority, or
         "chain of command", with which the system interprets commands,  so
         that  when  a  new  command is to be implemented, conflicts can be
         avoided with existing commands.

         The primary commands are of course those defined in MCR  and  DCL.
         But  there  are  several additional ways a command may be defined.
         Here is a list of all the various ways:

              1.  In a system-level Command Line Interpreter (CLI) command.

              2.  As a user-level CLI command.  (User-specific).

              3.  As a DCL command.

              4.  As an MCR command.

              5.  As a task installed with a name of the form "...XXX".

              6.  As an internal CCL command.

              7.  As a CCL TABLE command, assembled into CCL.

              8.  As a SYSCCL.CCL command.

              9.  As a USERCCL.CCL command.  (User specific).

     COMMAND RECOGNITION                                           Page 1-2
     


              10. As part of the LBL Software Tools package.


         All commands except types 2 and 9 are system-wide;  any  user  may
         use them.  Some DCL and MCR commands are priveleged, that is, only
         users with login UIC's in groups 1 through 7 may use them.

         Types 1 and 2 are special, applicable only to  users  whose  login
         account file specifies a CLI other than MCR or DCL.  These special
         cases are treated last in this document.

         Most users of RSX11M-PLUS have DCL as their primary  Command  Line
         Interpreter.   (This  is true at THE RECORD but not necessarily so
         elsewhere.) Your default CLI is specified  in  the  login  account
         file which is maintained by the System Manager.

         There are two additional wasy that a symbol can  become  a  system
         command:   as  a command file name, preceded by "@", or as part of
         the LBL Software Tools Package through the SHELL  program.   These
         two  type  of commands are not part of the normal chain of command
         -- they  must  be  specially  invoked.   They  are  therefore  not
         discussed further in this document.



         1.2  SEQUENCE OF COMMAND EVALUATION


         This chart shows (from the top down) the  sequence  in  which  THE
         RECORD's system evaluates types of commands:
          
             User's CLI -- DCL or CCL
             ========================
                        v
                       MCR
                       ===
                        v
              Installed ... tasks
              ===================
                        v
             CCL as catch-all (internal cmds)
             ================================
                        v
                CCL TABLE module
                ================
                        v
                USERCCL commands
                ================
                        v
                SYSCCL commands
                ===============
          


     COMMAND RECOGNITION                                           Page 1-3
     


         The importance of the sequence shown in  this  chart  is  that  it
         controls how commands are recognized.

         For example, if a command  "JOBCHECK"  exists  in  SYSCCL  at  the
         bottom  of  the  chain  and  a  task  were installed with the name
         "...JOB", the SYSCCL command could no longer be  accessed  because
         the  system  would  find  a  match  for  the letters "JOB" when it
         reached the level of checking installed tasks.  This is  the  kind
         of conflict that must be avoided.

         Another example.  We used to have a program with the name "...TYP"
         to  type  out  files.   When we installed Version 2.0 of M-Plus we
         wished to use DCL as our primary  CLI.   DCL  contains  a  command
         "TYPE"  which  has  some selective switches not offered by our old
         TYP, but we wanted to retain both.  It was necessary to change the
         program  name  to "...TIP" to distinguish it from the DCL command,
         since DCL (if present) always gets  first  crack  at  interpreting
         commands.

         Thus, when a programmer is designing a system with  user  commands
         (s)he  must  first,  consider which means (s)he will use to define
         those commands to the system, and second, avoid  any  command-name
         conflicts with other commands on other levels.*



         1.3  DEFINING COMMANDS FOR VARIOUS LEVELS


         Commands  may  be  defined   as   system-level,   group-level   or
         application-level,  and user-level.  A system-level command can be
         used by anyone (unless it is priveleged);  a  group-level  command
         is  restricted  to  a  certain  group  of users;  and a user-level
         command is available only to one individual or one UIC.



         1.3.1  System Level Commands


         System level commands may be defined as part of  DCL,  by  writing
         and  installing  a special program as a "...XXX" task, by defining
         it internally to CCL in its TABLE  module,  or  by  adding  it  to
         SYSCCL.   All means except SYSCCL require programming, compilation
         and task-building.  Adding a DCL command,  for  example,  requires
         that  you  learn a "meta-macro" language and code several MACRO-11
         modules.  A SYSCCL command is most  easily  defined  but  is  also
         least efficient.

         Note that once you have control of a terminal through a program or
         command  file,  that  program  or  command  file  is in effect the
         primary CLI for the terminal.   It  can  intercept  and  interpret
         typed-in commands in any way it wishes.

     COMMAND RECOGNITION                                           Page 1-4
     


         I will assume that most users are  familiar  with  how  to  define
         system-level  commands  through  installing  a  task  or adding to
         SYSCCL;  my aim in this document is to discuss  several  types  of
         group or user level commands.



         1.3.2  Group Level Commands


         If you wish to define a group of commands that is available  to  a
         specific group of users and only to that group, the best way is to
         use a special Command Line Interpreter (CLI).   The  users'  login
         accounts  can  then  be  altered with ACNT to specify this special
         program as their CLI.  This can be done as discussed by Digital in
         their System Management Manual, or, more easily, by using CCL as a
         CLI.



         1.3.2.1  Using CCL as alternate CLI - 

         The simplest way to obtain an alternate CLI is to  tailor  CCL  to
         your application.  If you only need one additional CLI you can use
         CCL as Downward supplies it in Version 8.0 on the RSX  SIG  Spring
         1982 tape.  If you need several application CLI's, only two simple
         changes are needed to CCL.MAC to create a special version for  one
         application.   For  example,  take  an  application  at THE RECORD
         called "LAYOUT-80".

         First, a new version  of  CCL  must  be  created  that  references
         application-specific  files instead of the standard SYSCLI.CCL and
         USERCLI.CCL.  The code in CCL that modifies "SYSCCL"  to  "SYSCLI"
         and  "USERCCL"  to  "USERCLI"  when  the program executes as a CLI
         might be changed to specify "SYSLAY" and  "USERLAY"  respectively,
         referencing files called "SYSLAY.CCL" and "USERLAY.CCL".

         Second, the tailored CCL must be installed under a different  name
         such  as  "...LAY" (being sure the name does not conflict with any
         system commands), and then set up as a CLI using the CLI  command.
         This could be made part of the standard STARTUP.CMD file.

         It should be noted that in the  version  of  CCL  in  use  at  THE
         RECORD,  another modification has been made at the point where CCL
         checks its task name to see whether it is the catchall (CA.) or  a
         CLI  (CCL).  Downward's original code looks for "CA.";  if that is
         the name, he acts as a catchall, and if not, as a CLI.  This  does
         not  work  if  DCL  is the primary CLI and allows commands to fall
         through to MCR and thence to CCL as  catchall.   We  reversed  the
         test  and  match on a task name of "CCL".  If our version is being
         used, that code would have to be altered in the additional  LAYOUT
         CLI to match for the task name "LAY".  (See CCL.SLP in [333,100].)

     COMMAND RECOGNITION                                           Page 1-5
     


         1.3.2.1.1  How the alternate CLI works - 

         Once LAY has been defined as a user's CLI, any  unsolicited  input
         will be interpreted by LAY.  First, LAY will search USERLAY.CCL in
         the user's login UIC.   Individualized  commands  can  be  defined
         there for each user.

         If a command is not defined in USERLAY.CCL, LAY will  next  search
         SYSLAY.CCL.   Any application-wide commands should be defined here
         using standard CCL definitions.  These commands will be  available
         to all LAY users.  

         As distributed by Downward, if CCL (LAY) does not find  a  command
         in  either  file,  it  simply  passes it on to MCR.  CCL, in other
         words, uses MCR as its catchall (turnabout is fair  play!).   Once
         again,   however,   only  a  very  simple  change  can  cause  the
         application CLI to totally insulate itself from MCR and  issue  an
         error  message  if  the  command  is not known to the application.
         Simply replace the two lines:
             CALL    PUTMCR
             JMP     FINISH
          
         with the line "BR 20$".

         If this further modification is made, it is important to recognize
         that  LAY  has  become  the  only  CLI.   This has two significant
                                      ____
         implications.

              1.  Any command not defined in SYSLAY.CCL or USERLAY.CCL will
                  be  unrecognized.   Nothing  falls through to MCR.  Users
                  are totally insulated from the system,  and  other  users
                  have no access to the LAY commands.

              2.  There is absolutely no conflict  with  any  other  system
                  commands.   You  are free to define any command you wish,
                  e.g.  to give your own meanings to  COPY,  DIRECTORY,  or
                  even PIP and TKB.  There are no restrictions.


         If you choose to insulate your application CLI from  MCR  in  this
         manner,  you should define a "breakout" command in your SYSCLI.CCL
         file, especially for debugging.  By a breakout command, I  mean  a
         means of getting the terminal back to MCR or DCL once you are into
         the alternate CLI mode.  You don't want to paint yourself  into  a
         corner.

         Here are two suggestions for breakout commands:

     COMMAND RECOGNITION                                           Page 1-6
     


          
             $3300BRK
             *SET /CLI=TI:MCR
          
             $1111.
             $3311MCR
             ?AMCR command
             *%A%
          

         The first command will set your CLI to be MCR when you type "BRK".
         It gets you out of LAY entirely.

         The second command simply passes whatever you type  along  to  MCR
         for  execution,  but  leaves LAY as your CLI.  Thus, "MCR PIP /LI"
         would list your directory.  (The $1111.  form allows the alternate
         form ".  PIP /LI".) When the command completes, you still have LAY
         as your CLI.  Of course, "MCR SET /CLI=TI:MCR" would do  the  same
         as the "BRK" command.



         1.3.2.1.2  Group command files using a CLI - 

         There is no direct way to  implement  group  command  files  under
         RSX11M-PLUS.   Using  CCL  as  an  alternate  CLI,  however, group
         command files can be developed indirectly.

         First, decide on a "group UFD", for example [77,1]  for  users  in
         group  77.   The  choice is entirely free;  it can be a priveleged
         UFD in groups 1 through 7 if you wish.  Store  all  command  files
         that are to be available to an entire group in this UFD.

         Now,  in  the  SYSCLI.CCL  file   (SYSLAY.CCL   for   the   Layout
         application),  add  a command definition such as the following for
         every command file:
          
             $6600FILNAM
             *@[77,1]FILNAM %A%
          

         This defines a "FILNAM" command for the group.  When a user  types
         "FILNAM  text"  CCL  will  issue  a command to MCR:  @[77,1]FILNAM
         text, where "text" is any parameters  you  wish  to  pass  to  the
         command file.

         Note that the CCL command "FILNAM" does not have to be the same as
         the  command  file  name;  you can create it with fewer letters or
         entirely different ones if  you  wish.   The  following  would  be
         perfectly legitimate:
          
             $1100X
             *@[77,1]FILNAM %A%

     COMMAND RECOGNITION                                           Page 1-7
     


          

         Now  all  the  user  needs  to  type  is  "X  text"  to   generate
         "@[77,1]FILNAM text".

         See  Downward's  CCL.DOC  for  complete  details  on  CCL  command
         construction.

         An alternative approach to group command files would be to  define
         an "@" command in your SYSCLI.CCL file that always points the user
         to the group UFD.  Note that this approach requires  the  user  to
         know the names of the command files.
          
             $1111@
             ?ACommand file
             *@[77,1]%A%
          

         This command definition makes "@" a command in itself to your CLI.
         Using  it  will  be  slightly different than the normal MCR use of
         "@filename";  to cause  CCL  to  recognize  the  division  between
         command  and  parameter  the  "@" must be followed by a space:  "@
         filename".  Or he can simply type "@" and have CCL prompt him  for
         the  file  name.   If  the user types "@ WORK", CCL will issue the
         command "@[77,1]WORK" to MCR.  Parameters can be added if desired,
         e.g.  "@ WORK parm1".

         It should be noted that commands of one  or  two  characters  will
         work  only  when  CCL is installed as CLI;  if CCL is installed as
         catchall, MCR will trap out these commands as  illegal.   Downward
         also supplies an MCR patch to circumvent this if you wish.



         1.3.3  A specially written CLI


         A second means of  designing  application  level  commands  is  by
         writing  another CLI program.  This must be done using MACRO-11 or
         FORTRAN and is thoroughly documented  in  the  DEC  documentation.
         Writing a CLI is not a trivial task.



         1.4  Advantages and Disadvantages; CCL versus special CLI


         A user-written CLI has one main advantage over using CCL as a CLI;
         response to commands is considerably faster and has less overhead.

         The slowest response to a command comes when it is  defined  in  a
         SYSCCL file (used by CCL executing as catchall).  You can see this
         by referring  to  the  diagram  given  earlier.   When  a  command

     COMMAND RECOGNITION                                           Page 1-8
     


         contained in SYSCCL is typed in, here is what happens:

              1.  The user CLI (DCL or CCL) searches its  internal  tables.
                  DCL  falls  through  to  step  4  if  MCR-fall-through is
                  enabled;  otherwise DCL issues  an  error  and  execution
                  stops.

              2.  If the CLI is CCL, it opens USERCLI.CCL and searches it.

              3.  If the CLI is CCL, it opens SYSCLI.CCL and  searches  it.
                  If  CCL  does not fall through to MCR, and the command is
                  not found, an  error  message  is  issued  and  execution
                  stops.

              4.  MCR searches its internal tables.

              5.  MCR searches the System Task  Directory  for  a  "...XXX"
                  task  with  "XXX" matching the first three letters of the
                  command.

              6.  CCL as catchall searches its internal table.

              7.  Catchall opens and searches USERCCL.CCL.

              8.  Catchall opens and searches SYSCCL.CCL.


         As you can see, before a command in SYSCCL is executed the  system
         has  executed three programs, searched four tables, and opened and
         searched four files.  Each file opened by name requires a  minimum
         of  six  disk  accesses  to  locate  the  UFD,  read the directory
         (actually another  file  --  so  add  four  more  files  read  and
         searched!), and then access the first block.

         A user-written CLI with internally defined commands comes  at  the
         top  of  the  list.   Only  one  program is executed, one table is
         searched, and (here is the big advantage) no files are opened  and
         read.

         The disadvantage of a CLI with internally coded commands  is  that
         to  add  or change a command, code must be written and the program
         must be recompiled, re-built,  and  re-installed.   This  requires
         users  to  stop using the CLI temporarily while the new version is
         installed.

         But lo!  CCL does have its own internal table  capability!   Using
         the  TABLE.MAC  feature  in  building  CCL  you  can  put your own
         commands into MACRO code and include them in CCL.

         This suggests that there is really no  need  to  write  any  CLI's
         other than CCL.  To develop and implement new commands:

     COMMAND RECOGNITION                                           Page 1-9
     


              1.  Use CCL  as  CLI  with  no  internal  commands  except  a
                  "breakout"   command.    Develop   and  test  application
                  commands in the SYSCLI file  where  they  can  be  easily
                  edited  and  modified.   (User-level commands can only be
                  defined in the USERCLI files since internal CCL  commands
                  are available to all users of the CLI.)

              2.  When a command has been tested and is unlikely to  change
                  further, remove it from the files and incorporate it into
                  CCL's internal table.








                               Table of Contents


         1.0   COMMAND RECOGNITION  . . . . . . . 1-1
         1.1   TYPES OF SYSTEM COMMANDS . . . . . 1-1
         1.2   SEQUENCE OF COMMAND EVALUATION . . 1-2
         1.3   DEFINING COMMANDS FOR VARIOUS LEVELS 1-3
         1.3.1 System Level Commands  . . . . . . 1-3
         1.3.2 Group Level Commands . . . . . . . 1-4
         1.3.2.1 Using CCL as alternate CLI . . . 1-4
         1.3.2.1.1 How the alternate CLI works  . 1-5
         1.3.2.1.2 Group command files using a CLI 1-6
         1.3.3 A specially written CLI  . . . . . 1-7
         1.4   Advantages and Disadvantages; CCL versus spec 1-7
