ftp.barnyard.co.uk

home *** CD-ROM | disk | FTP | other *** search

/ ftp.barnyard.co.uk / 2015.02.ftp.barnyard.co.uk.tar / ftp.barnyard.co.uk / cpm / walnut-creek-CDROM / JSAGE / ZSUS / TCJ / TCJ31UPD.WS < prev next >

Wrap

Text File | 2000-06-30 | 73KB | 1,472 lines

Z-System Corne≥ (c) by Jay Sage The Computer Journal, Issue 31 Reproduced with permission of author and publisher [This is my column from The Computer Journal issue #31. Since this articleì appeared, there have been extensive changes to the ARUNZ parameters. Youì should use this article only as a guide to ways to apply ARUNZ. For theì actual parameter expressions, please consult more recent documentation. TCJì issue #33 has more up-to-date information, for example. Jay Sage] In my last column I said that I would discuss the progress I have beenì making with a new version of ZEX, the memory-based batch processor forì ZCPR3. As frequently happens, however, another subject has come up andì preempted my attention. I thought I would still get to ZEX later in thisì column, but the column is already by far the longest I have written. So ZEXì and other matters planned for this time will have to wait. For ZEX that isì not a bad thing, since I still have a lot of work to do on it, and by twoì months from now there should be considerably more progress. L'Affaire ARUNZ: J'Accuse Not too long ago in a message on Z-Node Central, David McCord -- sysopì of the board and vice president of Echelon -- leveled a serious accusationì against me: that I have failed to provide proper documentation for my ARUNZì program. I immediately decided to mount a vigorous defense against thisì scurrilous charge using all the means at my disposal, including the awesomeì power of the press (i.e., this column in The Computer Journal). Unfortunately, I find my defense hampered by a small technicality. ì True, many other people, faced with this very same impediment, haveì seemingly not been discouraged in the slightest from proceeding aggressivelyì with their defense. However, I lack the character required to accomplishì this. What is this technicality? It is the fact that the charge is true. Excuses, Excuses An effective defense being out of the question, perhaps I can at leastì offer some lame excuses. First of all, it is not as true as it seems (if truth has degrees) thatì I have provided no documentation. There is a help file, ARUNZ.HLP, that atì this very moment resides, as it has for years, in the HELP: directory on myì Z-Node RAS (remote access system). Way back when ARUNZ was first madeì available to the user community, Bob Frazier was kind enough to prepare thisì help file for me, and it was included in the LBR file that I put up on my Z¡ Node. As a series of upgraded versions appeared, I began to omit the helpì file to avoid duplication and keep the new LBR files as small as possible. ìèAfter a while, of course, the original library that did include the helpì file was removed from RASs. Hence the impression that there is noì documentation. Of course, by now that help file is rather obsolete anyway. If you are observant, you may have caught in the previous paragraph theì deliberate circumlocution "made available to the user community". Why did Iì avoid the shorter and more natural expression "released"? Because ARUNZ hasì still to this day (more than two years -- or is it three now -- after itsì first 'availability'), not actually been released. Why? Because I stillì have not finished it. It is still in what I consider to be an incomplete,ì albeit quite usable, state. A few more tweaks, a couple of additionalì features, a little cleaning up of the source code, a detailed DOC file . . .ì and it should be ready for a full, official release. ARUNZ is, regrettably, not my only program that persists in this state. ì It is simply the oldest one. ZFILER and NZEX (new ZEX) suffer similarly. ì One might even say that this has become habitual with me. What happens, ofì course, is that I don't find the time to code that one little crucialì additional feature before some other pressing issue diverts my attention. ì And by the time I do get back to it, I have thought of still another featureì that just has to be included before the program should be released. One solution would be not to make the programs available until they areì really complete. There are two reasons why I have rejected this approach. ì First of all, though not complete to my satisfaction, the programs are inì quite usable condition. It would be a shame if only I -- and perhaps aì small group of beta testers -- had been able to take advantage of the powerì of ARUNZ during these two or three years. The second problem with holding the programs back is that a lot of theì development occurs as the result of suggestions from other users, who oftenì have applications for the program that I never thought of and would neverì think of. In a sense, I have chosen to enlist the aid of the entire userì community not only in the testing process but also in the programì development process. And I think we have both benefited from thisì arrangement. The procedure I have developed for keeping track of these 'released'ì test versions is to append a letter to the normal version number. As Iì compose this column, ARUNZ stands at version 0.9G, ZFILER stands at 1.0H,ì and NZEX stands at 1.0D. When final versions are released, I will drop theì letter suffixes (except for NZEX, which will become ZEX version 4.0). The usability of the programs is probably the fundamental factor thatì keeps them in their incomplete state. When one of them has some seriousì deficiency or or simply begs for an exciting new feature, it gets myì attention. Once it is working reasonably well, however, I can ignore it andì devote my attention to other things that badly need fixing. That is how Iì recently got started on NZEX. Making Amendsè Since excuses, no matter how excusing, do not solve a problem, I willì take advantage of this column to make amends for the poor state of the ARUNZì documentation by providing that documentation right here and now. I hope itì will lead more people to make more complete and effective use of ARUNZ,ì which for me has been the single most powerful utility program on myì computers. To understand ARUNZ one must first understand the concept of the ZCPRì alias, and to understand aliases one must understand the multiple commandì line facility. I have written some things about these subjects in earlierì columns, notably in issues #27 and #28, but I will start more or less fromì the beginning here. Multiple Command Lines One of the most powerful features of ZCPR3 is its ability to acceptì more than one command at a time and to process these commands sequentially. ì Quoting from my column in TCJ issue #27: The multiple command capability ofì Z System ... is important not so much because it allows the user to enter aì whole sequence of commands manually but rather because it allows otherì programs to do so automatically. Obviously, in order to process multiple commands, the list of commandsì (at least the unexecuted ones) must be stored in some secure place whileì earlier ones are being carried out. In the case of ZCPR3, there is aì dedicated area, called the multiple command line (MCL) buffer, located inì the operating system part of memory. It stores the command line togetherì with a pointer (a memory address) to the next command to be executed. Everyì time the ZCPR3 command processor returns to power, it uses the value of theì pointer to determine where to resume processing the command line. Only whenì the end of the command line is reached does the command processor seek newì command line input. Storing multiple commands in memory is not the only possibility. ì Another secure place to keep them is in a disk file. This is in some waysì what the SUBMIT facility does using the file $$$.SUB. The main drawback toì this approach is the speed penalty associated with the disk accessesì required to write and read this file. There is also always the possibilityì of running out of room on the disk or of the diskette with the $$$.SUB fileì being removed from the drive. Using a memory buffer is faster and moreì reliable. Digital Research's most advanced version of CP/M, called CP/M-Plus,ì also provides for multiple command line entry, but it does it in a ratherì different, and I think less powerful, way. When a multiple command line isì entered by the user, the system builds what is called a resident systemì extension (RSX), a special block of code that extends the operating systemì below its normal lower limit. This RSX holds any pending commands. Butì since it is not always present and is not at a fixed, known location inì memory, there is no straightforward way for programs to manipulate multipleìècommand lines. On the other hand, this method does provide a bigger TPAì when only single commands are entered. In a ZCPR3 system, the MCL has a fixed size and is in a fixed location. ì Moreover, a ZCPR3 program can find out where the MCL is located by lookingì up the information about it in the ZCPR3 environment descriptor (ENV),ì another block of operating-system memory containing a rather complete indexì to the features of the particular ZCPR3 system. The location of the ENV isì the one key fact that is conveyed to all ZCPR3 programs. Prior to ZCPRì version 3.3, the address of the ENV had to be installed into each programì manually by the user before the program could be used; with ZCPR33 thisì installation is performed automatically by the command processor as theì program is run. The Alias Program One of Richard Conn's brilliant concepts in designing ZCPR3 was theì utility program he called ALIAS, whose function is to create COM files that,ì in turn, build multiple command lines and insert them into the MCL buffer. ì When ALIAS is run, it prompts the user for (1) the name of the alias file toì create and (2) a prototype command line, nowadays called a script. When theì resulting COM file is run, it takes the script, uses the information in itì to construct a complete command line, and then places that command line intoì the MCL buffer so that the commands it contains will be run. The simplest script would be nothing more than a completely formedì command line. For example, if we wanted to have a command (COM file) thatì would display the amount of free space on each of drives A, B, and C, weì could make an alias SPACE.COM containing the script SP A:;SP B:;SP C: We assume here that our RCP (resident command package) includes the SPì (space) command. Such a script can have only a single purpose. Much more powerfulì capability is provided when the script can contain parameter expressionsì that are filled in at the time the command is run. The aliases produced byì ALIAS.COM support a number of parameter expressions, including the $1, $2,ì ... $9 parameters familiar from the SUBMIT facility. An alias calledì ASMLINK with a script containing the following command sequence SLR180 $1 IF ~ER SLRNK /A:100,$1/N,$1,VLIB/S,Z3LIB/S,SYSLIB/S,/E FI can then be used to assemble and (if there were no errors in assembly) linkì any program. The expression $1 is replaced by the first token on theì invoking command line after the name of the alias. A token, we should note,ì is a contiguous string of characters delimited (separated) by a space or tabì character. Thus with the commandè ASMLINK MYPROG the string "MYPROG" will be substituted for each of the three occurrences ofì the expression "$1" in the script to form the command line. Any commands inì the MCL after the alias command are appended to the expanded script. The Advent of ARUNZ One day it suddenly struck me that Conn-style aliases are extremelyì inefficient with disk space. Each one contains, of course, the prototypeì command line (the script), which is unique and essential to each alias, butì which is at most about 200 characters long and often much less (17 and 67 inì the two examples above, if I counted right). But each one also contains aì complete copy of the script interpreter and command line manipulation code,ì about 1K bytes long, which is exactly the same in each alias. Why not, Iì thought, separate these two functions, putting all the scripts into aì single, ordinary text file (ALIAS.CMD) and the alias processing code inì another, separate file (ARUNZ for Alias-RUN-Zcpr)? Because there is only a single copy of the ARUNZ code in the systemì rather than a copy of it with each alias, I felt that I could afford toì expand the code to include many additional features, in particular much moreì extensive parameter expansion capability. These features will be describedì later. The ALIAS.CMD File Let's begin by looking at the structure of the ALIAS.CMD file. First,ì we should make it clear that ALIAS.CMD is a plain, ordinary text file thatì you create using your favorite text editor or word processor (in non¡ document mode). Each physical line in the file contains a separate alias definition. ì At present there is no provision for allowing definitions to run over toì additional lines, so for long scripts your editor has to be able to handleì documents with a right margin of more than 200 characters. As I sit hereì composing this column, it occurs to me that a nice solution to this problemì might be to allow the ALIAS.CMD file to be created by a word processor inì document mode and to have WordStar-style soft carriage returns beì interpreted by ARUNZ.COM as line-continuation characters. I will experimentì with that possibility after I finish this column, and if it works there mayì be an ARUNZ version 0.9H by the time you are reading this. Each alias definition line contains two parts. The first part, theì name field, defines the name or names by which the alias will be recognized,ì and the second part, the script field, contains the script associated withì that name or those names. The name field must start in the very leftmost column (no leadingìèspaces), and the two fields are separated by a space or tab character. Thusì ALIAS.CMD might have the following general appearance: FIRST-NAME-FIELD first script NEXT-NAME-FIELD next script ... ... LAST-NAME-FIELD last script For ease of reading, I follow the convention of putting the alias name fieldì in upper case and the script strings in lower case, but you can use anyì convention (or no convention) you like, since ARUNZ does not generally careì about case (the sole exception will be described later). To make the ALIAS.CMD file easier to read, you can include comment andì formatting lines. Blank lines are ignored and can be used to separateì groups of related alias definitions. Also, any line that begins with aì space (no name field) will never match an alias name and will thus have theì effect of a comment line. You can use this to put titles in front of groupsì of definitions. To tell the truth, I always wanted to be able to format the ALIAS.CMDì file as I just described, but I never got around to adding the code to allowì it. As I was sitting here writing just now, I suddenly decided to see whatì would happen if the ALIAS.CMD file contained such lines. With BGii inì operation, a quick '\s' from the keyboard took me to the alternate task, andì I gave it a whirl. Imagine my surprise and delight to discover that theì formatting already works! No new code is required. The Name Field in ALIAS.CMD The name field can contain a simple name, like SPACE or ASMLINK, butì more complex and flexible forms are also supported. First of all, the nameì field can consist of any number of individual name elements connected by anì equal sign (with no intervening spaces, since a space would mark the end ofì the name field). Thus a line in ALIAS.CMD might have the followingì appearance: NAME1=NAME2=NAME3 script string Secondly, each name element can represent multiple names. There areì three characters that have special meanings in a name element. The first isì a question mark ('?'). As with CP/M file names, a question mark matches anyì character, including a blank space. Thus the alias name DIR? will match anyì of the following commands: DIR, DIRS, DIRR, and so on. The second special character is currently the period ('.'). Forì reasons that I will not go into here (having to do with a new feature underì consideration for ZCPR34), I may change this to another character (perhapsì the asterisk), so check the update documentation with any version of ARUNZì beyond 0.9G. The period does not match any character, but it signals theì comparison routine in ARUNZ that any characters after the period areìèoptional. If characters are present in the command name, they must matchì those in the alias name, but the characters do not have to be present. Forì example, the alias name field FIND.FILE=FILE.FIND will match any of the following commands (and quite a few others as well):ì FIND, FINDF, FINDFILE, FILE, FILEF, FILEFIND. It will not, however, matchì FILES or FINDSTR or FINDFILES. I have never had any occasion to make use of the capability, but theì two special characters can be combined in a single name element. Thusì FIND.FI?E matches FINDFILE and FINDFIRE but not FINDSTR, and ?DIR.R matchesì SDIR, SDIRR, XDIR, and XDIRR (but not DIR). I think you can see that theì special characters allow for very compact expressions covering many names. The third special character is the colon (':'). If any name elementì begins with a colon, then it will match any alias name whatsoever. This isì called the default alias, the alias to be run if no other match is found. ì Since ARUNZ scans through the ALIAS.CMD file from top to bottom searchingì for a matching name, if the default name is used at all, it makes sense onlyì as the last alias in the file, since no alias definitions in lines below itì can ever be invoked. Note that letters after the colon have noì significance; you may include them if you wish as a kind of comment. One possible use for the default alias would be a line like theì following at the end of the ALIAS.CMD file: :DEFAULT echo alias $0 not found in alias.cmd If no specific matching alias is found, this default alias will report thatì fact to the user as a kind of error message. I do not recommend using theì default alias in this way, however, because it will interfere with ZCPR33'sì normal invocation of the error handler when ARUNZ has been set up as theì extended command processor (ECP) and a bad command is entered. There is one use of the default alias that can augment the extendedì command processing power of ZCPR33. When ARUNZ has been set up as the ECPì and a command is found neither as a system command, nor COM file, nor ARUNZì alias, one might want to try running the command from COMMAND.LBR using theì LX program. This is a kind of chained ECP operation. ARUNZ is the first ECP; LX is the second. This can be accomplished, using version 1.6 or laterì of LX, by adding the following line at the end of the ALIAS.CMD file: :ECP-CHAIN lx / $0 $* The meaning of the parameters $0 and $* will be explained later. With thisì default alias, if a command cannot be resolved by a specific ARUNZ alias,ì then an LX command line will be generated to search for a COM file with theì name of the command in COMMAND.LBR. The special parameter '/' as the firstì command line parameter to LX tells LX, when it cannot resolve the commandì either, to pass to the ZCPR3 error handler only the user command line (i.e.,ì to omit the "LX / " part of the command).è This might be a good time to note that ARUNZ alias names are notì limited to only eight characters or to the characters allowed in disk fileì names. For example, you have a perfect right to define an alias with theì name FINDFILES (nine letters) and to invoke it with the command ARUNZì FINDFILES. If ARUNZ has been set up as your extended command processor (seeì my book "The ZCPR33 User Guide" for a discussion of ECPs), then when youì enter the command FINDFILES, the command processor will first look for aì disk file FINDFILE.COM, since it truncates the command name to eightì characters. If this file is not found, the command processor will then, inì effect, run ARUNZ FINDFILES, including all nine characters. I have notì thought of any uses for aliases with control characters in their names, butì you can define such aliases if you wish. Another fine point to be noted is that both leading blank spaces and anì initial colon are stripped from the command name before scanning for aì matching alias name. It is obvious that if leading blanks were notì stripped, a leading blank would prevent any match from being found. Theì colon is stripped so that a command entered as ":VERB" will match an aliasì name of 'VERB' without the colon. If a directory specification is includedì before the colon, it will not be stripped. When the BADDUECP option isì enabled in the configuration of ZCPR33, this allows illegal directoryì specifications to be passed to ARUNZ for processing. The Script Field in ALIAS.CMD The script field in the ALIAS.CMD file contains the prototype commandì line to be generated in response to a matching alias name. The scriptì contains three kinds of items: (1) characters that are to be put into the command line directly (2) parameter expressions that ARUNZ is to evaluate and convert to characters in the command line (3) directives to ARUNZ to perform special operations There is nothing that has to be said about the first class ofì characters. They comprise any characters not covered by the other two sets. ì The simple example of the SPACE alias, which would appear in ALIAS.CMD as SPACE sp a:;sp b:;sp c: has only direct characters. There are no special directives and noì parameters to evaluate. ARUNZ Parameters ARUNZ supports a very rich set of parameter expressions, which we willì now describe. As rich as the set is, there are still important parametersì that still need to be added. Some of these will be mentioned later in theìèdiscussion. First let's see what we can already do. Parameters begin with either a caret ('^') or a dollar sign ('$'). Theì former is quite simple; it is used to signal a control character. The ASCIIì representation of the character following the caret is logically ANDed withì 1FH, and the result is placed into the command line. Of course, controlì characters other than carriage return and line feed can equally well beì placed directly into the script. At present there is no trap to prevent generating a null characterì (caret-space will do this: space is 20H, and 20H & 1FH = 00H). If this isì used, the resulting null will effectively terminate the command line. Anyì characters that come after the null character will be ignored by the commandì processor. This could conceivably be useful for deliberately cancellingì pending commands in a command line, but I have never used it. In fact, Iì was surprised to find that I did not have a trap for it. On thinking aboutì it now, however, it seems best to continue to allow it. Just "user beware!"ì when it comes to employing it. Parameters introduced by a dollar sign provide much more varied,ì interesting, and powerful capabilities. The special ARUNZ directives areì also introduced by a dollar sign. A complete list of the characters thatì can follow the dollar sign, grouped by function, is given below. Detailedì discussion of each will follow. $ ^ * - digit (0..9) D U : . F N T " ' R M I Z Character Parameters The parameters '$' and '^' are provided to allow the two parameterì lead-in characters to be entered into the command line text. Many users,ì present company unhappily included, have made the mistake of trying to enterì a dollar sign directly into the alias script. If this is done, the dollarì sign is (mis)interpreted as a parameter lead-in character. You must putì '$$' in the script to get a single dollar sign in the command line. The worst example I have seen (and committed) of this kind of error isì in a command like "PATH A0 $$ A0". This looks perfectly reasonable and doesì not produce any kind of error message when it runs (as "PATH A0 $0 A0"ì would, for example, when $0 got expanded to 'PATH'). Unfortunately, it runsì as "PATH A0 $ A0", where the single dollar sign now means current-drive/user-0 (this is perhaps a flaw in the way the PATH works, but that isì the way it is). The proper form of the script is PATH A0 $$$$ A0è where each pair of dollar signs turns into a single dollar sign. Complete Command-Tail Parameters The parameters '*' and '-' refer to entire sections of the command lineì tail. The asterisk represents the entire tail exactly as the user enteredì it. The parameter expression $-n, where 'n' is a number from 0 to 9,ì represents the command tail less the first 'n' tokens (a token was definedì earlier). The parameter $-0 has the same meaning as $*. Many users have confused 'command line tail' with 'command line'. Theì two are not the same. A command line consists of the command name (theì 'verb') and the tail. Thus the command line tail is the command line lessì the first token. Perhaps some examples will help. Suppose the command lineì is command token1 token2 token3 token4 Then $* = "token1 token2 token3 token4" $-2 = "token3 token4" $-4 = "" Note that $-4 is the null string; that is, $-4 will be replaced by noì characters at all. Also note that there is no leading space in the string assigned to $*. ì ALIAS.COM (and the earliest version of ARUNZ, I believe) had a bug in thisì respect in that it did include the leading space in the command line tail,ì since that is how the tail is stored by the command processor in the bufferì beginning at memory address 0080H. The script "find $*" when invoked withì the tail "string" then became "find string" with two spaces between "find"ì and "string". In such a case, Irv Hoff's FIND program failed to work asì expected, probably because it was looking for " string" with a leadingì space. Complete Token Parameters The digit parameters '0' through '9' represent the corresponding tokenì in the command line that is being parsed. In the example command line aboveì the digit parameters have the following values: $0 = "command" $1 = "token 1" $5 = "" Except for the '0' parameter, these parameters are familiar from the CP/Mì SUBMIT facility. The expression $0 is an extension used to represent theìècommand verb itself. Just think of the tokens on the command line as beingì numbered in the usual computer fashion starting with zero instead of one. Aì token that is absent from the command line returns a null string (noì characters) as with $5 in the above example. As just mentioned, many users confuse the command line tail and theì command line. If you want only the tail, use the parameter $*. If you wantì to represent the entire command line, use the expression "$0 $*". Mostì often it is the command line tail that is to be passed to a command, and theì ALIAS.CMD line will read something like ALIAS realverb $* This is a direct implementation of the common meaning of 'alias' as anotherì name for something. When ALIAS is invoked, we simply want to substituteì 'realverb' for it while leaving the command tail as it was. There are other occasions, however, as with the LX default aliasì example given earlier, where the entire command line must be passed. Thereì are still other occasions, such as in the first default alias example above,ì where only the name of the verb used is needed. Because a given script inì ALIAS.CMD can correspond to many possible alias names, it is important toì have a parameter that will return the name that was actually used in anyì particular instance. Token Parsing Parameters There are many instances in which it is extremely useful to be able toì break any token down into its constituents. The parameters 'D', 'U', ':',ì and '.' do this. They assume that the token is in the form of a fileì specification, which may have (1) a directory specification using either aì named directory or a drive and/or user number; and/or (2) a file name;ì and/or (3) a file type. Each of the four parameters above is followed by aì number from 1 to 9 to designate the token to parse ('D' and 'U' can alsoì have a 0). After discussing each one individually, we will give someì examples. The parameter 'D' returns the drive specified or implied in theì designated token. If there is no directory specification or if only a userì number is given, then $Dn returns the default (logged) drive at the timeì ARUNZ constructs the command line. WARNING -- NOTE WELL: this is not necessarily the drive that will beì logged in at the time when that part of the command actually executes!! ì This, too, has been the source of grief in the use of ARUNZ. ARUNZ has noì infallible way to know what directory will be logged in when some futureì command runs; it only knows what directory is the default directory at theì time ARUNZ itself is running. The 'U' parameter is similar in all respects to 'D', and the sameì warning applies. The parameters $D0 and $U0 can also be used. They alwaysìèreturn the default drive and user at the time ARUNZ interprets the script. The parameter ':' represents the file name part of the token, while theì parameter '.' represents the file type part of the token. One way toì remember the characters for these two parameters is to think that colonì stands for the part of the token after a colon and period stands for theì part of the token after a period. Admittedly, 'N' for name and 'T' for typeì would have been more sensible, but as we shall see shortly, these areì already used for something else. Generally speaking, the entire token can be represented as $Dn$Un:$:n.$.n where 'n' is a digit. Let us consider some examples. Suppose the following command isì entered at the prompt: B1:WORK>command root:fn1.ft1 c:fn2 2:.ft3 and that COMMAND.COM is not found, so that the command is passed on to ARUNZì and the extended command processor. Also assume that the ROOT directory isì A15. Then here are the values of the parameters for the four tokens in theì command: $D0 = "B" $U0 = "1" $0 = "COMMAND" $1 = "ROOT:FN1.FT1" $D1 = "A" $U1 = "15" $:1 = "FN1" $.1 = "FT1" $2 = "C:FN2" $D2 = "C" $U2 = "1" $:2 = "FN2" $.2 = "" $3 = "2:.FT3" $D3 = "B" $U3 = "2" $:3 = "" $.3 = "FT3" Note the value of the following parametric expression: $D1$U1:$:1.$.1 = "A15:FN1.FN2" You can see that the 'D' and 'U' parameters can be used to convert a namedì directory into its drive/user form. System File Name Parameters The ZCPR3 ENV contains four system file names, each with a name and aì type. These file names, numbered 0..3, are used by various programs,ì especially shells. VFILER and ZFILER, for example, keep the name of theì file currently pointed to in system file name 1. These file names can alsoì be read and set using the utility program SETFILE.è The parameters 'F', 'N', and 'T' followed by a digit from 0 to 3ì return, respectively, the entire filename (name.typ), file name, and fileì type of the specified system file. User Input Parameters The single and double quote parameters are used for prompted userì input. The forms of the parameter expressions are $"prompt" or $'prompt' When the parameter $" or $' has been detected, any characters in the scriptì up to the matching parameter character or the end of the script line areì echoed as a prompt to the user's screen. These characters are echoedì exactly as they appear in the script; no conversion to upper case isì performed. The prompt string for the double quote parameter can containì single-quote characters, and the prompt string for the single quoteì parameter can contain double-quote characters. There is, at present, no wayì to include the type of quote character used as the parameter in the promptì string. After the prompt has been output to the console, ARUNZ reads in a lineì of input from the console (user input). At this point there is a subtle butì important distinction between the two user input parameters. The singleì quote form takes the entire text string entered from the console and placesì it in the command line. In particular, this input may contain semicolons,ì allowing the user to enter multiple commands. The double quote form ignoresì a semicolon and any text thereafter. This is intended for secure systems,ì where it prevents the user, when prompted for a program option, fromì slipping in complete additional commands. One pitfall to which many users have succumbed is the failure toì appreciate that the user input parameters perform their function at the timeì that ARUNZ is running and interpreting the script, not when the program inì the command line is running. Consider the alias definition ERAFILE dir $1;era $"File name to erase: " The intention here is to first display a list of the files that match theì first command line token and then to allow the user to enter the one to beì erased. This is not what will happen. ARUNZ will put up the prompt "Fileì name to erase: " at the time the command line is being built, i.e., beforeì DIR is run. The prompt will come before the directory display. The way around this problem is to use two ARUNZ aliases as follows: ERAFILE dir $1;/eraprompt ERAPROMPT era $"File name to erase: " Now when ERAFILE is run, it will display the directory and then run theìècommand "/ERAPROMPT". The slash here is a ZCPR33 feature that indicatesì that the command should be sent directly to the extended command processor. ì This saves the time that would otherwise be wasted searching for a fileì named ERAPROMPT.COM (actually, ERAPROMP.COM, since the ninth character willì be truncated from the name). If you are not running ZCPR33 (but you shouldì be!!) or are running BGii, use a space instead. This will work with bothì ZCPR33 and BGii and will have no effect in ZCPR30. I am using the slash inì the examples because a space is hard to see in print. When ERAPROMPT runsì and the user is prompted for the name, the directory listing will already beì on the screen. Whenever console input is requested by any program, one must keep inì mind the possibility that ZEX will be running and consider the question ofì whether the input request should be satisfied from the ZEX script or byì direct user input. ARUNZ is configured, in the absence of a specificì directive to the contrary, to turn ZEX input redirection off during ARUNZì prompted input. Thus, even if ZEX is running at the time ARUNZ is invoked,ì the user input parameters will request live user input. If you do want ZEX to be able to provide the response to ARUNZ promptedì input automatically from the ZEX script, then you must include the ARUNZì directive $I ('I' for input redirection) before the $" or $' parameter. Theì $I directive is effective only for the next user input operation. Afterì each prompted user input operation, the default for ZEX input redirection isì turned off. The $I directive need not immediately precede the $" or $' butì there must be a separate $I for each input requested. Register and Memory Parameters Two parameters are provided for referencing values of the ZCPR3 userì registers and the contents of any memory location in the system. By Richard Conn's original specification, there were ten user registersì numbered from 0 to 9. However, the block of memory in which those tenì registers fall is actually 32 bytes long. Conn designated the last 16 bytesì of this block as 'user definable registers', but he and others later usedì them in programs such as Term3 and Z-Msg. As a result, one has to be veryì careful in making use of them. The last 6 bytes of the first half of theì block were defined as 'reserved bytes'. Various uses have been made of themì as well. The ARUNZ parameter 'R' can reference any of the first 16 bytes usingì the form $Rn, where 'n' is a hexadecimal digit. The decimal digitsì reference the true user registers, and the additional digits 'A' through 'F'ì reference the reserved bytes. In the current version of ARUNZ, the value isì returned as a two character hexadecimal value. However, I would like toì provide in the future a way to return the value in either decimal orì hexadecimal form. A complication with the decimal form is the need toì indicate the format: one character, two characters with leading zeros, threeì characters with leading zeros, or the number of characters required for theì particular value with no leading zeros.è One of the uses I envisioned for this parameter, though I have neverì actually used it this way, is for automatic sequential numbering of files. ì Thus a script might include the string "copy $:1$r3.$.1=$1;reg p3". Thisì would copy the working file given by token 1 to a new file with the hexì value of register 3 appended to the file name. For a file name of PROG.Z80ì this might be PROG03.Z80. Then the value of register 3 would be incrementedì so that the next file name in sequence (PROG04.Z80) would be used the nextì time the alias was invoked. The parameter 'M' is used in the form $Mnnnn, where 'nnnn' is aì precisely four-digit hexadecimal address value. The parameter returns theì two character hexadecimal value of the byte at the specified memory address. ì I use this on my RAS to determine if the system is running in local mode. ì The BDOS page at address 0007H has a different value when BYE is running. ì There might be a script of the form if eq $m0007 c6;....;else;echo not allowed in remote mode;fi The commands represented by the ellipsis "...." will run only if in localì mode (BDOS apparently located at page C6H). ARUNZ Directives There are presently two ARUNZ directives. We already discussed one ofì them, 'I', under the user input parameters. The other one is 'Z'. Ordinarily, once ARUNZ has interpreted the alias script and evaluatedì the parameters, it appends to the resulting command line any commands in theì multiple command line buffer that have not already been executed. This isì usually what one wants. There is one possible exception. As I discussed in issues #27 and #28 of The Computer Journal, oneì sometimes wants an alias to invoke itself or other aliases recursively. ì This can sometimes lead to problems with the build up of unwanted pendingì commands that eventually causes the command line to overflow the bufferì space allowed for it. In such a case one might want only the currentì expanded script command line to be placed in the MCL, with any pendingì commands dropped. A $Z directive anywhere in the script will cause ARUNZ toì do this. Note that the directive is not a toggle; multiple uses has theì same effect as a singe use. Remember, however, that Dreas Nielsen's aliasì recursion technique, described in issue #28 and in examples below, isì generally preferable to the technique using $Z. Applications for ARUNZ Aliases In this section I will use a number of sample scripts to illustrateì various ways in which one can make use of the power of ARUNZ aliases. I'mì sure there are many I have not thought of, and I invite you to send me yourì suggestions and examples. In all cases I will be assuming that ARUNZ is theìèextended command processor (typically renamed to CMDRUN.COM). In general, one can identify the following classes of aliasì applications: (1) providing synonyms for commands (2) trapping and/or correcting command errors (3) automating complex operations into single commands Within the last category fall two special subclasses: (a) performing 'get, poke, & go' operations (b) providing special functions like recursion and repetition Command Synonyms The most basic use of aliases is to provide alternative names for commands. Here are some examples from my personal ALIAS.CMD file. For displaying the directory of a library file, I now use the programì LLF. However, after years of using LDIR, both before LLF was released andì still on most remote access systems, I prefer to use that name and haveì renamed LLF.COM to LDIR.COM. Sometimes, however, I forget or want to beì sure I am running LLF and enter the command LLF explicitly. Then I am savedì by the alias line LLF ldir $* Similarly, I have recently begun to use LBREXT instead of LGET. LGET isì easier to type, and I am used to it, so I have the alias LGET lbrext $* LBREXT is so new that I did not want to rename it to LGET, since I might tooì easily forget which program the disk file really is. I know I never haveì the old LDIR.COM around any more. In both of these examples, the aliasì simply substitutes a different verb in the command line; the tail is leftì unchanged. Before the advent of ZCPR33, when path searching always included theì current directory, I would speed up the disk searching in these cases byì including an explicit directory reference with the script. Thus the twoì commands above might be LLF a0:ldir $* LGET a0:lbrext $* This way the command processor would go straight to A0 no matter where I wasì logged in at the time. With ZCPR33 one can bypass the path search for commands that one knowsìèare in ALIAS.CMD by entering the command with a leading space or slashì (assuming the usual configuration of ZCPR33). Sometimes I might try toì outfox the system and, thinking LBREXT is the alias name, enter the commandì as '/LBREXT ...'. So that this will work, I extend the alias lines to LLF=LDIR a0:ldir $* LGET=LBREXT a0:lbrext $* The command is an alias for itself!! Odd, but useful. It is a good idea ifì you do this, however, to be absolutely sure to include an explicit directoryì prefix before the command name in the script. If you don't, the followingì situation can arise. Suppose the alias line reads TEST test $* but for some reason TEST.COM is not on the disk (or at least not on theì search path). Now you enter the command TEST. The command cannot be foundì as a COM file, so the command processor sends it to ARUNZ. ARUNZ proceedsì to regenerate the same command, which again cannot be found, and so on untilì you press the little red button or pull the plug. Not always to completeì catastrophe, but definitely a nuisance. With ZCPR33, if the command has anì explicit directory prefix, control is passed directly to the error handlerì if the COM file cannot be found in the specified directory. It figures thatì if you go to the trouble of specifying the directory, you must mean to lookì there only. Another use for synonyms is to allow a short-form entry of commands. ì Here are two examples: SLR.180 asm:slr180 $* ED.IT sys:edit $* Synonyms are especially helpful on a remote access system or on anyì system that will be used by people who are not familiar with it or expert inì its use. Consider, for example, the task of finding out if a certain fileì is somewhere on the system and where. Some systems use FINDF, the originalì ZCPR3 program for this purpose; others use one of the standard CP/M programsì (WIS or WHEREIS); and others have begun to use the new, enhanced ZSIGì program called FF. This can be very confusing to new users or to users whoì call many different systems. The solution is to provide aliases for all theì alternatives. Suppose FF is the real program in use. Then the followingì line in ALIAS.CMD will allow all the forms to be used equally: FINDF=WIS=WHEREIS ff $* In fact, while I am at it, I usually throw in a few other forms that someoneì might try and that are sufficiently unambiguous that one can guess with someì confidence that this is the function the user intended: FIND.FILE=FILE.FIND=WIS=WHERE.IS=FF a0:ff $* Note that this single alias, which occupies only 46 bytes in ALIAS.CMDìè(including the CRLF at the end of the line), responds to 8 commonly usedì commands for finding files on a system. Thus the cost is a mere 6 bytes perì command!! Trapping and Correcting Command Errors Aliases can be used to trap commands that would be errors and eitherì convert them into equivalent valid commands or provide some warning messageì to the user. It is generally not desirable to have a very long search path, becauseì every time a command is entered erroneously, the entire path has to beì searched before the extended command processor will be brought into play. ì On my SB180 with its RAM disk, I sometimes want the path to include onlyì M0:, the RAM disk directory. The RAM disk, of course, cannot contain all ofì the COM files I use. For COM files that reside on the floppy disk, I canì include an alias. For example, MEX.COM and all its associated files take up a lot of diskì space, and I keep them in a directory called MEX on my floppy drive B. Theì ALIAS.CMD file can have the line MEX mex:mex $* Without this alias I would have to remember to enter MEX:MEX manually. If Iì forgot, I would get the error handler and then have to edit the line toì include the MEX: prefix. The 16-byte entry above in the ALIAS.CMD fileì saves me all this trouble. Every computer user probably has some commands whose names heì habitually mistypes (switching 'g' and 'q' for example or reversing twoì letters). My fingers seem to prefer 'CRUNHC' to 'CRUNCH', so I have theì following alias line: CR.UNHC crunch $* Note that while I am at it, I allow the shorter form CR as well. My fingersì like that even better. On a remote access system there are many situations where correctingì common mistakes can be handy. Richard Jacobson (Mr. Lillipute, sysop of theì RAS that now serves TCJ subscribers) calls my Z-Node quite often. Either heì has a Wyse keyboard with very bad bounce (as he claims) or he is a lousyì typist (and refuses to admit it). When he wants to display a directory, hisì command is more likely to come out DDIR or DIRR than it is to come outì correctly as DIR. So I added those two forms to my existing alias whichì allowed XD and XDIR (and /DIR); it now reads: XD.IR=DDIR=DIR.R a0:dir $* Compensating for Richard's keyboard stutter takes up only seven extra bytesìèon my disk, not a very big sacrifice to make for a friend! Another example, one that is more than just a synonym for a mistypedì command, is an alias that comes into play when a command becomesì unavailable, perhaps because of a change in security level. The RCP may,ì for example, have an ERA command that is only available when the wheel byteì is set. When the wheel byte is off, ZCPR33 will ignore the command in theì RCP and forward an ERA command to the extended command processor or errorì handler (assuming there is no ERA.COM). You might want to trap the errorì before the error handler gets it using an alias such as ERA echo e%>rasing of files not allowed When the wheel byte is set, the ERA command will execute normally (unlessì entered with a leading space or slash). When the wheel byte is off, theì user will get the message "Erasing of files not allowed", which, unlike theì invocation of an error handler, makes the situation perfectly clear. It is obviously very hard for users to remember the DU forms forì directories on a remote system, and that is one reason why named directoriesì are provided. But even names are not always easy to remember precisely.ì Aliases can help by providing alternative names for logging intoì directories, provided ZCPR33 has been assembled with the BADDUECP optionì enabled so that invalid directory-change references are passed on to theì extended command processor. Suppose you have a directory called Z3SHELLS. One might easily forgetì the exact name and think that it is Z3SHELL or SHELLS or SHELL. Theì following line in ALIAS.CMD Z3SHELL:=SHELL:=SHELLS: z3shells: would take care of all of these possibilities. Note, however, that it willì not help a reference like "DIR SHELL:". [If you wanted this to be accepted,ì you would have to go to considerable trouble. You might be able to go intoì the NDR (named directory register) and tack onto the end an entry for aì directory named SHELL associated with the same drive and user as Z3SHELLS. ì All existing NDR editors will not allow a DU area to have more than oneì name, so you would have to use a debugger or patcher. If anyone tries this,ì let me know if it works.] I occasionally slip up and omit the colon on the end of a directoryì change command (and users on my Z-Node do it surprisingly often). It isì very easy for ARUNZ to pick this up as well and add the colon for you. Justì include the following alias line: Z3SHELL=Z3SHELLS=SHELL=SHELLS z3shells: All of these aliases can be combined into the single script: Z3SHELL.:=Z3SHELLS=SHELL.:=SHELL.S: z3shells: èSeven forms are covered by an entry of only 47 bytes, a cost of less than 7ì bytes each. Note that the name element Z3SHELLS, unlike the other threeì name elements, does not allow an optional colon. If it were included andì for some reason there were no directory with the name Z3SHELLS, you couldì get into an infinite loop. On my Z-Node I provide a complete set of aliases for all possibleì directories so that any legal directory can be entered with or withoutì colons and using either the DIR or the DU form. Thus, if Z3SHELLS is B4,ì the script above would be: Z3SHELL.:=Z3SHELLS=SHELL.:=SHELL.S:=B4.: z3shells: Before ZCPR33 came along and provided this service itself, I wouldì allow callers to use the DU form to log into unpassworded named directoriesì beyond the max-drive/max-user limits by including aliases of the above form. ì If the maximum user area were 3 in the above example, the commands "B4:" andì "B4" would still have worked (even under ZCPR30) because ARUNZ mapped themì into a DIR form of reference. Although this is no longer necessary withì ZCPR33, a complete alias line like the one above covers all bases. The userì can even enter any of the commands with a leading space or slash and theyì will still work. Finally, I provide on the Z-Node a catch-all directory change alias toì pick up directory change commands that don't even come close to somethingì legal. At the end of ALIAS.CMD (i.e., after all the other directory-changeì aliases described above, so that they get the first shot at matching), Iì include the line ?:=??:=???:=????:=?????:=??????:=???????:=????????: echo d%>irectory %<$0%> is not an allowed directory. %<t%>he^m^j valid directories are:;pwd Thus when the user enters the command "BADDIR:", he get the PWD display ofì the system's allowed directories prefixed by the message Directory BADDIR: is not an allowed directory. The valid directories are: [Note the use of Z33RCP's advanced ECHO command with case shifting ('%< toì switch to upper case and '%>' to switch to lower case) and control characterì inclusion (caret followed by the character).] Automating Complexity Complexity is a relative term, and in my old age (also relative) Iì enjoy the luxury of letting my computer perform as much labor on my behalfì as it possibly can. We already saw how ARUNZ aliases can provide shortì forms for commands (CR for CRUNCH). It can also allow one to completelyì omit commands. è At work I have been maintaining a phone directory in a file calledì PHONE.DIR. I got tired of invoking my PMATE text editor using the commandì "EDIT A0:PHONE.DIR", so I added the following line to ALIAS.CMD: PHONE edit a0:phone.dir Now I just type PHONE and, bingo, I'm in the editor ready to add a new name. ì Similarly, I used to look up numbers for people using JETFIND as follows: JF -gi smith|jones a0:phone.dir This would give me, from any directory, a paginated listing of lines inì PHONE.DIR containing either "smith" or "jones" (ignoring case). My poorì tired fingers ache just thinking about all that typing. Now I have theì alias line #=CALL=NUM.BER jf -gi $1 a0:phone.dir Now a simple " # smith" puts Smith's number up on my clean CRT screen in aì jiffy. Here is another frequent command that causes severe finger cramps. Youì want to find all the files in the current directory that have a typeì starting with 'D'. You have to type "XD *.D*". Wouldn't it be nice to haveì a directory program that automatically wildcarded the file specification. ì While I was fixing up FINDF to make my new FF, I built that feature into theì code. I've been too busy or too lazy to do the same for XD, so instead Iì added the alias line D xd $d1$u1:$:1*.$.1* $-1 This is a little hard to decipher at a glance because of all the dots andì colons and asterisks. But here's how it works. Suppose we are in B4: andì enter "D .D /AA" (the option /AA means to include SYS and DIR type files). ì The parameters in the alias have the following values: $D1 = "B" $U1 = "4" current drive and user, since none given explicitly $:1 = "" no file name given $.1 = "D" file type in first parameter $-1 = "/AA" the tail less the first token ".D" The command is thus translated by ARUNZ into XD B4:*.D* /AA Sometimes it can be nice to allow a command that takes a number ofì alternative options to run with only the option entered on the command line. ì I have a read file for MEX that provides automated, menu-based operation onìèPC-PURSUIT. I could invoke it as "MEX PCP". Instead, I have the alias PCP mex pcp I also do this with the KMD file transfer commands on my Z-Node, where Iì define the following aliases: S kmd s $* SK kmd sk $* SB kmd sb $* SBK kmd sbk $* SP kmd sp $* SPK kmd spk $* R kmd r $* RP kmd rp $* RB kmd rb RP kmd rp $* L kmd l $* LK kmd lk $* This way the user can skip typing "KMD". Actually, these aliases eachì contain numerous other synonyms as well. The 'S' alias, for example,ì includes "SEND", "DOWN", and "DOWNLOAD" as well. The cost in terms of diskì space to add all these aliases is so small that I let my enthusiasm andì imagination run wild. Note, however, that with the above aliases defined,ì the RCP should not have the 'R' (reset) and 'SP' (space) commands, sinceì they will take precedence over the alias. I changed the names of theseì commands to 'RES' and 'SPAC'. The remote user has no reason to use themì anyway. There are, of course, many really complicated sequences of commandsì (editing, assembling, and linking files, for example) that can very nicelyì be performed by aliases. Those are fairly obvious, and I have describedì quite a few in previous columns. I won't give any more examples here, but Iì will describe two special applications where ARUNZ aliases cut down aì complex process to simple proportions. The first is automation of the get-poke-go technique pioneered by Bruce Morgen. Automated GET-POKE-GO Here the alias does more than just save typing -- it remembers theì addresses that have to be poked, something you probably can't do. I willì illustrate it with an intriguing example that is sort of recursive. Suppose ARUNZ is the extended command processor, has been renamedì CMDRUN.COM, and is set to get its ALIAS.CMD file from the root directory. ì Next, suppose you also want to be able to invoke it manually and have it, inì that case, look for its ALIAS.CMD file along the entire path, including theì current directory. Suppose, furthermore, that CMDRUN.COM is a type-3ì program that loads and runs at address 8000H. By inspecting CMDRUN.COM, we find that we have to poke a 0 at offsetìè1CH (address 801CH) to turn off the ROOT configuration option and an FFH atì offset 24H (address 8024H) to turn on the SCANCUR option. If we are to makeì manual invocations using the alias name 'RUN', we can put the following lineì in the ALIAS.CMD file in the root directory, where the unpoked CMDRUN.COMì will find it: RUN get 8000 cmdrun.com;poke 801c 0;poke 8024 ff;jump 8000 $* I particularly chose this example because it illustrates the slightly moreì advanced version of GET-POKE-GO called GET-POKE-JUMP. One word of caution. ì This technique will only work under ZCPR33. BGii version 1.13 is very closeì to ZCPR33, but it still handles the JUMP command the way ZCPR30 did, and itì cannot use JUMP when a command tail is processed. I will now describe two very special operations that can be performedì very nicely with ARUNZ aliases: recursion and repetition. Special Recursion Aliases The following pair of aliases (more or less) that implement Dreasì Nielsen's recursion technique were described in my column in issue 28. Theyì allow one to execute a single command recursively. With each cycle the userì will be asked if he wants to continue. So long as the answer is yes, theì command will be executed repeatedly. Upon a negative reply, the recursiveì sequence will terminate, and any pending commands will execute. The alias that the user invokes can be called "REC.URSE" so that it canì be invoked with a simple 'REC'. It contains the following sequence ofì commands: if nu $1 echo;echo %< s%>yntax: %<$0 cmdname [parameters]^j else /recurse2 $* fi If invoked without at least a command name, this alias echoes a syntaxì message to the screen. Otherwise it invokes the second alias RECURSE2. Theì leading slash speeds things up by signaling the ZCPR33 command processorì that it should go directly to the extended command processor. If you areì using BackGrounder-ii (version 1.13), the slash should be replaced by aì space (the alias will then work with BGii or Z33). If you are using ZCPR30,ì don't use either; a space won't do you any good, and a slash will cause theì command to fail. The alias that does the real recursion (RECURSE2) has the followingì sequence of commands: fi $* if in r%>un %<"$*" %>again?è /$0 $* If the user answers the 'run again' query affirmatively, RECURSE2 will beì invoked again. By using '$0' instead of 'RECURSE2' the script will workì even if we later change its name. Special REPEAT Alias Here is a simple special alias that will allow a command that takes aì single argument (token) to be repeated over a whole list of argumentsì separated by spaces (not commas). The name of the alias is "REP.EAT" soì that it can be invoked with a brief 'REP'. The script contains theì following commands: $zxif if ~nu $2 echo $1 $2 $1 $2 fi if ~nu $3 /$0 $1 $-2 fi The '$z' in the first line declares the alias to be in recursive mode (anyì pending commands in the multiple command line buffer are dropped when thisì alias executes), and 'xif' clears the flow state. Invoked as REPEAT CMDNAME ARG1 ARG2 ARG3 for example, interpretation of the script the first time through results inì the following commands: xif if ~nu arg1 echo cmdname arg1 cmdname arg1 fi if ~nu arg2 /repeat cmdname arg2 arg3 fi The command line generated ("CMDNAME ARG1") is first echoed to the screen soì the user knows what is going on, and then it is run. Since there is aì second argument, the alias is reinvoked as "REPEAT CMDNAME ARG2 ARG3". Noteì that the first argument has been stripped away. After "CMDNAME ARG2" hasì also been run and stripped from the command, the interpreted command stringì will be: xif if ~nu arg3 echo cmdname arg3è cmdname arg3 fi if ~nu /repeat cmdname fi This time the null test in the second IF clause will fail, and the cycle ofì commands will come to an end. This form of the REPEAT alias suffers from the problems Dreas Nielsenì pointed out (it wipes out any commands following it on the original commandì line). A rigorous version can be made (adapting Dreas's technique) byì making two aliases as follows: REP.EAT if nu $2 echo;echo %< s%>yntax: %<$0 aliasname arg1 arg2 ...^j else /repeat2 $* fi REPEAT2 fi $1 $2 if ~nu $3 /$0 $1 $-2 If there is not at least one argument after the name of the command, aì syntax message is given. Otherwise a series of operations using REPEAT2ì begins in which the command is executed on the first argument, and thenì REPEAT2 is reinvoked with the same command name but with one argumentì stripped from the list of arguments. Note that the parameter $-2 is used. ì The first parameter (the command verb) is given explicitly as $1. "$-2"ì strips away the verb and the argument that has already been processed. Theì expression "$1 $-2" allows one to strip out the second token. Similarly,ì "$1 $2 $-3" would strip out the third token. "$1 $-3" would strip out theì second and third tokens, leaving the first one intact and moving theì remaining tokens down by two. Configuring ARUNZ There are several configuration options that allow the user to tailorì the way ARUNZ operates. The COM file is designed to make it easy to patchì in new values for most of the options using a program like ZPATCH. Execution Address for ARUNZ ARUNZ is written as a type-3 ZCPR33 program. In other words, it canì automatically be loaded to and execute at an address other than 100H. Inì this way, its invocation as an extended command processor can leave most ofì the TPA (transient program area) unaffected by its operation. In the LBRìèfile posted on RASs there are generally two versions of ARUNZ, one designedì to run at 100H (and usable in ZCPR30 systems) and one designed to run atì 8000H. Sometimes there are also REL files that the user can link with theì ZCPR libraries to run at any desired address. Display Control There are two bytes just after the standard ZCPR3 header at offset 0DHì in the COM file (just before the string "REG") that control the display ofì messages to the user during operation of ARUNZ. The first byte applies whenì ARUNZ has been invoked under ZCPR33 as an extended command processor; theì second applies to manual invocation (or any use under ZCPR30). Each bit of these two bytes could control one display feature. Atì present, only six of the bits are used. Setting a bit causes the messageì associated with the bit to be displayed; resetting the bit supresses theì display of the corresponding message. The least significant bit (bit 0) affects the program signon message. ì The usual setting is 'off' for ECP invocations and 'on' for manualì invocations. Bit 1 affects the display of a message of the form Running alias "XXX" This message is normally displayed only for manual invocations of ARUNZ. Bit 2 controls the display of the "ALIAS.CMD file not found" message. ì This message should generally be enabled, since it will not appear unlessì something has unexpectedly gone wrong, and you might as well know about it. Bit 3 controls the display of a message of the form Alias "XXX" not found This message is normally turned on for manual invocations only. When theì alias is not found by ARUNZ operating as a ZCPR33 ECP, control is turnedì over to the error handler, and there is no need for such a message. Theì message can alternatively be generated, in whatever form the user desires,ì using a default alias as described earlier. In that case, however, theì message will appear for ECP as well as manual invocations. Bits 4 and 5 apply only when ARUNZ has been invoked as an extendedì command processor, and they were included as a debugging aid while I wasì first developing ARUNZ. Both are normally turned off. If bit 4 is set,ì ARUNZ will display the message "extended command processor error" if itì could not process the alias during an ECP invocation. Bit 5 controls aì message of the form "shell invocation error". It is possible (though veryì tricky and not recommended) for an alias to serve as a shell. If ARUNZì fails to find an alias when invoked as a shell processor, then this messageì will be displayed if bit 5 is set. è Locating the ALIAS.CMD File There are several possibilities for how ARUNZ is to go about locatingì the ALIAS.CMD file. There are four configuration blocks near the beginningì of the ARUNZ.COM file; they are marked by text strings "PATH", "ROOT",ì "SCANCUR", and "DU". If the byte after "PATH" is a zero, then ARUNZ willì look in the specific drive and user areas indicated by the two bytesì following the string "DU". The first byte is for the drive and has a valueì of 0 for drive A, 1 for B, and so on. The second byte has the user numberì (00H to 1FH). If the byte after the string "PATH" is not zero, then some form of pathì search will be performed depending on the settings of the bytes after theì strings "ROOT" and "SCANCUR". If the byte after "ROOT" is zero, then theì entire ZCPR3 path will be searched. If the byte after "SCANCUR" is nonzero,ì then the currently logged drive and user will be included at the beginningì of the path. If the byte after "ROOT" is nonzero, then only the rootì directory (last directory specified in the path) will be searched, and theì byte after "SCANCUR" is ignored. My general recommendation is to use either the root of the path or aì specified DU, especially when ARUNZ is being used as the extended commandì processor. It can take a great deal of time to search the entire pathì including the current directory. With ARUNZ as the ECP this will be doneì every time you make a typing mistake in the entry of a command name, and theì extra disk accesses can get quite tedious and annoying. Use Register for Path Control There is an alternative way to control the path searching options thatì can give one the best of all possible worlds. After the string "REG" oneì can patch in a value of a user register, the value of which will be used toì specify the path search options PATH, ROOT, and SCANCUR instead of the fixedì configuration bytes described above. Any one of the full set of 32 ZCPR3 registers can be specified for thisì function by patching in a value from 00H to 1FH. If any other value isì used, the fixed configuration bytes will be used. If a valid register isì specified, its contents are interpreted as follows: bit 0 PATH flag (0 = use fixed DU; 1 = use path) bit 1 ROOT flag (0 = use entire path; 1 = use root only) bit 2 SCANCUR flag (0 = use path only; 1 = include current DU) By changing the value stored in the specified register, one can change theì way ARUNZ looks for the ALIAS.CMD file dynamically depending on theì circumstances. è Plans for the Future I don't have much writing stamina left, but I would like to finish withì a few comments about developments I would still like to see in ARUNZ. A fewì were mentioned in the main text above. There is a need for some additionalì parameters, such as register values in various decimal formats. One alsoì needs more flexible access to the directory specification part of a token. ì The present parameters only allow extracting a DU reference, and they don'tì allow any way to tell if an explicit directory is specified. There shouldì be a parameter that returns whatever DU or DIR string (including the colon)ì is present. If none is present, the parameter should return a null string. One of the things hampering the additional of more parameters is theì arcane form they presently take. I would like to find a much more rationalì system (and if you have any suggestions, I would love to hear them). I amì thinking of something like $S for system file, followed by 'F', 'N', or 'T'ì and then a number 0..3. Thus $ST2 would read Systemfile-Type-2. Commandì line tokens might be $T followed by 'D', 'U', 'P', 'F', 'N', or 'T' and thenì a digit 0..9 or 1..9. The 'P' option (path) would be the DU or DIR prefix,ì if any, including the colon. Problem: what letter do I use for the namedì directory or the path without the colon? The logical choices 'N' and 'D'ì are already used. Maybe I have to go to four letters: $T for token,ì followed by 'D' for directory part or 'F' for file part. The 'D' could beì followed by various letters (again, I am not sure what to use for all ofì them) to indicate: 1) the equivalent drive or default if none specified 2) the equivalent drive or null string if none specified 3) the same two possibilities for the user number 4) the equivalent or given named directory (but what if the directory has no name) 5) the whole directory prefix as given either including or not including the colon Similarly, the 'F' option could be followed by a letter to indicate theì whole filename, the name only, or the type only. As you can see, it is notì easy to identify all the things one might need and find a rational way toì express them all. It would be nice to have prompted input where the user's input could beì used in more than one place in the command line. User input would have toì be assigned to temporary parameters ($U1, $U2, and so on). Perhaps thereì should be the possibility of specifying default values for command lineì tokens when they are not actually given on the command line (as in ZEX). Itì might also be useful to be able to pull apart a token that is a list ofì items separated by commas. ARUNZ could use better error reporting for badly formed scripts. Atì present one just gets a message that there was an error in the script, butì there is no indication of what or where the error was. Ideally, theì interpreted line should be echoed to the screen with a pointer to theì offending symbol (NZEX has this).è There should be an option to have ARUNZ vector control to the ZCPR3ì error handler whenever it cannot resolve the alias or when there is a defectì in the script. At present, chaining to the error handler only occurs whenì ARUNZ has been invoked as an ECP. An intriguing possibility is to allow alias name elements to be regularì expressions in the Unix (or JetFind) sense. Then one could give an aliasì name like "[XS]DIR" to match either XDIR or SDIR. Perhaps there could be aì correspondence established between non-unique expressions and a parameterì symbol in the script. Then all my KMD aliases might be simpler: S[P]*[K]* kmd s$x1$x2 $* The name would read as follows: 'S' followed by zero or more occurrences ofì 'P' followed by zero or more occurrences of 'K'. The parameter $X1, forì example, would be the first regular expression, i.e., the 'P' if present orì null if not. This is fun to think about, but I am not at all sure that itì would really be worth the trouble to use or to code for. Any comments. It would also be nice to provide Dreas Nielsen's RESOLVE facilityì directly in ARUNZ aliases. These would use the percent character ('%') as aì lead-in. Any symbol enclosed in percent signs would be interpreted as aì shell variable name, and its value from the shell file would be substitutedì for it in the command line. The parameter '$%' would be used to enter aì real percent character. Next Time As usual, I have written much more than planned but not covered all theì subjects planned. I really wanted to discuss shells in more detail,ì particularly after the fiasco with the way WordStar 4 behaves by trying toì be a shell when it should not be. That will have to wait for next time, Iì am afraid. Also by next time I should be ready to at least begin theì discussion of ZEX. [This article was originally published in issue 31 of The Computer Journal, P.O. Box 12, South Plainfield, NJ 07080-0012 and is reproduced with the permission of the author and the publisher. Further reproduction for non- commercial purposes is authorized. This copyright notice must be retained. (c) Copyright 1988, 1991 Socrates Press and respective authors]