;                    Bringing Up The Key Z-System Tools 

     To take full advantage of this new operating     Press ^C To 
system environment, you'll need some basic tools.      Exit HELP  

A.  MYZ80.Z3T     B.  SALIAS.COM   C.  ARUNZ.COM     D.  ZDE.COM 
E.  ALIAS.CMD     F.  NAME.COM     G.  SAVENDR.COM   H.  PATH.COM 
I.  NZBLITZ.COM   J.  IF.COM       K.  ZFILER.COM    K.  ZFILER.CMD 
L.  SDZ.COM       M.  HELP.COM     N.  CRUNCH.COM    N.  UNCRUNCH.COM 
O.  LPUT.COM      O.  LBREXT.COM   O.  ZLT.COM       P.  ZERR.COM 
Q.  Z-4-AT.HLP    Q.  TOOLS.HLP 

     What follows is a tutorial on the files listed above and on how they 
illustrate Z-System capabilities. If you know nothing about CP/M or Z- 
System, you should read what follows. If you are familiar with both, you 
might want to skim the rest. Who knows, after reading this, you may never 
want to use Microsoft Windows again! Personally, I'd reformat my hard disk, 
put the DOS hidden files on it, bring up MYZ80, then Z-System and be up and 
running. Why waste valuable hard disk space on 16-bit software ; >

:A

                MYZ80.Z3T - A "Terminal Capabilities File" 

     In "user area 1" of "drive A" we find the "terminal capabilities 
segment" file MYZ80.Z3T. To activate this file, load it into the Z-System 
environment via

     A0:COMMANDS> nzcom 1:myz80.z3t

[Note: I am putting a space between the prompt and the command to make this 
more readable. You should *not* use a space in front of your commands when 
you issue them. Doing so has a special meaning under Z-System and in the 
examples discussed here, we do not want this special meaning to be active.  
End of note.]

     Now type

     A0:COMMANDS> cls

Your screen should clear. CLS is one of the "resident commands" you loaded 
when you brought up Z-System. If you had tried CLS *before* loading the 
.Z3T file, it would have had no effect. The .Z3T file supports clear 
screen, clear to end of line, cursor positioning, hi/lo lighting and other 
terminal dependent functions.

     Let's bring the key tools we'll be using and discussing into the CP/M 
environment at this point with IMPORT.

     A0:COMMANDS> import salias.com
     A0:COMMANDS> import arunz.com

     etc.

     A0:COMMANDS> import lbrext.com
     A0:COMMANDS> import zlt.com

[Note: For the commands above to work, copy these files from your 
distribution disk to the MYZ80 subdirectory on your hard disk first. End of 
note.]

The hilighting effect of the .Z3T file can be seen by running SDZ.  
Similary, ZFILER will show hilighting.

     A0:COMMANDS> sdz
     A0:COMMANDS> zfiler

[Note: IMPORT supports "wildcards" and full DOS path name prefixes. The 
above IMPORTs could be simplified to one command and the need to copy these 
files to the hard disk eliminated via:

     A0:COMMANDS> import a:*.com

Also, NZCOM will automatically load system segment files found in A0: if 
they have a filename of NZCOM, so if a copy of MYZ80.Z3T were placed in A0 
and named NZCOM.Z3T, when you bring up Z-System, after the segments in 
NZCOM.LBR are loaded, the .Z3T file will load, eliminating the need for the 
load from user area 1 of MYZ80.Z3T shown above. ZFILER could be used to do 
the copy and the rename. End of note.]

:B

         SALIAS.COM - A Screen-Oriented Standalone "Alias" Editor 

     The error message

     STARTZCM?

mentioned elsewhere can be fixed by creating what's called (a standalone) 
"alias" named STARTZCM.COM. Do this with SALIAS (pronounced "S-ALIAS.")

     A0:COMMANDS> salias startzcm

Type in the following script:

     echo s%>ystem loaded.

Exit "edit mode" by pressing ESC and save the result by pressing S. Quit 
SALIAS by typing X.

     When you brought up Z-System (by typing NZCOM), several files got 
created. One of them is named NZCPM.COM. This is what you use to leave Z- 
System and return to CP/M. To see the effect of the existence of 
STARTZCM.COM, leave and then reenter Z-System via:

     A0:COMMANDS> nzcpm
     A0> nzcom

The message "System loaded." followed by the A0:COMMANDS> prompt should 
appear at the end of the load sequence now.

     SALIAS may be used to define any "alias" you want. Another simple 
example of an alias will be presented when we discuss IF.COM elsewhere.

     NZCOM is "hard-coded" to run the command STARTZCM after it does its 
segment loading. STARTZCM may be anything you want. We chose to define a 
simple standalone alias that emits a brief message.

     If you type CLS now, to clear the screen, or SDZ, to display a sorted 
