ZDB
                          Version 1.0
                       Joseph I. Mortensen
                        November 23, 1990

                See ZDB.UPD for version history.

                      I.  Copyright Notice

ZDB is copyrighted (C) 1990 by Joseph I. Mortensen.  It is 
offered to the Z community for whatever use anyone has for it 
except selling it or in any way representing it as your own work.  
It may be freely copied and distributed.  Modify it to your 
taste.

                         II.  Description

ZDB is a simple name and address file capable of printing mailing 
labels and envelopes.  There is not much unique about that.  What 
sets ZDB apart are its size (under 7K) and speed (written in Z80 
assembler), its use of the Z- System extended TCAP and VLIB 
routines for screen graphics and cursor movement, its easy 
editing mode, and its use of the internal clock to date each 
entry automatically.  ZDB will also search for any string (or 
part thereof) in any field (using an adapted SCANNER from 
SYSLIB).  An express search for last name uses an in-RAM 
index of pointers for blazing speed.  The sort routine will sort 
the records alphabetically by last and first names or by zipcode 
(new with 1.0) and write a new file.  The old file is renamed and 
retained as a backup.  The new file is automatically reopened 
after the sort is done and the first record displayed just as on 
startup.  Label printing options allow the selection of any one 
of four keys for the output.  See Output section below.

ZDB is fully Z-System dependent.  If you lack a clock, ZDB
allows for manual entry of the date.  ZDB does not require an RCP 
or FCP or IOP to work.  It does need the extended TCAP with the 
13 graphics characters.

ZDB was edited with ZDE, assembled with ZMAC, and linked with ZML 
using DSLIB, VLIB, Z3LIB, and SYSLIB routines.  I developed it on 
my venerable Kaypro II'83 -- 5 MHz with 20 Meg Seagate, TurboROM, 
Rembrandt (from Spectre Technologies) character ROM for primitive 
graphics, Kenmore clock, and Z-System.

Please report bugs and make suggestions for improvement.  My 
address is at the end of this DOC file.

I owe much to those who've put together the Z libraries and 
generously shared their code listings.  I've learned and 
shamelessly borrowed code segments from them.  Some of the 
borrowing will be clearly recognized.

I am particularly indebted to Terry Hazen for his major 
contributions to this project.  Virtually all of his work has been carried forward to later releases.  He greatly improved the 
efficiency of the code, reduced its size, and added features.  
See the file ZDB.UPD in ZDBxx.LBR for version history.

                         III.  Installation

If you're running ZCPR3.3+, ZDB needs no ZCPR3 installation, but 
if you're running ZCPR3.0, you need to install ZDB in your usual 
way.

Before using ZDB you will need to patch it with your own return 
address.  You may also need to change the standout video flags or 
printer codes to match your terminal or printer.  See section VI 
on patching at the end of this DOC file.

                         IV.  Using ZDB

Entering 'ZDB /<cr>' at the command line will produce a help 
message.  If you also enter a data file name, ZDB will look for 
it, create it if it does not exist, and display either a blank 
record (if it's a new file) or the first non-erased one in the 
file.  If no file name is specified, ZDB will use ZDB.DTA as the 
default data file name.

If you don't have an internal clock (or have a clock module 
loaded), ZDB will ask for the current date.  If you wish to quit 
at this point, enter ^C at any time while entering the date.

The ZDB menu is displayed at the bottom of the screen:

A=Add E=Edit D=Delete F=Find X=Xfind >=Next <=Prev P=Print ^S=Sort Q=Quit

                             1.  Add

'A' for Add is the command used to enter new records.  The 
display is cleared and the cursor placed in the first field ready 
for your entry.  Each field is marked off with angle brackets -- 
>           < -- so you know how much space you have.  If you try 
to enter more characters than allowed in any field, you will get 
beeped at, but you can back up and fix things.  ^X, TAB or RETURN 
moves to the next field.  ^E moves to the previous one.  ^S/^D 
move cursor left/right.  Arrow keys are intercepted and inter- 
preted properly.  ^Y deletes from character at cursor to end of 
line.  After the last field, you are given a choice of redoing 
the entry to correct any mistakes or omissions or saving.  Press 
ESC at any point to finish the entry.  Boxes near the bottom of 
the screen display editing keys and give prompts.  On completion 
of a new entry you are given the option of continuing to add new 
records or quitting.  When you finish entering new records, you 
automatically are given the option of having the file sorted.

                             2. Edit

