The Computer Journal, Issue 35
Z-System Corner
© Jay Sage
Reproduced with permission of author and publisher.
My column about shells and WordStar Release 4 (WS4) in TCJ issue #33 prompted more than the usual level of commentary. There were extensive discussions on Z-Node-Central and the Lillipute Z-Node (the official TCJ bulletin board), and several messages reached me over the ARPA network. Not all of the comments were favorable, but I was nevertheless happy to receive them. They helped further clarify my thinking on the very important subject of shells and have spurred me on to prove my points by actually converting WS4 to a ZCPR2-style shell! After a bit of follow-up discussion, I will describe how this conversion was accomplished.
Corrections
There were some things I said in the previous column that were factually wrong, and before I do anything else I wish to correct them.
First, I stated that the Z-System code in WS4 was written by someone other than MicroPro. I was wrong. David McCord, who was vice president at Echelon at the time WS4 was developed, sent me a message with the facts of this matter. Echelon, through staff like David and through published materials, educated Peter Mireau of MicroPro on the facilities and philosophy of Z-System. Peter did all the actual programming, so the coding mistakes were his fault, not Echelon's or David's.
From a broader perspective, however, as I stated in the previous column, the real culprit was inadequate testing. Bugs in the code would have been discovered and conceptual issues clarified had more people in the Z community been involved as beta testers. There are so many different styles of using Z-System that it takes a number of testers to uncover problems. Within days after copies of WS4 were delivered to users of my Z-Node, I started getting questions about strange behavior exhibited by WS4, behavior that turned out to result from its operation as a shell.
A second mistake in the earlier column was my implication that WS4 does not get its own name from the ZCPR3 external file control block (XFCB). I no longer remember what made me think that this was the case, but David McCord assured me (and I have now verified for myself) that WS4 does, indeed, get its name from the XFCB when it sets up the shell stack entry.
Finally, one reader reported to me that my WSSHLOFF routine (the one that completely disables shells while WS4 is running and reenables them when WS4 terminated) crashed his system. Unfortunately, a large number of misprints crept into the listings in going from my disk file to the printed pages. Most of the typos were obvious, but one was compounded by a double error. In the WSSHLOFF listing, the value for EXITSUB was printed as 03BVh. The 'V' was obviously a mistake, and clever readers looked at the similar listing for WSSHLFIX, where the value was given as 03B3h. This, regrettably, looks correct but was also a typo. The proper value is 03BEh. We hope that Art Carlson will make sure that the listings in this column are transcribed accurately (so that all the mistakes will be mine!).
More WS4 Comments
While on the subject of WS4, I would like to add a few further comments about how it works. Not surprisingly (considering when it was developed), in creating its shell stack entry WS4 does not make use of the facility introduced with ZCPR version 3.3 that allows a program to determine from the XFCB not only its name but also the directory from which it was actually loaded (the user number is at offset 13 and the drive, with A=1, at offset 14).
As a result, in order for WS4 to be reinvoked as a shell, the command search path must include the directory in which WS4 is located. I mention this here as a reminder and suggestion to authors of new or updated shells and error handlers that they use this Z33 facility to avoid the requirement that the program be on the path and to speed up loading of the program (by eliminating any search for it). My WordStar conversion described later adds this feature.
With WS4 it is generally necessary that the command search path include WS4's directory for an additional reason. I learned the hard way that when WS4 runs under Z-System, it pays no attention to the drive and user number that WSCHANGE specified as the location for the overlay files; it only uses the search path to try to locate them.
This is a problem for me because, as I have explained at length in previous columns, I put only my small RAM disk on the path and use ARUNZ aliases to invoke all programs except the very few that fit on the RAM disk. With this approach, there is no way to get WS4 to find its overlay files. The conversion addresses this problem also.
ZCPR2 vs. ZCPR3 Shells
I would not like to take up again one of the subjects raised in issue #33: ZCPR2-style versus ZCPR3-style shells.
First an aside. Shells seem to be a surprisingly emotional issue. I thought my earlier column presented a fairly carefully and calmly reasoned discussion of some aspects of shells, including their pros and their cons. Some readers, however, took great offense at my even questioning the current method of implementing shells or of what some people are trying to do with them.
One reader went so far as to suggest that I had no business commenting on the subject when, by my own admission, there are a number of shells that I have never used. Besides the fact that this is hardly a reasoned argument, I would like to make sure that the following facts about shells are fully appreciated.
ZCPR3-style shells are a facility of the command processor. Without special code in the CPR, there would be no such shells. As the author of the two latest versions of the ZCPR command processor, I think I can speak with some authority (though certainly not with infallibility) on the subject, since in writing that code I had to consider the issue of shells rather carefully from a rigorous theoretical viewpoint.
ZCPR2-style shells, quite the contrary, are not a facility of the command processor; they are a facility of the individual shell programs. Their functioning depends only on the operation of the multiple command line facility. The command processor does not treat a Z2 shell command any differently than it treats any other command. This is really the key to the difference between the two shell implementations.
In the previous column I stated: "...I am coming to the conclusion that only programs like history shells...should be implemented as ZCPR3-style shells. Other programs, like ZFILER and WordStar should use the ZCPR2 style." I then invited readers to enlighten me if I was missing some important point. I got some responses to this invitation, but no one yet has offered me any evidence that I had missed any important point.
One reader reiterated essentially the same difference between Z2 and Z3 shells that I attempted to demonstrate with my example in which WordStar was invoked in a multiple command line. Apparently the point bears repeating.
This reader presented the point using a command line like the following:
ZFILER;ECHO TESTING
Under ZCPR2, ZFILER would run and present its file display to the user. If the user generated a command line "CMDLINE" as the result of a macro or in response to the prompt after the 'Z' command, a Z2-shell version of ZFILER would build the command sequence "CMDLINE;ZFILER" and insert it into the multiple command line buffer just before the next command to be executed. This would give:
CMDLINE;ZFILER;ECHO TESTING
The user's command line would run, and then ZFILER would be invoked again. Only on termination of ZFILER would the last command, "ECHO TESTING", be performed.
A Z3 shell would respond to the same command line from the user in quite a different way. As before, ZFILER would be invoked first. It would determine from the Z3 message buffer that it had been invoked manually and would respond by pushing its own name onto the shell stack. Then it would terminate. The command processor would then proceed to run "ECHO TESTING". Only after that, once the command line was empty, would ZFILER be reloaded, this time as a shell. Recognizing its shell status, it would now display its screen of file names and do its real work.
The reader who submitted this example, if I understood him correctly, viewed the Z3 behavior as correct and the Z2 behavior as wrong. If you are an experienced Z-System user, you will probably recognize in this reader a fellow expert (and, indeed, he is). He is so used to ZCPR3 that he no longer notices that it is the behavior of the Z3 shell that is truly bizarre!
Consider the following two command lines:
(1) ZFILER;ECHO TESTING
(2) ECHO TESTING;ZFILER
We have already analyzed the first one; the second one can safely be left as an exercise for the reader. We will simply state the answer that under ZCPR3 they will accomplish exactly the same thing! This is hardly a result that conforms to intuition, and I still remember in my early days as a Z-Node sysop trying to explain to quite a few users why the second command on a VFILER command line executes first!
Under ZCPR2 the result is just what one would expect. In the first case, ZFILER runs first, and ECHO runs only after the user terminates ZFILER using its 'X' command. In the second case, ECHO runs first and ZFILER second. In other words, with Z2 shells, commands are executed in the order they are entered, a notion that does not require long experience and great expertise to understand and get used to! And it gives the user a greater measure of control.
Mixed Z2 and Z3 Shells
The same reader submitted another interesting example that illustrates the confusing behavior that can arise when Z2 and Z3 shells are mixed. Here we assume that WordStar has been implemented as a Z2 shell and ZFILER as a Z3 shell. Suppose we use the 'R' command of WordStar to enter the command "ZFILER". WS4, as a Z2 shell, would generate the command line
ZFILER;WS
ZFILER, as a Z3 shell, would install itself on the shell stack and proceed to execute "WS". ZFILER would not run in its file maintenance mode until after we terminated WordStar.
This is, admittedly, probably not what one intended, since we most likely entered the ZFILER command with the intention of doing some file maintenance before returning to WordStar. On the other hand, it is certainly no more bizarre than what we saw in our earlier example.
If both WS4 and ZFILER were Z3 shells, then the invocation of ZFILER from the WS4 'R' command would cause it to become the active shell (the one on the top of the shell stack). The WS4 shell would be pushed down in the shell stack, and ZFILER would take control. With a little thought, however, you will see that the same is also true if both ZFILER and WS4 are Z2 shells!
The strange behavior with the mixed shells in the above example arises in part because ZFILER was not really being used as a shell in the Z3 sense, namely, as a replacement for the command processor's command-line input routine. It was intended as a file maintenance utility.
Suppose we had entered the command "EASE" (the Z3-type history shell) instead of "ZFILER" from our Z2 version of WordStar. This would establish EASE as the current shell and return to WordStar. That behavior would not seem strange, because in this case we would be thinking of our EASE command as establishing the shell to be used in place of the command processor the next time the command processor needed a new command line. So long as WordStar is running, there is no need for EASE to do anything. We expect it to take effect only after we are finished using WordStar.
Nested Z2 Shells and Recursive Aliases
Although I had once thought that the Z3 shell stack was required in order to nest shells, I showed in the earlier column that this is not the case. Z2-style shells can, in fact, be nested more flexibly. There is no predetermined limit to the nesting depth or to the amount of information that can be passed with each shell command line. The only limit is imposed by the length of the multiple command line buffer, just as with the nesting of aliases.
With the standard shell stack configuration of 4 32-byte entries, if a shell command uses only 16 bytes, 16 bytes are wasted. On the other hand, if a shell command needs 48 bytes to hold its information, it cannot run at all under this configuration (NZ-COM can come to the rescue by allowing the shell stack configuration to be changed on the fly). With Z2 shells, these problems go away. In 64 bytes of command line, one can have two 32-byte shell commands or a combination of one 16-byte shell command and one 48-byte shell command (or five 12-byte shell commands).
I did overlook one point when I described putting data for the shells on the command line. In the Z3 shell stack, one can include, after the shell command's terminating null, any binary data that one wishes. Thus 256 values are possible for each extra byte in the shell stack entry.
In order to carry shell data on the command line, several additional constraints apply. First, the command processor strips the high bits off all characters in the command line, so only 128 values are available to start with. Secondly, the null character cannot be used because the command processor would interpret this as the end of the command line (that leaves 127 values). Finally, letters are converted to upper case, thereby making the characters from 'a' to 'z' inaccessible (scratch another 26). This leaves only 101 possible values out of the original 256. Moreover, extra characters are required as flags to signal the program to consider itself as having been invoked as a shell (a service provided in ZCPR3 by a flag in the message buffer). All of these things reduce the efficiency with which the space in the command line buffer can be used compared to the space in the shell stack.
One reader pointed out that recursive aliases cannot be used with Z2-type shells. This is true... but only if one is using the pseudo-recursive alias that I invented. This kind of alias accomplishes a crude approximation to recursion by discarding any pending commands in the command line buffer. This will, indeed, discard any shell reinvocation commands. However, if one uses the logically sound and rigorous recursive alias technique invented by Dreas Nielsen (see my column in issue #28), there is no problem. It sometimes pays to do things right!
In fact, it seems to me that the Z2 shell is, in essence, a recursive alias, a program that keeps invoking itself. And this is just what most (if not all) Z3 shells actually do. I am still awaiting an example of something (good) that a Z3 shell can do that cannot be done in some equivalent way with a Z2 shell or recursive alias.
The Real Difference Between Z2 and Z3 Shells
After much reflection, I think I have finally put my finger on the fundamental distinction between Z2 and Z3 shells. It derives from the facts I alluded to earlier: that the Z3 shell is a true creature of the command processor and the Z2 shell is not.
Here is an example that will illustrate the point. Suppose the history shell EASE were implemented as a Z2-style shell and that while it is running, we issue the command "DIR". EASE will insert into the command line a sequence like the following:
DIR;EASE
DIR will run, and then EASE will be reinvoked. Looks fine! But now suppose the user enters the command "IF EXIST FN.FT". EASE will then generate the command line
IF EXIST FN.FT;EASE
If the file FN.FT exists, this will again work just fine, but suppose the file does not exist. Then the system will enter a false flow state, and the EASE command (and perhaps other commands pending in the command line after it) will be flushed by the command processor. The shell function will be lost, and any other pending commands will be processed in an unintended way.
For a Z2 shell to function properly in general, all command lines inserted by it must result in the same flow state at the end of the command line as at the beginning. With a MENU shell it could be possible for the system designer to guarantee this, since he can control which commands are generated by the shell. With a history type shell it would be nearly impossible to ensure that this condition would always be met.
The critical feature of shell processing under ZCPR3 is that _flow processing is suspended during the operation of shells_. This allows them to run, as they must, even after the user has passed a command that leaves the system in a false flow state. The ZCPR33 Users Guide goes into some detail on this matter, and had I remembered better what I wrote there, it would not have taken me this long to come to the essence of the Z2-vs.-Z3 shell issue.
Some users of ZCPR33 have modified the way the command processor deals with flow control in shell processing. No one has yet convinced me of the value of this (the risks are undeniable). It still seems to me that Z2-type shells and recursive aliases can accomplish the same thing, but in a logically sound way.
I have extended an invitation to Dreas Nielsen to write a series of columns for TCJ explaining his very powerful shell programs. Since he is also one of the people who has made this modification to the CPR, perhaps he will also present the other side of this story and explain why it is necessary or desirable to treat shells the way he does.
Remaking WordStar Release 4
When I first received my copy of WordStar 4 and encountered problems with the way it handled shells, I fired up the DSD debugger and tried to figure out how to fix it. After a considerable amount of rummaging about in the code (and especially trying to figure out what was going on inside WS.OVR), I gave up. Later I tried again... and failed again. In the course of preparing this column, I decided to have one more go at it, and this time things started to click.
The patches I will describe here are preliminary and have not yet been extensively tested. In fact, as I write this, I am the only one who has used them, and you know what I said above about the dangers of a test program that does not involve a variety of Z-System users. So, you are hereby recruited, if you are willing, to join the test program.
Since I may very well have made some mistakes, and since there are further changes that people may want to make (let's hear your suggestions), I will not only give the results; I will describe the process by which these patches have been developed.
Cracking the Code
The first step toward changing the code was figuring out how the virgin WordStar was doing what it did. In particular, I wanted to locate routines related to Z-System functions, so the first thing I tried was searching for all references to address 109h, which contains the address of the Z-System environment (ENV). Any WS4 feature that made use of a Z-System facility would have to get information from the ENV.
As best I recall, this did not turn up many references and did not particularly help (though it was a good idea, and that's why I mention it). In the end, I just started tracing the code from the beginning, figuring that WS4 would have to determine fairly early whether it was running under Z-System or standard CP/M. This turned out to be correct, and very soon I came to the key Z routine, at address 0AA4h in WS.COM. This routine returns the address and size of a Z-System module specified by an offset passed in the E register.
Having discovered this routine, I used DSD to find all references to it in WS.COM and WS.OVR. They occur with the following values of E:
E = 9h the command search path (PATH) E = 15h the named directory register (NDR) E = 18h the multiple command line buffer (MCL) E = 1Eh the shell stack (SHL) E = 22h the message buffer (MSG) E = 24h the external file control block (XFCB)
Setting up the Shell Stack
The block of code beginning around address 3CBFh in WS.OVR makes references to MCL, XFCB, and SHL. I guessed correctly that this had to be the code where WS4 sets up its shell stack entry. (This block of code, by the way, is where the shell-pushing mistake occurs for the case where the shell stack is currently empty.)
The patch for this part of WS.OVR (see Listing 1) modifies this code. First of all, since WS4 is going to operate as a Z2-type shell, we do not want it to do anything with the shell stack. It is easy to disable the code by simply skipping over it, but one has to watch out for subtleties. Indeed, in order for the 'R' command to use the MCL and not chain using the greatly inferior CP/M method, WS4 has to think that the shell entry was established successfully.
I noticed that a flag was being set into address 2200h, and I surmised that it is used by WS4 to show that it is running under Z-System. In the patch, I set this flag even though the shell stack entry is not being set up. I have not examined all references to this flag, and there is a chance that there are additional, more complex effects. If any problems appear with the patched version of WordStar, this flag might be involved. For the initial attempt at fixing WS4, I just took the easiest course of action, and so far it appears to have worked.
It seemed foolish to waste space in WS.OVR by doing nothing more than setting the flag and jumping to where the original code resumed (60AAh). Instead, I have used the space to compute the command line necessary to reinvoke WordStar. The code gets not only the name by which WordStar was invoked but also the drive and user number from which it was loaded. A command line of the form ";DUU:WSNAME" is generated.
There is one extra step in this part of the patch. When running as a Z3 shell, WS4 knows from the command status flag in the message buffer when it was invoked as a shell so it can put up the press-any-key message before clearing the screen and resuming operation. As a Z2 shell, WS4 cannot use this facility. Instead, a signal has to be included in the command tail. For reasons that I will not go into in full detail, I chose for this signal a comma at the very end of the tail. Very briefly, the comma is a handy character because it is not parsed into the default file control blocks, where a program could confuse it with a file name.
The final reinvocation command line, with its terminating null, takes the form
;DUU:WSNAME ,<0>
Since I could not be sure that this section of overlay code would persist in memory until the command would be used, I store it at the top of the WS4's user patch area (MORPAT).
The Initialization and Termination Patches
Having made the above modification, we must make two others in order to remain consistent. First, we must modify the WS4 initialization code in which it determines whether or not it was invoked as a shell. This is the patch at address 1A2Fh in WS.COM. The patch calculates the address of the last character passed in the command tail and checks to see if it was a comma. If not, it proceeds with normal operation of the program.
If there is a comma, the shell-wait message must be displayed until the user presses a key. But one must also remove the comma from the command tail to ensure that WordStar not think it has been passed a file name. At present I do this by replacing the comma with a space. This is not rigorous, but it seems to work, since WS4 is apparently not confused by a tail consisting only of spaces (unfortunately, a number of programs are).
Since WS4 no longer pushes its name onto the shell stack, we must also prevent it from popping the shell stack when it terminates. This is the patch at address 13CEh in WS.COM. This is the easiest patch of all, since we simply have to skip some code. As an additional benefit, this frees up about 40 bytes of space that we use for some of our other patch code.
Fixing the 'R' Command
Now we come to the main item in this set of patches - the code that makes the 'R' command work as a ZCPR2-type shell. The new code here is much more complex than what it replaces, and we can only fit part of it at the original location 67B2h in WS.OVR. We put what we can there and continue with the rest in the MORPAT area in WS.COM.
The basic strategy is to take the command line entered by the user in response to the 'R' command prompt, append the WS reinvocation command (including its semicolon separator), and append any remaining command line pending in the multiple command line buffer (if there is one, it will begin with a semicolon also). If there is enough room for the result in the MCL, then it is moved there and chained to. If not, a warning message is displayed on the screen until a key is pressed, and the user command is ignored.
To implement this strategy, I chose the simplest method I could think of. Since the 'R' command operates from the WordStar no-file menu, the entire WS edit buffer is available as a scratch area. I picked an arbitrary address of A000h for a buffer in which to build the new command line. Again, rigorous code calculate the address. My code is a quick-and-dirty solution.
Finding the Overlay Files
As I noted earlier, with my style of operation, WS4 had trouble finding its overlays. To solve that problem, the patch includes an optional section to install an internal search path for the overlay files. This patch is installed at address 0F5Fh in WS.COM, where it replaces a call for the location of the Z-System path with a call to a routine that returns the address and size of an internal path. In Listing 1 the internal path has the single element B4:, the directory in which I keep my WordStar program files. You can put any values you want here.
Installing the Patches
It is not possible to install the patches in WS.OVR using MLOAD or a debugger, because the OVR file is too large to load entirely into memory. ZPATCH, on the other hand, can handle the job splendidly. ZPATCH assumes an offset of 0000 for a file of type OVR, while the addresses in the listing are those shown when the file (as much as can fit) is read into memory under a debugger. To make things consistent, you should use the ZPATCH 'O' command to set the offset to 100.
Key in the new data carefully, checking from time to time that the address is still correct. Also, be careful not to go beyond a record boundary while in ZPATCH. It wraps from the end of the record back to the beginning of that record without warning (this really gave me grief until I caught on to the problem). When you get to the end of the current record, write it out (^W), advance to the next record (>), and reenter edit mode (E). Then you can resume entering data.
The attached listing was made with a specially configured version of the SLR Z80ASM assembler. Normally, I have it display addresses in logical order for easier interpretation. For hand keying of a patch, however, it is far more convenient to have the bytes of a word in physical order. Just watch out when reading the displayed symbol values. They, too, are stored in byte-reversed format.
It is possible to use MLOAD to install just the patches for WS.COM. Simply delete the parts of WSPAT.Z80 that refer to patches in WS.OVR and assemble the remaining code to a HEX file.
Enjoy playing with (and using) this different (improved) version of WordStar 4, and let me know what you think and what further suggestions you have.
Listing
; Program: WordStar Shell Modification Patches
; Author: Jay Sage
; Date: August 7, 1988
;--------------------------------------------------------
;
; PATCHES TO WS.OVR
;
;--------------------------------------------------------
3CBF 1E 24 ld e,24h
3CC1 CD A40A call envoff
3CC4 E5 push hl
3CC5 11 0D00 ld de,0dh
3CC8 19 add hl,de
3CC9 46 ld b,(hl)
3CCA 23 inc hl
3CCB 7E ld a,(hl)
3CCC C6 40 add a,'A'-1
3CCE 21 CB04 ld hl,namebuf
3CD1 36 3B ld (hl),'
3CD3 23 inc hl
3CD4 77 ld (hl),a
3CD5 23 inc hl
3CD6 78 ld a,b
3CD7 0E 2F ld c,'0'-1
3CD9 tens:
3CD9 0C inc c
3CDA D6 0A sub 10
3CDC 30 FB jr nc,tens
3CDE C6 3A add 10+'0'
3CE0 71 ld (hl),c
3CE1 23 inc hl
3CE2 77 ld (hl),a
3CE3 23 inc hl
3CE4 36 3A ld (hl),':'
3CE6 23 inc hl
3CE7 D1 pop de
3CE8 06 08 ld b,8
3CEA copyname:
3CEA 13 inc de
3CEB 1A ld a,(de)
3CEC FE 20 cp ' '
3CEE 28 05 jr z,copydone
3CF0 77 ld (hl),a
3CF1 23 inc hl
3CF2 05 dec b
3CF3 20 F5 jr nz,copyname
3CF5 copydone:
3CF5 36 20 ld (hl),' '
3CF7 23 inc hl
3CF8 36 2C ld (hl),','
3CFA 23 inc hl
3CFB 36 00 ld (hl),0
3CFD 3E FF ld a,0ffh
3CFF 32 0022 ld (zflag),a
3D02 C3 AA60 jp 60aah
;--------------------------------------------------------
67B2 21 381F ld hl,rcmdbuf
67B5 4E ld c,(hl)
67B6 06 00 ld b,0
67B8 23 inc hl
67B9 11 00A0 ld de,scratch
67BC ED B0 ldir
67BE 21 CB04 ld hl,namebuf
67C1 CD D113 call cpy2nul
67C4 C3 5B04 jp morpat
;--------------------------------------------------------
;
; PATCHES TO WS.COM
;
;--------------------------------------------------------
045B D5 push de
045C 1E 18 ld e,18h
045E CD A40A call envoff
0461 5E ld e,(hl)
0462 23 inc hl
0463 56 ld d,(hl)
0464 EB ex de,hl
0465 D1 pop de
0466 CD D113 call cpy2nul
0469 21 8603 ld hl,clrscr
046C CD C717 call scrnfn
046F 1E 18 ld e,18h
0471 CD A40A call envoff
0474 11 00A0 ld de,scratch
0477 47 ld b,a
0478 lenloop:
0478 1A ld a,(de)
0479 B7 or a
047A 28 11 jr z,oklength
047C 13 inc de
047D 10 F9 djnz lenloop
047F 11 9F04 ld de,errmsg
0482 0E 09 ld c,9
0484 CD 0500 call 0005h
0487 CD 491A call sak
048A C3 4E7F jp 7f4eh
048D oklength:
048D 11 0400 ld de,4
0490 EB ex de,hl
0491 19 add hl,de
0492 EB ex de,hl
0493 73 ld (hl),e
0494 23 inc hl
0495 72 ld (hl),d
0496 21 00A0 ld hl,scratch
0499 CD D113 call cpy2nul
049C C3 F613 jp 13f6h
049F errmsg:
049F 07 4D 43 4C db bell,'MCL Ovfl - press any key...$'
04A3 20 4F 76 66
04A7 6C 20 2D 20
04AB 70 72 65 73
04AF 73 20 61 6E
04B3 79 20 6B 65
04B7 79 2E 2E 2E
04BB 24
;--------------------------------------------------------
0F5F CD D913 call setpath
0F62 00 nop
0F63 00 nop
;--------------------------------------------------------
13CE C3 F613 jp 13f6h
13D1 cpy2nul:
13D1 7E ld a,(hl)
13D2 12 ld (de),a
13D3 B7 or a
13D4 C8 ret z
13D5 23 inc hl
13D6 13 inc de
13D7 18 F8 jr cpy2nul
13D9 setpath:
13D9 21 E013 ld hl,path0
13DC 7E ld a,(hl)
13DD 23 inc hl
13DE B7 or a
13DF C9 ret
13E0 02 path0: db 2
13E1 02 db 2
13E2 04 db 4
13E3 00 00 db 0,0
13E5 00 db 0
;--------------------------------------------------------
1A2F 21 8000 ld hl,80h
1A32 6E ld l,(hl)
1A33 CB FD set 7,l
1A35 7E ld a,(hl)
1A36 FE 2C cp ','
1A38 20 25 jr nz,1a5fh
1A3A 36 20 ld (hl),' '
1A3C 11 101B ld de,1b10h
1A3F 0E 09 ld c,9
1A41 CD 0500 call 0005
1A44 CD 491A call sak
1A47 18 16 jr 1a5fh
1A49 sak:
1A49 1E FF ld e,0ffh
1A4B 0E 06 ld c,6
1A4D CD 0500 call 0005
1A50 B7 or a
1A51 28 F6 jr z,sak
1A53 1E 0D ld e,0dh
1A55 0E 06 ld c,6
1A57 C3 0500 jp 0005
WSPAT.Z80
; Program: WordStar Shell Modification Patches
; Author: Jay Sage
; Date: August 7, 1988
; Patches to make the WordStar Release 4 'R' command operate as a ZCPR2-type
; shell. Several routines in WS.COM and WS.OVR must be changed.
;
; 1. WordStar must be prevented from pushing its name onto the Z-System shell
; stack. However, a flag that is used by the 'R' command to determine how
; to operate must be set as if WS4 had set itself up as a shell.
;
; 2. The popping of the shell stack when WS4 terminates must be disabled.
;
; 3. The user input to the prompt from the 'R' command must be handled
; differently. A command to reinvoke WS4 must be appended to the user's
; input, and then any commands pending in the multiple command line buffer
; must be added as well. The result is then placed into the command line
; buffer. If overflow occurs, the user command is ignored, and an error
; message is displayed until a key is pressed. The chaining command is of
; the form ";DUU:WSNAME ,". The comma at the end of the command tail is
; used as a signal that WS4 was invoked as a ZCPR2 shell.
;
; 4. An optional patch can be included to defeat the use of the path for
; searching for the overlay files. An internal path can be specified.
;------------------------------------------------------------
no equ 0
yes equ not no
intpath equ yes ; Use internal path to find OVR files?
morpat equ 045bh ; Patch area
namebuf equ morpat+128-16 ; Keep program ";DUU:PROGNAME ,<0>"
; ..at end of patch area
envoff equ 0aa4h ; WordStar ENV offset routine
zflag equ 2200h ; Z-System running flag
rcmdbuf equ 1f38h ; Buffer for 'R' command input
rcmd equ rcmdbuf+1 ; Beginning of user's command line
clrscr equ 0386h ; Clear screen character sequence
scrnfn equ 17c7h ; Routine to perform screen functions
conout equ 0280h ; Routine to output character in A to console
bell equ 07 ; Bell character
;----------------------------------------------------------------------
;
; PATCHES TO WS.OVR
;
;----------------------------------------------------------------------
; Modifications to the code that pushes WordStar onto the shell stack.
; This patch prevents the WordStar shell entry from being set up, but it
; sets the flag in 2200h that makes WordStar think that it has set it up.
; In this way, the 'R' command will work as it would with shells engaged.
; The space is used to determine the command line needed to reinvoke
; WordStar. The ZCPR33 facility for returning the directory in which the
; program was located is used to provide an explicit DU: prefix. The
; resulting command line is kept at the end of the user patch area.
offset defl 2380h ; Real address = address in overlay + offset
org 3cbfh ; Place to install patch
ld e,24h ; Get pointer to XFCB
call envoff ; HL -> XFCB
push hl
ld de,0dh ; Offset to user number where WS.COM found
add hl,de
ld b,(hl) ; User number to B
inc hl
ld a,(hl) ; Drive to A
add a,'A'-1 ; Convert drive to letter
ld hl,namebuf ; Point to buffer at end of patch area
ld (hl),';' ; Command separator
inc hl
ld (hl),a ; Store drive letter
inc hl
ld a,b ; Now work on user number
ld c,'0'-1 ; Tens value
tens:
inc c
sub 10
jr nc,tens
add 10+'0' ; Convert units to ASCII
ld (hl),c ; Stash tens digit
inc hl
ld (hl),a ; Stash units digit
inc hl
ld (hl),':' ; Insert colon
inc hl
pop de ; Get pointer to XFCB again
ld b,8 ; Maximum of 8 letters
copyname:
inc de ; Advance to next letter
ld a,(de)
cp ' '
jr z,copydone ; Quit at first space
ld (hl),a
inc hl
dec b
jr nz,copyname ; Quit after eight characters
copydone:
ld (hl),' ' ; Put shell signal tail (a comma)
inc hl
ld (hl),','
inc hl
ld (hl),0 ; Put in terminating null
ld a,0ffh ; Fool WS into thinking shell installed
ld (zflag),a
jp 60aah
end1pat:
endaddr defl 60aah - offset
free defl endaddr - end1pat
if $ gt endaddr
ERROR: Patch to shell installation at 3CBFh is too long
endif
;------------------------------------------------------------
; This patch takes the user's response to the 'R' command, adds the command
; to reinvoke WordStar, and appends any pending commands in the command line
; buffer. The result is written out to the command line buffer. This
; implements a ZCPR2-style shell for the 'R' command.
; If the resulting command line is too long for the MCL, an error message is
; displayed until a key is pressed, and then WS resumes as if no command line
; had been entered.
; The first part of this patch replaces code in WS.OVR. There is not enough
; space there for all the code, so it continues in the user patch area.
offset defl -1e00h ; Real address = address in overlay - offset
scratch equ 0a000h ; Area to use as scratch buffer
org 67b2h ; Address in WS.OVR
ld hl,rcmdbuf ; Point to 'R' command buffer
ld c,(hl) ; Get length into BC
ld b,0
inc hl ; Point to user's command
ld de,scratch ; Scratch buffer in RAM
ldir ; Copy user's command to buffer
ld hl,namebuf ; Point to WS4 reinvocation command line
call cpy2nul ; Copy through ending null
jp morpat ; Continue in patch area
end2pat:
free defl 67cbh - end2pat
if $ gt 67cbh
ERROR: Patch to command-line code at 67B2h is too long
endif
;----------------------------------------------------------------------
;
; PATCHES TO WS.COM
;
;----------------------------------------------------------------------
; This is the continuation of the patch in WS.OVR that inserts the user's
; command line, together with the WS reinvocation command, into the multiple
; command buffer.
org morpat
push de ; Save pointer to buffer
ld e,18h ; Get pending commands from MCL
call envoff
ld e,(hl) ; Get pointer to next command into DE
inc hl
ld d,(hl)
ex de,hl ; Switch into HL as source for copy
pop de ; Destination pointer into buffer
call cpy2nul ; Copy through ending null
ld hl,clrscr ; Clear the screen
call scrnfn
ld e,18h ; Get MCL pointer
call envoff ; HL -> MCL buffer, A = max characters
; Check length of new command
ld de,scratch ; Point to new command line
ld b,a ; Max length in B
lenloop:
ld a,(de)
or a
jr z,oklength
inc de
djnz lenloop
ld de,errmsg ; Display error message
ld c,9
call 0005h
call sak ; Wait for key to be pressed
jp 7f4eh ; Pretend no user input
oklength:
ld de,4 ; Offset to command line in buffer
ex de,hl ; Reverse pointers
add hl,de
ex de,hl ; HL = MCL, DE = MCL+4
ld (hl),e ; Set up pointer in MCL
inc hl
ld (hl),d
ld hl,scratch ; Source for command line
call cpy2nul ; Copy it in
jp 13f6h ; Chain to command line from WS
errmsg:
db bell,'MCL Ovfl - press any key...$'
end3pat:
free defl namebuf - end3pat
if $ gt namebuf
ERROR: Patch in MORPAT is too long
endif
;------------------------------------------------------------
; This optional patch causes WS4 to use an internal path to locate
; its overlay files.
if intpath
org 0f5fh ; This is where z3 path location is determined
call setpath ; Call alternative routine
nop ; Must fill 5 bytes
nop
endif ;intpath
;------------------------------------------------------------
; Modification to the termination routine that pops the shell stack.
; This patch eliminates the popping of the shell stack on exit from
; WordStar. The space from the end of this patch to 13f6h is available
; for other uses (40 bytes).
org 13ceh
jp 13f6h ; Exit routine
; This routine copies the string pointed to by HL to the address pointed to by
; DE until a null byte is encountered. The null byte is copied as well.
cpy2nul:
ld a,(hl) ; Get source character
ld (de),a ; Put into destination
or a ; Check for null
ret z ; If so, quit
inc hl ; Bump up pointers
inc de
jr cpy2nul
; Alternative internal path routine
if intpath
setpath:
ld hl,path0 ; Point to internal path size
ld a,(hl)
inc hl ; Point to actual path
or a ; Set flags
ret
path0: db 2 ; Allow up to two elements
db 2 ; Drive (A=1)
db 4 ; User
db 0,0 ; Space for another entry
db 0 ; Terminating null
endif ;intpath
end4pat:
free defl 13f6h - end4pat
if $ gt 13f6h
ERROR: Patch in shell popping code at 13CEh is too long
endif
;------------------------------------------------------------
; Modification to initialization code where WS4 determines if it was
; invoked as a shell. We have defined a convention where a comma on
; the end of the command line signals WS4 to display its shell-wait
; message and wait for the user to press a key.
org 1a2fh
ld hl,80h ; Point to command tail
ld l,(hl) ; Get length into L
set 7,l ; In effect, add 80h
ld a,(hl) ; Get last character
cp ',' ; See if it is a comma
jr nz,1a5fh ; Not a 'shell', so go on ahead
ld (hl),' ' ; Get rid of the comma
ld de,1b10h ; Display 'shell wait' message
ld c,9 ; (note: message is trashed by other code and
call 0005 ; ..cannot be called from elsewhere)
call sak ; Wait for key to be pressed
jr 1a5fh ; Proceed normally
sak:
ld e,0ffh ; Poll console input status
ld c,6
call 0005
or a
jr z,sak ; ..until a key is pressed
ld e,0dh ; Echo carriage return
ld c,6
jp 0005
end5pat:
free defl 1a5fh - end5pat
if $ gt 1a5fh
ERROR: Patch to initialization code at 1A2Fh is too long
endif
end
[This article was originally published in issue 35 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]