file directory, the screen won't clear and hilighting will no longer occur 
(because the "terminal capabilities segment" no longer contains the "fancy 
stuff" held in MYZ80.Z3T). To further automate things, we could beef up the 
STARTZCM alias by adding a line to it. Reexecute SALIAS on STARTZCM, press 
ctrl-N to insert a line in front of the echo etc. line and enter:

     nzcom 1:myz80.z3t
     echo s%>ystem loaded.

Now, when you bring up Z-System from CP/M (by typing NZCOM), you should see 
hilighting with SDZ, ZFILER etc. and CLS will work.

[Note: Of course, if a copy of MYZ80.Z3T, named NZCOM.Z3T, were in A0:, as 
mentioned elsewhere, this extra line in the STARTZCM standalone alias would 
not be necessary, since NZCOM automatically loads segments with names 
starting with NZCOM. We show it here only to illustrate how SALIAS and 
STARTZCM may be used. End of note.]

:C

                 ARUNZ.COM - An Extended Command Processor 

     The first thing you should do with this file is rename it to 
CMDRUN.COM. CP/M has 6 builtin (resident) commands. They are DIR, ERA, REN, 
SAVE, USER and TYPE. REN's command syntax is:

     A0> ren newname.typ=oldname.typ

If you try:

     A0:COMMANDS> ren cmdrun.com=arunz.com

it will fail, because REN is not a resident command under Z-System (to list 
the resident commands available, type H (help) at the A0:COMMANDS prompt). 
The "stock" resident command processor has ERA and TYPE and several others, 
but no REN. There are two ways to get around this problem. One way would be 
to leave Z-System and return to CP/M and use its REN command.

     A0:COMMANDS> nzcpm
     A0> ren cmdrun.com=arunz.com

and then return to Z-System:

     A0> nzcom

The other way is to run ZFILER, press the space bar til the file pointer is 
on ARUNZ.COM, then press R (to rename) and type in CMDRUN.COM. Exit ZFILER 
by pressing X.

     ARUNZ is what is known as an "extended command processor." A well- 
defined series of steps are taken by the command processor segment of Z- 
System as it tries to figure out how to resolve any command it's given at 
the "A prompt." If the command you enter is not one of the "resident" ones, 
or a "transient" one (a .COM file), your command is fed to an "extended 
command processor" named CMDRUN.COM. In ARUNZ's case, the command is 
resolved by searching for it in a text file named ALIAS.CMD.

     Here is a simple illustration of an ARUNZ type "alias." Use the full- 
screen text editor ZDE to create the file ALIAS.CMD.

     A0:COMMANDS> zde alias.cmd

Enter the following definition for the alias DIR.

     DIR sdz $*

Save the file (ESC S) and quit the editor (ESC Q).

If you had typed

     A0:COMMANDS> dir

before renaming ARUNZ.COM to CMDRUN.COM and running ZDE and creating the 
ALIAS.CMD file, Z-System would come back with the error

     DIR?

Why? Because, the "stock" resident command processor doesn't include a DIR 
and there is no "transient" DIR.COM.

     But now that we have an extended command processor and a definition 
for an alias DIR, the effect of the command

     A0:COMMANDS> dir

is the same as the effect of 

     A0:COMMANDS> sdz

The $* in the definition for the DIR alias means "the command tail", so 

     A0:COMMANDS> dir *.com

would resolve to

     A0:COMMANDS> sdz *.com

ARUNZ is a mature command processor, supporting many powerful parameters.  
As this document is only a primer, only one other parameter ($1) will be 
discussed (under IF.COM). Full documentation on ARUNZ is provided when you 
purchase Z-System.

:D

                      ZDE - A Full-Screen Text Editor 

     ZDE (Z-System Display Editor) is the most popular full-screen text 
editor for CP/M. Its use is mentioned briefly elsewhere as the tool to use 
to update the ARUNZ alias definition file ALIAS.CMD. ZDE is very similar to 
WordStar. You may use the "WordStar diamond" to move the cursor around 
(ctrl-S, -D, -E, -X).  Online help is available via ESC H. It is good for 
under 40k files. Full documentation is available.

:E

                  ALIAS.CMD - ARUNZ Alias Definition File 

     We touch on the role this text file plays under ARUNZ.COM. More 
information on ARUNZ and example ALIAS.CMD scripts are provided when you 
buy Z-System.

:F

                    NAME.COM - A Drive/User Area Namer 

     When you bring up Z-System, two "drive/user areas" are automatically 
given suggestive *names*. Drive A user 0 is named COMMANDS and drive B user 
0 is named WORK. To change directories, you may type the drive letter, then 
the user area number, then a colon (:) and finally the enter (return) key. 
Alternatively, if a name has been given to a drive/user area, you may type 
the name, the colon and the return key.

     A0:COMMANDS> work:
     B0:WORK>

NAME is a drive/user area namer. You might want to name Simeon's drive A 
user area 1, the one with MYZ80.Z3T in it. Although only one file has to do 
with terminal capabilities, let's name it TCAP.

     A0:COMMANDS> name 1:tcap

You may now type:
     
     A0:COMMANDS> tcap:

and you'll see

     A1:TCAP>

To make this association permanent, you could use the utility SAVENDR to 
create the file NZCOM.NDR.

     A0:COMMANDS> savendr nzcom

Files saved by SAVENDR have a default filetype of .NDR. Since we chose the 
filename NZCOM, when we bring up Z-System from CP/M, this segment will 
automatically load, along with NZCOM.Z3T (discussed elsewhere).
  
Named directories are a good idea because you no longer have to remember 
the drive/user they correspond to. Just the meaningful name *you* choose. 
You might for example want to call C0 PROJECTS and C1 DATABASE.

:G

               SAVENDR.COM - A Named Directory Segment Saver 

     This program simply saves the currently defined named directory 
segment names into a file named SAVED.NDR, if no command tail is given, or 
filename.NDR, if a filename is provided in the command tail. It's a good 
idea to use NZCOM as the filename, because NZCOM automatically loads 
segments with NZCOM filenames. I envision A.DSK files created by one person 
and distributed to others. These .DSK files will have a *logical* structure 
which an included .NDR file will help reveal.

:H

                 PATH.COM - A Command Search Path Utility 

     Stock Z-System comes with a command search path of A0 $$ A0. $$ means 
"currently logged drive, currently logged user area." This path is searched 
to find .COM files. Say you are logged into drive B, user 2, and you type

     B2> zfiler

Since ZFILER.COM is in drive A, user 0, the command will work. If 
ZFILER.COM had for some reason been moved to drive B user 0, the command 
above would fail. You may use the PATH utility to establish the search path 
you want. For example

     A0:COMMANDS> path c0 b0 $$ a0

If this path were active, and ZFILER.COM were in B0, the ZFILER command 
above would work.

:I

                   NZBLITZ.COM - A Z-System Image Saver 

     This utility will help speed up the transition from CP/M to Z-System.  
Instead of running NZCOM and waiting while all the segments load, you may 
use NZBLITZ to save a complete image of a loaded Z-System into a .COM file. 
For example:

     A0:COMMANDS> nzblitz image

A file named IMAGE.COM will be created. It will contain the named directory 
names, the terminal capabilites segment, the command search path etc. If 
you leave Z-System and return to MSDOS/DRDOS via QUIT), you may quickly 
regenerate this Z-System environment via:

     A0:COMMANDS> quit
     C:\MYZ80> cpm
     A0> image
     A0:COMMANDS>