'E' for Edit works exactly like Add except that it is for up- 
dating existing information.  You cannot edit the date.  It is changed automatically.

                            3. Delete

Pressing 'D' lets you eliminate a record from the file.  You are 
given a chance to say no if you mistakenly press the 'D'.  The 
record is filled with nulls except for the first byte which is 
0FFH.  When you do a sort, erased records are dropped from the 
new file.  Deleting a record does not change the record count in 
the upper left corner of the screen since the deleted record is 
still in the file until a sort is done.  Deleted records are not 
displayed or printed.

                            4.  Find

There are two search routines in ZDB.  "Express Search" is for 
last names only.  Press 'X' at the main menu.  A box appears and 
and asks your input.  Partial strings, even one letter, are OK.  
The routine is not case sensitive.  The first record to match 
your request is displayed.  You may stop the search at that point 
or continue.  If there's no match, you are told.

The other search works on any field but is slower.  Press 'F' 
for this one.  You may enter up to ten characters in the search 
string.  "Find" is not case sensitive, so "JOE" and "Joe" and 
"joe" are all the same to ZDB.  Partial strings are fine.  
Entering "Jo" to search for "Jones" will get the job done.  You 
can enter more than one word, e.g., "St. Paul," as long as they 
are in the same field.  If the search string is found in any 
field of any record, that record will be displayed on the screen.  
You may then opt to end the search or continue it.  If there's no 
match, ZDB tells you so.  Even in fairly large files, Find works 
quickly.  Express Search and Find are also available under the 
Output routine.

                       5.  Next, Previous

Next and Previous are for browsing through the file.  Pressing 
'>', or '.' both work for Next.  '<', or ',' both work for 
Previous.  If you are going backwards through the file and reach 
the first record, another Previous command will go to the end of 
the file.  "Next" acts in a similar fashion when it reaches the 
end of the file.  Two other commands, not on the menu, are 'T' 
(Top) and 'B' (Bottom).  They quickly take you to the first or 
last record in the file.

                            6.  Print

Print has a submenu offering a choice of printing labels or 
envelopes.  The label option gives the further choice of printing 
a single label, those which match a key, multiple copies, or the 
entire file.  When you select 'Key', you will be asked to select 
city, state, zip code, or a special code.  The special code looks 
at the first two letters of the Comments2 field for a match.  If 
you want to make labels for your Christmas card list, you could use 'CL' as the first two characters in the Comments2 field as 
your code.  There's room for lots of imagination for the use of 
this feature.  Both the label and envelope option allow you 
to use Find, Xfind, or Next before issuing the print command.  
Printer escape codes (Epson FX-85 compatible) are near the 
beginning of ZDB and may be patched as the user wishes.  A return 
address for the envelope is also hard coded in ZDB and should be 
changed for your use or eliminated.  See section below on 
patching.

                            7.  Sort

To avoid accidental sorts the command key is now ^S (Ctrl-S) and 
you can still abort after that.  Sort first indexes the file in 
use, sorts the index by last name and first name or by zipcode, 
depending on your choice, and then writes a new, sorted file in 
the current directory with the original file name.  The old file 
is retained as a backup with the name BACKUP.DTA.  If a previous 
BACKUP.DTA file is present, it is deleted.  Deleted records are 
purged when Sort writes a new file. Sort works very fast even on 
a floppy system, with most of the time spent writing the new 
file.  On a hard disk system it works in a matter of seconds.  On 
a RAM disk it would be something else.  When a sort is done an 
index requiring 16 bytes per record is created.  20K of free RAM 
would allow files of 1280 records to be sorted, well beyond most 
people's requirements.  Since ZDB takes less than 8K of RAM, most 
users will have 35-40K or more of free memory.

                       V.  File Structure

ZDB's data file uses a 256 byte record so that each one is on a 
page boundary.  There is no header to the file.  File size is 
limited to a mere 64K 256 byte records -- due to the use of 16 
bit counters for the number of records and the file pointer.  
Disk capacity is the real world limiter on file size.  On a 390K 
floppy, ZDB itself will take 8K.  Divide the remaining 382K by 2 
(you need twice the space in order to do a sort) to get maximum 
file size -- in this case 764 records of 256 bytes.

                          VI. Patching

