The Computer Journal, Issue 37

Z-System Corner

© Jay Sage

Reproduced with permission of author and publisher.

The main topic for this column will be the second installment of the discussion of ZFILER, the Z-System filer shell (Yes, I'm going to fool you all by actually doing as I promised last time!). As usual, there are several other items I would like to discuss briefly first. The original list included the following: (1) a Z-Node update; (2) a hint on patching those hardware-specific utilities provided by computer manufacturers that don't work right under NZ-COM so that they will work; (3) my views on the appropriate way for Z-System programs to be coded for compatibility with various stages of evolution of ZCPR3; (4) an update on making PRL files without a PRL-capable linker; and (5) a suggestion to programmers for how to deal with bad-directory-specification errors under Z-System. As usual, including all this material put TCJ's ink supply at risk, and I had room only for the first two items. Now that I have finished the article and am coming back to hone this section, I also have to add that I did not have room to complete the ZFILER discussion; the topics of customization and configuration will have to wait until another time.

Z-Node Update

As I mentioned in a previous issue, I have been hard at work trying to survey the Z-Node remote access systems (RASs) and to revitalize the network. It was Echelon's creation of that network that first got me started as a Z-System activist, and I continue to feel that it is the single most important source of mutual support for users and developers of the Z-System.

My list of currently active nodes is reproduced in Listing 1:

                              Z-Node List #49
                     Sorted by State/Area Code/Exchange


Revised Z-Node list as of December 31, 1988.  An "R" in the left column
indicates a node that has registered with Z Systems Associates.  Report
any changes or corrections to Jay Sage at Z-Node #3 in Boston (or by mail
to 1435 Centre St., Newton Centre, MA 02159-2469).


  NODE      SYSOP         CITY        STATE  ZIP    RAS Phone      PCP     Verified

   57 Steve Kitahata    Gardena         CA  90247  213/532-3336  CALAN/24  11/01/88
R   2 Al Hawley         Los Angeles     CA  90056  213/670-9465  CALAN/24  12/11/88
   35 Norman L. Beeler  Sunnyvale       CA  94086, 408/245-1420  CASJO/12  11/01/88
   25 Douglas Thom      San Jose        CA  95129  408/253-1309  CASJO/12  11/01/88
   35 Norman L. Beeler  Sunnyvale       CA  94086, 408/735-0176  CASJO/12
R   9 Roger Warren      San Diego       CA  92109  619/270-3148  CASDI/24  12/11/88
R  66 Dave Vanhorn      Costa Mesa      CA  92696  714/546-5407  CASAN/12  10/30/88
R  81 Robert Cooper     Lancaster       CA  93535  805/949-6404            12/29/88
R  36 Richard Mead      Pasadena        CA  91105  818/799-1632            11/01/88

   27 Charlie Hoffman   Tampa           FL  33629  813/831-7276  FLTAM/24  10/30/88
R  15 Richard Jacobson  Chicago         IL  60606  312/649-1730  ILCHI/24  11/01/88
R   3 Jay Sage          Newton Centre   MA  02159  617/965-7259  MABOS/24  12/31/88
   80 Paul Harmon       Minneapolis     MN  55407  612/560-9122  MNMIN/12    down

R  33 Jim Sands         Enid            OK  73703  405/237-9282            11/01/88
R  58 Kent R. Mason     Oklahoma City   OK  73107  405/943-8638

R   4 Ken Jones         Salem           OR  97305  503/370-7655            09/15/88
   60 Bob Peddicord     Selma           OR  97538  503/597-2852            11/01/88
R  24 Ben Grey          Portland        OR  97229  503/644-4621  ORPOR/12  12/25/88

R   6 Robert Dean       Drexel Hill     PA  19026  215-623-4040  PAPHI/24  12/10/88
R  38 Robert Paddock    Franklin        PA  16323  814/437-5647            11/01/88

   77 Pat Price         Austin          TX  78745  512/444-8691            10/31/88
R  45 Robert K. Reid    Houston         TX  77088  713/937-8886  TXHOU/24  10/03/88

   12 Norm Gregory      Seattle         WA  98122  206/325-1325  WASEA/24  11/01/88
R  78 Gar K. Nelson     Olympia         WA  98502  206/943-4842            09/10/88

R  65 Barron McIntire   Cheyenne        WY  82007  307/638-1917            12/12/88

R   5 Christian Poirier Montreal Quebec   H1G 5G5 CANADA  514/324-9031     12/10/88
R  40 Terry Smythe  Winnipeg    Manitoba  R3N 0T2 CANADA  204/832-4593     11/01/88
   18 Bruce Smith   Mississauga Ontario   L5E 2E5 CANADA  416/823-4521

   26 Robert Kuhmann  Belle Etoile, par St. Martin de la Brasque
                      84760 FRANCE, 11-33-90-77-60-15 (from USA)

   69 R.C. Page      Waltham Abbey, Essex, EN9 3EE, ENGLAND
    