It might be noted that with this approach, STARTZCM will no longer be 
automatically run (this only happens when you go from CP/M to Z-System with 
NZCOM). NZBLITZ does have a nice feature you may want to use, however. If 
you invoke NZBLITZ as follows

     A0:COMMANDS> nzblitz image;echo s%>ystem created 08/24/92

then, when you go from CP/M to Z-System, via

     A0> image

the message
     
     System created 08/24/92

will be displayed.

[Note: For those of you out there that will will accept nothing less than a 
"fully automatic" implementation, try this: MYZ80 is coded to automatically 
run a program named MYZ80GO.COM at startup. So, if the name you choose when 
you create your system image with NZBLITZ is MYZ80GO, then you can go 
directly from DOS to Z-System with one command!

     C:\MYZ80> cpm
     A0:COMMANDS>
     
End of note.]

:J

             IF.COM - A Powerful Conditional Command Processor 

     Z-System supports both a "resident command processor" and a "flow 
control command processor." Typical flow control commands are IF, ELSE and 
FI. These commands are frequently used in aliases to support conditional 
command invocation. Here's a simple example. Say you defined the following 
ARUNZ (or standalone) alias and called it MYTYPE:

     if exist $1;type $1;else;echo $1 %>doesn't exist;fi

Z-System uses semicolons (;'s) to separate commands in a multiple command 
line. Say the file MYZ80.DOC were in A0 and you were logged into A0 and you 
issued the command

     A0:COMMANDS> mytype myz80.doc

The "stock" flow control processor supports an IF which only supports a few 
testable conditions (ERROR and NULL). EXIST is not an included testable 
condition. The transient IF.COM, if available, will automatically load if 
the resident IF is insufficient. IF.COM supports a host of conditions, 
including EXIST. The command above would result in the typing out of 
MYZ80.DOC. Notice the role of the $1 argument. It gets replaced everywhere 
it occurs by the first argument in the command tail.  

     To see the testable conditions IF.COM supports, invoke IF using the 
standard Z-System help tail, //.

     A0:COMMANDS> if //

:K

                         ZFILER.COM And ZFILER.CMD 

       A Point And Shoot File Manager And Its Macro Definition File 

     ZFILER is a powerful "point and shoot" file manager. With it, you may 
view, rename, delete, copy, etc. files. It has online help which may be 
seen by typing / in response to its prompt. Typing / again will bring you 
back to the file name display.

     If you issue the command Z, ZFILER will provide a new prompt at which 
you may issue *any* Z-System command. For example, you might want to run 
the ZDE editor on the file TOOLS.HLP. Just type Z, and at the new prompt, 
type ZDE TOOLS.HLP. After you have finished your edit session and quit the 
editor, you will see the message "Strike Any Key --." Upon hitting a key, 
ZFILER's file name display will appear. ZFILER is a "front end" or "shell", 
a program which isolates a user from direct use of the operating system.

     ZFILER has a powerful feature worth mentioning at this point. If a 
file named ZFILER.CMD is available, and it contains the following:

     1! zde $p
     2! echo 08/24/92
     #
        1. edit currently pointed at file
        2. show version date

then, if the file pointer is on the file TOOLS.HLP and you press the 1 key, 
the ZDE editor will automatically run and you will be editing the file 
TOOLS.HLP! The structure and meaning of ZFILER.CMD files will not be 
discussed further here. Again, this information is well covered with the 
manual you get when you purchase Z-System.

:L

                   SDZ.COM - A Sorted Directory Utility 

     This program has been mentioned elsewhere as one that could be used to 
make the command

     A0:COMMANDS> dir

do something useful (via an ARUNZ alias). SDZ has many options. Type SDZ // 
to see what they are. 

     A0:COMMANDS> sdz *.hlp /da

would display the names of all .HLP files on all drives and in all user 
areas.

:M

                         HELP.COM - A Help Utility 

     One of the nicest things about Z-System is the extensive help 
available. Help comes in many forms. We've mentioned using the // as a 
command tail elsewhere. This shows you syntax and usage. This information 
is hardcoded in the executable (.COM) file. Another form of help is found 
in external .HLP files. These files are most effectively browsed with the 
HELP utility, HELP.COM. The files Z-4-AT.HLP and this file, TOOLS.HLP, are 
.HLP files.

     A0:COMMANDS> help a:z-4-at

would invoke the main help file, Z-4-AT.HLP. The file TOOLS.HLP, this file, 
is a "limb" or "branch" of this main file. .HLP files may be nested in a 
tree-like structure.

:N

                        CRUNCH.COM And UNCRUNCH.COM 

                  A Compression And A Decompression Tool 

     To save disk space, these two programs are used to compress and 
uncompress files. When a file is compressed, a much smaller file with the 
same first name and a filetype with a Z replacing the middle letter of the 
file's filetype is created. Other compression and packaging tools are 
available, but the tendency for CP/M material is to use CRUNCH followed by 
library packaging. See below for library tools.

:O

                    LPUT.COM And LBREXT.COM And ZLT.COM 

    A Library Building, A Library Extracting And A Library Typing Tool

     LPUT (Library PUT) is used to create and add members to library files 
(.LBR files). NZCOM.LBR is a library file. Other packaging techniques are 
popular (.ZIP, .ARC etc.) but .LBR's are the most common CP/M packaging 
method. LBREXT is used to extract files from libraries. It supports options 
to "inspect" (ie. say yes or no to the extraction) and "decompress", and 
all popular compression methods, including the latest, LZH, are supported.  
Finally, ZLT, Z Library Typer, lets you view (type out) a member of a 
library, compressed or not.

:P

                          ZERR - An Error Handler 

     When all else fails (the Z-System command processor can't find a 
flow control, resident, transient or extended command, or something else is 
wrong), if an "error handler" is installed and available, it will run it. 
ZERR is a popular one. It announces the nature of the error, presents you 
with the command in error and lets you edit the command and reissue it. 
This sure beats what most operating systems do. CP/M, for example, just 
echos the command in error followed by a ?.

     ZERR is "installed" by typing:

     A0:COMMANDS> zerr

:Q

                        Z-4-AT.HLP And TOOLS.HLP 

           The Main .HLP File And A Limb Off The Main .HLP File 

     If you got to TOOLS from Z-4-AT, you must have typed:

     A0:COMMANDS> help a:z-4-at

To return to the main .HLP file, Z-4-AT, type a period (.) or a caret <^>.

     A0:COMMANDS> help a:tools

would be the way to browse the TOOLS help file without accessing its 
"parent."

     .HLP files come in several flavors. These two are "user-indexed." 
There is a way to create "HELP-indexed" .HLP files as well. .HLP files are 
text files which may be viewed with an editor or simply TYPEd. The best way 
to browse them is with HELP.COM. Notice how you get hilighting by 
bracketing phrases with ctrl-A and ctrl-B.

