UU UU CCCCCC LL UU UU CCCCCC LL UU UU CC CC LL ++ UU UU CC CC LL ++ UU UU CC LL ++ UU UU CC LL ++ UU UU CC LL ++++++++++ UU UU CC LL ++++++++++ UU UU CC LL ++ UU UU CC LL ++ UU UU CC CC LL ++ UU UU CC CC LL ++ UUUUUU CCCCCC LLLLLLLLLL UUUUUU CCCCCC LLLLLLLLLL USER COMMAND LINKAGE-plus Version 6D 25 April 1984 William K. Walker Monsanto Research Corp. P. O. Box 32 Miamisburg, OH 45342 (513) 865-3557 UCL+ -- User Command Linkage Program Page 2 ACKNOWLEDGEMENTS This version of UCL+ incorporates a number of suggestions and ideas contributed by several peo- ple that I polled at the Fall 83 DECUS meeting. Unfortunately, I don't remember anybody's name (it was a REALLY frantic meeting; see, I bought this computer while I was there and...). So, whoever you were (I do remember some faces), thanks for your help! 1.0 INTRODUCTION UCL+ is a user command linkage program for use with RT-11 V5 and later monitors. It is upward compatible with the UCL program distributed with V5.1 with the following exceptions: 1. Symbol definitions are listed with the LIST (or LIST SYMBOLS) command; this is accomplished by typing "UCL" with the distributed UCL. 2. UCL+ accepts the "VMS-like" symbol definition syn- tax used by DEC's UCL, but it ignores it. Instead, the number of characters that must be typed to specify a command or symbol unambiguously is a function of context. E.g., if you have defined two symbols starting with "S", "SUPPER" and "SUPER", you must type four characters to distinguish between them. However, if they are "SIPPER" and "SUPER", only two characters are necessary. 3. UCL+ currently allows symbol names of no more than six characters. If you use a longer name in a definition, UCL+ will truncate it to six characters and issue a warning message to that effect. 4. Like DEC's UCL, UCL+ allows you to erase a symbol by giving it a null definition, but UCL+ assumes that you know what you are doing. I.e., UCL+ mere- ly issues a message notifying you that the symbol has been erased, whereas, UCL issues an "Are you sure?" prompt. UCL+ contains a number of extensions to the distributed UCL program: 1. UCL+ is optimized to minimize disk access. The symbol definitions are contained in internal tables UCL+ -- User Command Linkage Program Page 3 rather than a separate data file and an "execute-immediate" mode is available for commands that are defined in terms of other UCL commands. 2. More than one symbol definition can be deleted in a single command line via the ERASE command. All current symbol definitions can be removed with ERASE/ALL. 3. Provision has been made to chain to additional "UCL's". 4. A "run-by-name path" can be defined which extends the RT-11 "run-from-SY:" default. 5. You can STORE/RECALL the program settings to/from a separate ".UCL" file. 6. A PASS_ON command is included that allows you to force UCL+ to "pass-on" a given command string to the next program in the chain (the default mode) or to a program that you specify. 7. Symbol expansions can be DISPLAYed with or without execution. The DISLAY command can also be used to print pre-defined ASCII stings on the console (handy for sneaky escape sequences). 8. Provision has been made to make the addition of "hard-wired" commands fairly easy. These are, typ- ically, commands that are too complex to define as symbols. Two commands of this type are included as examples (and because the author finds them very handy!): a CD command which changes the default device (works a lot like the CP/M CD command) and an RNO command which is a DCL-style command for use with DECUS RUNOFF version M02.4. 9. If you run it directly, UCL+ will accept lower-case input. 2.0 HOW IT WORKS First, read sections 2.2.4.1 and 2.2.4.2 (pages 2-39 through 2-41) of the version 5 Software Support Manual... OK, now that you've done your homework (and saved me a lot of typing)... As you will recall, if you are using a version of RT-11 that UCL+ -- User Command Linkage Program Page 4 is sysgened to support User Command Linkage, RT goes through a certain logical sequence to evaluate a command line. First, it looks at the first word to see if this a valid RT-11 command. If not, it looks on SY: for a program to run that has the same name as this first word (let's call it "word1"). If "SY:word1.SAV" is not found, it runs SY:UCL.SAV (if it exists) and passes the entire command line to UCL. UCL understands two types of commands: "hard-wired" com- mands, which are installed by modifying the UCL source code (hereafter referred to simply as "commands"), and "symbols", which are commands that you define (or modify or delete) from the console. First, UCL checks to see if word1 is a valid command and, if so, calls the appropriate routine. If the command check fails, UCL looks for a match against the currently defined symbols and, if successful, invokes the symbol processing stuff (if you are redefining a symbol, this is trapped at this point also). Next, UCL checks to see if a new symbol is being defined and takes care of it if so. Finally, UCL uses the "run-by-name" path to look for "dev:word1.SAV" (the default is dev=DK) and, if found, runs it by passing the command "RUN command-string" to RT-11. If all else fails, you either get a "?UCL-F-Invalid Command" error message or, if the CHAIN command is in effect, UCL chains to the specified program, passing it the original command line. One final note: UCL can terminate with "?UCL-F-Ambiguous Command" during command or symbol processing if you fail to type enough characters to make a given command unambiguous. In summary then, when you enter a command: 1. RT-11 tries to execute it, then 2. RT-11 tries to run it off SY:, then 3. UCL tries to execute it as a command, then 4. UCL tries to execute it as a symbol, then 5. UCL tries to "run-by-name", then 6. you either get a nasty comment or UCL chains to another program. 3.0 SYMBOLS Symbols are defined by entering a "symbol definition string" in the format: symbol==definition. Where "symbol" is the command you are defining (6 characters max.) and "defini- tion" is the character-string (72 characters max.) that will govern the way that the symbol is replaced (expanded) when it is interpreted. UCL+ -- User Command Linkage Program Page 5 NOTE DEC's UCL uses a more "VMS-like" structure for defining symbols (possible example: REB*OOT:==BOOT DL0: vs. REBOOT==BOOT DL0:). UCL+ will accept this format also. In the simplest case, suppose you define the symbol "BUILD" by entering BUILD==EX/MAC/NORUN If you subsequently enter BUILD MYFILE this line is interpreted by UCL and passed back to RT-11 as EX/MAC/NORUN MYFILE You may also get multiple-line definitions via the backslash ("\") character. For example, the symbol "WHEN" defined as WHEN==DATE\TIME executes as if you had typed DATE TIME A "^" character or characters in the definition governs where the "argument-part" of the input command string is inserted when a symbol is expanded. Thus, BUILD==EX/MAC/NORUN and BUILD==EX/MAC/NORUN ^ are equivalent symbol definitions. The "^" operator is really handy when the "argument-part" is to be embedded in the middle of the expansion somewhere rather than tacked on the end. For example: VERSIO==RESORC SY:^.SAV/V If you type VERSION PIP this symbol will expand as UCL+ -- User Command Linkage Program Page 6 RESORC SY:PIP.SAV/V Finally, you may precede the "definition-part" with an underscore character ("_"). This will cause UCL to process the symbol expansion in "execute-immediate" mode. This means that the expanded symbol is processed immediately by UCL rather than being passed on to RT-11 as a command string. This feature will speed up command execution sub- stantially in those cases where one symbol is defined in terms of another symbol or hard-wired command. For example, SAY==DISPLAY "^ and SAY==_DISPLAY "^ are equivalent definitions. If you type SAY HELLO both will expand (on the first pass through UCL) as DISPLAY "HELLO BUT, in the first instance, the UCL program will be invoked twice: once to expand SAY HELLO and pass the string back to RT-11, and a second time to execute DISPLAY "HELLO. In the second example, UCL expands the command and then immediately executes the resultant command string. This latter form executes much faster, especially on a floppy-based system! Note that you are restricted to using "_" with definitions that expand to a single line. A==_B\C\D will not work correctly (well, not in this version anyways). Individual symbols can be deleted either by redefining them with a null definition or with the ERASE command. For exam- ple, suppose you have defined a symbol TEMP as TEMP==EDIT MYFILE.MAC\DELETE MYFILE.BAK You can delete this symbol by typing TEMP== (UCL will display the message "?UCL-W-Erased Symbol TEMP") or you can type ERASE TEMP UCL+ -- User Command Linkage Program Page 7 with the same effect. If you wish to delete more than one symbol, the ERASE command is more efficient (see the section on "hard-wired" commands for more details on the ERASE com- mand). One final note: you can define (or erase) symbols by running UCL directly and proceeding as described above in response to the "UCL>" prompt. However, there is one signi- ficant difference: you can include almost any character that you wish in a symbol definition (upper/lower case, escape, etc.) as long as RT-11 does not intercept it for it's own purposes (you couldn't use control-O, for example). For example, the escape sequence [H[J can be used to clear the screen on a VT100-style terminal. The following dialogue would define a symbol "CLS" to accom- plish this: UCL UCL> cls==_d "[H[J UCL> Note that you would also have to turn the single-line editor off, if it was in use. UCL+ -- User Command Linkage Program Page 8 4.0 "HARD-WIRED" COMMANDS The following is a brief description of the commands "hard-wired" into UCL. The CHAIN, DISPLAY, ERASE, LIST, PASS_ON, PATH, RECALL, and STORE commands are required to support the various UCL+ functional goodies. CD and RNO are included because they are handy, they are too complex to implement as symbols, and they serve as good examples of how to add your own hard-wired commands. Note that, as with RT-11 commands, UCL commands and symbols need not be typed in their entirety to be recognized. You need only type enough characters to make a command unambigu- ous (and to keep it from being mistaken as an RT-11 command). For example, "LIST COMMANDS" can be abbreviated as "LIS CO" ("LI CO" would be interpreted by RT-11 as a "LINK" command). CD dev == "Change Device" CD dev becomes ASSIGN dev DK: If the device mnemonic, "dev", is omitted you get ASSIGN SY: DK: CHAIN/switch file-spec ===== "Set Up Exit-On-Bad-Command Chain" The CHAIN command allows you to specify a program for UCL to chain to if UCL is unable to interpret a given command. The original command string is passed to the specified program in the same form and in the same fashion that the string was given to UCL. /RESET resets CHAIN to the default condition (i.e., turns off chaining) UCL+ -- User Command Linkage Program Page 9 DISPLAY/switch command-string ======= or DISPLAY "string ======= "Display Command Expansion or String" The DISPLAY command prints the expansion of the specified UCL command or symbol on the console or, if you precede the argument with a ", it simply prints the remainder of the string. Switches (not valid if DISPLAYing a string): /EXECUTE prints the expanded command and then executes it. /NOEXECUTE suppresses command execution (default). ERASE/switches symbol1,symbol2,... ===== "Erase Symbol(s)" The ERASE command allows you to delete a symbol or symbols that have been previously defined. If you specify the entire symbol name, it is deleted with no verification prompt. If you only type enough of the name to be unambigu- ous, you will get an "Are You Sure?" prompt. Switches: /ALL erases all of the symbols (arguments are ignored) /NOQUERY omits verification prompt /QUERY ask for operator verification (default if /ALL used) UCL+ -- User Command Linkage Program Page 10 LIST thing1,thing2,... ==== "List Current Commands/Symbols" The LIST command lists the "hard-wired" commands, currently defined symbols, CHAIN assignment, and run-by-name path on the console. If you type a LIST command with no arguments, the symbols are listed. Arguments: ALL list commands, symbols, chain data, and path list. CHAIN list the program to chain to if a command cannot be identified COMMANDS list the "hard-wired" commands PATH list the current run-by-name path list SYMBOLS list the current symbol definitions (default) NOTE If you list a symbol whose definition contains non-printing characters (an escape character, for example), UCL will indicate their presence with a "~" character. E.g., the "CLS" example in the previous section would list as CLS==_d "~[H~[J UCL+ -- User Command Linkage Program Page 11 PASS_ON/switch command-string ======= "Pass-on Command To Next (or another) Program" This command tells UCL to pass the specified command-string on to the program that you specified via the CHAIN command. If you specify a "program-name", then the command is passed to this program instead. If CHAINing is not in effect, and you failed to specify a program to chain to, you get your hand slapped with "UCL-F-No CHAIN In Effect". Note that the command string is passed "UCL-style" (byte count at location 510, string starting at 512) not "run-by-name" style. /TO:program-name causes the command-string to be passed to the specified program PATH/switch device1,device2,... ==== "Set Up 'Run-by-name' Search Path" If UCL does not know a given command, UCL follows the device list set up with the PATH command in attempting a "run-by-name". It uses DK: by default. The limit is about 20 device mnemonics. /RESET resets the path to the default value (DK:) RECALL file-spec ====== "Recall Symbol Definition and Status Tables" Recalls (loads) the symbol definition and status area from a file that has previously been created with the STORE com- mand. The default device is DK: and the default extension is .UCL (ie, DK:filnam.UCL where "filnam" is the file name you specify). UCL+ -- User Command Linkage Program Page 12 RNO/switches file-spec === "RUNOFF command" The RNO command implements a "RUNOFF" command for RT-11. It requires a copy of DECUS RUNOFF M02.4 or the equivalent resident on the system device (SY:). The following informa- tion is extracted from the comments in the UCL sources. RNO/switches MYFILE becomes RUNOFF outspec/switches=MYFILE The command switches and the RUNOFF switches and file specifications that they map to are as follows (consult the RUNOFF documentation for detailed information on usage): RNO RUNOFF --- ------ /BEGIN:n /B:n /START:n /END:n /E:n /ONLY:n /B:n/E:n /PAGE:n /FORMLENGTH:n /F:n /HYPHENATION /H:YES /NOHYPHENATION /H:NO /HELP /I /INFORMATION /STRIP /S /NOSTRIP ignored /UNDERLINE /U:L /UNDERLINE:BACKSPACE /U:B :SIMULATED /U:S :NONE /U:N /NOUNDERLINE /U:N /VERSION /V /WAIT /W UCL+ -- User Command Linkage Program Page 13 output specifications: /OUT:filename filename...= /PRINTER LP:...= /TERMINAL TT:...= no output spec. or LP:...= /DEFAULTS STORE file-spec ===== "Store Current Symbol Definition and Status Tables" The STORE command causes the symbol/status blocks to be written to a specified file. The default device is DK:, the default extension .UCL (DK:filnam.UCL). 5.0 EXAMPLES Here are a few examples of some of the symbols definitions that I use frequently. They are shown below in the same fashion that they would be listed via a LIST command. CLS==_d "~[H~[J BUILD==DELETE/INFO ^.BAK\EXECUTE/NORUN ^\DELETE ^.OBJ NEW==DIR/NEW REBOOT==BOOT SY: UCLZAP==CHAIN/RESET\PATH/RESET\ERASE/ALL/NOQUERY VERSIO==RESORC SY:^.SAV/V VT100==SET TT SCOPE,TAB,NOCRLF XM==BOOT SY:RT11XM.SYS