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 V08.02a 04 Apr 1991 For RT-11 V5.0 - V5.6 TSX-Plus V4.1 - V6.5 and RTEM William K. Walker RDB/Alpha Systems P. O. Box 149 Alpha, OH 45301-0149 (513) 426-0344/7094 rdbalpha@mcimail.com SPECIAL NOTE TO SCIENTISTS/RESEARCHERS Read the manual! Page ii TABLE OF CONTENTS 1.0 ACKNOWLEDGEMENTS . . . . . . . . . . . . . . . . . . . . . . 1 2.0 IMPORTANT NOTICES . . . . . . . . . . . . . . . . . . . . . 2 3.0 BEFORE YOU GET STARTED . . . . . . . . . . . . . . . . . . . 3 4.0 ABOUT THIS DOCUMENT . . . . . . . . . . . . . . . . . . . . 4 5.0 INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . 5 5.1 UCL+ Differences . . . . . . . . . . . . . . . . . . . . . . 5 5.2 UCL+ Enhancements . . . . . . . . . . . . . . . . . . . . . 6 6.0 INSTALLATION . . . . . . . . . . . . . . . . . . . . . . . . 8 6.1 Installing UCL.SAV . . . . . . . . . . . . . . . . . . . . 10 6.1.1 Installing UCL.SAV On RT-11 Systems . . . . . . . . . . 10 6.1.1.1 Installation As A UCL (UCL.SAV => UCL.SAV) . . . . . . 10 6.1.1.2 Installation As A UCF (UCL.SAV => UCF.SAV) . . . . . . 11 6.1.2 Installing UCL.SAV On TSX-Plus Systems . . . . . . . . . 11 6.1.2.1 Installation As A UCL (UCL.SAV => TSXUCL.SAV) . . . . 12 6.1.2.2 Installation As A UCI (UCL.SAV => UKMON.SAV) . . . . . 12 6.2 Installing UCLXM.SAV . . . . . . . . . . . . . . . . . . . 13 6.2.1 Installing UCLXM.SAV On RT-11 Systems . . . . . . . . . 13 6.2.1.1 Installation As A UCL (UCLXM.SAV => UCL.SAV) . . . . . 14 6.2.1.2 Installation As A UCF (UCLXM.SAV => UCF.SAV) . . . . . 14 6.2.2 Installing UCLXM.SAV On TSX-Plus Systems . . . . . . . . 15 6.2.2.1 Installation As A UCL (UCLXM.SAV => TSXUCL.SAV) . . . 16 6.2.2.2 Installation As A UCI (UCLXM.SAV => UKMON.SAV) . . . . 17 6.3 Installing UCLXD.SAV . . . . . . . . . . . . . . . . . . . 18 6.3.1 Installing UCLXD.SAV On RT-11 Systems . . . . . . . . . 18 6.3.1.1 Installation As A UCL (UCLXD.SAV => UCL.SAV) . . . . . 18 6.3.1.2 Installation As A UCF (UCLXD.SAV => UCF.SAV) . . . . . 19 6.3.2 Installing UCLXD.SAV On TSX-Plus Systems . . . . . . . . 20 6.3.2.1 Installation As A UCL (UCLXD.SAV => TSXUCL.SAV) . . . 21 6.3.2.2 Installation As A UCI (UCLXD.SAV => UKMON.SAV) . . . . 22 6.4 Installing The CI Handler . . . . . . . . . . . . . . . . 24 6.5 Installing UCL+ HELP . . . . . . . . . . . . . . . . . . . 25 6.6 Installing The UCL+ Distribution Under RTEM . . . . . . . 26 7.0 HOW IT WORKS . . . . . . . . . . . . . . . . . . . . . . . 27 7.1 RT-11 Command Processing With UCL Support . . . . . . . . 27 7.2 RT-11 Command Processing With UCF Support . . . . . . . . 28 7.3 TSX-Plus Command Processing . . . . . . . . . . . . . . . 28 8.0 SYMBOLS . . . . . . . . . . . . . . . . . . . . . . . . . 30 8.1 Defining Symbols . . . . . . . . . . . . . . . . . . . . . 30 8.2 Deleting Symbols . . . . . . . . . . . . . . . . . . . . . 32 8.3 Entering Special Characters . . . . . . . . . . . . . . . 32 8.4 Running UCL+ Directly . . . . . . . . . . . . . . . . . . 33 Page iii 8.5 Advanced Techniques . . . . . . . . . . . . . . . . . . . 34 8.5.1 Using The Quote Character ("|") . . . . . . . . . . . . 34 8.5.2 Argument String Parsing ("^n") . . . . . . . . . . . . . 35 8.5.3 Specifying Default Strings . . . . . . . . . . . . . . . 36 9.0 "HARD-WIRED" COMMANDS . . . . . . . . . . . . . . . . . . 39 9.1 CHAIN Command . . . . . . . . . . . . . . . . . . . . . . 40 9.2 DISPLAY Command . . . . . . . . . . . . . . . . . . . . . 41 9.3 ERASE Command . . . . . . . . . . . . . . . . . . . . . . 43 9.4 LIST Command . . . . . . . . . . . . . . . . . . . . . . . 44 9.5 PASS_ON Command . . . . . . . . . . . . . . . . . . . . . 46 9.6 PATH Command . . . . . . . . . . . . . . . . . . . . . . . 47 9.7 PROMPT Command . . . . . . . . . . . . . . . . . . . . . . 48 9.8 RECALL Command . . . . . . . . . . . . . . . . . . . . . . 49 9.9 RELOAD command . . . . . . . . . . . . . . . . . . . . . . 50 9.10 STORE Command . . . . . . . . . . . . . . . . . . . . . . 51 9.11 UCI_MODE Command . . . . . . . . . . . . . . . . . . . . 52 10.0 CI HANDLER . . . . . . . . . . . . . . . . . . . . . . . 53 11.0 INFORMATIONAL MESSAGES . . . . . . . . . . . . . . . . . 55 12.0 ERROR MESSAGES . . . . . . . . . . . . . . . . . . . . . 57 12.1 UCL+ "Warning" Messages (?UCL-W-...) . . . . . . . . . . 58 12.2 UCL+ Error Messages (?UCL-E-...) . . . . . . . . . . . . 59 12.3 UCL+ "Fatal" Messages (?UCL-F-...) . . . . . . . . . . . 62 12.4 Global Region Loader Errors (?UCLGRL-F-...) . . . . . . . 64 12.5 CI Handler Errors (?CI-...) . . . . . . . . . . . . . . . 65 13.0 EXAMPLES . . . . . . . . . . . . . . . . . . . . . . . . 66 14.0 V7 AND V8 RELEASE NOTES . . . . . . . . . . . . . . . . . 67 15.0 APPLICATION NOTES . . . . . . . . . . . . . . . . . . . . 72 15.1 Executing Command/Control Files "By-Name" . . . . . . . . 72 15.2 Sending Escape Sequences To The Printer . . . . . . . . . 72 15.3 Moving From UCL+ V6x To UCL+ V8.xx . . . . . . . . . . . 73 15.4 Disabling Argument Parsing . . . . . . . . . . . . . . . 74 15.5 Hints and Kinks: UCF, UCI, And SET UCL FIRST . . . . . . 75 15.5.1 Interception Of Monitor Commands . . . . . . . . . . . 75 15.5.2 Improper Expansion Of Monitor Commands . . . . . . . . 75 15.5.3 Single Key Commands . . . . . . . . . . . . . . . . . . 76 15.6 UCL+ Assembly Conditionals . . . . . . . . . . . . . . . 77 15.7 Changing The RT-11 UCL/UCF Device/File Name . . . . . . . 78 15.8 Changing The TSX-Plus UCL/UCI Defaults . . . . . . . . . 80 15.9 Controlling Command Line Factoring . . . . . . . . . . . 81 15.10 Patching UCL+ For RT-11 V5.1 . . . . . . . . . . . . . . 82 15.11 Implementing The CD And RNO Commands . . . . . . . . . . 83 15.12 Avoiding Conflicts With The SL RECALL Command . . . . . 84 15.13 Avoiding Conflicts With The TSX-Plus PROMPT Command . . 85 15.14 Controlling External Data (XD) File Initialization . . . 86 15.15 Enabling/Disabling UCL+ External Data (XD) Support . . . 88 Page iv 15.16 Changing The External Data (XD) Device/File Name . . . . 89 15.17 Implementing Both Global And Local Symbols Under TSX-Plus . . . . . . . . . . . . . . . . . . . . . . . . 90 15.18 Eliminating the TSX-Plus UCL Data File (TSXUCL.TSX) . . 91 16.0 REPORTING PROBLEMS AND SUGGESTIONS . . . . . . . . . . . 92 17.0 WISH LIST . . . . . . . . . . . . . . . . . . . . . . . . 93 18.0 UCL+ COMMAND AND SYNTAX SUMMARY . . . . . . . . . . . . . 94 19.0 UCL+ CUSTOMIZATION PATCH SUMMARY . . . . . . . . . . . . 95 20.0 INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . 96 UCL+ -- User Command Linkage Program - V08.02a Page 1 Acknowledgements 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. This ended what was, at the time, 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. The elimination of the dis- tinction between XM and non-XM "STORE" files was implemented for basically the same reason. The informational messages (?UCL-I-etc.) were added to keep Rally from shooting himself in the foot. Greg Adams provided the final increment of irritation that led to the implementation of the "external data" version of UCL+. Tim Clarke submitted some minor spelling and grammatical correc- tions in gentle revenge for my note on the cover page. He also came up with the sneaky TSX-Plus patch described in section 15.18. Rally Barnard gets the bug-of-the-year award for discovering an error that has been lurking in the weeds for four years. The field testing for this version was performed by Billy Youdel- man and myself (of course). UCL+ -- User Command Linkage Program - V08.02a Page 2 Important Notices 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.10 FOR UCL+ TO WORK PROPERLY (IT'S NOT MY FAULT -- IT'S DEC'S FAULT). RT-11 V5.4C/TSX-PLUS V6.3 OR LATER USERS ________________________________________ SOME VERSIONS OF THE SINGLE-LINE EDITOR IMPLEMENT A "RECALL" COMMAND AS A SET OPTION. IF THIS FUNCTIONALITY IS ENABLED, IT PREEMPTS THE UCL+ RECALL COMMAND. SEE THE APPLICATION NOTES, SECTION 15.12, 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.11, FOR DETAILS. THE STANDARD, HARD-WIRED "RNO" COMMAND IS ALSO AVAILABLE AS A CONDITIONAL ASSEMBLY (SEE SECTION 15.6). V07.57 OR EARLIER UCL+ USERS ____________________________ THE "NOSL" AND "SLON" COMMANDS HAVE BEEN ELIMINATED. AN ESCAPE CHARACTER CAN NOW BE ENTERED AS ITS OCTAL OR DECIMAL CODE ("<33>" OR "<27.>"). UCL+ -- User Command Linkage Program - V08.02a Page 3 Before You Get Started 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. UCL+ -- User Command Linkage Program - V08.02a Page 4 About This Document 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. When an underscore character ("_") must be used as part of the example text, operator input is not 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., - = 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>","<27.>", etc.) 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 - V08.02a Page 5 Introduction 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 Interface (TSX-Plus, V5.0 or later) 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 UCL+ does not "forget" symbol definitions after a user logs off. In addition, if you do not choose to use the "external data" version of UCL+, all commands and symbols will be "global", rather than local to a specific user. UCL+ -- User Command Linkage Program - V08.02a Page 6 Introduction 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 (an "external data" variant is op- tionally available), 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 in a sym- bol definition, including eight-bit and control characters. o You may, in addition to the symbol definitions, list other program parameters as well. List output may be directed to devices/files other than the console. o UCL+ can be employed, via the UCI_MODE command, as a "User Command Interface" (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 - V08.02a Page 7 Introduction 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 extended memory monitors. Almost the entire program is con- tinuously 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 - V08.02a Page 8 Installation 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 extended memory (XM) version of UCL+ (section 6.2) o UCLXD.SAV - the "external data" (XD) variant of the "vanilla" UCL+ program (section 6.3) o CI.SYS - the Command Line Interpreter handler (section 6.4) o UCLHLP.TXT - the help text necessary to build a UCL+ help program (section 6.5) The following is a list of who runs with what. The program names in upper case denote the "recommended" version of UCL+ for that particular environment. The XM version is recommended when it offers performance advantages. The XD version is flagged in those situations where maintenance of "user-specific" context data may be an issue. o RT-11 V5.0, V5.1, all monitors: UCL, uclxd o RT-11 V5.2 - V5.5, SJ and FB: UCL, uclxd o RT-11 V5.2 - V5.5, XM: ucl, uclxd, UCLXM o RT-11 V5.6 or later, SB and FB: UCL, uclxd o RT-11 V5.6 or later, except SB, FB: ucl, uclxd, UCLXM o TSX-Plus, V4.1: UCL, uclxd o TSX-Plus, V5.x: ucl, UCLXD o TSX-Plus, V6.0 or later: ucl, UCLXD, uclxm o RTEM, any version with UCL support: ucl, UCLXD 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 UCL+ -- User Command Linkage Program - V08.02a Page 9 Installation 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 alternate between two different RT-11 monitors on the same machine). See the application notes, sections 15.7 and 15.8, 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.4. 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.11, for details. The standard, hard-wired "RNO" command is also available as a conditional assembly (see section 15.6). UCL+ -- User Command Linkage Program - V08.02a Page 10 Installation 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). WARNING If you are using the Single-Line Editor (SL) and the SL "RECALL" command is enabled, issue the command SET SL NORECALL prior to installing UCL+. You can reenable the SL RECALL feature after UCL+ is installed. See section 15.12 for more details. 6.1.1.1 Installation As A UCL (UCL.SAV => UCL.SAV) - If you are already using a previous version of UCL+, you should first save your current symbol/status data. For example, .STORE SY:CURENT _______________ (Type "STORE SY:CURENT.UCL" if your old UCL+ is a V7.xx XM ver- sion.) 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 not. If it is V6x, follow the procedure described in the application notes (section 15.3). If it is V7.xx or later, you can just type .RECALL SY:CURENT ________________ to load the symbol/status data into your new copy of UCL+. UCL+ -- User Command Linkage Program - V08.02a Page 11 Installation Note that the above procedure is the same for TSX-Plus V4.1 users. 6.1.1.2 Installation As A UCF (UCL.SAV => 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> " ______________ ?UCL-I-Prompt changed to "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 WARNING If you are using the Single-Line Editor (SL) and the SL "RECALL" command is enabled, issue the command SET SL NORECALL prior to installing UCL+. You can reenable the SL RECALL feature after UCL+ is installed. See section 15.12 for more details. UCL+ -- User Command Linkage Program - V08.02a Page 12 Installation 6.1.2.1 Installation As A UCL (UCL.SAV => TSXUCL.SAV) - If you are already using a previous version of UCL+, you should first save your current symbol/status data. For example, .STORE SY:CURENT _______________ (Type "STORE SY:CURENT.UCL" if your old UCL+ is a V7.xx XM ver- sion.) To install UCL.SAV, just copy it to the system device. Note that the default TSX-Plus name for UCL is TSXUCL.SAV. .COPY UCL.SAV SY:TSXUCL.SAV __________________________ If you are not a previous UCL+ user, you're done, and you can proceed to define the symbols that you intend to use. Otherwise, the next step depends on whether your old UCL+ is V6x or not. If it is V6x, follow the procedures described in the application notes (section 15.3). If it is V7.xx or later, you can just type .RECALL SY:CURENT ________________ to load the symbol/status data into your new copy of UCL+. 6.1.2.2 Installation As A UCI (UCL.SAV => UKMON.SAV) - UCL+ can also be used on a TSX-Plus V5.0 or later system as a User Command Interface (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> " _____________ ?UCL-I-UCI_MODE enabled ?UCL-I-Prompt changed to "ukmon> " ukmon> ________ You would invoke UKMON.SAV as a UCI by typing .SET KMON UCI ____________ UCL+ -- User Command Linkage Program - V08.02a Page 13 Installation 6.2 Installing UCLXM.SAV UCLXM.SAV is a special version of UCL+ for use with extended memory (XM) monitors 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 10kb under a V6.4 monitor). This is due to the fact that the bulk of the program (20.5kb) resides in a shared global region. If multiple copies of UCL+ are running 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 a V6 version of UCL+. All examples in this section are for an RT-11 V5.2 monitor. WARNING If you are using the Single-Line Editor (SL) and the SL "RECALL" command is enabled, issue the command SET SL NORECALL prior to installing UCL+. You can reenable UCL+ -- User Command Linkage Program - V08.02a Page 14 Installation the SL RECALL feature after UCL+ is installed. See section 15.12 for more details. 6.2.1.1 Installation As A UCL (UCLXM.SAV => UCL.SAV) - If you are already using a previous version of UCL+, you should first save your current symbol/status data. For example, .store sy:curent _______________ (Type "store sy:curent.ucl" if your old UCL+ is a V7.xx XM ver- sion.) 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+ was V6x or V7.xx. If it was V6x, see the application note in section 15.3. If it is V7.xx or later, just type .recall sy:curent ________________ to load the symbol/status data into your new copy of UCL+. (Note: If the extension of the file you are RECALLing is not .UCL, you will need to enter the extension explicitly.) Finally, it is a good idea to run UCL and change the command prompt. .r ucl _____ UCL> prompt "uclxm> " ________________ ?UCL-I-Prompt changed to "uclxm> " uclxm> ________ 6.2.1.2 Installation As A UCF (UCLXM.SAV => 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 UCL+ -- User Command Linkage Program - V08.02a Page 15 Installation global region in extended 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> " ________________ ?UCL-I-Prompt changed to "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. 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.4 monitor, the command is as follows UCL+ -- User Command Linkage Program - V08.02a Page 16 Installation 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. WARNING If you are using the Single-Line Editor (SL) and the SL "RECALL" command is enabled, issue the command SET SL NORECALL prior to installing UCL+. You can reenable the SL RECALL feature after UCL+ is installed. See section 15.12 for more details. 6.2.2.1 Installation As A UCL (UCLXM.SAV => TSXUCL.SAV) - If you are already using a previous version of UCL+, you should first save your current symbol/status data. For example, .store sy:curent _______________ (Type "store sy:curent.ucl" if your old UCL+ is a V7.xx XM ver- sion.) If your previous version of UCL+ was also the XM version, you should REMOVE the global region. E.g., .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+ was V6x or V7.xx. If it was V6x, see the application note in section 15.3. If it is V7.xx or later, just type .recall sy:curent ________________ UCL+ -- User Command Linkage Program - V08.02a Page 17 Installation 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> " _________________ ?UCL-I-Prompt changed to "tsxucl> " tsxucl> ________ 6.2.2.2 Installation As A UCI (UCLXM.SAV => UKMON.SAV) - Under TSX-Plus, UCL+ can also be used as a User Command Interface (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> " _____________ ?UCL-I-UCI_MODE enabled ?UCL-I-Prompt changed to "ukmon> " ukmon> ________ You would invoke UKMON.SAV as a UCI by typing .set kmon uci ____________ UCL+ -- User Command Linkage Program - V08.02a Page 18 Installation 6.3 Installing UCLXD.SAV UCLXD.SAV is the "external data" (XD) variant of the "vanilla" UCL+ program, UCL.SAV. The two programs differ in the way that they maintain their context areas. When you do something that changes the UCL+ context (define a symbol, issue a PATH command, etc.), UCL.SAV "memorizes" this action by posting the change to its own disk image. Thus, UCL.SAV updates its context area "in- ternally." In contrast, UCLXD.SAV keeps its context area in a separate disk file named UCLPLS.DAT; it updates context "exter- nally." UCLXD.SAV will run under versions of RT-11 beginning with V5.0 (and the equivalent RTEM releases) and versions of TSX-Plus starting with V4.1. Since 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. However, the in- stallation procedure may differ in some cases. UCLXD.SAV is the recommended UCL+ program for TSX-Plus V5.x or later, and RTEM. 6.3.1 Installing UCLXD.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). WARNING If you are using the Single-Line Editor (SL) and the SL "RECALL" command is enabled, issue the command SET SL NORECALL prior to installing UCL+. You can reenable the SL RECALL feature after UCL+ is installed. See section 15.12 for more details. 6.3.1.1 Installation As A UCL (UCLXD.SAV => UCL.SAV) - If you are already using a previous version of UCL+, you should first save your current symbol/status data. For example, .STORE SY:CURENT _______________ (Type "STORE SY:CURENT.UCL" if your old UCL+ is a V7.xx XM ver- sion.) To install UCLXD.SAV, just copy it to the system device: UCL+ -- User Command Linkage Program - V08.02a Page 19 Installation .COPY UCLXD.SAV SY:UCL.SAV _________________________ Next, you should set up the UCL+ data device. I.e., .ASSIGN xd-device UCL: _____________________ where "xd-device" is the device where UCL+ external data file will be kept. It's a good idea to place this command in your start up command file. UCLXD.SAV maintains its symbol/status data in an external data file named UCLPLS.DAT. UCLXD.SAV looks for this file on device "UCL:." If the file is not found, it looks on SY:. If UCLPLS.DAT already exists, you're done. If not, you can create it at this point by running the UCL+ program: .R UCL _____ ?UCL-I-Data file not found; creating new one UCL> ________ If you have assigned UCL:, the data file will be created on that device. Otherwise, it will be created on the system device, SY:. If you are converting to the XD variant of UCL+ from a previous, non-XD, version, you will need to load the symbol/status data into your new copy of UCL+. If your old UCL+ is V6x, follow the procedures described in section 15.3. If it is V7.xx or later, simply 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. 6.3.1.2 Installation As A UCF (UCLXD.SAV => UCF.SAV) Beginning with V5.2, RT-11 supports User Commands First (UCF) as well as UCL. If you wish to use UCLXD.SAV as a UCF, the follow- ing is a reasonable installation procedure. (Note: If you desire to preserve the symbol/status data from an existing UCF program, use the techniques described in the previous section, 6.3.1.1. Also note that the command sequences are for RT-11 V5.2.) Copy UCLXD.SAV to the system device as file UCF.SAV. .copy uclxd.sav sy:ucf.sav _________________________ UCL+ -- User Command Linkage Program - V08.02a Page 20 Installation At this point, it is strongly recommended that you patch UCF.SAV ________ to change the name of the external data file used by this pro- gram. "UCFPLS.DAT" is a good choice. You may also wish to change the default external data device mnemonic from "UCL" to "UCF." The procedure for making these modifications is described in the application notes, section 15.16. Once UCF.SAV has been patched, assign its data device. E.g., assign xd-device ucf: where "xd-device" is the name of the device that will contain the UCF external data file. If the external data file already exists, you're done. If not, you can create it at this point by running the program directly. While you're at it, it's also a good idea to change the program's prompt. .r ucf _____ ?UCL-I-Data file not found; creating new one UCL> prompt "ucf> " ______________ ?UCL-I-Prompt changed to "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.3.2 Installing UCLXD.SAV On TSX-Plus Systems - If you are running TSX-Plus V4.1, installation is the same as it is for RT-11 (section 6.3.1). If you are running V5.0 or later, the procedure is somewhat different. You should make sure that UCL support is enabled when you execute your initial TSGEN. Also, TSX-Plus users must have read/write access to the UCL+ ex- ternal data (XD) file if they are to be able to define or erase symbols. The easiest way to accomplish this is to include the appropriate commands in the user's logon command file. The de- tails will depend on your system layout. If each user is assigned a private work area at logon time (usually a logical device), this can be designated as the UCL+ XD device also. For example, UCL+ -- User Command Linkage Program - V08.02a Page 21 Installation MOUNT LD0 DU1:FRED.DSK DK ASSIGN DK UCL This technique results in each user having their own private copy of the XD file UCLPLS.DAT and, thus, their own "local" set of symbol definitions. If you want all of your users to have read/write access to one central copy of UCLPLS.DAT, the command sequence might be some- thing like this: ACCESS SY:UCLPLS.DAT This approach gives "global" access to the UCL+ facilities; all users on the system have a common set of symbol definitions. WARNING If you are using the Single-Line Editor (SL) and the SL "RECALL" command is enabled, issue the command SET SL NORECALL prior to installing UCL+. You can reenable the SL RECALL feature after UCL+ is installed. See section 15.12 for more details. 6.3.2.1 Installation As A UCL (UCLXD.SAV => TSXUCL.SAV) - Under TSX-Plus, you may install the external data (XD) version of UCL+ either "locally" or "globally." Local installation causes each user to have their own set of symbol definitions; global instal- lation results in all users having access to a common set of sym- bols. (It is also possible to have both local and global sets -- see application note 15.17.) As discussed in the previous section (6.3.2), the XD version's behavior, once installed, depends on the assignment of the logical mnemonic "UCL." Aside from this consideration, the installation procedure is as follows: If you are already using a previous version of UCL+, you should first save your current symbol/status data. For example, .store sy:curent _______________ (Type "store sy:curent.ucl" if your old UCL+ is a V7.xx XM ver- sion.) Next, copy UCLXD.SAV to the system device. Note that the default TSX-Plus name for UCL is TSXUCL.SAV. .copy uclxd.sav sy:tsxucl.sav ____________________________ UCL+ -- User Command Linkage Program - V08.02a Page 22 Installation The XD version of UCL+ maintains its symbol/status data in an ex- ternal data file named UCLPLS.DAT. It looks for this file on device "UCL:." If the file is not found, it looks on SY:. For global installation under TSX-Plus, the mnemonic "UCL:" is not normally defined. If UCLPLS.DAT already exists, you're done. If not, this file will automatically be created the first time UCL+ is run. (A de- tailed discussion of XD file initialization can be found in the application notes, section 15.14.) In the following example, an XD file is created by running UCL+ directly. The prompt string is changed also. .r tsxucl ________ ?UCL-I-Data file not found; creating new one UCL> prompt "tsxucl> " _________________ ?UCL-I-Prompt changed to "tsxucl> " tsxucl> ________ If you have assigned UCL:, the data file will be created on that device. Otherwise, it will be created on the system device, SY:. If you are converting to the XD variant of UCL+ from a previous, non-XD version, you will need to load the symbol/status data into your new copy of UCL+. If your old UCL+ is V6x, follow the pro- cedures described in section 15.3. If it is V7.xx or later, sim- ply type .r tsxucl ________ tsxucl> recall sy:curent ________________ tsxucl> ________ 6.3.2.2 Installation As A UCI (UCLXD.SAV => UKMON.SAV) - UCL+ can be used on a TSX-Plus V5.0 or later system as a User Command Interface (UCI). It should be pointed out, however, that the XD version of UCL+ requires the most complicated UCI installation procedure. The non-XD version (section 6.1.2.2) is usually a better choice for the majority of applications. The XM version can also be used (section 6.2.2.2). The following example illustrates a typical UCI installation of UCLXD.SAV with the default name of UKMON.SAV. Note that the name of the external data file is changed to UKMON.DAT in order to avoid potential conflicts with the system UCL program. (At the time this document was prepared, the value that you should substitute for "XDFIL" was 036402 -- you can verify this by checking the UCL+ link map, UCL.MAP.) UCL+ -- User Command Linkage Program - V08.02a Page 23 Installation The device mnemonic for the XD file could also be changed from "UCL" to "SY." This would force the UCI program to obtain its symbol status data from a single, central file on the system device. (A more complete discussion of the procedure for chang- ing the XD file name and device can be found in section 15.16.) Note also that when UCI_MODE is enabled, the command prompt is changed as well. This helps to distinguish the "UCI" copy of UCL+ from other copies that might exist on the same system as "UCLs." .copy uclxd.sav sy:ukmon.sav ___________________________ .sipp ukmon.sav/a ________________ Base? _____ Offset? XDFIL _____ Base Offset Old New? 000000 XDFIL 101704 ;R __ 000000 XDFIL ;RUKM _____ 000000 XDFIL+2 ;RON ____ 000000 XDFIL+4 ________ .r ukmon _______ UCL> uci "ukmon> " _____________ ?UCL-I-UCI_MODE enabled ?UCL-I-Prompt changed to "ukmon> " ukmon> ________ You would invoke UKMON.SAV as a UCI by typing .set kmon uci ____________ UCL+ -- User Command Linkage Program - V08.02a Page 24 Installation 6.4 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-extended memory versions of the RT-11 monitor: .copy/sys ci.sys sy: ___________________ For extended memory monitors: .copy/sys ci.sys sy:cix.sys __________________________ See section 10.0 for more information in the CI handler. UCL+ -- User Command Linkage Program - V08.02a Page 25 Installation 6.5 Installing UCL+ HELP The UCL+ distribution includes a help-text file named UCLHLP.TXT. You can use this file to set up on-line help text for UCL+ 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:10 ____________________________ .LIB/MAC UCLHLP UCLHLP.TXT _________________________ .COP HELP.EXE+UCLHLP.MLB UCLHLP.SAV __________________________________ .COP UCLHLP.SAV SY: __________________ .HLP==R UCLHLP\^ _______________ NOTE If you are using a version of RT-11 prior to 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 7 instead of 10. This boundary may, of course, change again in later versions of RT-11. UCL+ -- User Command Linkage Program - V08.02a Page 26 Installation 6.6 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 Use the external data (XD) version of UCL+ (UCLXD.SAV). The system manager should place UCLXD in the "shared" portion of the virtual system device as file UCL.SAV. If, for some reason, the non-XD version of UCL+ is used (UCL.SAV), a copy of this program must be placed in each user's "private" area, and the distributed UCL program deleted from the shared area. Otherwise, the installa- tion procedure is essentially the same as for RT-11 sys- tems (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.4 contains further information on installing this handler. o The UCL+ help facility is normally installed in the shared area of the virtual system device. See section 6.5 for further information on installing the UCL+ help text. 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. UCL+ -- User Command Linkage Program - V08.02a Page 27 How It Works 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 Interfaces (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 the system device (SY:) for a program to run that has the same name as this first word (let's call it "word1"). If "SY:word1.SAV" is not found, it runs SY:UCL.SAV (if it exists) and passes the entire command line to UCL. UCL+ understands two types of commands: "hard-wired" 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-E-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 - V08.02a Page 28 How It Works In summary then, when you enter a command: 1) RT-11 tries to execute it, then 2) RT-11 tries to run it off SY:, then 3) UCL+ tries to execute it as a command, then 4) UCL+ tries to execute it as a symbol, then 5) UCL+ tries to "run-by-name", then 6) you either get a nasty comment or UCL+ chains to another program. 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: 1) UCF tries to execute it as a command, then 2) UCF tries to execute it as a symbol, then 3) UCF tries to "run-by-name", then 4) RT-11 tries to execute it, then 5) RT-11 tries to run it off SY:, then 6) you get "?KMON-F-Invalid command" 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-Plus 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 - V08.02a Page 29 How It Works 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-E-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- terface (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 - V08.02a Page 30 Symbols 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, the colon (":") in the symbol definition operator and, if present, the em- bedded asterisk ("*"), will be ignored. Note also that an embedded asterisk remains undisturbed if the UCL+ symbol definition operator ("==") is used. 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 UCL+ -- User Command Linkage Program - V08.02a Page 31 Symbols You may also get multiple-line definitions via the backslash ("\") character. For example, the symbol "WHEN" defined as WHEN==DATE\TIME executes as if you had typed DATE TIME A "^" character or characters in the definition governs where the "argument-part" of the input command string is inserted when a symbol is expanded. Thus, BUILD==EX/MAC/NORUN and BUILD==EX/MAC/NORUN ^ are equivalent symbol definitions. The "^" operator is really handy when the "argument-part" is to be embedded in the middle of the expansion somewhere rather than tacked on the end. For example: VERSIO==RESORC SY:^.SAV/V If you type VERSION PIP this symbol will expand as 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) UCL+ -- User Command Linkage Program - V08.02a Page 32 Symbols are functionally equivalent definitions. If you type SAY HELLO both will expand (on the first pass through UCL+) as DISPLAY "HELLO" But, in the first instance, the UCL+ program will be invoked ___ twice: once to expand SAY HELLO and pass the string back to RT-11, and a second time to execute DISPLAY "HELLO". In the second example, UCL+ expands the command and then immediately 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-I-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 UCL+ -- User Command Linkage Program - V08.02a Page 33 Symbols you need to include a character of this type in a symbol defini- tion, you can do so by entering its value in the form for octal numbers, or for decimal values, where "nnn" is a 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 or 255. decimal). Likewise, "<209>" would be ignored because 9 is an invalid octal digit, but "<209.>" would work properly since it is a valid decimal number. Also note that when you list a UCL+ symbol definition that in- cludes non-printing characters, it displays their octal codes. For instance, the escape character lists as "<033>", not "<027.>". 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, suppose you wanted to define a symbol to invoke a frequently used command file named CLENUP.COM. Defining the sym- bol from the UCL+ prompt prevents RT-11 from attempting to pro- cess the "@" character. The dialogue might look something like the following: UCL+ -- User Command Linkage Program - V08.02a Page 34 Symbols .R UCL UCL> clenup==$@sy:clenup UCL> 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 15.9), 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. Support for nested default strings was added with V08.01. 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 or 27 decimal): regis==disp "<33>Pp"\disp "^"\disp "<33>|\" UCL+ -- User Command Linkage Program - V08.02a Page 35 Symbols Refer to section 15.9 of the "Application Notes" for a discussion 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 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: UCL+ -- User Command Linkage Program - V08.02a Page 36 Symbols 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: 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 UCL+ -- User Command Linkage Program - V08.02a Page 37 Symbols 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 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.RNO and directs output to the printer (LP: is the default output specifi- cation). 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 You may also nest default strings. For example, suppose you didn't want the above RNO command to default to LP as the output device. Instead, you want it to produce an output DOC file with the same name as the input RNO file. The following definition will do the trick: RNO==R RUNOFF\^2[^1]=^1\<003> The "^2[^1]" construction tells UCL+ to use the first argument sub-string if a second sub-string is not specified. Now, if you UCL+ -- User Command Linkage Program - V08.02a Page 38 Symbols type "RNO SCHMOO", you will get R RUNOFF SCHMOO=SCHMOO If you do specify an output file explicitly, then the default will be overridden. If you type "RNO SCHMOO TEMP.TXT", the ex- pansion will be exactly the same as in the earlier example. There are a few 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. A specification such as "^1[^2]" is a waste of time for similar reasons. o Nested defaults only make sense when they are applied to sub-strings. For example, "^[^1]" is pointless since the default would never be used. The only logical ex- ception is "^[^0]", and I saw no point in adding several lines of code to handle this special case. Use "^1[^0]" instead. o UCL+ will interpret the default string construction "[^]" as "[^1]". o Any default specification other than "[^n]", where n is a value from 0 through 9, will be treated as plain text. UCL+ -- User Command Linkage Program - V08.02a Page 39 "Hard-Wired" Commands 9.0 "HARD-WIRED" COMMANDS The following is a brief description of the commands "hard-wired" into UCL+. These are the commands which support the various UCL+ functional goodies. 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 - V08.02a Page 40 "Hard-Wired" Commands 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.11). Note also that CHAINing is disabled when UCL+ is running as a UCF. NOCHAIN disables chaining. Examples: NOCHAIN CHAIN SY:BADWRD.SAV UCL+ -- User Command Linkage Program - V08.02a Page 41 "Hard-Wired" Commands 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-E-Invalid DISPLAY ar- gument" error message to be issued. UCL+ -- User Command Linkage Program - V08.02a Page 42 "Hard-Wired" Commands Examples: DISPLAY CD DL0 DISPLAY/EXECUTE WORD4 DISPLAY "HERE ARE TWO BEEPS<7><7>" DISPLAY/PRINTER "LINE OF TEXT" UCL+ -- User Command Linkage Program - V08.02a Page 43 "Hard-Wired" Commands 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 - V08.02a Page 44 "Hard-Wired" Commands 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 - V08.02a Page 45 "Hard-Wired" Commands /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 - V08.02a Page 46 "Hard-Wired" Commands 9.5 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-E-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 - V08.02a Page 47 "Hard-Wired" Commands 9.6 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 re- places 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 - V08.02a Page 48 "Hard-Wired" Commands 9.7 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. Note that recent versions of TSX-Plus implement a monitor level PROMPT command that can interfere with the UCL+ PROMPT command. Section 15.13 discusses this in more detail. Examples: PROMPT UCLXM> PROMPT "TSXUCL> " UCL+ -- User Command Linkage Program - V08.02a Page 49 "Hard-Wired" Commands 9.8 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. (Also works with XD files.) The default device is DK:. The default ex- tension is .UCL (i.e., DK:filnam.UCL where "filnam" is the file name you specify) in binary mode, and .UCJ if the /JOURNAL switch is used. NOTE Beginning with RT-11 V5.4C (extended memory monitor), and TSX-Plus V6.3, 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.12, 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 Examples: RECALL SY:UCLXM RECALL/JOURNAL BADWRD UCL+ -- User Command Linkage Program - V08.02a Page 50 "Hard-Wired" Commands 9.9 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 - V08.02a Page 51 "Hard-Wired" Commands 9.10 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 (i.e., DK:filnam.UCL where "filnam" is the file name you specify) in binary mode, and .UCJ if the /JOURNAL switch is used. 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" text file Examples: STORE SY:UCL STORE/JOURNAL BADWRD UCL+ -- User Command Linkage Program - V08.02a Page 52 "Hard-Wired" Commands 9.11 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 Interface" (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.6), 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 - V08.02a Page 53 CI Handler 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. WARNING!!! Turning off both DCL and CCL effectively turns off the monitor. 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 RT-11 non-extended memory monitors, the file should be SY:CI.SYS. If you are going to use it under a monitor with exended memory sup- port, make a copy named SY:CIX.SYS. Under RTEM, it should reside in the "mark zone" as SY:CIM.SYS. UCL+ -- User Command Linkage Program - V08.02a Page 54 CI Handler NOTE CI will not run under versions of RT-11 prior to V5.2; it will not work with TSX-Plus either. Also, beginning with V5.6, RT-11 implemented a SET CLI command and mod- ifications to the appropriate utilities which essen- tially duplicate the functionality of the CI handler. However, CI will still work properly under these later monitors. NOTE TO RTEM USERS Starting with V2.1, RTEM uses the UCF facility to im- plement 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 displayed by SET CI HELP will reflect this difference also. UCL+ -- User Command Linkage Program - V08.02a Page 55 Informational Messages 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-Data file not found; creating new one Indicates that the external data (XD) version of UCL+ was unable to find its symbol/status file. A new file is created and ini- tialized. ?UCL-I-Erased symbol A....A Issued when you erase a symbol via the "null definition" method. "A....A" is the symbol name. ?UCL-I-PATH disabled Indicates that the NOPATH command has been executed successfully. ?UCL-I-Prompt changed to "A....A" Indicates that a PROMPT command has been issued to change the UCL+ command prompt. "A....A" is the text of the new prompt string. ?UCL-I-Replaced existing symbol Indicates that you have replaced an existing symbol definition with another. UCL+ -- User Command Linkage Program - V08.02a Page 56 Informational Messages ?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-I-UCI_MODE disabled Indicates that an explicit NOUCI_MODE command has been suc- cessfully issued. This message is not displayed if a CHAIN com- mand disables a previous UCI_MODE command. ?UCL-I-UCI_MODE enabled Indicates that a UCI_MODE command has been successfully issued. UCL+ -- User Command Linkage Program - V08.02a Page 57 Error Messages 12.0 ERROR MESSAGES The following are the error messages for the current UCL+ pack- age. There are three levels of severity. "Warning" level messages are preceeded with the prefix "?UCL-W-" (for example, "?UCL-W-No argument; CHAIN not enabled"), and they indicate that the program may have done something that produced an erroneous result. Warning level conditions do not cause pro- gram termination. Most error messages are preceeded with an "E" prefix (e.g., "?UCL-E-Invalid command"). These messages indicate that an error of moderate severity has occurred. These might be termed "cor- rectable" errors. If UCL+ has been run directly, this level of error will cause a return to the program prompt. "Fatal" messages are prefixed with "?UCL-F-" (for example, "?UCL-F-Read error"). A fatal error is a condition that prevents the program from running reliably. When an error of this type occurs, UCL+ aborts to the monitor. NOTE If you are running the XM version of UCL+, some "fatal" messages may be issued through the global region loader. Thus, if you receive an error with a "?UCLGRL-F-" prefix that is not listed as a global re- gion loader error, check the listing of "fatal" mes- sages. UCL+ -- User Command Linkage Program - V08.02a Page 58 Error Messages 12.1 UCL+ "Warning" Messages (?UCL-W-...) 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. 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 - V08.02a Page 59 Error Messages 12.2 UCL+ Error Messages (?UCL-E-...) 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. ?UCL-E-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. ?UCL-E-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. ?UCL-E-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. ?UCL-E-Cannot 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:. ?UCL-E-Conflicting switches You specified two or more command switches that conflict with one another (for example, DISPLAY/TERM/PRINT...). ?UCL-E-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. UCL+ -- User Command Linkage Program - V08.02a Page 60 Error Messages ?UCL-E-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. ?UCL-E-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 error. ?UCL-E-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. ?UCL-E-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:. ?UCL-E-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. ?UCL-E-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. ?UCL-E-Invalid switch A....A You specified an illegal command switch. "A....A" is the switch causing the error. UCL+ -- User Command Linkage Program - V08.02a Page 61 Error Messages ?UCL-E-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. ?UCL-E-Protected file already exists A....A The STORE command was unable to create the output file you speci- fied because a protected file of the same name already exists. "A....A" is the file name. ?UCL-E-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. ?UCL-E-Symbol definition table full You attempted to define a new symbol, but UCL+ had no room left to store the definition. ?UCL-E-Symbol(s) not found A....A The ERASE or LIST/INDIVIDUAL commands were unable to find the name of the symbol that you specified. "A....A" is the unknown symbol or symbols. ?UCL-E-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. ?UCL-E-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. UCL+ -- User Command Linkage Program - V08.02a Page 62 Error Messages 12.3 UCL+ "Fatal" Messages (?UCL-F-...) ?UCL-F-Cannot access data file Under normal circumstances, this error could only occur if you have placed the XD file on a non-sharable device, such as magtape, and another program already has ownership of this device. It is more likely that this error would be triggered due to corruption of the UCL+ program image. ?UCL-F-Cannot create data file UCL+ was unable to create an external data file. Likely causes are a lack of room on the disk, or a write-protected output device. ?UCL-F-Data file read error An input error occurred when the XD version of UCL+ attempted to load its symbol/status tables from the external data file. ?UCL-F-Data file write error An output error occurred when the XD version of UCL+ attempted to initialize a newly created external data file. ?UCL-F-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-F-Write error while updating symbol blocks An output error occurred when UCL+ was updating its internal sym- bol definition/status tables (or, in the case of the XD version, its external data file). The UCL+ program file or XD file may have been corrupted. UCL+ -- User Command Linkage Program - V08.02a Page 63 Error Messages ?UCL-F-Wrong version 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 V8 series program. "A....A" is the offending file name. UCL+ -- User Command Linkage Program - V08.02a Page 64 Error Messages 12.4 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"). Also, some UCL+ "fatal" messages may be issued through the global region loader. The only errors documented in this section are those that are triggered by the global region loader itself. Thus, if you receive an error with a "?UCLGRL-F-" prefix that is not listed as a global region loader error, check the listing of "fatal" messages. ?UCLGRL-F-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. ?UCLGRL-F-Not XM monitor You attempted to run the XM version of UCL, but you were not us- ing an extended memory monitor. ?UCLGRL-F-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, or if UCL+ has not been INSTALLed with this privilege. ?UCLGRL-F-I/O error The loader encountered a problem when it attempted to access the program image on disk. Possible causes include a bad block within the program disk image, or the program storage device may be write protected. UCL+ -- User Command Linkage Program - V08.02a Page 65 Error Messages 12.5 CI Handler Errors (?CI-...) The CI handler generates messages for two error conditions as follows. ?CI-F-Wrong version of RT-11 You attempted you use the CI handler with a version of RT-11 prior to 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 - V08.02a Page 66 Examples 13.0 EXAMPLES Here are a few examples of some of the symbol definitions that I find useful. 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 CD ==assign ^[sy] dk CLS ==_d "<033>[H<033>[J DBO ==dir/brief/order:type DD ==dir/order:date/col:1 EXIT ==\ FB ==boot sy:rt11fb.sys FIND ==ind sy:find 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 PICH10==_d/p/nof "<033>[1w PICH16==_d/p/nof "<033>[4w QUIET ==set tt quiet REBOOT==dup sy:/o/y RNO ==r runoff\^2[^1]=^1\<003> 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 These are some definitions that I use on my TSX-Plus system. $RECAL==_recall DSP ==_d NOWIND==set window off RT11 ==$stop SENDME==r transf\^2[^1]/T=^1/S\<003> TAKE ==r transf\^2[^1]=^1/S/T\<003> WALKER==_d "You're already logged on, dummy<007>!" WINDOW==set window ^[narrow]\set printwindow/dev=ls:/type=la210 UCL+ -- User Command Linkage Program - V08.02a Page 67 V7 and V8 Release Notes 14.0 V7 AND V8 RELEASE NOTES This section is a journal of the principal changes and enhance- ments to UCL+ over the past few years. It is provided as a con- venience to those of you who are updating to the current version of UCL+, and wish to get an idea of the differences between this version and your current release. Changes to versions prior to V07.55b: o I changed the release/version designation. V7C was fol- lowed by V07.04. o Support has been added to UCL+ to allow it to be used as a User Command Interface (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.5 in the application notes and the description of the UCI_MODE command (section 9.11) for further information on this feature. o CHAIN and PATH work somewhat differently than in V6x 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. 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 - V08.02a Page 68 V7 and V8 Release Notes 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 added code to "work around" some inconsistencies 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 introduced 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 - V08.02a Page 69 V7 and V8 Release Notes 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. 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 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 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. Changes for V08.00: o "External data" (XD) support was added. The XD version of UCL+ maintains its symbol/status area in a separate data file. UCL+ -- User Command Linkage Program - V08.02a Page 70 V7 and V8 Release Notes o The XM and non-XM versions of UCL+ can now RECALL each others context files. The .UCX extension for XM binary mode context files was eliminated. o The hard-wired NOSL and SLON commands were eliminated. They are still available as a conditional assembly. o A bug was fixed in STORE/JOURNAL: The PROMPT command is listed with the prefix character when UCI_MODE is in ef- fect. o Error processing was split into "E" and "F" levels. The latter always forces a hard exit. o The UCL+ global region loader was modified to compensate for some eccentricities in the TSX-Plus V6.31 handling of global regions. Changes for V08.01: o Support was added for "nested" default strings. This allows one argument sub-string to act as the default value for another. o Symbol definition processing was modified so that tabs framing the "==" operator would be treated the same as spaces. Changes for V08.01c: o A bug was fixed in the DISPLAY and PASS_ON commands: Switches with leading blanks caused command arguments to be processed incorrectly. Changes for V08.01d: o Some minor documentation updates were made. Changes for the latest version (V08.02a): o Fixed a bug that caused the DISPLAY command to mishandle strings containing character values above 177 octal if the strings were not being sent to the console. o Added support for entering character codes in decimal format. You can now use "" for octal or "" for decimal values. o Removed the SL$C conditional; the hard-wired NOSL and SLON commands are no longer available. UCL+ -- User Command Linkage Program - V08.02a Page 71 V7 and V8 Release Notes o Finally worked around the last reported TSX-Plus global region bug. This was some sort of mysterious bug in TSX-Plus that caused the XM version of UCL+ to crash the first time it was run -- sometimes, on some systems. o Fixed string processing error that occurred when defini- tion was prompted for following null symbol definition entry. o Tested for RT-11 V5.6 and TSX-Plus V6.5 compatibility. o The documentation was updated. UCL+ -- User Command Linkage Program - V08.02a Page 72 Application Notes 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: .R 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/210 style printer: .R UCL UCL> pich10==_cqwenc [1w UCL> pich16==_cqwenc [4w UCL> UCL+ -- User Command Linkage Program - V08.02a Page 73 Application Notes 15.3 Moving From UCL+ V6x To UCL+ V8.xx UCL+ V8 will not allow you to RECALL version 6 or earlier series .UCL files. There is a technique, using the RT-11 utility SIPP, that will allow you to transfer your symbol definitions, etc. without reentering them all. The patch proceeds as follows: 1) Using SIPP, change the embedded version number at loca- tion 21620 in the old ".UCL" file from 6 to 8. 2) RUN a V8.xx copy of UCL+ and RECALL the patched sym- bol/status file. 3) Issue a PROMPT command to restore the "UCL>" prompt. 4) Issue a STORE command to write a new ".UCL" file. 5) If you need the CD or RNO commands, implement them by using the techniques described in section 15.11. In the example below, both the ".UCL" file and the V8 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 10 __ 000000 021621 014 ________ * ________ .RUN UCL _______ prompt ______ ?UCL-I-Prompt changed to "UCL> " UCL> recall xxxxxx _____________ UCL> store xxxxxx ____________ UCL> ________ . Once the above commands have been executed, the resulting V8 copy of UCL.SAV will be in the same configuration as your original V6 copy. UCL+ -- User Command Linkage Program - V08.02a Page 74 Application Notes 15.4 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 illustrate 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+ 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'." UCL+ -- User Command Linkage Program - V08.02a Page 75 Application Notes 15.5 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.5.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!" 15.5.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 UCL+ -- User Command Linkage Program - V08.02a Page 76 Application Notes effect, pass your command line to the monitor in an unaltered form. For the preceeding example, define DUMP==DUMP 15.5.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! UCL+ -- User Command Linkage Program - V08.02a Page 77 Application Notes 15.6 UCL+ Assembly Conditionals You can build a somewhat customized version of UCL+ by modifying the conditionals file, UCL.CND, prior to assembly. The prefix conditional, PFX, determines the prefix character used by UCL+ when UCI_MODE is in effect. You can change this prefix by changing the definition of PFX from a period (".") to some other character. 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. You can also remove the UCI_MODE command by setting UCI$C equal to 0. Other conditionals are documented in the file UCL.CND. Use the command file UCL.COM to build UCL+, UCLXD.COM to build the "external data" variant, and UCLXM.COM to build the XM ver- sion. UCL+ -- User Command Linkage Program - V08.02a Page 78 Application Notes 15.7 Changing The RT-11 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. 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. UCL+ -- User Command Linkage Program - V08.02a Page 79 Application Notes .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.6 -- presumably, it will be fixed sooner or later. 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. UCL+ -- User Command Linkage Program - V08.02a Page 80 Application Notes 15.8 Changing The TSX-Plus 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. UCL+ -- User Command Linkage Program - V08.02a Page 81 Application Notes 15.9 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:(^) _________________ 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 "<003>" at the end of the "regis" symbol de- finition specifies a control-C character.) .R UCL UCL> regis==r ucl\d "<033>Pp"\d "^"\d "<033>|\"\<003> UCL> color==_regis S(M0(AH0L50S100)1( etc... UCL> UCL+ -- User Command Linkage Program - V08.02a Page 82 Application Notes 15.10 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 026356, 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 - V08.02a Page 83 Application Notes 15.11 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 sec- tion 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+. Note, however, that the hard-wired RNO command is designed to work with DECUS RUNOFF, not the more extensive Bonner Labs version. The "UCL+ Assembly Conditionals" application note (section 15.6) explains how to do this. UCL+ -- User Command Linkage Program - V08.02a Page 84 Application Notes 15.12 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. An SL RECALL command is also implemented under TSX-Plus starting with V6.3. 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 pro- cess 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. This same trick will also work with TSX-Plus (for somewhat dif- ferent reasons) as long as you define a $RECALL command within UCL+. Note that you must run UCL+ directly to define this symbol: .R UCL UCL> $recal==_recall UCL> 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 - V08.02a Page 85 Application Notes 15.13 Avoiding Conflicts With The TSX-Plus PROMPT Command If you are using UCL+ under a recent version of TSX-Plus, there is a potential conflict between the UCL+ PROMPT command and the TSX-Plus PROMPT command. The simplest solution is to run UCL+ directly before changing its prompt. For example: .r tsxucl ________ UCL> prompt "tsxucl> " _________________ ?UCL-I-Prompt changed to "tsxucl> " tsxucl> ________ However, if you wish to change the UCL+ prompt from the monitor level, you need to define a symbol that will prevent KMON from intercepting the command prematurely. The following example shows such a definition for a symbol named "PMT." pmt==_prompt Note that this definition uses "execute immediate" mode to tell UCL+ that PMT is defined in terms of a command that UCL+ already understands. This prevents UCL+ from passing the symbol expan- sion back to the monitor. Another point to keep in mind when you change the UCL+ prompt from the monitor level is the importance of framing the prompt string with quote characters if you want the prompt to include leading or trailing blanks. For instance, the command pmt "tsxucl> " specifies a trailing space as part of the UCL+ prompt. If you omit the quotation marks, TSX-Plus will trim off any trailing blanks before the command is passed to UCL+. When you run UCL+ directly, the quotation marks are not required. UCL+ -- User Command Linkage Program - V08.02a Page 86 Application Notes 15.14 Controlling External Data (XD) File Initialization Occasionally, you may wish to modify the way that the "external data" (XD) version of UCL+ initializes the XD data file (UCLPLS.DAT). This is most likely if you are installing UCL+ "locally" under TSX-Plus. Local installation causes every user, or group of users, to have their own private UCL+ set up. This is accomplished by forcing the XD version of UCL+ to maintain a separate copy of UCLPLS.DAT for each user. This file contains the context data (symbol de- finitions, "run-by-name" path, CHAINing status, etc.) used by the UCL+ program. If the XD version of UCL+ cannot find a copy of UCLPLS.DAT, it creates one. The initial configuration specified in this XD file is: o no symbols defined, o no CHAIN in effect, and o run-by-name path set equal to "DK:". If you need a different initial set-up, you must modify the in- ternal configuration of the UCL+ program. The following il- lustrates the most straightforward approach. It is assumed that you are performing a local installation of the XD version of UCL+ on a TSX-Plus system (V5.0 or later). First, you need to create, and initialize, a copy of UCL+. You will start with a copy of the "vanilla" version of UCL+ (UCL.SAV), rather than the XD version (UCLXD.SAV): .copy ucl.sav sy:tsxucl.sav __________________________ Next, run TSXUCL, and initialize it to the desired base-line UCL+ configuration for all users on the system. The following example changes the UCL+ prompt, and "pre-defines" the CD and RNO symbols by RECALLing them from the UCLINI.UCJ journal file. (This file is included on the UCL+ distribution kit). .r tsxucl ________ UCL> prompt "tsxucl> " _________________ ?UCL-I-Prompt changed to "tsxucl> " tsxucl> recall/journal uclini _____________________ tsxucl> ________ Since you are performing a local installation, you should also establish a specific device for each user, or group of users, that will contain their individual copy of UCLPLS.DAT. The best UCL+ -- User Command Linkage Program - V08.02a Page 87 Application Notes way to do this is to assign the logical mnemonic "UCL:" within each user's start up command file. For example: MOUNT LD0 DU1:FRED.DSK DK . . . ASSIGN DK UCL Finally, patch TSXUCL.SAV to enable XD support. This is accom- plished by changing the contents of location SDSBBK from 1 to 0. (When this document was prepared, the value of SDSBBK was 032634, but you might wish to check the link map, UCL.MAP, just to make sure. A more complete discussion of this patch can be found in application note 15.15.) .sipp tsxucl.sav/a _________________ Base? _____ Offset? SDSBBK ______ Base Offset Old New? 000000 SDSBBK 000001 0 _ 000000 SDSBBK+2 050162 ________ Once XD support is enabled, UCL+ will behave as follows: Following logon, whenever a user invokes UCL+ it will load its symbol/status data from UCL:UCLPLS.DAT. Any UCL+ context changes (defining a new symbol, for example) are posted to this file also. If UCLPLS.DAT does not exist, UCL+ will create it, and is- sue the message "?UCL-I-Data file not found; creating new one". If you defined any symbols within TSXUCL.SAV prior to enabling XD support, these definitions will show up in each user's UCLPLS.DAT when it is created. UCL+ -- User Command Linkage Program - V08.02a Page 88 Application Notes 15.15 Enabling/Disabling UCL+ External Data (XD) Support External data (XD) support can be enabled or disabled by patching a single location in the non-XM version of UCL+. In fact, the only difference between the distributed "vanilla" version of UCL+ (UCL.SAV) and the XD version (UCLXD.SAV) is the contents of this one location. When XD support is disabled, UCL+ maintains its symbol/status data "internally." The symbol definitions, CHAIN and PATH specifications, and so forth, are stored within the program's disk image. When these context data are changed, the disk image is modified. When XD support is enabled, the UCL+ context area is maintained in a separate file named UCLPLS.DAT. This XD file is located on device UCL:, if this logical mnemonic is defined on the system. If UCL: is undefined, UCL+ looks for it on SY:. UCL+ will create the XD file if it does not exist. To enable XD support, use the following SIPP patch. The string "nnnnnn" is the name of the program you are patching. "SDSBBK" is the location to be patched. (The value for SDSBBK was 032634 when this document was written, but you may wish to verify this from the link map, UCL.MAP.) .SIPP nnnnnn.SAV/A _________________ Base? _____ Offset? SDSBBK ______ Base Offset Old New? 000000 SDSBBK 000001 0 _ 000000 SDSBBK+2 050162 ________ The same, basic patch can be used to disable XD support. The only difference is that you place a 1 in location SDSBBK instead of a 0. In summary, a 1 in location SDSBBK disables XD support; a 0 turns it on. UCL+ -- User Command Linkage Program - V08.02a Page 89 Application Notes 15.16 Changing The External Data (XD) Device/File Name The UCL+ external data (XD) file is usually named UCLPLS.DAT. When UCL+ is searching for this file, it looks on device UCL: first. If UCL: does not exist, UCL+ defaults to SY:. It follows the same logic when the XD file is created: If UCL: exists, UCLPLS.DAT is created there. If not, the file is created on SY:. If you need to change the XD device or file name, you can do this with a SIPP patch. To change the XD device, change the RAD50 contents of location XDDEV. The file name, also stored in RAD50, can be changed by patching the three words starting at XDFIL. At the time this document was written, the value for XDDEV was 036400, and XDFIL was 036402. (You can verify this by checking the link map, UCL.MAP.) Note that XDFIL immediately follows XDDEV -- i.e., XDFIL = XDDEV+2. In the example below, a copy of UCLXD.SAV named MYPROG.SAV is patched to change the XD device/file name to SY:MYPROG.DAT. The reason the device mnemonic is changed from UCL: to SY: is that this forces MYPROG to keep its XD file on the system device. .SIPP MYPROG.SAV/A _________________ Base? _____ Offset? XDFIL _____ Base Offset Old New? 000000 XDDEV 101704 ;R __ 000000 XDDEV ;RSY ____ 000000 XDDEV+2 ;RMYP _____ 000000 XDDEV+4 ;RROG _____ 000000 XDDEV+6 ________ UCL+ -- User Command Linkage Program - V08.02a Page 90 Application Notes 15.17 Implementing Both Global And Local Symbols Under TSX-Plus It is possible to install UCL+ in such a way that each TSX-Plus user will have access to both a "local" and a "global" set of UCL symbols. The local symbols are unique to, and maintained by, the individual users. The global symbols are system-wide, and are (presumably) maintained by the system manager. TSX-Plus UCL sequencing will work in the normal fashion with this addition: If a symbol is not found in the local set, the global set will be searched. Note that this also means that local sym- bol definitions will take precedence over global definitions. Here's how you set things up: First, install a copy of the "vanilla" UCL+ program, UCL.SAV, on the system device. Name it UCLGBL.SAV. Define all your global symbols within this program. (You'll have to run it directly to do this.) You can use the installation instructions in sections 6.1.2 and 6.1.2.1 as a guideline for installing UCLGBL. However, you should give casual users read-only access to SY:UCLGBL.SAV. _________ Next, install an XD version of UCL+, following the general pro- cedures decribed in section 15.14. Prior to enabling XD support, initialize TSXUCL so that it CHAINs to SY:UCLGBL.SAV. It's also a good idea to "pre-define" some sort of "list global" symbol (GLIST is a possible name) that will make it easy for users look at the global symbol definitions. The following illustrates this initialization sequence: .r tsxucl UCL> prompt "tsxucl> " ?UCL-I-Prompt changed to "tsxucl> " tsxucl> chain sy:uclgbl.sav tsxucl> glist==_pass list tsxucl> Essentially, what you end up with is two UCL+ programs strung to- gether. TSXUCL maintains, and processes, the user's local symbol definitions. But, if a symbol is invoked that the local UCL does not recognize, the global UCL will get a crack at it. UCL+ -- User Command Linkage Program - V08.02a Page 91 Application Notes 15.18 Eliminating the TSX-Plus UCL Data File (TSXUCL.TSX) Later versions of TSX-Plus automatically create a data file (TSXUCL.TSX) for use by the distributed UCL program. Of course, if you are using UCL+, this file is of no practical use, and you can delete it with no adverse effect once TSX-Plus is booted. There is also a sneakier way to get rid of TSXUCL.TSX. This method requires the modification of TSGEN.MAC prior to building TSX-Plus. Or, if you are using a recent version of TSX-Plus, you can accomplish the same thing with the TSXMOD program. In either case, you need to modify the file specification at label UCLDAT. The file spec will look like this: UCLDAT: .RAD50 /SY TSXUCLTSX/ Once you have located this file name, change the device spec from SY to the null device, NL. UCLDAT: .RAD50 /NL TSXUCLTSX/ Since NL cheerfully accepts I/O requests without actually doing anything, TSXUCL.TSX never gets created. At the same time, TSX-Plus seems to be perfectly happy, as long as it's allowed to go through the motions of creating the file. UCL+ -- User Command Linkage Program - V08.02a Page 92 Reporting Problems and Suggestions 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. O. Box 149 Alpha, OH 45301-0149 (513) 426-7094/0344 My electronic addresses are: CompuServe: 71066,24 MCI Mail: rdbalpha Internet: rdbalpha@mcimail.com 71066.24@compuserve.com Telex: 6503331675 (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 floppys. UCL+ -- User Command Linkage Program - V08.02a Page 93 Wish List 17.0 WISH LIST Aside from the usual fiddling about with the internals, I am cur- rently thinking about the following additions/changes to future versions of UCL+: o a reasonable way to change the number of characters al- located for symbol names and symbol definitions, and o a method to change the total number of symbol defini- tions allowed in UCL+. I do NOT intend to implement a "symbol definition editor." Use STORE/JOURNAL or LIST/INDIVIDUAL/OUT and edit the output. UCL+ -- User Command Linkage Program - V08.02a Page 94 UCL+ Command and Syntax Summary 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 "[^m]" means use mth part as default _ "execute-immediate" flag insert character whose octal code is "nnn" insert character whose decimal 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 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) STORE Saves the UCL+ symbol definition and status tables UCI_MODE Set UCL+ "pass-line-to-KMON" mode (TSX-Plus only) FILE NAME EXTENSIONS ____________________ .DAT "External data" symbol/status file .UCJ Journal mode symbol/status file .UCL Binary mode symbol/status file UCL+ -- User Command Linkage Program - V08.02a Page 95 UCL+ Customization Patch Summary 19.0 UCL+ CUSTOMIZATION PATCH SUMMARY The following is a list of the UCL+ customization patches men- tioned in various places in this manual. The section numbers refer to the primary section of the manual where each patch is discussed. The information in the "Symbol" and "Value" columns is abstracted from the link map, UCL.MAP. Symbol Value Section Effect ______ _____ _______ ______ FUDGE 026356 15.10 Work around RT-11 V5.1 bug SDSBBK 032634 15.15 Enable/disable XD support XDDEV 036400 15.16 Change XD file default device XDFIL 036402 15.16 Change XD file name The values listed for these patches were current at the time this manual was produced. However, it never hurts to double-check them against the link map. UCL+ -- User Command Linkage Program - V08.02a Page 96 I N D E X 20.0 INDEX This is, for now, a partial index; I will expand it as time per- mits. The emphasis is on the UCL+ commands and major components. This section is intended to serve as a supplement to the table of contents. In many cases the table of contents provides a suffi- cient level of detail to locate a particular subject. In these instances, index entries are either omitted or simplified. UCL+ commands appear in upper case. % character see Wildcards * character see Asterisk, embedded and Wildcards == operator see Defining symbols Argument parsing . . . . . . . . . . 7, 34, 35, 36, 37, 68, 74 Asterisk, embedded . . . . . . . . . . . . . . . . . . . . 30 Bugs Fixed . . . . . . . . . . . . . . . . . . . . 67, 68, 69, 70 Reporting . . . . . . . . . . . . . . . . . . . . . . . . 92 RT-11 V5.1 patch . . . . . . . . . . . . . . . . . . . 2, 82 CCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 CD . . . . . . . . . . . . . . . . . . . . . . . 2, 9, 69, 73 Defining . . . . . . . . . . . . . . . . . . . . 37, 83, 86 CHAIN . . . . . . . . . . . . . . . . . 27, 41, 44, 67, 69, 90 Description . . . . . . . . . . . . . . . . . . . . . . . 40 Disabled by UCF . . . . . . . . . . . . . . . . . . . . . 40 Disabled by UCI_MODE . . . . . . . . . . . . . . . . . . 52 Effect on UCI_MODE . . . . . . . . . . . . . . . 40, 56, 67 Error message . . . . . . . . . . . . . . . . . . . . . . 58 Informational message . . . . . . . . . . . . . . . . . . 55 Invoked via PASS_ON . . . . . . . . . . . . . . . . . . . 46 Restored by NOUCI_MODE . . . . . . . . . . . . . . . . . 52 Showing its status . . . . . . . . . . . . . . . . . . . 45 CI handler . . . . . . . . . . . . . . . . . . . . . 7, 8, 28 Description . . . . . . . . . . . . . . . . . . . . . . . 53 Error messages . . . . . . . . . . . . . . . . . . . . . 65 Installation . . . . . . . . . . . . . . . . . . . . . . 24 RT-11 and TSX-Plus restrictions . . . . . . . . . . . . . 54 RTEM bug . . . . . . . . . . . . . . . . . . . . . . . . 69 RTEM installation . . . . . . . . . . . . . . . . . . . . 26 Concise Command Language see CCL UCL+ -- User Command Linkage Program - V08.02a Page 97 I N D E X DCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Default strings . . . . . . . . . 1, 7, 34, 36, 37, 38, 69, 83 Changing delineators . . . . . . . . . . . . . . . . . . 77 Nested . . . . . . . . . . . . . . . . . . . 34, 37, 38, 70 Defining symbols (see also "Symbols" section) Examples . . . . . . . . . . . . 66, 72, 74, 75, 76, 81, 84 Digital Command Language see DCL DISPLAY . . . . . . . . . 6, 31, 32, 35, 59, 60, 68, 69, 70, 72 Description . . . . . . . . . . . . . . . . . . . . . . . 41 Use with TSX-Plus . . . . . . . . . . . . . . . . . . . . 29 ERASE . . . . . . . . . . . . . . . . . . . . . . . . . . 6, 32 /ALL removed . . . . . . . . . . . . . . . . . . . . . . 67 Description . . . . . . . . . . . . . . . . . . . . . . . 43 Error messages . . . . . . . . . . . . . . . . . . . 59, 61 Execute-immediate mode . . . . . . . . . . . . . . 31, 32, 84 Global region . . . . . . . . 7, 13, 14, 15, 16, 17, 50, 64, 68 Global region loader . . . . . . . . . . . . . . . . . . . 70 Error messages . . . . . . . . . . . . . . . . . . . . . 64 Installation see "Installation" section LIST . . . . . . . . . 27, 39, 45, 46, 52, 60, 67, 69, 72, 79 /INDIVIDUAL . . . . . . . . . . . . . . . . 1, 44, 45, 61, 93 Description . . . . . . . . . . . . . . . . . . . . . . . 44 NOCHAIN . . . . . . . . . . . . . . . . . . . . . . 67, 68, 69 Description . . . . . . . . . . . . . . . . . . . . . . . 40 Informational message . . . . . . . . . . . . . . . . . . 55 NOPATH . . . . . . . . . . . . . . . . . . . . 67, 68, 69, 75 Description . . . . . . . . . . . . . . . . . . . . . . . 47 Informational message . . . . . . . . . . . . . . . . . . 55 NOSL see SLON NOUCI_MODE . . . . . . . . . . . . . . . . . . . . . . . . 67 Description . . . . . . . . . . . . . . . . . . . . . . . 52 Informational message . . . . . . . . . . . . . . . . . . 56 PASS_ON . . . . . . . . . . . . . . . . . . . . . . . . . 6, 70 Description . . . . . . . . . . . . . . . . . . . . . . . 46 PATH . . . . . . . . . . . . . . . . . . . . . 18, 27, 67, 69 (see also Run-by-name) Description . . . . . . . . . . . . . . . . . . . . . . . 47 Informational message . . . . . . . . . . . . . . . . . . 56 Showing its status . . . . . . . . . . . . . . . . . . . 45 Using with UCF . . . . . . . . . . . . . . . . . . . . . 75 PROMPT . . . . 11, 14, 15, 17, 20, 22, 52, 67, 70, 73, 86, 90 Conflict with TSX-Plus PROMPT . . . . . . . . . . . . 48, 85 UCL+ -- User Command Linkage Program - V08.02a Page 98 I N D E X Description . . . . . . . . . . . . . . . . . . . . . . . 48 Informational message . . . . . . . . . . . . . . . . . . 55 Quoting . . . . . . . . . . . . . . . . . 7, 34, 35, 36, 68, 81 RECALL . . . . . 6, 10, 11, 12, 13, 14, 16, 18, 19, 21, 22, 27 /JOURNAL . . . . . . . . . . . . . . . . . . 61, 68, 69, 86 Conflict with SL RECALL . . . . . . . . . . . . . . . 49, 84 Description . . . . . . . . . . . . . . . . . . . . . . . 49 Error messages . . . . . . . . . . . . . . . 59, 60, 62, 63 V6x file recovery . . . . . . . . . . . . . . . . . . . . 73 V8.xx changes . . . . . . . . . . . . . . . . . . . . . . 70 RNO . . . . . . . . . . . . . . . . . . . . . . . 2, 9, 69, 73 Defining . . . . . . . . . . . . . . . . . . 37, 66, 83, 86 Hard-wired command . . . . . . . . . . . . . . . . . 77, 83 Run-by-name . . . . . . . . . 6, 27, 28, 29, 44, 46, 47, 60, 68 (see also PATH, NOPATH) SLON . . . . . . . . . . . . . . . . . . . . . . . . . . 2, 70 STORE . . . . . . . . 1, 6, 10, 12, 14, 16, 18, 21, 49, 73, 79 /JOURNAL . . . . . . . . . . . . . . . . 51, 68, 69, 70, 93 Description . . . . . . . . . . . . . . . . . . . . . . . 51 Error messages . . . . . . . . . . . . . . . . . . . 60, 61 Symbols see "Symbols" section UCF . . . . . . . . . . . . . . . . . . . . . 5, 27, 29, 53, 65 Changing RT-11 defaults . . . . . . . . . . . . . . . . . 78 Command processing . . . . . . . . . . . . . . . . . . . 28 Effect on CHAIN . . . . . . . . . . . . . . . . . . . . . 40 Hints and kinks . . . . . . . . . . . . . . . . . . . . . 75 UCL.SAV installation . . . . . . . . . . . . . . . . . . 11 UCLXD.SAV installation . . . . . . . . . . . . . . . . . 19 UCLXM.SAV installation . . . . . . . . . . . . . . . . . 15 Under RTEM . . . . . . . . . . . . . . . . . . . . . . . 54 UCI . . . . . . . . . . . . . . . . . . . . . 5, 6, 27, 29, 67 Changing TSX-Plus defaults . . . . . . . . . . . . . . . 80 Hints and kinks . . . . . . . . . . . . . . . . . . . . . 75 UCL.SAV installation . . . . . . . . . . . . . . . . . . 12 UCLXD.SAV installation . . . . . . . . . . . . . . . . . 22 UCLXM.SAV installation . . . . . . . . . . . . . . . . . 17 UCI_MODE . . . . . . . . . . . . . . . . . . . . 6, 23, 29, 67 Changing "prefix character" . . . . . . . . . . . . . . . 77 Description . . . . . . . . . . . . . . . . . . . . . . . 52 Disabled by CHAIN . . . . . . . . . . . . . . . . . . 40, 67 Error message . . . . . . . . . . . . . . . . . . . . . . 61 Informational message . . . . . . . . . . . . . . . . . . 56 Invokes "prefix character" . . . . . . . . . . . . . . . 52 Removing support for . . . . . . . . . . . . . . . . . . 77 UCL . . . . . . . . . . . . . . . . . . . . . . . . . 5, 53, 65 Changing RT-11 defaults . . . . . . . . . . . . . . . . . 78 Changing TSX-Plus defaults . . . . . . . . . . . . . . . 80 UCL+ -- User Command Linkage Program - V08.02a Page 99 I N D E X UCL.SAV installation . . . . . . . . . . . . . . . . 10, 12 UCLXD.SAV installation . . . . . . . . . . . . . . . 18, 21 UCLXM.SAV installation . . . . . . . . . . . . . . . 14, 16 User Commands First see UCF User Commands Last see UCL User Command Interface see UCI Wildcards . . . . . . . . . . . . . . . . . . . . . . . 44, 69 \ operator see Defining symbols ^ operator see Defining symbols, Argument parsing _ operator see Defining symbols, Execute-immediate mode | operator see Defining symbols, Quoting