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.57 11 May 1988 William K. Walker Monsanto Research Corp. P. O. Box 32 Miamisburg, OH 45342 (513) 865-3557 SPECIAL NOTE TO SCIENTISTS/RESEARCHERS Read the manual! Page ii TABLE OF CONTENTS 1.0 ACKNOWLEDGEMENTS . . . . . . . . . . . . . . . . . . . . . . 1 2.0 IMPORTANT NOTICES . . . . . . . . . . . . . . . . . . . . . 1 3.0 BEFORE YOU GET STARTED . . . . . . . . . . . . . . . . . . . 2 4.0 ABOUT THIS DOCUMENT . . . . . . . . . . . . . . . . . . . . 2 5.0 INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . 4 5.1 UCL+ Differences . . . . . . . . . . . . . . . . . . . . . . 4 5.2 UCL+ Enhancements . . . . . . . . . . . . . . . . . . . . . 5 6.0 INSTALLATION . . . . . . . . . . . . . . . . . . . . . . . . 7 6.1 Installing UCL.SAV . . . . . . . . . . . . . . . . . . . . . 8 6.1.1 Installing UCL.SAV On RT-11 Systems . . . . . . . . . . . 8 6.1.1.1 Installation As A UCL (UCL.SAV) . . . . . . . . . . . . 8 6.1.1.2 Installation As A UCF (UCF.SAV) . . . . . . . . . . . . 9 6.1.2 Installing UCL.SAV On TSX-Plus Systems . . . . . . . . . . 9 6.1.2.1 Installation As A UCL (TSXUCL.SAV) . . . . . . . . . . . 9 6.1.2.2 Installation As A UCI (UKMON.SAV) . . . . . . . . . . 10 6.2 Installing UCLXM.SAV . . . . . . . . . . . . . . . . . . . 10 6.2.1 Installing UCLXM.SAV On RT-11 Systems . . . . . . . . . 11 6.2.1.1 Installation As A UCL (UCL.SAV) . . . . . . . . . . . 11 6.2.1.2 Installation As A UCF (UCF.SAV) . . . . . . . . . . . 12 6.2.2 Installing UCLXM.SAV On TSX-Plus Systems . . . . . . . . 13 6.2.2.1 Installation As A UCL (TSXUCL.SAV) . . . . . . . . . . 13 6.2.2.2 Installation As A UCI (UKMON.SAV) . . . . . . . . . . 14 6.3 Installing The CI Handler . . . . . . . . . . . . . . . . 14 6.4 Installing UCL+ HELP . . . . . . . . . . . . . . . . . . . 15 6.5 Installing The UCL+ Distribution Under RTEM . . . . . . . 16 7.0 HOW IT WORKS . . . . . . . . . . . . . . . . . . . . . . . 17 7.1 RT-11 Command Processing With UCL Support . . . . . . . . 17 7.2 RT-11 Command Processing With UCF Support . . . . . . . . 18 7.3 TSX-Plus Command Processing . . . . . . . . . . . . . . . 18 8.0 SYMBOLS . . . . . . . . . . . . . . . . . . . . . . . . . 20 8.1 Defining Symbols . . . . . . . . . . . . . . . . . . . . . 20 8.2 Deleting Symbols . . . . . . . . . . . . . . . . . . . . . 22 8.3 Entering Special Characters . . . . . . . . . . . . . . . 22 8.4 Running UCL+ Directly . . . . . . . . . . . . . . . . . . 23 8.5 Advanced Techniques . . . . . . . . . . . . . . . . . . . 24 8.5.1 Using The Quote Character ("|") . . . . . . . . . . . . 24 8.5.2 Argument String Parsing ("^n") . . . . . . . . . . . . . 25 8.5.3 Specifying Default Strings . . . . . . . . . . . . . . . 26 9.0 "HARD-WIRED" COMMANDS . . . . . . . . . . . . . . . . . . 28 9.1 CHAIN Command . . . . . . . . . . . . . . . . . . . . . . 29 Page iii 9.2 DISPLAY Command . . . . . . . . . . . . . . . . . . . . . 30 9.3 ERASE Command . . . . . . . . . . . . . . . . . . . . . . 32 9.4 LIST Command . . . . . . . . . . . . . . . . . . . . . . . 33 9.5 NOSL/SLON Command . . . . . . . . . . . . . . . . . . . . 35 9.6 PASS_ON Command . . . . . . . . . . . . . . . . . . . . . 36 9.7 PATH Command . . . . . . . . . . . . . . . . . . . . . . . 37 9.8 PROMPT Command . . . . . . . . . . . . . . . . . . . . . . 38 9.9 RECALL Command . . . . . . . . . . . . . . . . . . . . . . 39 9.10 RELOAD command . . . . . . . . . . . . . . . . . . . . . 40 9.11 STORE Command . . . . . . . . . . . . . . . . . . . . . . 41 9.12 UCI_MODE Command . . . . . . . . . . . . . . . . . . . . 42 10.0 CI HANDLER . . . . . . . . . . . . . . . . . . . . . . . 43 11.0 INFORMATIONAL MESSAGES . . . . . . . . . . . . . . . . . 45 12.0 ERROR MESSAGES . . . . . . . . . . . . . . . . . . . . . 46 12.1 UCL+ "Warning" Messages (?UCL-W-...) . . . . . . . . . . 46 12.2 UCL+ "Fatal" Messages (?UCL-F-...) . . . . . . . . . . . 47 12.3 Global Region Loader Errors (?UCLGRL-F-...) . . . . . . . 50 12.4 CI Handler Errors (?CI-...) . . . . . . . . . . . . . . . 50 13.0 EXAMPLES . . . . . . . . . . . . . . . . . . . . . . . . 52 14.0 V7 RELEASE NOTES . . . . . . . . . . . . . . . . . . . . 53 15.0 APPLICATION NOTES . . . . . . . . . . . . . . . . . . . . 56 15.1 Executing Command/Control Files "By-Name" . . . . . . . . 56 15.2 Sending Escape Sequences To The Printer . . . . . . . . . 56 15.3 Moving From UCL+ V6x To UCL+ V7.xx . . . . . . . . . . . 57 15.4 Moving From UCL+ V6x Or V7.xx To UCL+ (XM) V7.xx . . . . 58 15.5 Disabling Argument Parsing . . . . . . . . . . . . . . . 58 15.6 Hints and Kinks: UCF, UCI, And SET UCL FIRST . . . . . . 59 15.6.1 Interception Of Monitor Commands . . . . . . . . . . . 59 15.6.2 Improper Expansion Of Monitor Commands . . . . . . . . 60 15.6.3 Single Key Commands . . . . . . . . . . . . . . . . . . 60 15.7 UCL+ Assembly Conditionals . . . . . . . . . . . . . . . 60 15.8 Modifying RT-11 To Change The UCL/UCF Device/File Name . . . . . . . . . . . . . . . . . . . . . . . . . . 61 15.9 Modifying TSX-Plus To Change The UCL/UCI Defaults . . . . 63 15.10 Controlling Command Line Factoring . . . . . . . . . . . 63 15.11 Patching UCL+ For RT-11 V5.1 . . . . . . . . . . . . . . 65 15.12 Implementing The CD And RNO Commands . . . . . . . . . . 66 15.13 Avoiding Conflicts With The SL RECALL Command . . . . . 67 16.0 REPORTING PROBLEMS AND SUGGESTIONS . . . . . . . . . . . 68 17.0 WISH LIST . . . . . . . . . . . . . . . . . . . . . . . . 69 18.0 UCL+ COMMAND AND SYNTAX SUMMARY . . . . . . . . . . . . . 70 UCL+ -- User Command Linkage Program - V07.57 Page 1 Spring 1988 DECUS Release 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 Equip- ment Corporation, Maynard, MA; TSX-Plus is a product of S & H Computer Systems, Nashville, TN. The "^0" construct and the facility for entering octal character codes were added at the suggestion of C. E. Chew of Australia -- thus ending an unprecedented four months of stability for the UCL+ package. The idea of adding a provision for specifying default argument strings in symbol definitions came from Rally Barnard, Albu- querque, NM. The addition of the LIST/INDIVIDUAL facility came about because I finally got tired of everybody asking me for it and because it is, after all, rather convenient. LIST SYMBOLS was added for basically the same reasons. The informational messages (?UCL-I-etc.) were added to keep Rally from shooting himself in the foot. The field testing for this version was performed by Rally Bar- nard, Ellen Bachmann, Jim Lindesmith, and myself (of course). 2.0 IMPORTANT NOTICES RT-11 V5.1 USERS ________________ IF YOU ARE GOING TO USE THIS VERSION OF UCL+ UNDER AN RT-11 V5.1 MONITOR (OR EQUIVALENT RTEM-11 MONITOR), YOU MUST APPLY THE PATCH IN SECTION 15.11 FOR UCL+ TO WORK PROPERLY (IT'S NOT MY FAULT -- IT'S DEC'S FAULT). RT-11 V5.4C OR LATER USERS __________________________ THE EXTENDED MEMORY VERSION OF THE SINGLE-LINE EDITOR IMPLEMENTS A RECALL COMMAND AS A SET OPTION. IF THIS FUNCTIONALITY IS ENABLED, IT PREEMPTS THE UCL+ RECALL COMMAND. SEE THE APPLICA- TION NOTES, SECTION 15.13, FOR A DISCUSSION OF HOW TO WORK AROUND THIS PROBLEM. V07.54 OR EARLIER UCL+ USERS ____________________________ THE "CD" AND "RNO" COMMANDS ARE NO LONGER INCLUDED IN THE DISTRI- BUTED UCL+ PROGRAM. "CD" CAN NOW BE DEFINED AS A SYMBOL, AS CAN A BASE-LINE "RNO" COMMAND. SEE THE APPLICATION NOTES, SECTION 15.12, FOR DETAILS. THE STANDARD, HARD-WIRED "RNO" COMMAND IS UCL+ -- User Command Linkage Program - V07.57 Page 2 Spring 1988 DECUS Release ALSO AVAILABLE AS A CONDITIONAL ASSEMBLY (SEE SECTION 15.7). 3.0 BEFORE YOU GET STARTED Before you start using UCL+, there are a few things that you should keep in mind. o 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 accustomed to the basic facilities. o If you intend to use the extended features, particularly UCF or UCI_MODE, make sure you read the available do- cumentation. Note that there are a number of goodies contained in the application notes (section 15.0) at the end of this manual. o READ THE INSTALLATION INSTRUCTIONS (section 6.0) for your particular environment. o RTEM users can assume that the material concerning RT-11 also applies to the RTEM equivalent environment. The significant exceptions are the installation procedures and the use of the UCF facility. 4.0 ABOUT THIS DOCUMENT A fair amount of effort has gone into this manual to give reason- ably comprehensive coverage of the contents of the UCL+ distribu- tion kit. It does not, however, attempt to include material already available in the relevant operating system documentation, nor is there extensive coverage of internals. Where examples are felt to be necessary, the following conven- tions are followed: o Examples, unless otherwise noted, are for RT-11 V5.0; no "factoring" is used. o In most examples, operator input is underlined. o All visible lines of input are assumed to be terminated with a carriage return. o "Non-printing" characters and control characters are identified by an abbreviation enclosed by angle brackets ("<>"). E.g., UCL+ -- User Command Linkage Program - V07.57 Page 3 Spring 1988 DECUS Release - = carriage return (CR) - = escape (ESC) - = control-C (ETX) - = control-Y (EM) Note, however, that instances of digits enclosed in an- gle brackets (e.g.,"<003>") are a part of the normal UCL+ symbol definition syntax. o Examples and procedure descriptions, except where noted, assume that all necessary files are on the default device (DK:). UCL+ -- User Command Linkage Program - V07.57 Page 4 Spring 1988 DECUS Release 5.0 INTRODUCTION UCL+ is a user command linkage program for use with RT-11 V5 or later, RTEM V2.0 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, RTEM, and TSX-Plus) o UCI - User Command Interpreter (TSX-Plus, starting with V5.0) o UCF - User Commands First (RT-11, starting with V5.2) In general, UCL+ can be used as a direct replacement for the "UCLs" distributed with these operating systems. There are some relatively minor incompatibilities between UCL+ and the distri- buted versions, as well as a substantial number of enhancements. The remainder of this section summarizes these differences. 5.1 UCL+ Differences UCL+ is upward compatible with the UCL program distributed with RT-11 (and the TSX-Plus TSXUCL program) with the following excep- tions. o UCL+ accepts the "VMS-like" symbol definition syntax 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 con- text. 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. o 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. 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. UCL+ -- User Command Linkage Program - V07.57 Page 5 Spring 1988 DECUS Release 5.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 do- cument 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 sin- gle command line via the ERASE command. All current symbol definitions can be removed with ERASE *. o You can chain to additional "UCLs". 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 exe- cution. The DISPLAY command can also be used to output ASCII strings to the console or printer (handy for sneaky escape sequences). o You can enter and use virtually any character, including eight-bit and control characters, in a symbol defini- tion. 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 functionality was added with UCL+ V7 to take advantage of the UCI facility in TSX-Plus. o You may dynamically redefine the prompt string issued by UCL+. UCL+ -- User Command Linkage Program - V07.57 Page 6 Spring 1988 DECUS Release o A "quoting" facility is available to override the effect of "operator" characters. o In order to allow more complex command definitions, UCL+ supports the parsing of argument strings into as many as nine sub-strings. o You may define default values for argument strings and argument sub-strings. o If you have an RT-11 V5.2 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 various Com- mand Language Interpreters (CLIs). 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 continuously resident in a global region in extended memory. It is very fast, and uses only 512 (decimal) words of low memory. UCL+ -- User Command Linkage Program - V07.57 Page 7 Spring 1988 DECUS Release 6.0 INSTALLATION This section of the manual contains information on the installa- tion of the major components of the UCL+ distribution. These are: o UCL.SAV - the "vanilla" UCL+ program (section 6.1) o UCLXM.SAV - a special XM version of UCL+ (section 6.2) o CI.SYS - the Command Line Interpreter handler (section 6.3) o UCLHLP.TXT - the help text necessary to build a UCL+ help program (section 6.4) 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+ distribution 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 or RTEM. TSX-Plus users should also note that the installation procedures for TSX assume that the user has sufficient privilege to execute them -- i.e., installation will be probably be accomplished by the system manager. The examples also assume that you are going to use the default program names when you install the various components. 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, sec- tions 15.8 and 15.9, for information on changing these defaults. If you are converting from any version of UCL+ prior to V07.50, you should also read section 8.5 and the application note in sec- tion 15.5. Please remember that reasonable attempts are made to keep succes- sive versions of UCL+ upward compatible, but there is no guarantee that they are downward compatible. Thus, V7.55 will accept V7.54 journal files, but it is very unlikely that things will work the other way around. V07.54 OR EARLIER UCL+ USERS The "CD" and "RNO" commands are no longer included in the distributed UCL+ program. "CD" can now be defined as a symbol, as can a base-line "RNO" command. See the application note, section 15.12, for details. The UCL+ -- User Command Linkage Program - V07.57 Page 8 Spring 1988 DECUS Release standard, hard-wired "RNO" command is also available as a conditional assembly (see section 15.7). 6.1 Installing UCL.SAV UCL.SAV is the "vanilla" UCL+ program. It will run under ver- sions of RT-11 beginning with V5.0 (and the equivalent RTEM releases) 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 environments. The installation procedure may differ, however, in some cases. 6.1.1 Installing UCL.SAV On RT-11 Systems - For all versions 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 supporting User Commands First (UCF), UCL+ can be used as a UCF also (except RTEM). 6.1.1.1 Installation As A UCL (UCL.SAV) - If you are already using a previous version of UCL+, you should first save your cur- rent 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. 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 15.3). 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. UCL+ -- User Command Linkage Program - V07.57 Page 9 Spring 1988 DECUS Release 6.1.1.2 Installation As A UCF (UCF.SAV) - Beginning with V5.2, 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 installation procedure is as follows (note that this command sequence is for RT-11 V5.2): .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-CLIs enabled: UCF DCL CCL UCL When UCL+ runs as UCF, it automatically detects this condition, and processes commands appropriately. 6.1.2 Installing UCL.SAV On TSX-Plus Systems - If you are run- ning TSX-Plus V4.1, installation is the same as it is for RT-11 (section 6.1.1). If you are running V5.0 or later, the procedure is somewhat different. Note that you should make sure that UCL support is enabled when you execute your initial TSGEN. Also note that TSX-Plus users must have read/write access to the UCL+ program if they are to be able to define or erase symbols. The easiest way to accomplish this is to include an ACCESS com- mand in the user's logon command file. For example: ACCESS SY:TSXUCL.SAV 6.1.2.1 Installation As A UCL (TSXUCL.SAV) - If you are already using a previous version of UCL+, you should first save your cur- rent 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, UCL+ -- User Command Linkage Program - V07.57 Page 10 Spring 1988 DECUS Release 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 15.3). 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+. 6.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 Inter- preter (UCI). The following example illustrates a typical in- stallation with the default UCI name of UKMON.SAV. Note that the command prompt is changed during this procedure to help distin- guish the "UCI" copy of UCL+ from other copies that might exist on the same system as "UCLs". .COPY UCL.SAV SY:UKMON.SAV _________________________ .R UKMON _______ UCL> uci "ukmon> " _____________ ukmon> ________ You would invoke UKMON.SAV as a UCI by typing .SET KMON UCI ____________ 6.2 Installing UCLXM.SAV UCLXM.SAV is a special version of UCL+ for use with the extended memory (XM) monitor on systems running RT-11 V5.2 or later. It can also be used under TSX-Plus monitors that are compatible with RT-11 V5.2 (TSX-Plus V6.0 or later). UCLXM has a minimal low memory presence -- typically, about 512 (decimal) words. The remainder of the program, about 10K words, resides in a global region in extended memory. In the RT-11 environment, UCLXM is significantly faster than the "vanilla" UCL+ due to the fact that all but a two-block "stub" is permanently memory resident. UCLXM is a direct, functional replacement for the distributed UCL program. As with the "vanilla" UCL+ program, UCLXM can also be used as a UCF program. Under TSX-Plus, speed improvement resulting from the use of UCLXM instead of the regular UCL+ program will depend on such factors as the amount of memory available for cache, and the amount of swapping normally seen on the system. It is interesting to note, however, that the "low memory" image of UCLXM is less than 512 bytes (a user job size of 8kb under a V6.1 monitor). This is due to the fact that the bulk of the program (20kb) resides in a shared global region. If multiple copies of UCL+ are running UCL+ -- User Command Linkage Program - V07.57 Page 11 Spring 1988 DECUS Release simultaneously, they are all sharing the same global region and, thus, sharing most of their run-time code. WARNING!!! Do not attempt to run UCLXM.SAV under a monitor that is not compatible with RT-11 V5.2 or later. The results are unpredictable -- your system may crash. 6.2.1 Installing UCLXM.SAV On RT-11 Systems - Installing the XM version of UCL+ under RT-11 is a reasonably straightforward pro- cess, 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 V5.2 monitor. 6.2.1.1 Installation As A UCL (UCL.SAV) - If you are already using a previous version of UCL+, you should first save your cur- rent 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 version of UCL+, follow the procedure described in the application notes (section 15.4) to transport your symbol definitions. If your previous UCL+ is an XM version, you can just 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. UCL+ -- User Command Linkage Program - V07.57 Page 12 Spring 1988 DECUS Release .r ucl _____ UCL> prompt "uclxm> " ________________ uclxm> ________ 6.2.1.2 Installation As A UCF (UCF.SAV) - Beginning with V5.2, 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 its own, unique global region in ex- tended memory. The installation 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-CLIs enabled: UCF DCL CCL UCL When UCL+ runs as UCF, it automatically detects this condition, and processes commands appropriately. UCL+ -- User Command Linkage Program - V07.57 Page 13 Spring 1988 DECUS Release 6.2.2 Installing UCLXM.SAV On TSX-Plus Systems - Installing the XM version of UCL+ under TSX-Plus is similar to the RT-11 pro- cedure. As with RT-11, there may be some special considerations if you are "porting" from an earlier, non-XM version of UCL+. In addition, the XM version of UCL+ must be able to use TSX-Plus global region support. This can be accomplished by editing TSGEN.MAC prior to building TSX-Plus, or through the use of the INSTALL command. PRO/TSX-Plus users must use the INSTALL com- mand, since TSGEN.MAC is not included in the PRO distribution. For a V6.1 monitor, the command is as follows install add sy:tsxucl.sav/priv=(nodebug,sysgbl) The best place to put this command is in a detached job command file that is executed when TSX-Plus is booted. Also note that TSX-Plus users must have read/write access to the UCL+ program if they are to be able to define or erase symbols. The easiest way to accomplish this is to include an ACCESS com- mand in the user's logon command file. For example: ACCESS SY:TSXUCL.SAV All examples in this section are for a TSX-Plus V6.0 monitor. 6.2.2.1 Installation As A UCL (TSXUCL.SAV) - If you are already using a previous version of UCL+, you should first save your cur- rent 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 TSXUCL.SAV. .copy uclxm.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 an XM version or a non-XM version. If it is a non-XM version of UCL+, follow the procedure described in the application notes (section 15.4) to transport your symbol definitions. If your previous UCL+ is an XM version, you can just type .recall sy:curent ________________ UCL+ -- User Command Linkage Program - V07.57 Page 14 Spring 1988 DECUS Release to load the symbol/status data into your new copy of UCL+. Finally, it is a good idea to run TSXUCL and change the command prompt. .r tsxucl ________ UCL> prompt "tsxucl> " _________________ tsxucl> ________ 6.2.2.2 Installation As A UCI (UKMON.SAV) - Under TSX-Plus, UCL+ can also be used as a User Command Interpreter (UCI). The following example illustrates a typical installation with the default UCI name of UKMON.SAV. Note that the name of the global region used by UKMON.SAV is changed from the default value of "UCL". Note also that the command prompt is changed during this procedure to help distinguish the "UCI" copy of UCL+ from other copies that might exist on the same system as "UCLs". .copy uclxm.sav sy:ukmon.sav ___________________________ .sipp sy:ukmon.sav/a ___________________ Base? _____ Offset? 1024 ____ Base Offset Old New? 000000 001024 101704 ;R __ 000000 001024 ;RUKM _____ 000000 001026 < > ;RON ____ 000000 001030 < FP> ________ .r ukmon _______ UCL> uci "ukmon> " _____________ ukmon> ________ You would invoke UKMON.SAV as a UCI by typing .set kmon uci ____________ 6.3 Installing The CI Handler The CI (Command line Interpreter) handler can be used on RT-11 V5.2 or later systems to control the action of the various com- mand line interpreters (CLIs). It contains no executable handler _____________________ code; all it does is execute SET commands. 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: UCL+ -- User Command Linkage Program - V07.57 Page 15 Spring 1988 DECUS Release .copy/sys ci.sys sy:cix.sys __________________________ See section 10.0 for more information in the CI handler. 6.4 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+ com- mands in one of two ways: o 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.1 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). Note that both the RT-11 and UCL+ help text files contain a macro named "HELP." You should retain the RT-11 version of this macro. o 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.1. All required files are assumed to be on the default device (DK:). .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\^ _______________ NOTE If you are using RT-11 V5.2, the SPLIT boundaries 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. This boundary may, of course, change again in later versions of RT-11. UCL+ -- User Command Linkage Program - V07.57 Page 16 Spring 1988 DECUS Release 6.5 Installing The UCL+ Distribution Under RTEM The following special considerations and restrictions apply to using the UCL+ package under the RT-11 Emulator (RTEM): o The UCL program (UCL.SAV) should be placed in your "private" area. The distributed UCL program resides in the read-only portion of the virtual system device. The system manager should either rename the distributed UCL program (if there is one) or delete it. Otherwise, the installation procedure is the same as for RT-11 systems (section 6.1.1.1). o If it is to be used, the CI handler should be placed in the "mark zone" portion of the virtual system device. This is normally done by the system manager. Section 6.3 contains further information on installing this handler. o Later versions of RTEM use the UCF facility to implement specialized commands for this environment. Thus, the UCF facility is not available to RTEM users. o The UCL+ help facility is normally installed in the "shared" area of the virtual system device. See section 6.4 for further information on installing the UCL+ help text. In summary: the UCL+ program is placed in the user's "private" area; the help program and the CI handler are installed by the system manager in the "shared" area, with the handler residing in the "mark zone." UCL+ -- User Command Linkage Program - V07.57 Page 17 Spring 1988 DECUS Release 7.0 HOW IT WORKS First, read the appropriate sections of the RT-11 Software Sup- port 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.2 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 (UCIs) and the UCL SET commands. OK, now that you've done your homework (and saved me a lot of typing)... 7.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 cer- tain 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 en- tire command line to UCL. UCL+ understands two types of commands: "hard-wired" commands (LIST or RECALL, for example), which are "built in" to UCL+ (hereafter referred to simply as "commands"), and "symbols", 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 command is in effect, UCL+ chains to the specified program, and passes it the original command line. UCL+ -- User Command Linkage Program - V07.57 Page 18 Spring 1988 DECUS Release In summary then, when you enter a command: o RT-11 tries to execute it, then o RT-11 tries to run it off SY:, then o UCL+ tries to execute it as a command, then o UCL+ tries to execute it as a symbol, then o UCL+ tries to "run-by-name", then o you either get a nasty comment or UCL+ chains to another program. 7.2 RT-11 Command Processing With UCF Support If your RT-11 is version 5.2 or later, you have support available for User Commands First (UCF) processing. If you turn UCF sup- port 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 complicated 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 unrecognized 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 following sequence: o UCF tries to execute it as a command, then o UCF tries to execute it as a symbol, then o UCF tries to "run-by-name", then o RT-11 tries to execute it, then o RT-11 tries to run it off SY:, then o you get "?KMON-F-Invalid command" 7.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 7.1): TSX passes the command string to UCL+ only if KMON fails to recognize it. Things get a little more complicated, however, if you are running under a V5.0 or later monitor. UCL+ -- User Command Linkage Program - V07.57 Page 19 Spring 1988 DECUS Release o 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). o 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 in- spected 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 pro- cessing (i.e., it works like the RT-11 UCF facility -- see section 7.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+ commands over KMON commands (i.e., you can replace monitor commands with UCL+ commands). o Unless UCL is set FIRST, the monitor DISPLAY command 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). o UCL+ can also be used, under TSX, as a User Command In- terpreter (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.57 Page 20 Spring 1988 DECUS Release 8.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 dynamically to define your own commands. For the pur- poses of this document, these user-defined commands will be referred to as "symbols". The following sections present a sum- mary of how to define and manipulate these symbols. 8.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 "definition" is the character-string (72 characters max.) that will govern the way that the symbol is replaced (expanded) when it is inter- preted. 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 the DEC format as well as the "normal" one. However, if an asterisk is embedded in the symbol name, it will be ignored. 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.57 Page 21 Spring 1988 DECUS Release 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 RESORC SY:PIP.SAV/V Finally, you may precede the "definition-part" with an underscore character ("_"). This will cause UCL+ to process the symbol ex- pansion 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 pro- cessed immediately by UCL+ rather than being passed on to RT-11 as a command string. This speeds up command execution substan- tially. For example, SAY==DISPLAY "^" (example 1) and SAY==_DISPLAY "^" (example 2) are equivalent definitions. If you type SAY HELLO UCL+ -- User Command Linkage Program - V07.57 Page 22 Spring 1988 DECUS Release 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 ex- ecutes the resultant command string. Thus, example 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). 8.2 Deleting Symbols Individual symbols can be deleted either by redefining them with a null definition or with the ERASE command. For example, sup- pose 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 sym- bol, the ERASE command is more efficient (see section 9.3 for more details on the ERASE command). 8.3 Entering Special Characters There are a number of characters that cannot be typed directly. Examples of these "special" characters include control characters intercepted by RT-11 (control-O, control-S, etc.), and eight-bit codes recognized by some of the newer terminals and printers. If you need to include a character of this type in a symbol defini- tion, you can do so by entering its octal value in the form UCL+ -- User Command Linkage Program - V07.57 Page 23 Spring 1988 DECUS Release where "nnn" is an octal number of up to three digits. For example, to define a symbol, "BELL", which will ring the bell on the console: BELL==_D "<007> Actually, it is not necessary to enter all three digits; you may omit the leading zeros. Thus, the bell character could also be represented as "<07>" or "<7>". Note that UCL+ treats an invalid "" sequence as if it were just a normal string of characters. Thus, "<507>" would not be translated into a character because 507 is too big to be a one-byte value (the maximum value is 377 octal). Likewise, "<209>" would be ignored since 9 is an invalid octal digit. 8.4 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 inter- cept it for its own purposes (you couldn't use control-O, for ex- ample). In some cases, this is an easier way to enter a "special" character than the method described in the previous section (8.3). This is particularly true if you are using an earlier version of RT-11 that does not allow the entry of lower case characters at the monitor level. For instance, 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 accomplish this (items enclosed in angle brackets represent single 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. The applications notes, particularly the section on defining sym- bols that invoke command files and IND control files (section 15.1) and the discussion of command line factoring (section UCL+ -- User Command Linkage Program - V07.57 Page 24 Spring 1988 DECUS Release 15.10), contain further examples of when it is useful to run UCL+ directly. 8.5 Advanced Techniques This section contains a description of the "quoting", "argument parsing", and "default string" features of UCL+. The first two were added to UCL+ beginning with V07.50; the last appeared in V07.55. These features are very useful, but they should be used with a little care and forethought. In particular, it is impor- tant to understand how they work (and, perhaps, experiment a bit) when defining UCL+ symbols that have nested expansions. 8.5.1 Using The Quote Character ("|") - Quoting is primarily used to force UCL+ to treat an operator (the "^" and "\" characters, for example) as normal text. This is done by pre- ceeding the character to be quoted by the "|" operator. The most common application is to allow characters to be displayed as part of a text string that would normally be interpreted as operators. For example, the symbol definition: EXAMPL==_D "|\" Typing EXAMPL would print a "\" at the console. As a more useful illustration, suppose you wanted to send a line of ReGIS graphics instructions to a VT241 (to change the screen colors, perhaps). You will need to preceed the graphics output with the text "Pp" and follow it with "\" ("" in- dicates the escape character). Under TSX-Plus, the following symbol definition will do the trick (note the use of the quote character to display the "\"). regis==disp "Pp"\disp "^"\disp "|\" An alternate method is to enter the octal code for the escape character rather than typing it in directly (escape=33 octal): regis==disp "<33>Pp"\disp "^"\disp "<33>|\" Refer to section 15.10 of the "Application Notes" for a discus- sion on implementing this symbol under RT-11. It is good policy, by the way, to use the quote character only when it is required. The other thing to watch out for is nested command expansions (a symbol defined in terms of another symbol defined in terms of another...). Consider, for example, the problem of defining a UCL+ -- User Command Linkage Program - V07.57 Page 25 Spring 1988 DECUS Release symbol to display the quote character itself. The actual symbol definition is EXAMPL==_D "||||" Why four quote characters? Because this definition results in ____ two "quoting scans": once when the EXAMPL symbol is processed and expanded, and once when the resultant D (DISPLAY) command is scanned. In other words, the keyboard command to print a "|" is DISPLAY "||" In order to define a symbol whose expansion is the above command, you must quote both quotes! (Typing DISPLAY "|" prints the second quotation mark, not a "|" -- think about it.) Most situations are not as messy as this one. The best rule of thumb is to "work from the bottom up." 8.5.2 Argument String Parsing ("^n") - Argument string parsing allows you to extend the function of the "^" operator. UCL+ can break up the "argument part" of a command string into as many as nine sub-strings. These sub-strings are specified by following the "^" operator with a number from "1" to "9." UCL+ assumes that the sub-strings are separated by spaces. For example, the phrase "this is a test" consists of four sub-strings. As a simple il- lustration of how this works in practice, consider the following symbol definition. EXAMPL==_D "^2 ^1" If you type EXAMPL YOU THERE UCL+ will, in turn, display THERE YOU A more useful example is PMOVE -- a symbol for "moving" protected files: PMOVE==UNPRO/SYS ^1\COP/SYS/DEL/PROT ^ This command will copy a protected file from one place to another, and then delete the original copy of the file. By the way, once you have PMOVE defined, you can define a sneaky symbol that deletes protected files: PDELET==_PMOVE ^ NL: UCL+ -- User Command Linkage Program - V07.57 Page 26 Spring 1988 DECUS Release The combination "^0" has a special meaning. This construct will supply the number of sub-strings (up to a maximum of nine) that occur within a given argument string. For example, consider the following symbol definition: EXAMPL==_D ""^" HAS ^0 WORDS IN IT" If you type EXAMPL THIS IS A TEST UCL+ will print "THIS IS A TEST" HAS 4 WORDS IN IT The "^0" construct is most likely to be used when UCL+ builds a string to be passed to another program. This other program may wish to use the number of sub-strings as a first-line error check. Using argument parsing is not nearly as tricky as quoting (sec- tion 8.5.1, above), but there are a couple of basics that you must keep in mind. o The "^" operator, unmodified by a trailing numeric value, causes the entire argument string, including em- bedded spaces, to be inserted into the command expan- sion. An operator of the form "^n" inserts a sub-string without the "framing" spaces; i.e., the sub-string will never contain blanks. o Any construction of the form "^n" is treated as a pars- ing operator. However, the sequence "^|n" is not. In other words, in an instance where you need to disable parsing, quote the "n". 8.5.3 Specifying Default Strings - When you are defining a sym- bol, there may be instances where you wish to supply a default argument string or sub-string. This default string will be in- serted into the command expansion if the operator does not enter an argument string. Default strings are specified by enclosing the text in square brackets ("[]") immediately following the in- sertion operator ("^" or "^n" where "n" is a digit from 1 to 9). A simple and useful example of this technique is the "CD" com- mand. Prior to UCL+ V07.55, CD was a hard-wired command because it was too complex to define as a symbol. If you typed just "CD" with no argument, it expanded into the RT-11 command string "AS- SIGN SY DK." If you included the name of a device, it produced "ASSIGN device DK" (e.g., CD DY0 became ASSIGN DY0 DK). This can UCL+ -- User Command Linkage Program - V07.57 Page 27 Spring 1988 DECUS Release be a very handy command if, for example, you frequently bounce around between a number of logical devices. By taking advantage of the "default string" feature of UCL+, you can define the CD command as a symbol: CD==ASSIGN ^[SY] DK If you don't specify an argument string, the default string "SY" automatically will be inserted. Thus, "CD" becomes "ASSIGN SY DK", and "CD FOO" expands as "ASSIGN FOO DK." Default strings can also be used in conjunction with argument parsing. The following example defines an "RNO" command which invokes the RUNOFF program: RNO==R RUNOFF\^2[LP:]=^1\<003> If you type "RNO SCHMOO", RUNOFF processes file SCHMOO.DOC and directs output to the printer (LP: is the default output speci- fication). I.e., you get the following command expansion: R RUNOFF LP:=SCHMOO If you supply an output spec, it overrides the default text. Thus, "RNO SCHMOO TEMP.TXT becomes: R RUNOFF TEMP.TXT=SCHMOO There are a couple of points to keep in mind when you use the default string facility: o The default text is "sticky." Once the text for an in- sertion operator has been defined, it stays defined. Thus, defining something like ZORCH==_D "^1[MY] ^1[TEXT]" is a waste of typing. UCL+ scans symbol definitions from left to right, and it will always pick up, and use, the default text "MY"; "TEXT" will never be used. o Default text insertion is not nested. The default string is treated strictly as text (although quoting works). A construction such as "^2[^1]" will not cause the first sub-string to be used as the default for the second sub-string; instead, the text "^1" will be inserted. UCL+ -- User Command Linkage Program - V07.57 Page 28 Spring 1988 DECUS Release 9.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. 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 unambiguous (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 inter- preted by RT-11 as a "LINK" command). The commands are listed in alphabetical order. Underlining with "====" is used to highlight the command itself. Optional modi- fiers, 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 ar- gument). UCL+ -- User Command Linkage Program - V07.57 Page 29 Spring 1988 DECUS Release 9.1 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 program 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 re- tains the most recent CHAIN file specification. Note that the CHAIN command will also disable UCI_MODE if it is in effect (see also section 9.12). NOCHAIN disables chaining. Examples: NOCHAIN CHAIN SY:BADWRD.SAV UCL+ -- User Command Linkage Program - V07.57 Page 30 Spring 1988 DECUS Release 9.2 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 executes it (not valid if DISPLAYing a string). /NOEXECUTE suppresses command execution (default). /FORM0 allows the printer handler to do a formfeed be- fore 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 (recom- mended if you are sending escape sequences 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 ar- gument" error message to be issued. Examples: DISPLAY CD DL0 UCL+ -- User Command Linkage Program - V07.57 Page 31 Spring 1988 DECUS Release DISPLAY/EXECUTE SLON DISPLAY "HERE ARE TWO BEEPS<7><7>" DISPLAY/PRINTER "LINE OF TEXT" UCL+ -- User Command Linkage Program - V07.57 Page 32 Spring 1988 DECUS Release 9.3 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 entire 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) Examples: ERASE ZOOT,FINSTER,WALD ERASE * UCL+ -- User Command Linkage Program - V07.57 Page 33 Spring 1988 DECUS Release 9.4 LIST Command LIST[/switches] [thing1[,thing2,...]] ==== or LIST/INDIVIDUAL [symbol-spec1[,symbol-spec2,...]] ==== "List Current Commands/Symbols/Attributes" The LIST command lists the "hard-wired" commands, currently de- fined symbols, CHAIN assignment/status, run-by-name path, and present release/version to the specified device or file. If you type a LIST command with no arguments, the symbols are listed. If you omit the output specification, output is directed to the console. The /INDIVIDUAL switch allows you to list a single symbol defini- tion or a specific subset of the symbol definitions. Wildcard characters ("*" and "%") can be used to specify the symbols to be listed. Wildcards work in much the same way that they do in the RT-11 DIRECTORY command. E.g., the argument "A*" specifys all symbols whose name begins with "A"; "A%" asks for all two-character names beginning with "A". LIST/INDIVIDUAL does not display the "Current symbols:" header or the summary text issued by LIST SYMBOLS. This is not a bug; it is a deliberate feature. The intent is to allow you to employ the /OUT switch to create subset journal files. For example, LIST/I/OUT:MYSYMS.UCJ * would create a legitimate UCL+ journal file containing only the current symbol definitions. Switches: /FORM0 allows the printer handler to do a formfeed be- fore the first page of output (default; has no effect unless SET LP FORM0 command is in effect) /INDIVIDUAL allows the listing of a single symbol or a subset of the symbol definitions; wildcards can be used in the symbol specification /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 UCL+ -- User Command Linkage Program - V07.57 Page 34 Spring 1988 DECUS Release /PRINTER sends output to the printer (LP:) /TERMINAL sends output to the console (default) Arguments: ALL list commands, symbols, chain data, path list, and version. ("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 SUMMARY list the number of symbols currently defined and the number of entries remaining for new definitions SYMBOLS list the current symbol definitions (default) VERSION list the program name and version NOTE If you list a symbol whose definition contains non-printing characters (an escape character, for exam- ple), UCL+ will indicate their presence by printing the octal code for each character enclosed in angle brackets. E.g., the "CLS" example in section 8.4 in- cludes escape characters (escape=33 octal). It would list as CLS ==_d "<033>[H<033>[J Examples: LIST LIST CHAIN,PATH LIST/PRINTER * LIST/INDIVIDUAL A*,B%%%% LIST/INDIVIDUAL FOO UCL+ -- User Command Linkage Program - V07.57 Page 35 Spring 1988 DECUS Release 9.5 NOSL/SLON Command NOSL or SLON ==== ==== "SL editor on/off" These commands turn the single-line editor off or on. If UCL+ is being run directly, the effect is to toggle SL lo- cally. 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 define a sym- bol that rings the bell on the console, you could use the follow- ing sequence of commands: .UCL UCL> nosl UCL> bell==_d " If NOSL or SLON is entered via the monitor, the effect is the same as typing, respectively, SET SL OFF or SET SL ON. UCL+ -- User Command Linkage Program - V07.57 Page 36 Spring 1988 DECUS Release 9.6 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 pro- gram 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 Examples: PASS_ON LIST PASS_ON/TO:BADWRD NUTS==_D "NUTS TO YOU TOO" UCL+ -- User Command Linkage Program - V07.57 Page 37 Spring 1988 DECUS Release 9.7 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. When you enter a new device list, it replaces the old one. The limit is about 20 device mnemonics. It is not necessary to include the trailing colon when you specify a device; "DL0:" and "DL0" are interpreted in the same way. The NOPATH command disables the "run-by-name" function. If you have previously issued a NOPATH command, typing the PATH command by itself (no arguments) restores the old search path. Examples: PATH DK,DL0,DL1 NOPATH PATH DU0:,DU1: UCL+ -- User Command Linkage Program - V07.57 Page 38 Spring 1988 DECUS Release 9.8 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. Examples: PATH UCLXM> PATH "TSXUCL> " UCL+ -- User Command Linkage Program - V07.57 Page 39 Spring 1988 DECUS Release 9.9 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 command. 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). NOTE Beginning with RT-11 V5.4C, the extended memory version of the single-line editor implements a RECALL command as a SET option. If this functionality is enabled, it preempts the UCL+ RECALL command. See the application notes, section 15.13, for a discussion of how to work around this problem. 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 con- sole if /NOQUIET is in effect /NOQUIET allows echo of commands to console when doing /JOURNAL input; use this switch with caution, especially if commands may include console escape sequences /QUIET this is the default; suppresses echo of commands when doing /JOURNAL input; invalid with /BINARY; also suppresses "warning level" messages (e.g., "?UCL-W-Replaced existing symbol") Examples: RECALL SY:UCLXM RECALL/JOURNAL BADWRD UCL+ -- User Command Linkage Program - V07.57 Page 40 Spring 1988 DECUS Release 9.10 RELOAD command RELOAD ====== "Reload The UCL+ Global Region" When you are using the special XM version of UCL+, almost the en- tire program is permanently resident in a global region in ex- tended memory. The RELOAD command allows you to force UCL+ to reload this memory region from the copy of the UCL+ program that you are currently running. The RELOAD command always forces UCL+ to run; it does not return to the monitor automatically. This occurs even if you issue the RELOAD command at the monitor level. UCL+ -- User Command Linkage Program - V07.57 Page 41 Spring 1988 DECUS Release 9.11 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 ex- tension 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; 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 "editable" command file Examples: STORE SY:UCL STORE/JOURNAL BADWRD UCL+ -- User Command Linkage Program - V07.57 Page 42 Spring 1988 DECUS Release 9.12 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 UCIs. 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+: o CHAINing is disabled. Non-UCL+ command strings are passed to KMON for execution. o If specified, the "prompt-text" replaces the normal UCL+ line prompt; if no "prompt-text" is specified, the default prompt ("UCL> ") is assumed (same effect as a PROMPT command). o 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 section 15.7), this character is a period ("."). Thus, for example, the LIST command becomes ".LIST". NOUCI_MODE acts as follows: o The CHAINing condition in effect prior to the UCI_MODE command is restored. o If no prompt-text is specified, the default UCL+ prompt is restored ("UCL> "). o The normal hard-wired command names are restored. Examples: UCI_MODE "UKMON> " NOUCI_MODE UCL+ -- User Command Linkage Program - V07.57 Page 43 Spring 1988 DECUS Release 10.0 CI HANDLER This "handleroid" allows you to turn the various RT-11 Command Line Interpreters (CLIs) on or off using SET commands. It will also show which CLIs are enabled. There are four CLIs: UCF (User Commands First), DCL (Digital Command Language), CCL (Concise Command Language), and UCL (User Command Linkage). Refer to the RT-11 documentation for an explanation of each. The possible SET commands 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 CLIs By default, RT-11 has all CLIs 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-CLIs enabled: DCL CCL UCL Note that SET CI RESET restores/insures the above default condi- tion. It is not possible to INSTALL CI. This is because CI contains 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 some- thing 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. Under RTEM, it should reside in the "mark zone" as SY:CIM.SYS. NOTE TO RTEM USERS RTEM V2.1 uses the UCF facility to implement additional monitor commands and options that are specific to the RTEM environment. The CI handler automatically adjusts to this requirement. Under RTEM, SET CI RESET is equivalent to SET CI UCF,DCL,CCL,UCL. The text dis- played by SET CI HELP will reflect this difference also. UCL+ -- User Command Linkage Program - V07.57 Page 44 Spring 1988 DECUS Release WARNING!!! Turning off both DCL and CCL effectively turns off the monitor. NOTE CI will not run under versions of RT-11 prior to V5.2. It will not work properly with TSX-Plus either. UCL+ -- User Command Linkage Program - V07.57 Page 45 Spring 1988 DECUS Release 11.0 INFORMATIONAL MESSAGES Certain UCL+ operations trigger "informational" messages. These messages, preceeded by "?UCL-I-", are typically used to provide verification that a particular action has been taken in response to a command. They are not error messages. ?UCL-I-CHAIN disabled Indicates that the NOCHAIN command has been executed suc- cessfully. ?UCL-I-CHAIN in effect to A....A Indicates that the CHAIN command has been executed successfully. "A....A" is the program name. ?UCL-I-PATH disabled Indicates that the NOPATH command has been executed successfully. ?UCL-I-"Run-by-name" path: A....A Indicates that the PATH command has been executed successfully. "A....A" is the "run-by-name" path that was established by the PATH command. UCL+ -- User Command Linkage Program - V07.57 Page 46 Spring 1988 DECUS Release 12.0 ERROR MESSAGES The following are the error messages for the current UCL+ pack- age. There are two levels of severity. "Warning" level messages are preceeded with the prefix "?program-W-" (for example, "?UCL-W-Replaced existing symbol"), and they indicate that the program may have done something that produced an erroneous result. Warning level conditions do not cause program termina- tion. "Fatal" messages are issued when UCL+ detects an error condition that prevents the program from producing any useable output. These messages are preceeded with "?program-F-" (for ex- ample, "?UCL-F-Ambiguous command C"). 12.1 UCL+ "Warning" Messages (?UCL-W-...) Erased symbol A....A Issued when you erase a symbol via the "null definition" method. "A....A" is the symbol name. No argument; CHAIN not enabled You have issued a CHAIN command without specifying a program name, and no program name had been stored by a previous CHAIN command. Replaced existing symbol Indicates that you have replaced an existing symbol definition with another. Truncating symbol definition to 72 characters You have used too many characters to describe a symbol defini- tion. UCL+ stores the new symbol, but truncates the definition 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.57 Page 47 Spring 1988 DECUS Release 12.2 UCL+ "Fatal" Messages (?UCL-F-...) 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 unidentified com- mand. 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, DISPLAY/TERM/PRINT...). File not found A....A The RECALL command was unable to find the file that you speci- fied. "A....A" is the file name causing the error. 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 errone- ous file name. Invalid argument A....A You issued a hard-wired command with an invalid argument (for ex- ample, LIST X). "A....A" is the text of the argument causing the UCL+ -- User Command Linkage Program - V07.57 Page 48 Spring 1988 DECUS Release error. Invalid device You specified a device that is unknown to the operating system. This error occurs with the RECALL or STORE command. It may also occur if you make an error when you use LIST/OUT:. 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 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 sym- bol 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 required. Invalid switch A....A You specified an illegal command switch. "A....A" is the switch causing the error. Not enough room for file A....A The STORE command was unable to find enough room for the output file (18 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 com- mand. 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 command. "A....A" is the name of the file in which the error occurred. UCL+ -- User Command Linkage Program - V07.57 Page 49 Spring 1988 DECUS Release RELOAD invalid while journaling The journal file that you specified in a RECALL/JOURNAL command contained a symbol name that UCL+ interpreted as a RELOAD com- mand. 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. Unable to access LP: UCL+ was unable to find device LP:, or another job "owns" LP:. This error may occur when you use the /PRINT option, and its most frequent cause is the failure to make a logical assignment for LP:. 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 im- plies that the area where the ".UCL" file was created is cor- rupted. "A....A" is the name of the file in which the error occurred. 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. UCL+ -- User Command Linkage Program - V07.57 Page 50 Spring 1988 DECUS Release 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. 12.3 Global Region Loader Errors (?UCLGRL-F-...) If you are running the XM version of UCL+, you may occasionally 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 re- quires more than 768 words of low memory. Not XM monitor You attempted to run the XM version of UCL, but you were not us- ing the extended memory monitor. PLAS error Some sort of memory management related error occurred when the loader attempted to create or attach to the global region. The most likely causes under RT-11 are a shortage of extended memory, or an attempt to create too many global regions. If you are run- ning under a TSX-Plus V6.0 or later monitor, this error can also occur if you do not have SYSGBL privilege. 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. 12.4 CI Handler Errors (?CI-...) The CI handler generates messages for two error conditions as follows. UCL+ -- User Command Linkage Program - V07.57 Page 51 Spring 1988 DECUS Release ?CI-F-Wrong version of RT-11 You attempted you use the CI handler with a version of RT-11 prior to V5.2. ?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.57 Page 52 Spring 1988 DECUS Release 13.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. $RECAL==_recall BIG ==_d "<033>#3^<033>E<033>#4^" BUILD ==delete/info ^.bak\execute/norun ^\delete ^.obj CLS ==_d "<033>[H<033>[J DBO ==dir/brief/order:type EXIT ==\ HLP ==r uclhlp\^ INSPEC==edit/inspect J ==show jobs MEMORY==show memory MOVE ==cop/sys/del NEW ==dir/new NOQUIE==set tt noquiet NOWIDE==_d "<033>[?3l<033>[?25h PDELET==_PMOVE ^ NL: PICH10==_d/p/nof "<033>[1w PICH16==_d/p/nof "<033>[4w PMOVE ==unpro/sys ^1\cop/del/sys/prot ^ QUIET ==set tt quiet REBOOT==dup sy:/o/y RNO ==r runoff\^2[lp:]=^1\<003> SAY ==_d "^" SS ==sh sub SUM ==dir/sum ULINE ==_d "<033>[4m^<033>[0m" VERSIO==resorc sy:^.sav/v VT100 ==set tt scope,tab,nocrlf WIDE ==_d "<033>[?3h<033>[?25h XM ==boot sy:rt11xm.sys UCL+ -- User Command Linkage Program - V07.57 Page 53 Spring 1988 DECUS Release 14.0 V7 RELEASE NOTES UCL+ V7 contains a number of extensions to, and minor differences from, V6L (the last publicly released V6 series UCL+). Changes to previous V07.xx versions: o I changed the release/version designation. V7C was fol- lowed by V07.04. o UCL+ has been updated to work properly under TSX-Plus V5. o 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 15.6 in the application notes and the description of the UCI_MODE command (section 9.12) for further information on this feature. o CHAIN and PATH work somewhat differently than in previ- ous versions. The /RESET switch has been removed. NOCHAIN and NOPATH commands have been added. 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. o The /ALL switch has been removed from the ERASE command. For V7, the equivalent to the old "ERASE/ALL" command is now "ERASE *". o The LIST command has been expanded. Either "LIST ALL" or "LIST *" will produce a full listing. "LIST VERSION" has been added. o A bug has been fixed concerning the way that UCL+ deter- mines command ambiguity. Formerly, UCL+ would report a command as ambiguous if it detected an ambiguous 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.57 Page 54 Spring 1988 DECUS Release o The DISPLAY command has been cleaned up. UCL+ now re- fuses to DISPLAY "non-expandable" command strings (most of the hard-wired commands, insertion or replacement of symbol definitions, symbols defined in "chained-to" UCLs). o A special "XM version" of UCL+ is now included on the distribution kit. It is intended for use with monitors having support for global regions in extended memory (i.e., RT-11 V5.2 or later; TSX-Plus V6.0 or later). Almost all of the "UCLXM" executable code is permanently memory resident. It is very fast, and uses only 512 (decimal) words of low memory. An additional hard-wired command, "RELOAD", has been added to UCLXM. o Beginning with V07.46, the method that UCL+ uses to search the "run-by-name" path list has been changed slightly. UCL+ no longer exits to the monitor if it en- counters the name of a non-existent device. Instead, it ignores the error, and tries the next device in the list. o V07.47 contains code to "work around" some inconsisten- cies in the RT-11 spooler. If, for example, you issue a DISPLAY/PRINT/NOFORM0 command with spooler flag page support enabled, you will no longer get an unwanted flag page. UCL+ also avoids the generation of a gratuitous trailing form feed when the SET LP ENDPAG=n option is in effect. o V07.50 introduces two new advanced features: "quoting" and argument parsing. Quoting allows you to use the quote character ("|") to force UCL+ to treat the character immediately following it as text, regardless of any special meaning that it might normally have to the UCL+ parser. Argument parsing makes it possible to indicate where a specific fragment of the argument text is to be inserted when building a command string. o With V07.53, the default mode for RECALL/JOURNAL has been changed from /NOQUIET to /QUIET. Changes for V07.55b: o Some minor bugs were fixed in the "run-by-name" and sym- bol format checking algorithms. o STORE/JOURNAL now outputs NOCHAIN and NOPATH commands if the CHAIN and PATH facilities have been disabled. UCL+ -- User Command Linkage Program - V07.57 Page 55 Spring 1988 DECUS Release o The "^0" construct was added to allow the insertion of information about how many sub-strings were contained in an argument string. o Support was added to allow the specification of octal character codes (""); the output of the DISPLAY, LIST, and STORE/JOURNAL commands was changed to this format also. o The CI handler had a bug which crashed RTEM if the "...Are you sure?" message was triggered; this has been fixed. The CI version is now V03.03. o Provision was added to allow the specification of default text for the "^" and "^n" insertion operators. o The CD and RNO hard-wired commands were removed. CD can be defined as a symbol; a base-line RNO command can be specified as a symbol, or the hard-wired version enabled with an assembly conditional. Changes for V07.56: o The /INDIVIDUAL switch was added to the LIST command. This allows the listing of a single symbol definition or, through the use of wildcards, a given subset of the currently defined symbols. o LIST SUMMARY was added which displays the number of sym- bols currently defined and the number of entries avail- able for additional definitions. Changes for the latest version (V07.57): o Informational messages were added to verify the action of the [NO]CHAIN and [NO]PATH commands. o A warning message was added to handle the situation where a CHAIN command is issued with no argument, and no program name has previously been established. o The output format for LIST CHAIN and LIST PATH was modi- fied slightly. o A bug was fixed in RECALL/JOURNAL that allowed a blank input line to trigger an attempt to run a program with a null file name if the PATH command was active. UCL+ -- User Command Linkage Program - V07.57 Page 56 Spring 1988 DECUS Release 15.0 APPLICATION NOTES This section contains an assortment of hints, restrictions, cus- tomization patches, and notes for the current version of UCL+. 15.1 Executing Command/Control Files "By-Name" UCL+ can be used to execute indirect command files and IND con- trol files "by-name". In fact, if you set things up properly, you can ensure that they are executed in the proper context re- gardless of whether SET KMON IND is in effect or not. The fol- lowing 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 _________________ 15.2 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 dis- able 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: .CQWENC==_D/P/NOF "<033>^ You can then define specific printer-control commands by using 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> UCL+ -- User Command Linkage Program - V07.57 Page 57 Spring 1988 DECUS Release 15.3 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: o Using SIPP, change the embedded version number at loca- tion 21620 in the old ".UCL" file from 6 to 7. o RUN a V7.xx copy of UCL+ and RECALL the patched sym- bol/status file. o Issue a PROMPT command to restore the "UCL>" prompt. o Issue a STORE command to write a new ".UCL" file. o If you need the CD or RNO commands, you can implement them by using the techniques described in section 15.12. 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. Also note the use of the /A switch. .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 ________ * ________ .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. UCL+ -- User Command Linkage Program - V07.57 Page 58 Spring 1988 DECUS Release WARNING!!! The above patch will not work for the XM version of UCL+. You must apply the method described in the fol- lowing application note if you intend to run the XM version. 15.4 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: o 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. o Run the "vanilla" UCL+ and issue a STORE/JOURNAL command to produce a ".UCJ" file. o Run the XM version of UCL+ and issue a RECALL/JOURNAL to load the symbol/status data written out in the previous step. o If you need the CD or RNO commands, you can implement them by using the techniques described in section 15.12. 15.5 Disabling Argument Parsing There may be instances where you do not wish the sequence "^n" to ___ insert an argument sub-string. This is most likely to occur if you are converting an earlier version of UCL+ to a V07.50 or later version and have a symbol definition that is supposed to concatenate the argument string with a number. The solution is to use the "|" operator to quote the "n". The easiest way to il- lustrate this is with an example. Suppose we define a symbol named EXAMPL in the following fashion (RT-11 V5.2 syntax): exampl==_d "^2" If you type exampl I am R2D UCL+ -- User Command Linkage Program - V07.57 Page 59 Spring 1988 DECUS Release UCL+ will display only the word am because it takes the characters "^2" to mean "insert the second argument sub-string here." However, if you define EXAMPL as exampl==_d "^|2" and type exampl I am R2D UCL+ will then correctly display I am R2D2 Because you have "quoted" the "2", UCL+ interprets the definition as "insert the entire argument string ahead of the '2'." 15.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 interpretation. In any of these in- stances, 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 command line in unaltered form. This occa- sions a couple of "gotchas" that you have to watch out for. 15.6.1 Interception Of Monitor Commands - Some valid KMON com- mands may be trapped prematurely by UCL+. This situation occurs when there is a conflict between a monitor command or normal com- mand abbreviation and a symbol name. For example, the HELP com- mand under TSX-Plus would normally be invoked as "H", "HE", "HEL", or "HELP". If you wish to avoid a conflict with, say, a symbol named "HELLO", then it would be necessary to define the following symbols: H==HELP HE==HELP HEL==HELP conversely, the above situation allows you to override monitor commands with your own. E.g., DELETE==_d "The DELETE command is not allowed!" UCL+ -- User Command Linkage Program - V07.57 Page 60 Spring 1988 DECUS Release 15.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 expansions. As an illustration, suppose your run-by-name path is "DK:" and DK: is currently assigned to SY:. The command "DUMP/TERM RUB- ISH.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 expand 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+ to, in ef- fect, pass your command line to the monitor in an unaltered form. For the preceeding example, define DUMP==DUMP 15.6.3 Single Key Commands - 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 de- fine some handy single-key symbols that the monitor would strongly disapprove of under normal circumstances. For example: \==edit ??????==help One user that I know of (Ray Moran) places his VT100 in alternate keypad mode (with a UCL+ command, of course!) and executes sym- bols whose names correspond to the escape sequences generated by the individual keys. If you are using a VT220, or anything with an LK201 style key- board. You have even more keys that you can define! 15.7 UCL+ Assembly Conditionals You can build a somewhat customized version of UCL+ by modifying the conditionals file, UCL.CND, prior to assembly. UCL+ -- User Command Linkage Program - V07.57 Page 61 Spring 1988 DECUS Release 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. Default strings are delineated by square brackets ("[]"). If you wish to use some other set of characters, change the values for DFPFX and DFSFX to modify, respectively, the prefix and suffix character. A hard-wired RNO command can be enabled by defining the condi- tional RNO$C: RNO$C = 1 Edit this line into the beginning of file UCL.CND. RNO is a DCL-style command for use with DECUS RUNOFF M02.4. The documen- tation for RNO can be found in the source file UCLHWC.MAC. Including the RNO command increases the size of UCL+ by 430 decimal words. Use the command file UCL.COM to build UCL+. Use UCLXM.COM to build the XM version. 15.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 locations 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 V5.2, there will not be any ..UCFD/..UCFF values. UCL+ -- User Command Linkage Program - V07.57 Page 62 Spring 1988 DECUS Release If you are a somewhat disorderly person (perhaps you are undergo- ing 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 following exam- ple, 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 system, 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. .SIPP RT11XM.SYS/A _________________ Base? _____ Offset? ..UCLF ______ Base Offset Old New? 000000 ..UCLF 101704 ;R __ 000000 ..UCLF _____ 000000 ..UCLF+2 < > ;RXM ____ 000000 ..UCLF+4 ________ There is no such thing as a free lunch. Be aware of the follow- ing "patch catches": o If you install either of the above patches, you should use the UCL+ LIST command to obtain a list of the cur- rent symbol definitions even if you are using a version of RT-11 that supports the command "SHOW COMMANDS." The reason for this is that RT-11 responds to "SHOW COM- MANDS" by attempting to run SY:UCL.SAV, even though you have changed the name of the "UCL" that it uses for all other purposes. This problem exists in RT-11 versions as recent as V5.4 -- presumably, it will be fixed sooner or later. UCL+ -- User Command Linkage Program - V07.57 Page 63 Spring 1988 DECUS Release o If you change the RT-11 UCL device name, remember that symbol definitions, and such like, will be installed in the copy of UCL+ on the device that you specified. If that device is VM:, and you have defined some symbols that you don't want to lose, use the STORE command, or some other technique, to save the UCL+ context on a non-volatile device. 15.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 UCIs 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 something like UKMNAM: .RAD50 /SY UKMON SAV/ To change the defaults, edit the rad50 file names prior to assem- bling 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. 15.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 sequence. This can affect the way that you define a symbol that employs factoring as part of its definition. For example, suppose that you wish to define a symbol, "FTN", to invoke the FORTRAN compiler in a specialized fashion that com- piles one or more files resident on device "FTN:". If you are using TSX-Plus, you can define the symbol at the monitor level: .FTN==FORT FTN:(^) _________________ UCL+ -- User Command Linkage Program - V07.57 Page 64 Spring 1988 DECUS Release However, the example above will not work properly if you are run- ning RT-11. This is because RT-11 expands the factoring prior to passing the command line to UCL+. Thus, RT-11 would remove the "unnecessary" parentheses in the preceeding monitor level com- mand, and UCL+ would see the definition as "FTN==FORT FTN:^". The solution, in this case, is to run UCL+ directly: .R UCL _____ UCL> ftn==fort ftn:(^) _________________ UCL> ________ The tendency of RT-11 to pass "rare" rather than "raw" commands to UCL+ can cause more subtle problems also. Suppose, for example, that you wanted to define a command to send a line of ReGIS graphics instructions to a VT241 to change the screen colors. You must preceed the graphics output with the text "Pp" and follow it with "\" ("" indicates the escape character). At first glance, it would seem that the fol- lowing symbol definition sequence would do the trick (note the use of the quote operator to display the "\"). .R UCL UCL> regis==disp "<033>Pp"\disp ^\disp "<033>|\" UCL> color==_regis S(M0(AH0L50S100)1( etc... UCL> Unfortunately, since RT-11 is allowed to "touch" the color speci- fication string in the above example, it will strip out most of the parentheses, and the COLOR command will not work. One solu- tion is to define the REGIS symbol in such a way that it will run UCL+ directly (the EXIT symbol is necessary to force a return to the monitor). .R UCL UCL> regis==r ucl\d "<033>Pp"\d "^"\d "<033>|\"\exit UCL> exit==\ UCL> color==_regis S(M0(AH0L50S100)1( etc... UCL> UCL+ -- User Command Linkage Program - V07.57 Page 65 Spring 1988 DECUS Release 15.11 Patching UCL+ For RT-11 V5.1 When you run the UCL+ program, it executes a "context check" to determine which environment it is running in. Unfortunately, there is a bug in RT-11 V5.1 which sets some extraneous bits in the monitor version code. This causes the non-XM version of UCL+ to behave incorrectly when running under V5.1. If you are using UCL+ with RT-11 V5.1, apply the following patch to the file UCL.SAV to force UCL+ to assume that it is running under V5.1. Look at the link map on the UCL+ distribution (UCL.MAP) and find the value of the label "FUDGE" (when this document was prepared, the value for "FUDGE" was 026214, but you should check the link map just to make sure). Use SIPP to disable the release/version check in the context routine ("" denotes a carriage return, "" is a control-Y, operator input is underlined): .SIPP UCL.SAV/A ______________ Base? _____ Offset? FUDGE _____ Base Offset Old New? 000000 FUDGE 002002 240 ___ 000000 FUDGE+2 005067 ________ Note that it is not necessary to apply this type of patch to the XM version of UCL+ (UCLXM.SAV) because it will not run under ver- sions of RT-11 prior to V5.2. UCL+ -- User Command Linkage Program - V07.57 Page 66 Spring 1988 DECUS Release 15.12 Implementing The CD And RNO Commands The CD and RNO hard-wired commands were dropped from UCL+ begin- ning with V07.55. CD was eliminated because the inclusion of support for default strings in UCL+ made it possible to define CD as a symbol. RNO is no longer included because almost everyone was using it at a base-line level only and, thus, an RNO symbol definition would serve just as well in most cases. If you need the CD command, you can define it as a symbol in the following fashion: CD==ASSIGN ^[SY] DK A base-line RNO symbol can be defined as: RNO==R RUNOFF\^2[LP:]=^1\<003> There are, of course, several variants on the RNO symbol. For example, if you always emulate form-feeds with line-feeds, you can force the /F option into the output specification: RNO==R RUNOFF\^2[LP:]/F=^1\<003> Both the CD and RNO symbols are discussed in more detail in the discussion on "Advanced Techniques", section 8.5.3. There is also a journal file on the UCL+ distribution kit named UCLINI.UCJ that contains symbol definitions for CD and RNO. If you wish, you can define these symbols by simply RECALLing the journal file. E.g., RECALL/JOURNAL UCLINI If you need the full-fledged, hard-wired RNO command, it can be enabled by modifying the UCL+ conditionals file (UCL.CND) and re- building UCL+. The "UCL+ Assembly Conditionals" application note (section 15.7) explains how to do this. UCL+ -- User Command Linkage Program - V07.57 Page 67 Spring 1988 DECUS Release 15.13 Avoiding Conflicts With The SL RECALL Command Beginning with RT-11 V5.4C, the extended memory version of the Single-Line (SL) Editor implements a RECALL command as a SET op- tion. Since this command is processed by SL, it will always take precedence over the UCL+ RECALL command. This problem will occur in any situation where SL is enabled to process keyboard input, even when UCL+ is run directly. One solution is to define a symbol that simply expands as a UCL+ RECALL command in execute-immediate mode. For example: RCALL==_RECALL Another approach takes advantage of a peculiarity of the RT-11 Keyboard Monitor (KMON). If you type $RECALL at the monitor prompt, SL will ignore the command and pass it on to KMON. KMON will, in turn, strip off the leading "$" and pass it on to UCL+. If you decide to use this technique, it's also a good idea to de- fine a $RECALL symbol so that everything will work consistently if you run UCL+ directly. Note that you must run UCL+ directly to define this symbol: .R UCL UCL> $recal==_recall UCL> ^C Finally, you can always patch SLX.SYS to change the name of the SL RECALL command to something else. The specifics are left as an exercise to the reader. In brief, you must find out where the string "RECALL" is stored in the handler (it will be in ASCIZ format) and change it. If you want to change the SET command also, you will need to look in block 0 of SLX.SYS for two words of RAD50 data that translate to "RECALL." UCL+ -- User Command Linkage Program - V07.57 Page 68 Spring 1988 DECUS Release 16.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 by telephone or paper mail at: William K. Walker RDB/Alpha Systems P. 0. Box 149 Alpha, OH 45301 (513) 426-7094/0344 or William K. Walker Monsanto Research Corp. P. O. Box 32 A-152 Miamisburg, OH 45342 (513) 865-3557 If you are on Compuserve, my ID is 71066,24. Leave a message on EasyPlex, or in the PDP-11 forum area. If you have access to Western Union EasyLink, my mailbox number is 62752448 (or Telex 62752448 ESL UD). On MCI Mail, my user name is RDBALPHA; the user ID is 333-1675 (or Telex 6503331675 MCI UW). If you discover a genuine bug in the current version of UCL+, and you are the first to report it, you get a post-paid copy of the next release -- you can even keep the floppy. UCL+ -- User Command Linkage Program - V07.57 Page 69 Spring 1988 DECUS Release 17.0 WISH LIST Aside from the usual fiddling about with the internals, I cur- rently plan to make the following additions/changes to future versions of UCL+: o a revision to the STORE and RECALL commands that will eliminate the incompatibility between .UCL and .UCX files, o a reasonable way to change the number of characters al- located for symbol names and symbol definitions, o a method to change the total number of symbol defini- tions allowed in UCL+, and o provision for the "nesting" of default string specifica- tions. I do NOT intend to implement a "symbol definition editor." Use STORE/JOURNAL or LIST/INDIVIDUAL/OUT 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. UCL+ -- User Command Linkage Program - V07.57 Page 70 Spring 1988 DECUS Release 18.0 UCL+ COMMAND AND SYNTAX SUMMARY SYMBOL DEFINITION SYNTAX ________________________ name==definition where "name" is a six-character symbol name "definition" specifies the symbol expansion OPERATORS _________ == symbol definition \ line separation/termination ^n[text] argument insertion if "n" used, insert nth part if "[text]" used, "text" is default string _ "execute-immediate" flag insert character whose octal code is "nnn" | quote flag; treat next character as text only "HARD-WIRED" COMMANDS _____________________ CHAIN Sets up UCL+ exit chaining DISPLAY Displays a string or UCL+ command/symbol expansion ERASE Deletes one or more UCL+ symbols LIST Lists the current UCL+ commands/symbols/status NOSL Turns the single-line editor off PASS_ON Passes a command string to a program "UCL-style" PATH Sets up the UCL+ "run-by-name" path PROMPT Sets the UCL+ command-line prompt string RECALL Loads symbol definition and status tables RELOAD Reloads a UCL+ global region (XM version only) SLON Turns the single-line editor on STORE Saves the UCL+ symbol definition and status tables UCI_MODE Set UCL+ "pass-line-to-KMON" mode (TSX-Plus only)