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