ZDB has a patchable flag to control whether a character will be 
used to terminate each field in the display, and if so, which 
character should be used.  A termination character is useful if 
your terminal is set so that the entire data fields are not 
shown, for example, dim standout on a dark screen, so you can 
tell where the end of the field is when adding or editing fields.

010Bh
TERMF     db   '<'  If a character ('<' is default), use that 
                    character to terminate each data field 
                    display.  
                    If OFF (00h), don't display a field 
                    termination character.
When ZDB is invoked, you may specify the name of the data file 
you wish to use.  If no data file name is specified, ZDB will use 
the default data file name patched below.  Enter it as you would 
type it, including the '.', and leaving all trailing fields as 
spaces.

010Dh         'filename.typ' < max
         db   'ZDB.DTA     '
         db   0         ; termination

The printer escape codes are at 0119h and following.  Labels for 
each will help you locate the patch area.  Each string must be 0- 
terminated.  There's plenty of extra room for complicated printer 
escape codes.  The following are Epson FX-85 compatible codes.  
You can eliminate any of them by making the first byte 0.  Use 
ZP, ZPATCH or ZAP or DU3 or similar disk editors to do the patch.  
Always keep a backup copy before you patch -- just in case.

	db	'RST'
reset:	db	esc,'@'		; printer reset string
	ds	3		; extra space
	db	0		; termination
;
; Set printer for printing return address:
;
	db	'RIN'
rin:	db	esc,'x',1	; printer nlq string
	db	0fh		; condensed print
	db	esc,'p',1	; proportional print
	ds	7		; extra space
	db	0		; termination
;
; Set printer for printing main address:
;
	db	'AIN'
ain:	db	esc,'E'		; set emphasized print
	db	esc,'x',1	; set nlq mode
	db	esc,'p',1	; set proportional print
	ds	4		; extra space
	ds	0		; termination
;
; Set left margin for envelope address:
;
	db	'ELM'
lemarg:	db	esc,'l',40	; may also use tabs
	ds	9		; extra space
	db	0		; termination
;
; Set left margin for label address.  Set to 0 if no return address is
; desired.
;
	db 	'LLM'
llmarg:	db	0		; printer init string or tabs/spaces
	ds	10		; extra space
	db	0		; termination;
; Use return address in label (only if labels are large enough):
;
	db	'LRA'
lra:	db	0		; 0 if no return address is desired
;
; Set number of lines per label:
;
	db	'LPL'
labln:	db	esc,'C',6	; set lines per label
	ds	5		; extra space
	db	0		; termination

A default return address (the author's own) follows the printer 
patch area.  Look for "RTA" in the code to locate it.  It comes 
immediately after "RTA".

You can easily edit the return address in ZDB.COM using WordStar  
in document mode, just as you would edit any other document.  
Just keep the editing to the return address text portion!  If the 
return address text is displayed clearly, the editing will work 
just fine, and WordStar will put the cr's and lf's in the right 
places!  Note that this technique does NOT work using ZDE!
;
; Return address patch goes here.  For normal business size 
; envelopes, the number of line feeds must remain 14 and the string 
; must be 0-terminated.  To eliminate the return address change retadr
; to a terminating null (00h) and put 14 line feeds in addrsp.
;
	db	'RTA'
retadr:
line1:	db	'Joseph I. Mortensen'
	db	cr,lf
line2:	db	'4214 Chelsea Ct.'
	db	cr,lf
line3:	db	'Midland, MI 48640'
	db	cr,lf,lf
	ds	18		; room for more characters
	db	0		; termination
;
; Space from return address to address.  For normal business envelopes,
; the total number of line feeds in the return address and addrsp should 
; be 14.  If the return address is the normal three lines, addrsp should
; contain 10 line feeds.
;
	db	'ASP'
addrsp:	db	lf,lf,lf,lf,lf
	db	lf,lf,lf,lf,lf
	ds	4		; room for 14 line feeds
	db	0		; termination
	db	'RTA'

Joseph I. Mortensen
4214 Chelsea Ct.
Midland, MI 48640Voice 517 835-6923
Compuserve 70037,3161
GEnie J.MORTENSEN3
Also regularly check in at Sage East and Ladera