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 V07.44 06 June 85 William K. Walker Monsanto Research Corp. P. O. Box 32 Miamisburg, OH 45342 (513) 865-3557 SPECIAL NOTE TO SCIENTISTS/RESEARCHERS Read the manual! TABLE OF CONTENTS 1.0 ACKNOWLEDGEMENTS . . . . . . . . . . . . . . . . . . . 1 2.0 BEFORE YOU GET STARTED . . . . . . . . . . . . . . . . 1 3.0 ABOUT THIS DOCUMENT . . . . . . . . . . . . . . . . . 1 4.0 INTRODUCTION . . . . . . . . . . . . . . . . . . . . . 2 4.1 UCL+ Differences . . . . . . . . . . . . . . . . . . . 2 4.2 UCL+ Enhancements . . . . . . . . . . . . . . . . . . 3 5.0 INSTALLATION . . . . . . . . . . . . . . . . . . . . . 5 5.1 Installing UCL.SAV . . . . . . . . . . . . . . . . . . 5 5.1.1 Installing UCL.SAV On RT-11 Systems . . . . . . . . 5 5.1.1.1 Installation As A UCL (UCL.SAV) . . . . . . . . . 5 5.1.1.2 Installation As A UCF (UCF.SAV) . . . . . . . . . 6 5.1.2 Installing UCL.SAV On TSX-Plus Systems . . . . . . . 6 5.1.2.1 Installation As A UCL (TSXUCL.SAV) . . . . . . . . 7 5.1.2.2 Installation As A UCI (UKMON.SAV) . . . . . . . . 7 5.2 Installing UCLXM.SAV . . . . . . . . . . . . . . . . . 7 5.2.1 XM Installation As A UCL (UCL.SAV) . . . . . . . . . 8 5.2.2 XM Installation As A UCF (UCF.SAV) . . . . . . . . . 9 5.3 Installing The UC Handler . . . . . . . . . . . . . . 10 5.4 Installing The CI Handler . . . . . . . . . . . . . . 11 5.5 Installing UCL+ HELP . . . . . . . . . . . . . . . . . 11 6.0 HOW IT WORKS . . . . . . . . . . . . . . . . . . . . . 13 6.1 RT-11 Command Processing With UCL Support . . . . . . 13 6.2 RT-11 Command Processing With UCF Support . . . . . . 14 6.3 TSX-Plus Command Processing . . . . . . . . . . . . . 15 7.0 SYMBOLS . . . . . . . . . . . . . . . . . . . . . . . 16 7.1 Defining Symbols . . . . . . . . . . . . . . . . . . . 16 7.2 Deleting Symbols . . . . . . . . . . . . . . . . . . . 18 7.3 Running UCL+ Directly . . . . . . . . . . . . . . . . 18 8.0 "HARD-WIRED" COMMANDS . . . . . . . . . . . . . . . . 20 8.1 CD Command . . . . . . . . . . . . . . . . . . . . . . 20 8.2 CHAIN Command . . . . . . . . . . . . . . . . . . . . 21 8.3 DISPLAY Command . . . . . . . . . . . . . . . . . . . 22 8.4 ERASE Command . . . . . . . . . . . . . . . . . . . . 23 8.5 LIST Command . . . . . . . . . . . . . . . . . . . . . 23 8.6 NOSL/SLON Command . . . . . . . . . . . . . . . . . . 25 8.7 PASS_ON Command . . . . . . . . . . . . . . . . . . . 25 8.8 PATH Command . . . . . . . . . . . . . . . . . . . . . 26 8.9 PROMPT Command . . . . . . . . . . . . . . . . . . . . 26 8.10 RECALL Command . . . . . . . . . . . . . . . . . . . 26 8.11 RELOAD command . . . . . . . . . . . . . . . . . . . 27 8.12 RNO Command . . . . . . . . . . . . . . . . . . . . . 27 8.13 STORE Command . . . . . . . . . . . . . . . . . . . . 28 8.14 UCI_MODE Command . . . . . . . . . . . . . . . . . . 29 9.0 UC HANDLER . . . . . . . . . . . . . . . . . . . . . . 30 10.0 CI HANDLER . . . . . . . . . . . . . . . . . . . . . 31 11.0 ERROR MESSAGES . . . . . . . . . . . . . . . . . . . 33 11.1 UCL+ "Warning" Messages . . . . . . . . . . . . . . . 33 11.2 UCL+ "Fatal" Messages . . . . . . . . . . . . . . . . 34 11.3 Global Region Loader Errors . . . . . . . . . . . . . 37 11.4 CI Handler Errors . . . . . . . . . . . . . . . . . . 38 12.0 EXAMPLES . . . . . . . . . . . . . . . . . . . . . . 39 13.0 V7 RELEASE NOTES . . . . . . . . . . . . . . . . . . 40 14.0 APPLICATION NOTES . . . . . . . . . . . . . . . . . . 42 14.1 Executing Command/Control Files "By-Name" . . . . . . 42 14.2 Changing The Effect Of RNO/DEFAULTS . . . . . . . . . 42 14.3 Sending Escape Sequences To The Printer . . . . . . . 42 14.4 Moving From UCL+ V6x To UCL+ V7.xx . . . . . . . . . 43 14.5 Moving From UCL+ V6x Or V7.xx To UCL+ (XM) V7.xx . . 44 14.6 Hints and Kinks: UCF, UCI, And SET UCL FIRST . . . . 45 14.6.1 Interception Of Monitor Commands . . . . . . . . . 45 14.6.2 Improper Expansion Of Monitor Commands . . . . . . 45 14.6.3 Single Key Commands . . . . . . . . . . . . . . . . 46 14.7 UCL+ Assembly Conditionals . . . . . . . . . . . . . 46 14.8 Modifying RT-11 To Change The UCL/UCF Device/File Name . . . . . . . . . . . . . . . . . . 47 14.9 Modifying TSX-Plus To Change The UCL/UCI Defaults . . . . . . . . . . . . . . . . . . . . . . 48 14.10 Controlling Command Line Factoring . . . . . . . . . 48 15.0 REPORTING PROBLEMS AND SUGGESTIONS . . . . . . . . . 50 16.0 WISH LIST . . . . . . . . . . . . . . . . . . . . . . 51 UCL+ -- User Command Linkage Program - V07.44 Page 1 Spring 1985 DECUS Distribution 1.0 ACKNOWLEDGEMENTS Throughout this document, reference is made to the RT-11 and TSX-Plus operating systems. RT-11 is a product of Digital Equipment Corporation, Maynard, MA; TSX-Plus is a product of S & H Computer Systems, Nashville, TN. For this release of UCL+, Ray Moran deserves some credit for suggesting journaling (I won't say anything about how diffi- cult it was to implement). In addition, kudos are due the individual(s) on the RT-11 Development Team (or whatever it is called these days) that put global region support in the V05.02 XM monitor -- this is what made the fast XM version of UCL+ possible. Finally, thanks are due to Rally Barnard, Jack Crowell, and Ray Moran for helping to field test this monster. 2.0 BEFORE YOU GET STARTED Before you start using UCL+, there are a couple of things that you should keep in mind. 1. You don't have to get fancy. With a couple of fairly minor exceptions, you can just use UCL+ as a direct replacement for your distributed UCL. Try the sneaky stuff once you get addicted to having it around. 2. If you intend to use the extended features, particularly UCF or UCI_MODE, make sure you read the available documentation. Note that there are a number of goodies contained in the application notes at the end of this manual. 3.0 ABOUT THIS DOCUMENT A fair amount of effort has gone into this manual to give reasonably comprehensive coverage of the contents of the UCL+ distribution kit. It does not, however, attempt to in- clude material already available in the relevant operating system documentation, nor is there extensive coverage of in- ternals. Where examples are felt to be necessary, the following con- ventions are followed: o examples, unless otherwise noted, are for RT-11 V5.0; no "factoring" is used UCL+ -- User Command Linkage Program - V07.44 Page 2 Spring 1985 DECUS Distribution o in most examples, operator input is underlined o all visible lines of input are assumed to be ter- minated with a carriage return o "non-printing" characters and control characters are identified by an abbreviation enclosed by angle brackets ("<>"); e.g., - = carriage return (CR) - = escape (ESC) - = control-C (ETX) - = control-Y (EM) 4.0 INTRODUCTION UCL+ is a user command linkage program for use with RT-11 V5 or later and TSX-Plus V4.1 or later monitors. It contains full support for the user command related features of these operating systems. These include: o UCL - User Command Linkage (RT-11 and TSX-Plus) o UCI - User Command Interpreter (TSX-Plus, starting with V5.0) o UCF - User Commands First (RT-11, starting with V05.02) In general, UCL+ can be used as a direct replacement for the "UCL's" distributed with these operating systems. There are some relatively minor incompatibilities between UCL+ and the distributed versions, as well as a substantial number of enhancements. The remainder of this section summarizes these differences. 4.1 UCL+ Differences UCL+ is upward compatible with the UCL program distributed with RT-11 (and the TSX-Plus TSXUCL program) with the fol- lowing exceptions. o 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. UCL+ -- User Command Linkage Program - V07.44 Page 3 Spring 1985 DECUS Distribution o UCL+ currently allows symbol names of no more than six characters. If you use a longer name in a de- finition, UCL+ will truncate it to six characters and issue a warning message to that effect. o UCL+ is different from the TSX-Plus TSXUCL program in that all commands and symbols are "global", rather than local to a specific user. In addition, UCL+ does not "forget" symbol definitions after a user logs off. 4.2 UCL+ Enhancements UCL+ contains a number of extensions to the distributed RT-11 and TSX-Plus UCL programs. The following list is a summary of the most important ones. Refer to the relevant sections of this document for further detail. o UCL+ is optimized to minimize disk access. The symbol definitions are contained in internal tables rather than a separate data file and an "execute-immediate" mode is available for commands that are defined in terms of other UCL commands. o 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 *. o You can chain to additional "UCL's". o A "run-by-name path" can be defined which extends the monitor's "run-from-SY:" default. o You can STORE/RECALL the program settings to/from a separate file. You can do this in either "binary" or "journal" mode. Journal files can be edited. o 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. o Symbol expansions can be DISPLAYed with or without execution. The DISPLAY command can also be used to output ASCII strings to the console or printer (handy for sneaky escape sequences). o Provision has been made to make the addition of "hard-wired" commands fairly easy. These are, typically, commands that are too complex to define as symbols. Two commands of this type are included UCL+ -- User Command Linkage Program - V07.44 Page 4 Spring 1985 DECUS Distribution 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. o If you run it directly, UCL+ will accept lower-case input and most control characters. o You may, in addition to the symbol definitions, list other program parameters as well. List output may be directed to devices/files other than the console. o UCL+ can be employed, via the UCI_MODE command, as a "User Command Interpreter" (UCI). This func- tionality was added with UCL+ V7 to take advantage of the UCI facility in TSX-Plus. o You may dynamically redefine the prompt string is- sued by UCL+. o An optional UC "pseudo-device" handler is provided which allows UCL+ to "remember" the "input-spec" part of the last UCL+ command. This text can be retrieved, at the command level, by using the "^" character in place of the argument in a subsequent command. o If you have an RT-11 V05.02 or later monitor, you can take advantage of some additional features: - A CI "handleroid" is included which allows you to control and display the action of the vari- ous Command Language Interpreters (CLI's). For example, SET CI UCF turns on the User Commands First (UCF) facility. - A special version of UCL+ is available for the XM monitor. Almost the entire program is con- tinuously resident in a global region in ex- tended memory. It is very fast, and uses less than 500 decimal words of low memory. UCL+ -- User Command Linkage Program - V07.44 Page 5 Spring 1985 DECUS Distribution 5.0 INSTALLATION This section of the manual contains information on the in- stallation of the major components of the UCL+ distribution. As with all sections of this document, a basic familiarity with RT-11 and, if applicable, TSX-Plus is assumed. In all of the examples in this section, the UCL+ distribu- tion is assumed to be on the default device, DK:. Examples, unless otherwise noted, will work on RT-11 V5.0 or later systems and/or the functionally equivalent version of TSX-Plus. The examples also assume that you are going to use the default program names when you install the various com- ponents. There are cases where this may not be true (for example, if you use both the SJ and XM RT-11 monitors). See the application notes, sections 14.8 and 14.9, for informa- tion on changing these defaults. 5.1 Installing UCL.SAV UCL.SAV is the "vanilla" UCL+ program. It will run under versions of RT-11 beginning with V5.0 and versions of TSX-Plus starting with V4.1. As it does a context check on start-up, it is not necessary to generate a special version for either operating system. It is, in fact (and by design), possible to use the same copy of UCL+ in both en- vironments. The installation procedure may differ, however, in some cases. 5.1.1 Installing UCL.SAV On RT-11 Systems - For all ver- sions of RT-11, UCL+ serves as a direct replacement for the distributed UCL program (note that the V5.0 distribution contained no UCL program). For those versions of RT-11 sup- porting User Commands First (UCF), UCL+ can be used as a UCF also. 5.1.1.1 Installation As A UCL (UCL.SAV) - If you are already using a previous version of UCL+, you should first save your current symbol/status data. For example, .STORE SY:CURENT _____ _________ To install UCL.SAV, just copy it to the system device: .COPY UCL.SAV SY:UCL.SAV ____ _______ __________ If you are not a previous UCL+ user, you're done. Other- wise, the next step depends on whether your old UCL+ is V6x or V7.xx. If it is V6x, apply the patch described in the UCL+ -- User Command Linkage Program - V07.44 Page 6 Spring 1985 DECUS Distribution application notes (section 14.4). If it is V7.xx, you can skip the patch and type .RECALL SY:CURENT ______ _________ to load the symbol/status data into your new copy of UCL+. Note that the above procedure is the same for TSX-Plus V4.1 users. 5.1.1.2 Installation As A UCF (UCF.SAV) - Beginning with V05.02, RT-11 supports User Commands First (UCF) as well as UCL. If you wish to use UCL+ as a UCF, you need only make a copy with the appropriate name and turn on UCF support in the monitor. Unless you are doing something sneaky, the in- stallation procedure is as follows (note that this command sequence is for RT-11 V05.02): .copy ucl.sav sy:ucf.sav ____ _______ __________ .r ucf _ ___ UCL> prompt "ucf> " ______ _____ _ ucf> ________ The easiest way to invoke UCF processing is via the CI handler. I.e., .set ci ucf,show ___ __ ________ ?CI-I-CLI's enabled: UCF DCL CCL UCL When UCL+ runs as UCF, it automatically detects this condi- tion, and processes commands appropriately. 5.1.2 Installing UCL.SAV On TSX-Plus Systems - If you are running TSX-Plus V4.1, installation is the same as it is for RT-11 (section 5.1.1). If you are running V5.0 or later, the procedure is somewhat different. Note that you must request UCL support when you execute your initial TSGEN. UCL+ -- User Command Linkage Program - V07.44 Page 7 Spring 1985 DECUS Distribution 5.1.2.1 Installation As A UCL (TSXUCL.SAV) - If you are already using a previous version of UCL+, you should first save your current symbol/status data. For example, .STORE SY:CURENT _____ _________ To install UCL.SAV, just copy it to the system device. Note that the default TSX-Plus name for UCL is TSXUCL.SAV. .COPY UCL.SAV SY:TSXUCL.SAV ____ _______ _____________ If you are not a previous UCL+ user, you're done, and you can proceed to define the symbols that you intend to use. Otherwise, the next step depends on whether your old UCL+ is V6x or V7.xx. If it is V6x, apply the patch described in the application notes (section 14.4). If it is V7.xx, you can skip the patch and type .RECALL SY:CURENT ______ _________ to load the symbol/status data into your new copy of UCL+. 5.1.2.2 Installation As A UCI (UKMON.SAV) - UCL+ can also be used on a TSX-Plus V5.0 or later system as a User Command Interpreter (UCI). The following example illustrates a typ- ical installation with the default UCI name of UKMON.SAV. Note that the command prompt is changed during this pro- cedure to help distinguish the "UCI" copy of UCL+ from other copies that might exist on the same system as "UCL's". .COPY UCL.SAV SY:UKMON.SAV ____ _______ ____________ .R UKMON _ _____ UCL> uci_mode "ukmon> " ________ _______ _ ukmon> ________ You would invoke UKMON.SAV as a UCI by typing .SET KMON UCI ___ ____ ___ 5.2 Installing UCLXM.SAV UCLXM.SAV is a special version of UCL+ for use with the ex- tended memory (XM) monitor on systems running RT-11 V05.02 or later. It is significantly faster than the "vanilla" UCL+ program and it uses less than 500 decimal words of low memory (low memory is always at a premium with the XM moni- tor). UCLXM is a direct, functional replacement for the distributed UCL program. As with the "vanilla" UCL+ pro- gram, UCLXM can also be used as a UCF program. UCL+ -- User Command Linkage Program - V07.44 Page 8 Spring 1985 DECUS Distribution The installation process is reasonably straightforward, although there may be some special considerations if you are "porting" from an earlier, non-XM version of UCL+. All examples in this section are for an RT-11 V05.02 moni- tor. WARNING!!! Do not attempt to run UCLXM.SAV under a non-XM monitor or under a version of RT-11 prior to V05.02. Your system will probably crash. 5.2.1 XM Installation As A UCL (UCL.SAV) - If you are already using a previous version of UCL+, you should first save your current symbol/status data. For example, .store sy:curent _____ _________ If your previous version of UCL+ was also the XM version, you should REMOVE the global region. .remove ucl ______ ___ To install UCLXM.SAV, copy it to the system device as UCL.SAV. .copy uclxm.sav sy:ucl.sav ____ _________ __________ If you are not a previous UCL+ user, you're done, and you can proceed to define the symbols that you intend to use. Otherwise, the next step depends on whether your old UCL+ is an XM version or a non-XM version. If it is a non-XM ver- sion of UCL+, apply the patch described in the application notes (section 14.5). If it is an XM version, you can skip the patch and type .recall sy:curent ______ _________ to load the symbol/status data into your new copy of UCL+. Finally, it is a good idea to run UCL and change the command prompt. .r ucl _ ___ UCL> prompt "uclxm> " ______ _______ _ uclxm> ________ UCL+ -- User Command Linkage Program - V07.44 Page 9 Spring 1985 DECUS Distribution 5.2.2 XM Installation As A UCF (UCF.SAV) - Beginning with V05.02, RT-11 supports User Commands First (UCF) as well as UCL. If you wish to use UCL+ as a UCF, you need to make a copy with the appropriate name and turn on UCF support in the monitor. Unless you plan to do something sneaky (like letting UCL and UCF share the same global region -- risky!), you must also patch your UCF so that it will establish it's own, unique global region in extended memory. The installa- tion procedure is as follows. Remove the UCF global region and create a new copy of UCF.SAV on SY:. .remove ucf ______ ___ .copy uclxm.sav sy:ucf.sav ____ _________ __________ Next, apply the customization patch to cause UCF.SAV to use a unique global region. .sipp sy:ucf.sav/a ____ ____________ Base? _____ Offset? 1024 ____ Base Offset Old New? 000000 001024 101704 ;R __ 000000 001024 ;RUCF _____ 000000 001026 < > ________ Following this, it is recommended that you run UCF and change the command prompt. .r ucf _ ___ UCL> prompt "ucfxm> " ______ _______ _ ucfxm> ________ The easiest way to invoke UCF processing is via the CI handler. I.e., .set ci ucf,show ___ __ ________ ?CI-I-CLI's enabled: UCF DCL CCL UCL When UCL+ runs as UCF, it automatically detects this condi- tion, and processes commands appropriately. UCL+ -- User Command Linkage Program - V07.44 Page 10 Spring 1985 DECUS Distribution 5.3 Installing The UC Handler Three versions of the UC handler are included on the UCL+ distribution kit. The associated "conditionals" files (ex- tension .CND) are also included. These are: o UC.SYS, UC.CND -- non-XM RT-11 version o UCX.SYS, UCX.CND -- XM version for RT-11 o UC.TSX, UCTSX.CND -- TSX-Plus version The UC handler is not terribly useful on RT-11 systems; it was developed primarily for use under TSX-Plus with UCI_MODE in effect. Installation for RT-11 systems just involves copying the appropriate handler to the system device. For example, if you are running an RT-11 XM monitor: .COPY/SYS UCX.SYS SY: ________ _______ ___ The RT-11 versions are assembled without error logging and without device I/O timeout support. If your monitor was built with either one of these features, you will have to rebuild the UC handler. The easiest way to do this is to edit the conditionals file, and reassemble UC. The follow- ing command sequence is for the XM monitor. .MACRO/OBJ:UCX UCX.CND _____________ _______ .LINK/EXEC:UCX.SYS/NOBIT UCX _______________________ ___ Installation on TSX-Plus systems will require that you exe- cute a new TSGEN so that TSX will "expect" to find UC.TSX when it boots up (see the TSX-Plus documentation for de- tails). Once the TSGEN has been done, and before you boot TSX, copy the UC handler to the system area: .COPY UC.TSX SY: ____ ______ ___ Note that the UC handler must be LOADed to use it under RT-11. This is not a problem, of course, with TSX-Plus. See section 9.0 for more information on the UC handler. UCL+ -- User Command Linkage Program - V07.44 Page 11 Spring 1985 DECUS Distribution 5.4 Installing The CI Handler The CI (Command line Interpreter) handler can be used on RT-11 V05.02 or later systems to control the action of the various command line interpreters (CLI's). It contains no __ executable handler code; all it does is execute SET com- __________ _______ ____ mands. Installation is, therefore, very simple. Just copy CI.SYS to your system device, giving it the name appropriate to your particular monitor. For non-XM versions of the RT-11 monitor: .copy/sys ci.sys sy: ________ ______ ___ For the XM monitor: .copy/sys ci.sys sy:cix.sys ________ ______ __________ See section 10.0 for more information in the CI handler. 5.5 Installing UCL+ HELP The UCL+ distribution includes a help-text file named UCLHLP.TXT. You can use this file to set up on-line help text for UCL+ commands in one of two ways: 1. The most general, and most tedious, method is to edit the HELP macros contained in UCLHLP.TXT into HELP.TXT and then rebuild the HELP program. This technique is described in the RT-11 Installation Guide. If you are using version 5.01 or later of RT-11, you will have to use SPLIT.SAV to create HELP.EXE and HELP.TXT (see file UNSUP.TXT on the RT-11 distribution kit). 2. The second approach involves the creation of a separate HELP program for UCL+. In this case, you create a macro library from UCLHLP.TXT, build a secondary HELP program, and define a symbol (I like to use HLP) to invoke it. The following example assumes that you are using RT V5.01. .SPLIT HELP.EXE=HELP.SAV/B:7 _____ _____________________ .LIB/MAC UCLHLP UCLHLP.TXT _______ ______ __________ .COP HELP.EXE+UCLHLP.MLB UCLHLP.SAV ___ ___________________ __________ .COP UCLHLP.SAV SY: ___ __________ ___ .HLP==R UCLHLP\^ ______ ________ UCL+ -- User Command Linkage Program - V07.44 Page 12 Spring 1985 DECUS Distribution NOTE If you are using RT-11 V05.02, the SPLIT boun- daries are different for HELP.SAV. In the above example, the value for the "/B" switch in the first line becomes 10 (octal) instead of 7. UCL+ -- User Command Linkage Program - V07.44 Page 13 Spring 1985 DECUS Distribution 6.0 HOW IT WORKS First, read the appropriate sections of the RT-11 Software Support Manual (for version 5.0, this is sections 2.2.4.1 and 2.2.4.2 -- pages 2-39 through 2-41). If you are running RT-11 version 5.02 or later, and you are interested in User Commands First (UCF), read that stuff too. TSX-Plus users should check out the additional material in the TSX manuals on User Command Interpreters (UCI's) and the UCL SET com- mands. OK, now that you've done your homework (and saved me a lot of typing)... 6.1 RT-11 Command Processing With UCL Support As you will recall, if you are using a version of RT-11 that 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 (LIST or RECALL, for example), which are "built in" to UCL+ (hereafter referred to simply as "commands"), and "sym- bols", which are commands that you define (or modify or delete) from the console. When UCL+ receives a command line, it first 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. Next, if the PATH command is turned on, UCL+ uses the "run-by-name" path to look for a program named "dev:word1.SAV" (the default is dev=DK) and, if it finds it, runs it by passing the command "RUN command-string" to RT-11. Finally, if all else fails, UCL+ exits with a "?UCL-F-Invalid command" error message or, if the CHAIN com- mand is in effect, UCL+ chains to the specified program, and passes it the original command line. UCL+ -- User Command Linkage Program - V07.44 Page 14 Spring 1985 DECUS Distribution 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. 6.2 RT-11 Command Processing With UCF Support If your RT-11 is version 5.02 or later, you have support available for User Commands First (UCF) processing. If you turn UCF support on (this can be done with the CI handler; see section 10.0), RT-11 will collect your command line and, after checking for IND syntax, pass it directly to a program named SY:UCF.SAV. You can use UCL+ as a "UCF" by making a copy of it named UCF.SAV. UCL+ will now be intercepting commands before the monitor gets them! This can get really ______ tricky because UCF can, in effect, override normal RT-11 commands. The implications of all this can get pretty com- plicated and are beyond the scope of this manual; read the RT-11 documentation and release notes for details. The main thing to remember is that UCL+ processes unrecog- nized commands differently when it is running as UCF than it does when it is running as UCL. As UCF, it passes unknown commands to the monitor; as UCL it issues an error message. This makes sense, because UCF gets commands first while UCL gets them last. The simplest situation, with UCF support turned on and UCL turned off, causes command lines to be processed in the fol- lowing sequence: 1. UCF tries to execute it as a command, then 2. UCF tries to execute it as a symbol, then 3. UCF tries to "run-by-name", then 4. RT-11 tries to execute it, then 5. RT-11 tries to run it off SY:, then 6. you get "?KMON-F-Invalid command" UCL+ -- User Command Linkage Program - V07.44 Page 15 Spring 1985 DECUS Distribution 6.3 TSX-Plus Command Processing If you are using UCL+ with TSX-Plus version 4.1, things work more or less the same as they do with RT-11 (see section 6.1): TSX passes the command string to UCL+ only if KMON fails to recognize it. Things get a little more compli- cated, however, if you are running under a V5.0 or later monitor. 1. TSX-Plus V5.0 looks for a "UCL" named SY:TSXUCL.SAV. Version 4.1 uses the same name as RT-11 (SY:UCL.SAV). 2. Version 5 implements a UCL "SET option". SET UCL NONE turns off user command linkage (now who would want to do that?). SET UCL LAST causes command processing to work like it did under V4.1 (except you get a "?KMON-F-Unrecognizable command" error message instead of "?UCL-F-Invalid command"). SET UCL MIDDLE allows TSXUCL to examine the command string after it is inspected for a match against the monitor commands, but before command file/run-by-name processing. SET UCL FIRST causes TSXUCL to be invoked prior to all KMON processing (i.e., it works like the RT-11 UCF facility -- see section 6.2). Note that MIDDLE will cause UCL+'s run-by-name path to take priority over TSX's; FIRST will, in addition, give priority to UCL+ com- mands over KMON commands (i.e., you can replace monitor commands with UCL+ commands). 3. Unless UCL is set FIRST, the monitor DISPLAY com- mand will preempt the UCL+ DISPLAY command. This means that you will need to define a symbol in order to invoke the UCL+ DISPLAY command properly (for example, DSPLAY==_d). 4. UCL+ can also be used, under TSX, as a User Command Interpreter (UCI). When UCI support is turned on (via the SET KMON UCI command), the UCI effectively replaces the keyboard monitor (note that this is ________ different from SET UCL FIRST where KMON collects the command, and then passes it to UCL). UCL+ can be used as a UCI by making a copy of it with the appropriate name (the default is SY:UKMON.SAV) and utilizing the UCL+ UCI_MODE command. See the TSX-Plus user documentation for further information. UCL+ -- User Command Linkage Program - V07.44 Page 16 Spring 1985 DECUS Distribution 7.0 SYMBOLS This is probably the most important section of this manual. The main reason for using UCL+ (unless you just don't like to have a lot of empty space on your disk) is that it gives you the ability to dynamically define your own commands. For the purposes of this document, these user-defined com- mands will be referred to as "symbols". The following sec- tions present a summary of how to define and manipulate these symbols. 7.1 Defining 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.), "==" is the symbol definition operator, 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. NOTE DEC's UCL uses a more "VMS-like" structure for de- fining symbols (possible example: REB*OOT:==BOOT DL0: vs. REBOOT==BOOT DL0:). UCL+ will accept the DEC format as well as the "normal" one. 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 UCL+ -- User Command Linkage Program - V07.44 Page 17 Spring 1985 DECUS Distribution 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 in- serted 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 RESORC SY:PIP.SAV/V Finally, you may precede the "definition-part" with an un- derscore character ("_"). This will cause UCL+ to process the symbol expansion in "execute-immediate" mode. In other words, you are telling UCL+ that you are defining one symbol in terms of another symbol or hard-wired command. Thus, the expanded symbol is processed immediately by UCL+ rather than being passed on to RT-11 as a command string. This speeds up command execution substantially. For example, SAY==DISPLAY "^" (example 1) and SAY==_DISPLAY "^" (example 2) are equivalent definitions. If you type SAY HELLO both will expand (on the first pass through UCL+) as DISPLAY "HELLO" UCL+ -- User Command Linkage Program - V07.44 Page 18 Spring 1985 DECUS Distribution 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 im- mediately executes the resultant command string. Thus, ex- ample 2 executes much faster, especially on a floppy-based system, because UCL+ is only run once to process it, instead of twice. 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). 7.2 Deleting Symbols 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 with the same effect. If you wish to delete more than one symbol, the ERASE command is more efficient (see section 8.4 for more details on the ERASE command). 7.3 Running UCL+ Directly You can also define (or erase) symbols by running UCL+ directly and proceeding as described above in response to the "UCL>" prompt. There is one significant difference, however: 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 instance, the escape sequence [H[J UCL+ -- User Command Linkage Program - V07.44 Page 19 Spring 1985 DECUS Distribution can be used to clear the screen on a VT100-style terminal. The following dialogue would define a symbol "CLS" to accom- plish this (items enclosed in angle brackets represent sin- gle control characters; e.g., ): .UCL UCL> cls==_d "[H[J UCL> Note that, if the single-line editor was enabled, you would have to turn it off before defining the above symbol. UCL+ -- User Command Linkage Program - V07.44 Page 20 Spring 1985 DECUS Distribution 8.0 "HARD-WIRED" COMMANDS The following is a brief description of the commands "hard-wired" into UCL+. Commands such as CHAIN, DISPLAY, ERASE, LIST, etc. are required to support the various UCL+ functional goodies. Others, like CD, RNO, NOSL, and SLON 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 com- mand). For example, "LIST COMMANDS" can be abbreviated as "LIS CO" ("LI CO" would be interpreted by RT-11 as a "LINK" command). The commands are listed in alphabetical order. Underlining with "====" is used to highlight the command itself. Op- tional modifiers, switches, and so forth, are enclosed in square brackets ("[]") and these may be nested (for example, [["]prompt-text["]] indicates that the quotes are optional as well as the entire argument). 8.1 CD Command CD [dev] == "Change Device" CD dev becomes ASSIGN dev DK: If the device mnemonic, "dev", is omitted you get ASSIGN SY: DK: Note that the colon (:) at the end of the device mnemonic is not required; "CD DY0" is the same as "CD DY0:". UCL+ -- User Command Linkage Program - V07.44 Page 21 Spring 1985 DECUS Distribution 8.2 CHAIN Command [NO]CHAIN [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 pro- gram in the same form and in the same fashion that the string was given to UCL+. Issuing a CHAIN command with no argument restores or retains the most recent CHAIN file specification. Note that the CHAIN command will also dis- able UCI_MODE if it is in effect (see also section 8.14). NOCHAIN disables chaining. UCL+ -- User Command Linkage Program - V07.44 Page 22 Spring 1985 DECUS Distribution 8.3 DISPLAY Command DISPLAY[/switches] command-string ======= or DISPLAY "string["] ======= "Display Command Expansion or String" The DISPLAY command prints the expansion of the specified UCL+ command or symbol or, if you enclose the argument with quotation marks, the indicated string is simply printed as is followed by a carriage-return/line-feed. If the trailing quote is omitted, no carriage control is appended (this is the preferred method for sending escape sequences). Output can be directed to the console (the default), the printer, or some other specified device/file. Switches: /EXECUTE prints the expanded command and then exe- cutes it (not valid if DISPLAYing a string). /NOEXECUTE suppresses command execution (default). /FORM0 allows the printer handler to do a formfeed before the first page of output (default; has no effect unless SET LP FORM0 command is in effect) /NOFORM0 prevents the printer handler from executing a formfeed before the first page of output (recommended if you are sending escape se- quences to the printer) /PRINTER directs output to the printer (device LP:). /OUTPUT:file-spec directs output to the specified device/file. /TERMINAL directs output to the console (default). Note that the DISPLAY command is only valid for commands that cause a command expansion to be passed to the keyboard monitor. It also does not work across a CHAIN. Attempting to DISPLAY a "non-expandable" command will cause a "?UCL-F-Invalid DISPLAY argument" error message to be is- sued. UCL+ -- User Command Linkage Program - V07.44 Page 23 Spring 1985 DECUS Distribution 8.4 ERASE Command 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 en- tire symbol name, it is deleted with no verification prompt. If you only type enough of the name to be unambiguous, you will get an "Are You Sure?" prompt. The command "ERASE *" will delete all of the symbols. Switches: /NOQUERY omits verification prompt /QUERY ask for operator verification (default if ERASE * used) 8.5 LIST Command LIST[/switch] thing1[,thing2,...] ==== "List Current Commands/Symbols/Attributes" The LIST command lists the "hard-wired" commands, currently defined symbols, CHAIN assignment/status, run-by-name path, UC handler status, and present version/release to the speci- fied device or file. If you type a LIST command with no ar- guments, the symbols are listed. If you omit the output specification, output is directed to the console. Switches: /FORM0 allows the printer handler to do a formfeed before the first page of output (default; has no effect unless SET LP FORM0 command is in effect) /NOFORM0 prevents the printer handler from executing a formfeed before the first page of output /OUTPUT:file-spec sends output to the specified device/file /PRINTER sends output to the printer (LP:) /TERMINAL sends output to the console UCL+ -- User Command Linkage Program - V07.44 Page 24 Spring 1985 DECUS Distribution Arguments: ALL list commands, symbols, chain data, path list, version, and UC handler status ("LIST *" has the same effect) 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) UC_STATUS list the contents of the UC handler's text buffer VERSION list the program name and version 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 section 7.3 would list as CLS==_d "~[H~[J UCL+ -- User Command Linkage Program - V07.44 Page 25 Spring 1985 DECUS Distribution 8.6 NOSL/SLON Command NOSL or SLON ==== ==== "SL editor on/off" These commands turn the single-line editor off or on. If UCL+ is RUN directly, the effect is to toggle SL locally. This assumes, of course, that SL was installed and turned on prior to running UCL+ and that SL is enabled for use by user programs. This is particularly handy if you need to include characters in a symbol definition that are intercepted by the single-line editor. For example, if you wished to de- fine a symbol that rings the bell on the console, you could use the following sequence of commands: .UCL UCL> nosl UCL> bell==_d " UCL> slon If NOSL or SLON is entered via the monitor, the effect is the same as typing, respectively, SET SL OFF or SET SL ON. 8.7 PASS_ON Command PASS_ON[/TO:program-name] 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 UCL+ -- User Command Linkage Program - V07.44 Page 26 Spring 1985 DECUS Distribution 8.8 PATH Command [NO]PATH [device1[,device2,...]] ==== "Set Up 'Run-by-name' Search Path" If UCL+ does not "know" a given command, it 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. Issuing a PATH command without specifying a device list causes UCL+ to restore or retain the most recent "run-by-name" path. The NOPATH command disables the "run-by-name" function. 8.9 PROMPT Command PROMPT [["]prompt-text["]] ====== "Change Prompt String" The PROMPT command is used to change the UCL+ input prompt. This command is frequently employed when UCL+ is being used in "UCI mode". The replacement prompt text may optionally be enclosed in quotes. If you issue the PROMPT command with no argument, the default prompt ("UCL> ") is restored. 8.10 RECALL Command RECALL[/switches] 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:. The default extension is .UCL (ie, DK:filnam.UCL where "filnam" is the file name you specify) if you are running the "vanilla" UCL+ program, .UCX if you are using the special XM version of UCL+, and .UCJ if the /JOURNAL switch is in effect (either version). Switches: /BINARY this is the default; loads a file created as a binary image of the UCL+ symbol/status area /JOURNAL loads a "journal" file; echos the input to the console unless /QUIET is in effect UCL+ -- User Command Linkage Program - V07.44 Page 27 Spring 1985 DECUS Distribution /QUIET suppresses echo of commands when doing /JOURNAL input; invalid with /BINARY; also suppresses "warning level" messages (e.g., "?UCL-W-Replaced existing symbol") 8.11 RELOAD command RELOAD ====== "Reload The UCL+ Global Region" When you are using the special XM version of UCL+, almost the entire program is permanently resident in a global re- gion in extended memory. The RELOAD command allows you to force UCL+ to reload this memory region from the disk copy of the UCL+ program that you are currently running. 8.12 RNO Command 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 UCL+ -- User Command Linkage Program - V07.44 Page 28 Spring 1985 DECUS Distribution /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 output specifications: /OUTPUT:filename filename...= /PRINTER LP:...= /TERMINAL TT:...= no output spec. or LP:...= /DEFAULTS 8.13 STORE Command STORE[/switches] 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 is .UCL (ie, DK:filnam.UCL where "filnam" is the file name you specify) if you are running the "vanilla" UCL+ program, .UCX if you are using the spe- cial XM version of UCL+, and .UCJ if the /JOURNAL switch is in effect (either version). Switches: /BINARY this is the default; stores a file as a binary image of the UCL+ symbol/status area /JOURNAL writes a "journal" file; the file is stored as the series of commands necessary to recreate the present UCL+ configuration; i.e., as an "edit- able" command file UCL+ -- User Command Linkage Program - V07.44 Page 29 Spring 1985 DECUS Distribution 8.14 UCI_MODE Command [NO]UCI_MODE [["]prompt-text["]] ======== "Switch 'UCI Mode' On/Off" The UCI_MODE command is employed to set up UCL+ for use as a "User Command Interpreter" (UCI). TSX-Plus provides a facility for designating UCI's. Typically, a UCI is used to process user input either prior to, or instead of, the normal keyboard monitor (KMON). Issuing a UCI_MODE command has the following effect on UCL+: 1. CHAINing is disabled. Non-UCL+ command strings are passed to KMON for execution. 2. If specified, the "prompt-text" replaces the normal UCL+ line prompt; if no "prompt-text" is speci- fied, the default prompt ("UCL> ") is assumed (same effect as a PROMPT command). 3. The names of the hard-wired commands are changed by ___ _____ __ ___ __________ ________ ___ _______ __ the addition of a "prefix character". Unless you ___ ________ __ _ _______ __________ reassemble UCL+ to change or eliminate it (see sec- tion 14.7), this character is a period ("."). Thus, for example, the LIST command becomes ".LIST". NOUCI_MODE acts as follows: 1. The CHAINing condition in effect prior to the UCI_MODE command is restored. 2. If no prompt-text is specified, the default UCL+ prompt is restored ("UCL> "). 3. The normal hard-wired command names are restored. UCL+ -- User Command Linkage Program - V07.44 Page 30 Spring 1985 DECUS Distribution 9.0 UC HANDLER Starting with V07.04, you may use UCL+ in conjunction with the UC "handleroid" to "remember" what might be called the "input-spec" part of the last UCL+ command line. This stored text can be retrieved for use in a subsequent command **AT THE COMMAND LEVEL** via the "^" character. This is most useful when using UCL+ in UCI_MODE, and it works a lot like the "^" construct in symbol definitions. The differ- ence is that only the part of the command string preceeded by a leading space and ending with a "terminator" (space, "/", "=", comma, or null byte) is "memorized". For example, the command sequence FOO/BAR ARG1 FREEP ^ is equivalent to FOO/BAR ARG1 FREEP ARG1 If you are running a monitor like TSX-Plus that supports user-written UCI's, the UC handler becomes a lot more use- ful. In this case, UCL+ can be used (in conjunction with the UCI_MODE command) to accept and process all command-level console input. This allows you to use the "UC memory" feature with monitor commands as well as UCL+ com- mands. For example: FORT FOO LINK/MAP:^/FORE ^ DEL ^.OBJ,^.BAK The UC handler must be memory-resident (loaded) to use this feature under RT-11. You can use the LIST UC_STATUS command (section 8.5) to see if the UC handler is "available" (loaded) and to look at the contents of UC's text buffer. NOTE If you are using the UC handler under RT-11, remember that it will only work properly in con- junction with UCL commands and symbols. Note also that it will probably not work correctly with most commands if UCF support is enabled. UCL+ -- User Command Linkage Program - V07.44 Page 31 Spring 1985 DECUS Distribution 10.0 CI HANDLER This "handleroid" allows you to turn the various RT-11 Com- mand Line Interpreters (CLI's) on or off using SET commands. It will also show which CLI's are enabled. There are four CLI's: UCF (User Commands First), DCL (Digital Command Language), CCL (Concise Command Language), and UCL (User Command Linkage). Refer to the documentation for RT-11 V05.02 for an explanation of each. The possible SET com- mands for the CI (Command Interpreter) handleroid are: SET CI [NO]UCF -- turn UCF on/off SET CI [NO]DCL -- turn DCL on/off SET CI [NO]CCL -- turn CCL on/off SET CI [NO]UCL -- turn UCL on/off SET CI HELP -- display SET commands SET CI RESET -- same as SET CI NOUCF,DCL,CCL,UCL SET CI SHOW -- display the active CLI's By default, RT-11 has all CLI's enabled except UCF. In other words, the normal situation is equivalent to SET CI NOUCF,DCL,CCL,UCL Thus, if you issued a SET CI SHOW command under an unaltered monitor, CI would report ?CI-I-CLI's enabled: DCL CCL UCL Note that SET CI RESET restores/insures the above default condition. It is not possible to INSTALL CI. This is because CI con- tains only SET code. As there is no executable handler code, there is no reason why CI should be installable -- it would just waste a device slot in the monitor tables that could be used for something else. The monitor will execute the SET options as long as CI has the right name and resides on SY:. Thus, for the RT-11 SJ and FB monitors, the file should be SY:CI.SYS. If you are going to use it under XM, make a copy named SY:CIX.SYS. NOTE CI will not run under versions of RT-11 prior to V05.02. It doesn't go to the trouble of checking for TSX-Plus, however, so if you try it with TSX it's your funeral. UCL+ -- User Command Linkage Program - V07.44 Page 32 Spring 1985 DECUS Distribution WARNING!!! Turning off both DCL and CCL effectively turns off the monitor. UCL+ -- User Command Linkage Program - V07.44 Page 33 Spring 1985 DECUS Distribution 11.0 ERROR MESSAGES The following are the current UCL+ error messages. There are two levels of severity. "Warning" level messages are preceeded with the prefix "?UCL-W-" (for example, "?UCL-W-Replaced existing symbol"), and they indicate that the program may have done something that produced an errone- ous result. Warning level conditions do not cause program termination. "Fatal" messages are issued when UCL+ detects an error condition that prevents the program from producing any useable output. These messages are preceeded with "?UCL-F-" (for example, "?UCL-F-Ambiguous command C"). 11.1 UCL+ "Warning" Messages Erased symbol A....A Issued when you erase a symbol via the "null definition" method. "A....A" is the symbol name. Replaced existing symbol Indicates that you have replaced an existing symbol defini- tion with another. Truncating symbol definition to 72 characters You have used too many characters to describe a symbol de- finition. UCL+ stores the new symbol, but truncates the de- finition part to 72 characters. Truncating symbol name to 6 characters You have used too many characters in a symbol name. UCL+ stores the new symbol, but truncates the name to 6 characters. UCL+ -- User Command Linkage Program - V07.44 Page 34 Spring 1985 DECUS Distribution 11.2 UCL+ "Fatal" Messages If you are running under a TSX-Plus V5, or later, monitor, those messages flagged with "(*)" will result in a "?KMON-F-Unrecognizable command" error message unless UCL+ is run directly. Ambiguous command A....A (*) You have not typed enough characters for UCL+ to determine which command or symbol to execute. "A....A" is the uniden- tified command. Ambiguous switch A....A You have not typed enough characters for UCL+ to determine which command switch to use. "A....A" is the text of the unknown switch. Ambiguous symbol A....A You issued an ERASE command without specifying enough characters for UCL+ to determine which symbol to erase. "A....A" is the name of the ambiguous symbol specification. Conflicting switches You specified two or more command switches that conflict with one another (for example, RNO/TERM/PRINT...). File not found A....A The RECALL command was unable to find the file that you specified. "A....A" is the file name causing the error. Illegal device You specified a device that is unknown to the operating sys- tem. This error occurs with the RECALL or STORE command. Illegal file name A....A You specified a file name in an invalid format (for example, too many characters, or invalid characters). "A....A" is the erroneous file name. UCL+ -- User Command Linkage Program - V07.44 Page 35 Spring 1985 DECUS Distribution Invalid argument A....A You issued a hard-wired command with an invalid argument (for example, LIST X). "A....A" is the text of the argument causing the error. Invalid command A....A (*) UCL+ was unable to recognize the command string (no match with the hard-wired commands, no match with the symbols, the "run-by-name" search failed, and no CHAIN was in effect). "A....A" is the unknown command string. Invalid context: wrong RT-11 version or monitor, or UCL not loaded properly This message is issued by the XM version of UCL+ and indi- cates a failure of it's initial context check. One of the following errors was detected: o you attempted to run the XM version under a version of RT-11 prior to V05.02, o you were not running the XM monitor or were running TSX-Plus, or o the contents of the UCL+ global region were not loaded correctly (it may be possible to correct this with a RELOAD command). Invalid DISPLAY argument A....A You attempted to DISPLAY something that is not DISPLAYable (i.e., the input command does not result in a command expansion; a LIST command, for example), or you tried to DISPLAY a command or symbol that does not exist. "A....A" is the text of the invalid DISPLAY target. Invalid or missing option You specified an incorrect option to a command switch, or you failed to specify an option value where one was re- quired. Invalid switch A....A You specified an illegal command switch. "A....A" is the switch causing the error. UCL+ -- User Command Linkage Program - V07.44 Page 36 Spring 1985 DECUS Distribution Not enough room for file A....A The STORE command was unable to find enough room for the output file (18 decimal blocks are required). "A....A" is the file name. Read error A....A UCL+ encountered an error when it attempted to read data from a file. This error is most commonly generated by the RECALL command. This may be due to a hard input error, but the usual cause is an attempt to RECALL a journal file without specifying the /JOURNAL switch to the RECALL com- mand. "A....A" is the name of the file in which the error occurred. RELOAD invalid while journaling The journal file that you specified in a RECALL/JOURNAL com- mand contained a symbol name that UCL+ interpreted as a RELOAD command. Edit the journal file to correct this error and try the RECALL command again. Symbol definition table full You attempted to define a new symbol, but UCL+ had no room left to store the definition. Symbol not found A....A The ERASE command was unable to find the name of the symbol that you specified. "A....A" is the unknown symbol. UCI_MODE invalid for this monitor You issued a UCI_MODE command when you were running under RT-11 or a version of TSX-Plus prior to V5.0. Write error A....A UCL+ encountered an error when it attempted to write data to a file. This error is generated by the STORE command, and it implies that the area where the ".UCL" file was created is corrupted. "A....A" is the name of the file in which the error occurred. UCL+ -- User Command Linkage Program - V07.44 Page 37 Spring 1985 DECUS Distribution Wrong file format A....A You attempted to execute a RECALL/JOURNAL on a binary format file or a RECALL/BINARY on a journal file. "A....A" is the name of the file that you attempted to RECALL. Wrong version of UCL A....A You tried to RECALL a symbol definition/status file that was created by a version of UCL+ that is too old. For example, a ".UCL" file created by a V1 UCL+ would be incompatible with a V7 series program. "A....A" is the offending file name. 11.3 Global Region Loader Errors If you are running the XM version of UCL+, you may oc- casionally see error messages from the global region loader. These messages are all "fatal" errors and will be prefixed with "?UCLGRL-F-" (for example, "?UCLGRL-F-No room"). No room You have insufficient memory for the loader to run. This is highly unlikely under normal circumstances; the loader never requires more than 756 words of low memory. PLAS error Some sort of memory management related error occured when the loader attempted to create or attach to the global re- gion. The most likely causes are a shortage of extended memory, or an attempt to create too many global regions. I/O error The loader encountered a problem when it attempted to access the program image on disk. Possible causes include a bad block within the program disk image, or the program storage device may be write protected. UCL+ -- User Command Linkage Program - V07.44 Page 38 Spring 1985 DECUS Distribution 11.4 CI Handler Errors The CI handler generates messages for two error conditions as follows. ?CI-F-Wrong version of RT-11 You attempted you use the CI handler with a version of RT-11 prior to V05.02. ?CI-W-Disable access to monitor commands/utilities; Are you sure? You have issued a SET command to CI that will result in turning off both DCL (Digital Command Language) and CCL (Concise Command Language). You are, in effect, asking to turn off your entire RT-11 command interface (except for a few of the UCL+ hard-wired commands, assuming that UCF or UCL is still enabled). In keeping with the idea that RT-11 is an "open system", CI will go ahead and do this if you respond with "Y" for yes. UCL+ -- User Command Linkage Program - V07.44 Page 39 Spring 1985 DECUS Distribution 12.0 EXAMPLES Here are a few examples of some of the symbol 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 EXIT ==\^ INSPEC==EDIT/INSPECT KILL ==DELETE/NOQUERY/LOG NEW ==DIR/NEW PICH10==_d/p/nof "~[1w PICH16==_d/p/nof "~[4w REBOOT==DUP SY:/O/Y SAY ==_d "^" ULINE ==_d "~[4m^~[0m" VERSIO==RESORC SY:^.SAV/V VT100 ==SET TT SCOPE,TAB,NOCRLF XM ==BOOT SY:RT11XM.SYS UCL+ -- User Command Linkage Program - V07.44 Page 40 Spring 1985 DECUS Distribution 13.0 V7 RELEASE NOTES UCL+ V7 contains a number of extensions to, and minor dif- ferences from, V6L (the last publicly released version). 1. I changed the version/release designation. V7C was followed by V07.04. 2. UCL+ has been updated to work properly under TSX-Plus V5. 3. Support has been added to UCL+ to allow it to be used as a User Command Interpreter (UCI). This was implemented when the author discovered that TSX-Plus version 5 was distributed with a UCI facility (heh, heh, heh)... As a consequence, the UCI_MODE/NOUCI_MODE and PROMPT commands were added to allow UCL+ to be dynamically reconfigured for use as a UCI. See section 14.6 in the application notes and the description of the UCI_MODE command (section 8.14) for further information on this feature. 4. CHAIN and PATH work somewhat differently than in previous versions. The /RESET switch has been removed. NOCHAIN and NOPATH commands have been ad- ded. The effect of these latter commands is to disable their respective functions. A subsequent CHAIN or PATH command with no argument restores the previous condition. Note that a CHAIN command will turn off UCI_MODE if it is in effect. 5. The /ALL switch has been removed from the ERASE command. For V7, the equivalent to the old "ERASE/ALL" command is now "ERASE *". 6. The LIST command has been expanded. Either "LIST ALL" or "LIST *" will produce a full listing. "LIST VERSION" and "LIST UC_STATUS have been added. 7. A bug has been fixed concerning the way that UCL+ determines command ambiguity. Formerly, UCL+ would report a command as ambiguous if it detected an am- biguous match within the hard-wired commands. UCL+ now searches the symbols as well before returning an error. A non-ambiguous match in the hard-wired command list still takes priority over searching the symbol list. UCL+ -- User Command Linkage Program - V07.44 Page 41 Spring 1985 DECUS Distribution 8. The DISPLAY command has been cleaned up. UCL+ now refuses to DISPLAY "non-expandable" command strings (most of the hard-wired commands, insertion or replacement of symbol definitions, symbols defined in "chained-to" UCL's). 9. A special "XM version" of UCL+ is now included on the distribution kit. It is intended for use with RT-11 XM monitors having support for global regions in extended memory (i.e., RT-11 V05.02 or later). Almost all of the "UCLXM" executable code is per- manently memory resident. It is very fast, and uses less than 500 decimal words of low memory. An additional hard-wired command, "RELOAD", has been added to UCLXM. UCL+ -- User Command Linkage Program - V07.44 Page 42 Spring 1985 DECUS Distribution 14.0 APPLICATION NOTES This section contains an assortment of hints, restrictions, customization patches, and notes for the current version of UCL+. 14.1 Executing Command/Control Files "By-Name" UCL+ can be used to execute indirect command files and IND control files "by-name". In fact, if you set things up properly, you can ensure that they are executed in the proper context regardless of whether SET KMON IND is in ef- fect or not. The following examples illustrate the technique. Note that you must run UCL+ directly to define the necessary symbol for a command file. For command files: .UCL ___ UCL> zoot==$@sy:zoot _______________ UCL> ________ For control files: .FEEP==IND SY:FEEP _________ _______ 14.2 Changing The Effect Of RNO/DEFAULTS The effect, in the distributed version of UCL+, of the RNO command's /DEFAULT switch is to place the string "LP:" at the beginning of the CSI command string that is passed to the RUNOFF program. This default text string can be changed by editing the .ASCIZ string at label DEFTXT in the file UCLHWC.MAC. For example, if you are directing output to an el-cheapo printer that doesn't do formfeeds, you might want to change DEFTXT to "LP:/F". 14.3 Sending Escape Sequences To The Printer Starting with V6K, the LIST and DISPLAY commands include a FORM0/NOFORM0 option. This option allows you to optionally disable the effect of the "SET LP FORM0" command; i.e., output can be directed to the printer without a preceding formfeed. This technique is most useful when you wish to send an escape sequence to the printer without triggering a gratuitous blank page. A handy way to accomplish this is to define a generalized symbol for doing this sort of thing ("" represents the escape character): UCL+ -- User Command Linkage Program - V07.44 Page 43 Spring 1985 DECUS Distribution .UCL UCL> nosl UCL> cqwenc==_d/p/nof "^ UCL> You can then define specific printer-control commands by us- ing the general symbol like a "function". For example, to define commands to control the pitch of an LA50/100/120 style printer: .UCL UCL> pich10==_cqwenc [1w UCL> pich16==_cqwenc [4w UCL> 14.4 Moving From UCL+ V6x To UCL+ V7.xx UCL+ V7 will not allow you to RECALL version 6 or earlier series .UCL files. There is a technique, using the RT-11 utility SIPP, that will allow you to transfer your symbol definitions, etc. without reentering them all. The patch proceeds as follows: 1. Using SIPP, change the embedded version number at location 21620 in the old ".UCL" file from 6 to 7. 2. RUN a V7.xx copy of UCL+ and RECALL the patched symbol/status file. 3. Issue a PROMPT command to restore the "UCL>" prompt. 4. Issue a STORE command to write a new ".UCL" file. In the example below, both the ".UCL" file and the V7 copy of UCL.SAV are assumed to be on DK:; "xxxxxx.UCL" is your V6x ".UCL" file. Note that the SIPP patch is for a V6L file. .R SIPP _ ____ *xxxxxx.UCL/A ____________ Base? _____ Offset? 21620 _____ Base Offset Old New? 000000 021620 006006 \ _ Base Offset Old New? 000000 021620 006 7 _ 000000 021621 014 ________ * ________ UCL+ -- User Command Linkage Program - V07.44 Page 44 Spring 1985 DECUS Distribution .RUN UCL ___ ___ prompt ______ UCL> recall xxxxxx ______ ______ UCL> store xxxxxx _____ ______ UCL> ________ . Once the above commands have been executed, the resulting V7 copy of UCL.SAV will be in the same configuration as your original V6 copy. WARNING!!! The above patch will not work for the XM version of UCL+. You must apply the method described in the following application note if you intend to run the XM version. 14.5 Moving From UCL+ V6x Or V7.xx To UCL+ (XM) V7.xx If you wish to use the XM version of UCL+, you can transfer the symbol/status data from a non-XM version of UCL+ in the following fashion: 1. If your old ".UCL" file is V6x, apply the patch described in the preceding application note to a "vanilla" copy (i.e., the non-XM version) of the current UCL+ program. If your file was created with a V7.xx UCL+, just run the distributed non-XM UCL+ program and execute a RECALL command. 2. Run the "vanilla" UCL+ and issue a STORE/JOURNAL command to produce a ".UCJ" file. 3. Run the XM version of UCL+ and issue a RECALL/JOUR- NAL to load the symbol/status data written out in the previous step. UCL+ -- User Command Linkage Program - V07.44 Page 45 Spring 1985 DECUS Distribution 14.6 Hints and Kinks: UCF, UCI, And SET UCL FIRST If you are using UCL+ as a UCI, command lines are inspected by UCL+ before they are processed by the operating system's ______ keyboard monitor (KMON). If you are using UCL+ as UCF or, under TSX-Plus, with SET UCL FIRST in effect, KMON collects the command line, but it is passed to UCL+ without interpre- tation. In any of these instances, the effect is that UCL+ inspects the command before the monitor does. Only if UCL+ does not recognize the command will the monitor see the com- mand line in unaltered form. This occasions a couple of "gotchas" that you have to watch out for. 14.6.1 Interception Of Monitor Commands - Some valid KMON commands may be trapped prematurely by UCL+. This situation occurs when there is a conflict between a monitor command or normal command abbreviation and a symbol name. For example, the HELP command under TSX-Plus would normally be invoked as "H", "HE", "HEL", or "HELP". If you wish to avoid a con- flict with, say, a symbol named "HELLO", then it would be necessary to define the following symbols: H==HELP HE==HELP HEL==HELP Conversly, the above situation allows you to override moni- tor commands with your own. E.g., DELETE==_d "The DELETE command is not allowed!" 14.6.2 Improper Expansion Of Monitor Commands - This second gotcha is a little more subtle. Some monitor commands have the same name as the utilities that they invoke. If you are, for example, running as UCF with PATH in effect, this can cause invalid command expan- sions. As an illustration, suppose your run-by-name path is "DK:" and DK: is currently assigned to SY:. The command "DUMP/TERM RUBISH.DAT" should be passed to KMON undisturbed (assuming that you haven't defined your own DUMP command). However, UCL+ will spot program DUMP.SAV on "DK:", and ex- pand the command as "RUN DK:DUMP/TERM RUBISH.DAT". DUMP will see something like "RUBISH.DAT=/TERM" and give you what might seem, at the time, to be a mysterious error message. I normally avoid this problem by disabling the run-by-name path (NOPATH command). If you have a need to retain the run-by-name search path, define some symbols that will cause UCL+ -- User Command Linkage Program - V07.44 Page 46 Spring 1985 DECUS Distribution UCL+ to, in effect, pass your command line to the monitor in an unaltered form. For the preceeding example, define DUMP==DUMP 14.6.3 Single Key Commands - All is not gotchas... UCL+ is not very picky about the characters that you use in symbol names. If you are using UCL+ as a UCI under TSX-Plus, then you are running UCL+ directly whenever you input a command line. This means that you can define some handy single-key symbols that the monitor would strongly disapprove of otherwise. For example: \==edit |==edit/create ??????==help One user that I know of (Ray Moran) places his VT100 in al- ternate keypad mode (with a UCL+ command, of course!) and executes symbols whose names correspond to the escape se- quences generated by the individual keys. If you are using a VT220, or anything with an LK201 style keyboard. You have even more keys that you can define! 14.7 UCL+ Assembly Conditionals You can build a somewhat customized version of UCL+ by mod- ifying the conditionals file, UCL.CND, prior to assembly. The prefix conditional, PFX, determines the prefix character used by UCL+ when UCI_MODE is in effect. You can change this prefix by changing the definition of PFX from a period (".") to some other character. Two non-essential hard-wired commands, RNO and CD, are nor- mally included when UCL+ is assembled. If you do not wish to include the CD command, set conditional CD$C equal to zero; to eliminate the RNO command, set RNO$C equal to zero. Excluding both the CD and RNO commands decreases the size of UCL+ by 472 decimal words. Use the command file UCL.COM to build UCL+. Use UCLXM.COM to build the XM version. UCL+ -- User Command Linkage Program - V07.44 Page 47 Spring 1985 DECUS Distribution 14.8 Modifying RT-11 To Change The UCL/UCF Device/File Name The RT-11 monitor can be modified to run UCL.SAV or UCF.SAV from some device other than SY:. The name of the UCL or UCF program can also be changed. To accomplish this, you need to know the offsets for some or all of the following loca- tions in the monitor: o ..UCLD - UCL device name o ..UCLF - UCL file name o ..UCFD - UCF device name o ..UCFF - UCF file name The values located at the above offsets are all radix-50 and, as you might expect, the file name immediately follows the device name. I.e., ..UCLF is located at ..UCLD+2 and ..UCFF at ..UCFD+2. If you are an orderly person, you can find the values for these offsets by inspecting the link map for your monitor. Note that, if your monitor version is earlier than V05.02, there will not be any ..UCFD/..UCFF values. If you are a somewhat disorderly person (perhaps you are un- dergoing TECO withdrawal), you can find ..UCLF and ..UCFF by employing the SIPP search function and looking for a radix-50 UCL or UCF, respectively. In either case, once you know where these locations are, you can use SIPP to patch your monitor to taste. In the follow- ing example, the UCL device is patched from "SY:" to "UCL:". I usually do this because I can then assign some other device to be UCL: in my start-up command file (VM: is a nice choice). The labels ..UCLD and ..UCLF represent the offsets that were obtained from the monitor's link map. .SIPP RT11XM.SYS/A ____ ____________ Base? _____ Offset? ..UCLD ______ Base Offset Old New? 000000 ..UCLD 075250 ;R __ 000000 ..UCLD ;RUCL _____ 000000 ..UCLF ________ If you run more than one type of RT-11 monitor on your sys- tem, you may wish to use different copies of UCL and/or UCF depending on which monitor is booted. In the example below, the XM monitor is patched to run UCLXM.SAV rather than UCL.SAV. UCL+ -- User Command Linkage Program - V07.44 Page 48 Spring 1985 DECUS Distribution .SIPP RT11XM.SYS/A ____ ____________ Base? _____ Offset? ..UCLF ______ Base Offset Old New? 000000 ..UCLF 101704 ;R __ 000000 ..UCLF _____ 000000 ..UCLF+2 < > ;RXM ____ 000000 ..UCLF+4 ________ 14.9 Modifying TSX-Plus To Change The UCL/UCI Defaults If you select UCL support when you generate TSX-Plus (if not, why are you reading this?), the default UCL program name is SY:TSXUCL.SAV (if you are running V5.0 or later). Likewise, the default name for user-written UCI's is SY:UKMON.SAV. The easiest way to change these names is to edit the TSGEN.MAC file prior to building TSX-Plus. These values are not normally modified by the user and, thus, will not be found within the "user area" of TSGEN.MAC. If you hunt around with the editor, however, you should be able to find them. For example, if you have V5.1B and want to change the UCL default name, you will discover a line of code that should look like UCLNAM: .RAD50 /SY TSXUCLSAV/ If you are modifying the UCI default, you will find some- thing like UKMNAM: .RAD50 /SY UKMON SAV/ To change the defaults, edit the rad50 file names prior to assembling TSGEN.MAC. For instance, you could edit the value at label "UCLNAM:" to change the UCL name from SY:TSXUCL.SAV to UCL:TSXUCL.SAV. Further variations on this theme I leave as an exercise to the user. 14.10 Controlling Command Line Factoring Both RT-11 and TSX-Plus support command line factoring. However, they don't execute it in the same processing se- quence. This can effect the way that you define a symbol that employs factoring as part of it's definition. For example, suppose that you wish to define a symbol, "FTN", to invoke the FORTRAN compiler in a specialized fashion that compiles one or more files resident on device "FTN:". If you are using TSX-Plus, you can define the sym- bol at the monitor level: UCL+ -- User Command Linkage Program - V07.44 Page 49 Spring 1985 DECUS Distribution .FTN==FORT FTN:(^) _________ _______ However, the example above will not work properly if you are running RT-11. This is because RT-11 expands the factoring prior to passing the command line to UCL+. Thus, RT-11 would remove the "unecessary" parentheses in the preceeding monitor level command, and UCL+ would see "FTN==FORT FTN:^". The solution, in this case, is to run UCL+ directly: .R UCL _ ___ UCL> ftn==fort ftn:(^) _________ _______ UCL> ________ UCL+ -- User Command Linkage Program - V07.44 Page 50 Spring 1985 DECUS Distribution 15.0 REPORTING PROBLEMS AND SUGGESTIONS I want to know about bugs! I am also interested in suggestions for improving UCL+ as well as any interesting applications that you may have found for it. I can be contacted at one of the following addresses: William K. Walker Monsanto Research Corp. P. O. Box 32 Miamisburg, OH 45342 (513) 865-3557 William K. Walker P. 0. Box 149 Alpha, OH 45301 (513) 426-7094 If you are on Compuserve, my ID is 71066,24. Leave a mes- sage in EMAIL or in the PDP-11 SIG (within the SIG, address stuff to "Bill Walker 71066,24"). UCL+ -- User Command Linkage Program - V07.44 Page 51 Spring 1985 DECUS Distribution 16.0 WISH LIST Aside from the usual fiddling about with the internals, I currently plan to make the following additions to future versions of UCL+: o a reasonable way to change the number of characters allocated for symbol names and symbol definitions, o a method to change the total number of symbol de- finitions allowed in UCL+, and o an RNO command for Bonner Lab RUNOFF. I do NOT intend to implement a "symbol definition editor". Use LIST/JOURNAL and edit the output. I also don't plan to add an "F77" command -- I am hoping that the RT-11 people will do this.