R  62 Lindsay Allen  Perth, Western AUSTRALIA 6153       61-9-450-0200     12/21/88
   50 Mark Little    Alice Springs, N.T. AUSTRALIA 5750  61-089-528-852

I have added three new columns to Echelon's original format. The one on the far right shows the last date on which operation of the system was verified. The column to its left indicates for nodes accessible by PC-Pursuit the code for the outdial city and the highest bit rate supported for that city.

At this point I have at least attempted (usually several times) to call every North American Z-Node on Echelon's old list. Where contact was made, I requested that the sysops register with Z Systems Associates, and the ones who have done so are designated by an "R" in the leftmost column. For this listing I have retained a number of systems that seemed still to be interested in the Z-System but have not yet registered. However, if I do not hear from them, they will be dropped from the next list. So, if you use one of those nodes (or one of the nodes I have already dropped), please let the sysop know that you want him to continue as a Z-Node, and suggest that he delay no longer in registering. Once we have all the sysops' names and addresses, we can start to think about things like a software distribution chain to make it easier for the nodes to stay current with Z-System software developments. Many of the boards I called had only very old versions of programs.

I would like to extend a special welcome to several new Z-Nodes, and I look forward to doing this in each column as more new nodes come on line. Bob Dean has for some time run the excellent Drexel Hill NorthStar system in Drexel Hill, Pennsylvania, just outside Philadelphia. When I saw what an enthusiastic Z-System supporter he was, I asked Bob if he would like to become a Z-Node. He was delighted and has joined the network as node number 6. Ted Harmon in Minneapolis has been working for some time at getting his node (#80) up, and I hope that he will be in regular operation by the time you read this. So far I have not succeeded in connecting with his node.

Bob Cooper in Ventura, California, is the newest node (#81), and from many voice conversations with him during the past couple of months I know how enthusiastic Bob is. His node is no in full scale operation. Since newly commissioned systems generally have fewer callers than established systems, their sysops would, I am sure, especially appreciate your calls.

Patching Programs for NZ-COM

As I described in an earlier column, NZ-COM creates a Z-System automatically from the host CP/M-2.2 system by setting up a virtual system underneath the original one and forwarding calls presented to the virtual BIOS (basic input/output system, the hardware-specific portion of the operating system code) to the "real" BIOS except for warm boots, which are intercepted to prevent a reloading of the host CP/M system. This produces a software environment that is indistinguishable from a manually installed Z-System, and all programs that adhere to CP/M or Z-System standards should run perfectly.

There is, however, a class of programs that generally do not follow those rules. These are most often utilities supplied by the manufacturer of the computer to perform special operations, such as configuration of the hardware. They usually make assumptions about the internals of the operating system code - in most cases, the BIOS - under which they are running. (Regrettably, they usually take no steps to verify that the environment is what they expect - see Bridger Mitchell's column in TCJ #36.)

Programs of this type generally do not run correctly under NZ-COM, just as they would not run correctly if the user rewrote his or her BIOS without taking into account the assumptions the manufacturer made as to the location of certain data structures in the BIOS. (This same problem is less likely to occur, I believe, in a Z3PLUS Z-System running under CP/M-Plus, because Z3PLUS operates as an RSX, which was a fully defined system facility under CP/M-Plus. Manufacturers' configuration utilities are more likely to understand RSXs and operate correctly under them.)

There are two approaches to dealing with this challenge. In many cases the configuration utilities are used only when the system is initially set up (and the newly configured system is then stored on the system tracks of the boot disk). In other cases the configuration utilities are used only when the system is cold booted (i.e., powered up). These situations pose no problem, since the hardware utilities can be run under standard CP/M before the NZCOM command is issued to invoke the Z-System.

In some cases, however, the configuration utilities are needed on a more regular basis. Utilities for setting baud rates, screen attributes, or printer characteristics may fall into this class. These situations can present a considerable nuisance to the computer user, who easily becomes so accustomed to the facilities of Z-System that he or she nearly loses the ability to operate under vanilla CP/M. I can suggest two possible solutions here.

One approach is to put the configuration utility in a directory that is not on the path (or to give it a new name) and invoke it indirectly by way of an alias. The alias would initiate a SUBMIT batch operation, as described in the NZ-COM manual, that would first remove the NZ-COM system using the NZCPM command, then run the configuration utility under vanilla CP/M, and finally reload the standard NZ-COM system. (If you are very clever, you can probably make an ARUNZ alias figure out which of several standard versions of NZ-COM is running and automatically reload it.) This approach will give the appearance of successful operation under NZ-COM of a utility that actually cannot run under it. The main penalty is the extra time it takes to exit from and return to the NZ-COM system. There is also a problem if you have loaded a module (RCP, FCP, NDR, etc.) that is not the one in your standard configuration. It will be lost.

The second approach is to make the utility work properly under NZ-COM. In many cases I have been able to accomplish this without the source code for the utility by using the technique described below. But be forewarned; the technique will not always work.

Most of these BIOS-specific utilities determine the address of the data structures to be modified by adding an offset to the BIOS warm boot entry point whose address is obtained from the warm boot vector (jump instruction) stored at address 0000H in a CP/M system. Usually the instruction LD HL,(0001) is used to load the address into the HL register. The problem is that under NZ-COM this vector points to the NZ-COM virtual BIOS, and offsets from it generally fall right in the middle of one of the Z-System modules. Not only does the utility fail to make the desired change to the machine's real BIOS; it even corrupts some other code, resulting in behavior that ranges from unpredictably bizarre to instantly catastrophic.

The simplest corrective patch consists of replacing the LD HL,(0001) indirect load instruction with a LD HL,WBOOT direct load instruction, where WBOOT is the actual warm boot entry point address of the real BIOS. This kind of patch is performed by using some utility to scan the utility's code for occurrences of the three-byte sequence 2A (load HL indirect immediate), 01, 00 (the immediate address 0001H). ZPATCH is a natural candidate for performing the search, but it unfortunately uses 00 as its string terminator and thus cannot search for a zero byte. Perhaps Steve Cohen will eliminate this minor shortcoming in a future version of ZPATCH (hint, hint - I know you're reading this column, Steve).

The next step is to replace the 2A byte with 21, the direct load opcode. The other two bytes, 01 and 00, are replaced by the BIOS address that you have determined previously (perhaps by looking at the contents of memory location 0001H while running normal CP/M). The low byte is entered first in place of the 01 (it will always be 03). The second byte will be a some relatively large number, almost always with a first hex character of D, E, or F.

Blindly replacing sequences as described above does have its risks. Without careful inspection you cannot be sure that the sequences are being used to perform the assumed function. If you are an experienced coder, you can use a disassembler (such as the one built into debuggers like DDT and DDTZ) to examine the code. The LD HL,(0001) should be followed fairly soon by an ADD HL,DE or ADD HL,BC to add the offset to the BIOS structure to be modified. There is also always the possibility that the utility gets the address it needs in some other way (for example, LD A,(0002) will get the page address of the BIOS).

The procedure I just described "hardwires" the utility to a BIOS at a specific address. This is fine until you someday set up a new CP/M host system with a different BIOS starting address or until you give this modified version to a friend with a different BIOS. By then you will have forgotten all about these patches and will be pulling your hair out trying to figure out why the utility that worked perfectly before is now misbehaving. By then you will also have forgotten exactly what was patched and will not know how to fix the utility.

A more sophisticated patch will allow the program to work with a BIOS at any address. This approach follows Bridger Mitchell's philosophy of "know your environment." The patch checks to see if it is running under NZ-COM and makes the changes only when it is.

Source code for this patch, which can be applied using the MLOAD utility, is given in Listing 2:

This is macro code that defines an ENV and TCAP for a CP/M system.

; PROGRAM:      CPMENV.LIB
; AUTHOR:       Jay Sage
; DATE:         June 16, 1991

; --------------------------------------------------------

; System configuration information (***** USER EDIT *****)

cpumhz  equ     4               ; CPU speed in MHz

; Operating system addresses and sizes.

biospg  equ     0d1h            ; Page where BIOS starts

bios    equ     100h * biospg
doss    equ     28              ; Size of DOS in records
dos     equ     bios - 80h * doss
ccps    equ     16              ; Size of CCP in records
ccp     equ     dos - 80h * ccps

; Information about drives and user areas available

;               PONMLKJIHGFEDCBA
drvec   equ     0000000000001111B
highdsk equ     'D'             ; Letter of highest drive
maxdisk equ     highdsk - '@'   ; Highest drive (A=1)
maxuser equ     31              ; Highest user area

; Data about console screen and printers

crtwid  equ     80              ; Width of CRT screen
crtlen  equ     24              ; Number of lines on screen
crtuse  equ     crtlen -2       ; Number of lines to use

prtwid  equ     80              ; Printer width
prtlen  equ     66              ; Printer total length
prtuse  equ     prtlen - 8      ; Printer lines to use
prtff   equ     1               ; Formfeed flag (1 if used)
                           
; --------------------------------------------------------

; Here is a macro to define and internal ENV for use
; under CP/M.

cpmenv  macro

        jp      0       ; Dummy jump address

        db      'Z3ENV' ; Environment ID
        db      81h     ; ENV type

        dw      0       ; external path
        db      0       ; elements in path

        dw      0       ; RCP address
        db      0       ; number of records in RCP

        ; LOTS MORE OMITTED

        dw      intenv  ; ZCPR3 Environment Descriptor
        db      2       ; number of records in ENV

        ; LOTS MORE ZERO VALUES

        db      cpumhz  ; Processor Speed in MHz

        db      maxdisk ; maximum disk
        db      maxuser ; maximum user

        db      1       ; 1=OK to accept DU, 0=not OK

        db      0,0

        db      crtwid  ; width of CRT
        db      crtlen  ; number of lines on CRT
        db      crtuse  ; number of lines of text on CRT

        dw      drvec
        db      0

        db      prtwid  ; data for printer
        db      prtlen
        db      prtuse
        db      prtff

        db      0,0,0,0

        dw      ccp
        db      ccps

        dw      dos
        db      doss

        dw      bios

        db      'SH      '      ; shell variable filename
        db      'VAR'           ; shell variable filetype

        db      '        '      ; filename 1
        db      '   '           ; filetype 1

        ; MORE SIMILAR DATA

;  Fill unused space with nulls

        rept    128-($-intenv)
        db      0
        endm

;  End of Environment Descriptor -- beginning of TCAP

; ***** USER EDIT *****

; Extended Termcap Data

ESC     EQU     27      ; ASCII escape character

; I have adopted the convention that a terminal name is
; terminated with a space character, therefore no spaces
; within the name. Also that the terminal name is unique
; in the first eight characters.

NZTCAP: DB      'WYSE-50D     ' ; Terminal name (13 bytes)

; The Graphics section is no longer fixed so we must
; provide an offset to it.  One byte is sufficient for a
; two-record TCAP.

        DB      GOELD-NZTCAP    ; Offset to GOELD

; Bit 7 of B14 indicates the new Extended TCAP.  Bits 6-0
; are undefined.

        DB      10000000B       ; Extended TCAP

; B15 b0        Standout        0 = dim, 1 = inverse
; B15 b1        Power Up Delay  0 = None, 1 = 10-sec delay
; B15 b2        No Wrap         0 = Line Wrap, 1 = No Wrap
; B15 b3        No Scroll       0 = Scroll, 1 = No Scroll
; B15 b4        ANSI            0 = ASCII, 1 = ANSI

        DB      00000111B

        DB      'K'-'@'         ; Cursor up
        DB      'J'-'@'         ; Cursor down
        DB      'L'-'@'         ; Cursor right
        DB      'H'-'@'         ; Cursor left

        DB      00              ; Clear-screen delay
        DB      00              ; Cursor movement delay
        DB      00              ; Clear-to-end-of-line delay

; Strings start here.

        DB      ESC,'+',0       ; Clear-screen string
        DB      ESC,'=%+ %+ ',0 ; Cursor movement string
        DB      ESC,'T',0       ; Clear-to-end-of-line
        DB      ESC,')',0       ; Standout-on string
        DB      ESC,'(',0       ; Standout-end string
        DB      0               ; Terminal init string
        DB      ESC,'(',0       ; Terminal deinit string

; Extensions to Standard Z3TCAP

        DB      ESC,'R',0       ; Line Delete
        DB      ESC,'E',0       ; Line Insert
        DB      ESC,'Y',0       ; Clear-to-end-of-screen

; Set Attribute strings once again included.

        DB      ESC,'G',0       ; Set Attributes
        DB      '0248',0        ; Attributes

; These two allow reading the Terminal's screen.

        DB      ESC,'?',0       ; Read current cursor pos
        DB      ESC,'6',0       ; Read line until cursor

; Graphics start here.

GOELD:  DB      0               ; On/Off Delay

; Graphics strings offset from Delay value.

        DB      ESC,'H',2,0     ; Graphics mode On
        DB      ESC,'H',3,0     ; Graphics mode Off
        DB      ESC,'`0',0      ; Cursor Off
        DB      ESC,'`1',0      ; Cursor On

; Graphics Characters

        DB      '2'             ; Upper left corner
        DB      '3'             ; Upper right corner
        DB      '1'             ; Lower left corner
        DB      '5'             ; Lower right corner
        DB      ':'             ; Horizontal line
        DB      '6'             ; Vertical line
        DB      '7'             ; Full block
        DB      ';'             ; Hashed block
        DB      '0'             ; Upper intersect
        DB      '='             ; Lower intersect
        DB      '8'             ; Mid intersect
        DB      '9'             ; Right intersect
        DB      '4'             ; Left intersect

;  Fill unused space with nulls

        REPT    128-($-NZTCAP)
        DB      0
        ENDM

;  End of NZTCAPD

        endm

There are several pieces of information that you will have to determine in advance and enter into the patch code. I have put all that information at the front of the patch using macros where appropriate. If you do not have a macro assembler, you can always put the material directly into the code where the macros are called instead.

First, as before, you have to determine all the addresses at which indirect loads from address 0001 have to be changed to direct loads. These values have to be placed in the patch address table in the patch code. Since the patch will be added to the end of the existing utility code, you will also have to determine that address. You can calculate this from the file size of the COM file in records as displayed either by STAT or by SD with the "C" option. Alternatively, you can read the COM file into a debugger and note the next free address it reports. This address must be entered as the value of the symbol PATCHADDR.

Most of the utility programs I have patched this way start at 100H with a jump to the actual working code. The destination address of that jump must be determined and entered as the value of the symbol STARTADDR. If the utility does not begin with a jump, then you will have to examine the code at 100H and determine the instructions that occupy the first three or more bytes. These instructions should be entered into the REPLACED macro in the patch. The address of the next instruction after the ones replaced should be entered as the value for STARTADDR.

Once you have put all the necessary data into the UTILPAT.Z80 source code, it should be assembled to a HEX file. Then the patch can be added to UTIL.COM to make NEWUTIL.COM by using the following command:

MLOAD NEWUTIL=UTIL.COM,UTILPAT

Be sure to save the original program, and test the new version carefully. One additional word of caution. Some utilities cannot be expected to work under NZ-COM no matter what you do. For example, a utility that takes the running CP/M system and writes it to the system tracks will fail because under NZ-COM the only part of the CP/M system that is still present is the BIOS. For the same reason, programs that try to patch the BDOS will fail.

ZFILER, Installment 2

Last time we covered most of the built-in functions and had left the macro commands for this time. One built-in function was also deferred, the option command "O", and we will take up that subject first.

The Option Command

When the option command letter "O" is pressed, a special options screen is displayed. Eleven operating characteristics can be changed from a menu with the following appearance (approximately):

A. single replace query        Y
B. group replace query         Y
C. archive replace query       N
D. verify query                Y
E. verify default              Y
F. suppress SYS files          Y
G. sort by file name           N
H. set copied file attributes  Y
I. use dest file attributes    Y
J. archive destination         Y
K. search path for CMD file    N

We will explain the meaning of each of these options in a moment. First a few words about the mechanics. While the options menu is displayed, pressing the index letter at the left will cause the setting of the corresponding option to be toggled, and the new state will be shown in the column at the right. The listing above shows the initial state of the options in my personal version of ZFILER. When you are finished toggling options, just press carriage return to return to the main ZFILER menu. These option settings are stored in the ZFILER shell stack entry and will thus continue in effect through all ZFILER operations until the command "X" is used to terminate the shell.

The first three options concern how ZFILER responds when copying (or moving) files and a file of the same name already exists in the destination directory. Item A applies when individual files are copied (commands "C" and "M"); item B applies when a group copy is performed (commands "GC" and "GM"); and item C applies when performing an archiving operation (command "GA"). If the option is "YES", then ZFILER will prompt one before existing files are erased and give one the chance to cancel the operation for that file, leaving the existing file intact. If the option is toggled to "NO", then existing files will be overwritten without even a message.

The next two options affect the verification of the copied file in the destination directory. Item D determines whether or not the user will be asked about verification. If this option is set to "N", then the state of option E will determine whether or not verification is performed on file copies. If this option is set to "Y", then before each copy, move, group copy, or group move, ZFILER will put up the prompt "Verify (Y/N)?".

The next two options affect the way files are displayed on the screen. If item F is set to "Y", then files with the "system" or SYS attribute will be suppressed, that is, not included among the selected files on which ZFILER acts. This is a reasonable choice for this option, since the most common use of the SYS attribute is to make the files disappear from consideration during file maintenance and display operations. Item G on the options menu determines whether files are sorted first by name and then by type or vice versa. Changing this option is presently equivalent to the "A" command from the main ZFILER command menu.

The next three options concern how file attributes are treated when files are copied. One possibility is to create new files with a clean slate of attributes (that is, all attributes reset: not read-only, not SYS, not archived). This is what will happen when option H is set to "N" (but note option J, which may override this). When the attributes of the destination file are to be set, they can be set in two possible ways. If a file of the same name existed in the destination directory, then its file attributes could be used for the copy that replaces it. This is what will be done if option I is set to "Y". If option I is set to "N" or if there was no matching file in the destination directory, then the attributes will be set to match those of the source file.

Option J can set a special override for the archive or ARC attribute. If the option is set to "N", then the ARC attribute is treated just like the other attributes according to options H and I. If option J is set to YES, then the destination file always has its ARC attribute set.

There was at one time a great deal of controversy over the way the ARC attribute is handled under ZFILER. At one time it was always reset, so that the destination file would be marked as not backed up. Another school of thought asserted that, on the contrary, the file was backed up, since there was a copy of it on the source disk from which the file was copied. That latter argument made considerable sense in the case of copying files from a master disk to a RAM disk before a work session. Here it was certainly important to start with all files marked with the ARC attribute so that one could easily tell at the end of the session which files had been modified so that they could be copied back to the permanent storage medium.

All in all, I never understood this controversy. Both approaches clearly have merit, and since ZFILER supports both, I saw no reason for all the argument. In a future version of ZFILER, I think I would like to add a flag word that would indicate which drives should automatically set the ARC flag when the J option is set to YES. That way, the option could be made to apply to RAM drives only.

The final item on the option menu, option K, determines how the macro command file ZFILER.CMD (see discussion below) will be located. There are two choices. If option K is set to YES, then ZFILER will look for it first in the currently displayed directory and then along the entire ZCPR3 search path. This option is useful if one wants to have different macro command files that apply to specific directory areas. Alternatively, if option K is set to NO, then ZFILER locates the CMD file without using the path. Depending on how ZFILER is configured (this will be discussed another time), the file will be sought either in the root directory of the path (the last directory specified on the search path) or in a specific drive/user area coded into ZF.COM. This alternative results in faster operation, especially if the specified directory resides on a RAM disk.

The options controlled by the option menu can also be permanently changed in the ZFILER program file using a patching utility like ZPATCH. In the first page of the file, you will see the ascii string "OPT:". The eleven bytes following this string contain the startup values for the eleven options. Patch a byte to 00 for NO or FF for YES.

ZFILER Macros

Although ZFILER can accomplish many tasks using its built-in functions, its real power comes from the macro facility, which allows it to be extended to include any functions that can be performed using combinations of other programs. This is where ZFILER really makes use of its power as a shell. First I will describe how the macro facility is used, and then I will describe how the user defines the macro functions. As with the built-in functions, macro functions can operate either on single files or on groups of files. The single-file macro facility is well developed and was already present in nearly the same form in VFILER; the group macro facility is new with ZFILER and has not been fully developed yet.

Invoking Macros

One way to initiate a macro operation on the pointed-to file is to press the macro invocation key, which is normally the escape key. A prompt of "Macro:" will appear after the normal ZFILER command prompt. At this point you have several choices. If you know the key corresponding to the macro you want to run, then you can simply press that key. ZFILER will then construct a command line and pass it on to the command processor for execution. If ZFILER is configured for instant macro operation (it generally is), then macros associated with the number keys "0" through "9" can be initiated without the macro invocation key; the number key entered alone at the main ZFILER command prompt will generate the macro function.

If you press the macro invocation key a second time, a user-created help screen will be displayed. This screen generally lists the available macro functions. You can now press the key for the desired function, or you can press carriage return to cancel the macro operation and return to the main ZFILER menu. The help menu screen will also be displayed if you press the "#" key. This is a holdover from VFILER and arises in part because of the structure of the file in which the macros are defined (more on this shortly).

Group macros are invoked in a similar way from the group function command line. After you have tagged a group of files, press the "G" key to enter group mode. The prompt will list only the built-in group functions, but if you press the macro invocation key, you can proceed as described above for single-file macro operations, except that the macro function will be performed on each of the tagged files.

The group macro facility works a little differently than the single-file macro facility. Since the command line would generally not be long enough to contain the commands for all the tagged files, the group macro facility works by writing out a batch file for processing by ZEX or SUBMIT. In this way there is virtually no limit to the number of files on which group macros can operate.

There are many configurable options (described below) that are associated with the group macro operation. These include the name of the ZEX or SUB batch file, the directory to which it is written, and the command line that ZFILER generates to initiate the batch operation. The NZ-COM version of ZFILER uses a file called ZFILER.ZEX and the command line "ZEX ZFILER". The Z3PLUS version, under which ZEX will not run, uses a file called ZFILER.SUB and a command line of "SUBMIT ZFILER".

Since macros (and the main menu "Z" function) work by passing commands to the command processor, file tags will be lost in the process, and when ZFILER resumes operation, it starts afresh. In a future version of ZFILER, I hope to preserve the tag information by having it optionally written to a temporary file (the shell stack entry is far too small) and read back in when ZFILER resumes.

Defining Macros - The CMD File

Now let's learn how to define the macro functions we want. As I indicated earlier, the macros are defined in a file called ZFILER.CMD (the ZFILER ComManD file). In the version of ZFILER distributed with NZ-COM and Z3PLUS, the CMD file is searched for in the root directory of the ZCPR3 command search path. As described earlier, the option menu allows the entire path to be used. There are also some additional configurable options that will be discussed another time. You must be sure to put your ZFILER.CMD file in the appropriate directory. If the file cannot be located, you will still get the macro prompt, but, after you have specified a macro key, the error message "ZFILER.CMD NOT Found" will be displayed.

The ZFILER.CMD file is an ordinary text file that you can create with any editor or wordprocessor that can make plain ascii files (WordStar in nondocument mode, for example). The CMD file has two parts. The first part contains the macro command definitions; the second contains the help screen (described earlier).

In the first part of the CMD file, each line defines a macro. The character in the first column is the key associated with that definition (case does not matter). Macros can be associated with the 10 number keys, 26 letter keys, and all printable special characters except for "#" (explained below). The space character and all control characters are not allowed. Owing to an oversight, the rubout character can be associated with a macro!

After the character that names the macro there can be any number of blanks (including zero). If the first non-blank character is "!", then the "strike any key" (shell-wait) prompt will appear before ZFILER puts up the file display after a macro command is run. This should be used whenever the macro will leave information on the screen that you will want to read. After the "!" there can again be any number of spaces. Any remaining text on the line is taken as the script for the macro command.

The second part of the CMD file starts when a "#" character is found in the first column (hence the exclusion of that character as a macro name). Once that character appears, all remaining text, including text on the line, will be used as the help screen. Since ZFILER will add some information to the display (the name of the pointed-to file and a prompt), you will generally want to keep the help screen to no more than 20 lines, including an extra blank line at the end for spacing. With some experimentation you will get the hang of designing this screen.

Macro Scripts

ZFILER macro scripts are similar to those in ARUNZ and in the other menu shells (MENU, VMENU, FMANAGER) in that parameter expressions can appear. The critical parameters - the ones that implement functions that cannot be achieved any other way - are those that convey information about the directory currently displayed by ZFILER and about the pointed-to file. Parameters consist of a "$" character followed by one of the characters listed below.

User prompt parameters

 ' User input prompt
 " User input prompt

Parameters for directories

- currently displayed directory
 C DIR form
 D Drive letter
 U User number
- home directory (from which ZFILER was invoked)
 H DU form
 R Home DIR

Parameters for pointed-to file

 P Full information (DU:FN.FT)
 F File name (FN.FT)
 N File name only
 T File type only

Special parameters

 ! GO substitution indicator
 $ The dollar character

The parameters are listed in a special order above, and we will explain that later. First we will just present the meaning for each parameter.

The parameter expressions $" and $' are used to display a prompt message to the user and to read in a response string. Single and double quotes are equivalent. Once the prompt parameter has been detected, all subsequent characters up to one of the quote characters are displayed as the user prompt. Thus, if I am not mistaken, there is presently no way to put either quote character into the prompt. The end of the line or the end of the file will also terminate the prompt.

No special character interpretation is performed while expanding the prompt. If you want to make fancy screens, you can include escape sequences and some control characters (obviously carriage return won't work). In the future, ZFILER should be enhanced to provide a means to generate all control characters, to allow special characters to invoke screen functions based on the current terminal definition, and to expand directory and file parameters in the prompt.

Now for the directory parameters. Parameters C, D, and U return information about the currently displayed directory, while H and R return information about the home directory, the one from which ZFILER was originally invoked. PLEASE NOTE: macros always operate from the home directory. The reason for this is that ZFILER can display directories with user numbers higher than 15 even when it is not possible to log into these areas. If you want to operate in the displayed directory, then your script must include an explicit directory-change command of the form "$D$U:" at the beginning (or "$C:" if your system requires the use of named directories) and a command of the form "$H:" (or "$R:") at the end.

One special note about the parameters that return directory names. If the directory has no name, then the string "NONAME" is returned. This will presumably not match any actual name and will lead, one hopes, to a benign error condition. These parameters are included only for systems that do not allow directories to be indicated using the DU form (I hope that few if any systems are set up this way).

Now we come to the four file name parameters. They allow us to generate easily the complete file specification or any part of it. Note that "$F" is not quite the same as "$N.$T". The latter always contains a dot; the former does not if the file has no file type.

Finally, we have two special parameters. "$$" is included to allow a dollar sign character to be entered into the script. "$!" is a control parameter that is used only when a group macro is executed. If it is placed immediately before a token (string of contiguous characters), then that token will be replaced by the string "GO" on all but the first expansion of the script. This allows group macro scripts to operate faster by avoiding repetitive loading of a COM file. It must be used with great care and consideration, however, for reasons that I will not go into here.

Rules for Script Expansion

ZFILER follows a specific sequence of steps when expanding a script, one that gives it a special feature that, I would guess, few users are aware of. The first step in the expansion is to process only the user-input prompt parameters, substituting for the prompt whatever the user entered in response. This results in a modified script that is then processed by the second step in the expansion. Because the expansion is handled this way, the user input Scan include ZFILER script parameters! Thus the script can be used to write a script. You will see an example of this later.

The second step in the expansion is to substitute values for the directory parameters, which are a kind of constant. They do not change as a function of the pointed-to file. Finally, in a third step, the remaining parameters are expanded. For group macros, this final step in the expansion is repeated for each of the tagged files. The file parameters are expanded differently for each file, and, starting with the second tagged file, the "$!" parameter causes "GO" substitution.

Macro Examples

Listing 3 shows an example of a ZFILER.CMD file, one designed to illustrate some techniques of macro writing:

Q   ql $p

U ! if $t=?q?;$!sys:uf $p $d$u:;else;$!sys:uncr $p $d$u:;fi

S ! $!sfa $p $" SFA Options (/o,o.. o=ARC,-ARC,R/O,R/W,SYS,DIR): "
K ! $d$u:;$!crunch $f $"Destination directory (DU:) -- ";$h:
B   $d$u:;crunch $f $"Destination directory (DU:) -- ";sfa $f /arc;$h:

M ! /move $p $"Destination directory for move: "

X ! $d$u:;:$n $" Command Tail: ";$h:
Z ! $d$u:;$" Command to perform on file: " $f $" Tail: ";$h:
0 ! $"Enter ZFILER macro script: "
#                  SAMPLE ZFILER MACROS FOR TCJ

0. on-line macro        A. set Archive bit              N. NULU
1. LPUT                 B. Backup (cr/sfa)              O.
2. Z80ASM to COM        C. CRC                          P. Protect
3. Z80ASM to REL        D. Date display                 Q. QL
4. Compare Files        E. Edit                         R.
5.                      F.                              S. SFA
6.                      G.                              T. Type
7.                      H.                              U. Uncompress
8.                      I.                              V. VLU
9.                      J.                              W.
                        K. Krunch                       X. eXecute
                        L. LDIR                         Y.
                        M. Move                         Z. run command

$!  ZEX 'GO'            $D  DRIVE               $P  DU:FN.FT    $F  FN.FT
$".."  PROMPT           $U  USER                $N  FN          $T  FT
$'..'  PROMPT           $H  HOME

While writing this article, I discovered that one can include blank lines as shown to make the CMD file easier to read. The help screen part of the listing is taken from my personal script file (which, I have to confess, I have not really worked very hard at). The macro definition part of the listing includes only a few of the definitions.

The macro "Q" is included to illustrate a very simple, but useful, type of macro. It invokes the very powerful file typing program QL (quick look) on the pointed-to file. This is handy when you want more powerful viewing capability than that offered by the built-in "V" command. QL can handle crunched files and libraries, and it can display text or hex forward or backward.

Macro "U" uncompresses a file. It illustrates a more complex script that involves flow control and parameters that extract individual components of the pointed-to file name. It tests the file type to see if the middle letter is "Q" or "Z". In the former case, it unsqueezes the file; in the latter, it uncrunches it. The uncompressed file it put into the source file's directory.

Macros S, K, and B illustrate the use of input prompting. The first one allows the user to specify the file attributes to be set. Note that the prompt includes a helpful reminder of the syntax required by SFA.

Macro K crunches files to a user-specified destination. It also illustrates how one logs into the currently displayed directory. I do this here so that a null answer to the prompt (i.e., just a carriage return) will result in the crunched files being placed in the currently displayed directory rather than in the home directory, as would otherwise be the case (since that is where the macro runs from, remember). As a result, however, this macro will not operate properly in user areas above 15 under BGii or versions of the command processor that do not allow logging into high user areas.

Macro B performs a slightly more complex function. It not only compresses the pointed-to file to a specified destination directory, but it then marks the source file as having been backed up. A combination of the group archive built-in command (to tag files that need backing up) and a group macro B (to perform the backup) gives the ZFILER user a way to back up files in crunched form on the backup disk.

Macro M is included to show that a ZFILER macro, when it needs to do something more complex than it is capable of doing all by itself, can pass the task to an ARUNZ alias. The MOVE alias first determines whether the source and destination are on the same drive. In that case, MOVE.COM is used to perform the move. Otherwise, the source file is copied to the destination and then deleted. What we have, therefore, is a MOVE command that frees the user of the responsibility of worrying about which drives are involved - another example of how Z-System can free you from considerations that need not concern you, that do not require human intelligence to decide.

The final three macro examples are execution macros. Macro X causes the pointed-to file to be executed. A more sophisticated version might check to make sure that the file type is COM. I opted for the flexibility of pointing, for example, to PROGRAM.Z80 and having PROGRAM.COM run. If there is no COM file with a matching name, the error handler will take care of things. You will note the leading colon before the "$n" parameter. It makes sure that the current directory is searched even if it is not on the path. Prompted input is used to allow a command tail to be included.

The Z macro performs a user-specified function on the pointed-to file. Two separate user prompts allow both the command and a command tail to be given. For example, if you wanted to squeeze the file to A0:, you would enter "SQ" in response to the first prompt and "A0:" in response to the second.

The 0 macro illustrates how the response to a prompt can be used as a ZFILER script. This macro takes care of all those functions we forgot to include in ZFILER.CMD. The whole macro is just prompted input, and whatever we answer will be run as a script. I use this function so often that I put it on a number key so that it can be invoked with a single key rather than the usual pair. Also, as you may have noticed, I include in the macro help screen a list of the parameters that can be used.

The only real limitation of this macro-to-write-a-macro approach is that prompted input cannot be included in the response. As I write this, however, it occurs to me that this limitation could be overcome by recursively parsing the prompt parameters until none remain, and only then going on to the subsequent macro expansion steps.

Well, I was going to discuss patching and configuring ZFILER, but this article is already too long, so that will just have to wait for another time. I hope that this article will help you get more out of ZFILER. See you in the next issue!

[This article was originally published in issue 37 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 1989, 1991 Socrates Press and respective authors]