*****************************************************************************
* CDZSWP *
* A UTILITY TO ACCESS CD-ROM FILES FROM A Z-SYSTEM (CP/M) *
* Adapted from CD Sweep (c), V1.3, 1996 by Duncan Elvin *
* (with permission, 19 Sept 1997) *
*****************************************************************************
This program began with a manual conversion of Duncan Elvin's original C
program, CDSWEEP version 1.3 into Z80 Assembly, then was adapted to a screen-
oriented method of operation using standard Z-System TCAP utilities. To keep
from re-writing all the little utilities again, heavy use was made of the
standard libraries, SYSLIB, Z3LIB and VLIB.
As the utility grew, enhancements were also added to transfer the file
datestamp data from source files on CD-ROM to destination files using DSLIB
utilities originally developed for ZSDOS, but which also work with
DateStamper (tm). As with other programs I have written, the display format
of date display in the program can be configured for either US (mm/dd/yy) or
European (dd.mm.yy) forms.
In the spirit of maintaining some sort of machine portability, an overlay-
type of scheme was developed to retain the overall program functionality with
different types of unique drivers needed by different types of CD-ROM drives.
Different drivers may be constructed as needed and should be compatible with
the core program as long as the interface is rigidly maintained.
To ease flexibility, overlays may be; added over the base program for use
as a default, placed in a default drive/user area under a default name, or
specified as a command-line argument to override an added default driver.
Configuration of the defaults (Date display format, location and name of
overlay file) is eased by a .CFG file using Al Hawley's excellent ZCNFG.COM
configurator utility.
OPERATION.
This program begins by first verifying that a valid Z-System environment
exists in the system. Without it, cursor movement controls and other items
would need to be hard-coded thereby violating the portable nature of the
system. If that test passed, the system checks to see if any argument has
been passed on the command line (other than the Help request, "//"). If an
argument is detected, it is parsed and an attempt to open the defined file
is made under the assumption that it is a driver file. If no argument is
detected, then the overlay area is examined to see if a driver has been
embedded in the code as a default. If the Overlay area is vacant (detected
by a length word of Zero), an attempt is made to load the defined default
driver from the Drive/User specified in the configuration header. Following
this search/load sequence allows the user to experiment with different
driver files regardless of whether an overlay is permanently installed or
not, and to operate in a consistent manner across different systems.
When an overlay is loaded from an external file (specified or default), two
checks are performed to validate the image. First, only one sector is
initially read, and the first two bytes are examined as a word (length in
bytes) to insure that it is less than or equal to the 2k (2048) byte area
reserved in the main program body. Secondly, a specific ID string at a
fixed location in the file is compared to a valid sequence for overlays. If
both of these checks pass, the rest of the file is read in, and the overlay
initialization entry point is called. Any final CD-ROM drive or system-
specific validations are performed at this point, and error status returned
to the main code body. An example of actions which are included in the SCSI
overlay for B/P Bios include validating that the running system is indeed
B/P Bios, and re-configuring the CD-ROM drive to use 512-byte sectors to
transfer data from the Drive instead of the default 2048-byte sectors.
If all is well to this point, the Primary Volume Descriptor from the
CD-ROM is then read and the Root Directory displayed. From this point on,
you are in a screen-oriented system with control executed via cursor
movement and command keys resembling a WordStar subset. The selection of
such a set of keys was made to retain consistency with other Z-System tools
and to avoid learning (yet another) command set. The screens operate on
a "currently-selected" entry basis of the currently-displayed set on the
screen. Marking of the "currently-selected" entry is both by an arrow
pointer to the left of the entry, and highlighting/reverse-video of the
entry number and name as defined in the ZCPR TCAP. Each entry contains the
name of the entry, the size (rounded up to the nearest k), date/time stamp
and type of entry; "
" for a Subdirectory, or "-----" for a normal file
that may be transferred to another location or displayed.
At any time while using this program, a brief help screen is available
which presents a synopsis of the available commands, as well as the
Identifying Text string returned by the Driver module. This help is
accessed by typing a question mark ("?").
NAVIGATING.
You may move around in the current screen by using the Line-Up (Control-E)
and Line-Down (Control-X) keys. The movement wraps from bottom to top and
vice-versa (giving a Line-Down on the bottom file selects the top file, etc).
If there are more entries than a single screen can support, you may page
forward (display the next screenful) or backward (display the previous
screenful) using the "standard" Control-C (Page Forward) and Control-R
(Page Backward). This pair of commands do not wrap as the line commands
within a screen. You may return to the first entry of the first screen at
any time by pressing the "H" (Home) key.
When a Sub-directory is the "current" entry, logging into that directory
is simply a matter of pressing the "Enter" (or "Return") key. Returning to
the parent (previous) directory is just as simple by pressing Period (".").
As a side note, it may also be accomplishing by moving the "current" pointer
to the first entry which bears the name "..". The currently-selected
directory name and complete path is always displayed on the second line down
on the display with "\\" representing the Root or Home directory. Trying to
move the the parent directory from the root accomplishes nothing.
Trivia NOTE: Each directory contains an entry number 0 which is not shown,
nor is it accessible from this program. It is essentially a confirmation
entry for the data block of the current directory and not needed.
SEARCHING.
A primative string search capability is implemented to locate selected text
patterns. A full-featured ambiguous CP/M filename.type search was not
implemented due to the time overhead which would be required to first parse
each name string from the CD-ROM index, then perform an ambiguous name and
type comparison. Instead, a modified search algorithm was used which follows
the wildcard conventions of "?" matching any single character and "*"
matching a complete period-delimited field. The implication of this is that
a search for "*" and "*.*" are not the same. The former will match "FOOBAR"
while the latter will not since no second field exists. This is a possible
area for improvement.
An initial search is started by pressing Control-F. You will be prompted
for a string search pattern on the next-to-last line on the screen. When
you end the string by pressing Enter, the current directory will be scanned
beginning with the first entry after the "parent" entry. The first matching
name is selected as the current entry and will be marked as the selected
entry. If this entry is not on the currently-displayed screen, the screen is
re-drawn to include the matching entry.
The search may be repeated by pressing Control-L as long as you remain in
the same directory. Repeated searched commence at the entry after the last
match until the end of the directory is reached. The search buffer is
cleared when a directory is logged. Actions such as navigating, copying and
viewing files do not affect either the search entry, or positioning after a
match.
VIEWING.
Non-directory entries may be "typed" (viewed) on the screen by pressing
"V". Attempting to view a directory is an error, and your terminal will
beep obnoxiously in response. There are no possible safeguards against
trying to "view" non-text files, but you are cautioned against this since
some binary files may result in code sequences being sent to the terminal
which will alter or eliminate its ability to properly function (e.g. change
the terminal mode or baud rate).
Viewing files is on a screen-by-screen "paged" basis, pausing when the
screen is full. Pressing any key will cause the next screen to be displayed
with a final prompt to press "any key to return to the directory" on the last
screen. Only forward viewing is supported.
To correctly maintain a line count as the file is displayed, an equivalent
character count is maintained, and only one less than the number of
characters-per-line (as defined in the ZCPR3 TCAP) are printed. Ascii TAB
characters are expanded to multiple-spaces on MOD-8 boundaries. Another
nuance is that Ascii Carriage Returns (0DH) are ignored, and Ascii Line Feed
characters (0AH) used as the key to start a new line. This is satisfactory
for files using only a single End-of-Line character such as those created by
Unix, but there are some systems which use only a single Carriage Return to
terminate lines. Viewing these files will appear to result in only a single
(large) line.
COPYING.
The Copy Command is used to copy the currently-selected file to another
drive on the system. It is activated by pressing "C" on the keyboard. You
will be prompted for a destination file specification on the next-to-last
line on the screen. For ease of use, a default file spec is displayed
consisting of the Drive and User existing when CDZSWP was invoked, as well as
a file name and type derived by parsing the selected entry. If this is an
acceptable destination, simply pressing Enter will begin the copy. If not,
a new destination may be specified in ZCPR3 form (i.e. DU:fn.ft or DIR:fn.ft)
with unspecified elements resorting to the default values.
When the file data is successfully copied, the source date/time stamp
information is transferred to the destination in both Create and Modify
fields if file stamping is supported. The transfer of file stamp data uses
DSLIB utilities and functions with ZSDOS and DateStamper. For stamping
methods which also contain a "last accessed" field (DateStamper and NZTIM),
the Last Accessed field will reflect the system time that the copy ended.
As with the View command, an attempt to copy a selection will treat
you to the sound of the "bell" (or beep, squawk, etc) and nothing will be
copied.
EXITING.
Pressing the "X" key at any time a command key is accepted will gracefully
exit the program by restoring the entry Drive/User logged in at entry, and
De-Initializing the Terminal by using the standard ZCPR TCAP function in the
VLIB library.
LOADING/UNLOADING DISCS.
Depending on the features implemented in the specific driver module, it may
be possible to load and unload installed discs with the "+" and "-" keys
respectively. This is most often available on tray-type CD-ROM drives, and
is specifically implemented in the B/P Bios driver using a Sony CDU-55S SCSI
CD-ROM drive. With other types of drives, these keys usually degrade in
functionality to simply spinning and stopping the Disc.
--------------------------- TECHNICAL --------------------------------
All source code in this package is designed for assembly with Al Hawley's
ZMAC Z80/Z180 assembler and linker (ZML). Other tools needed include my
MYLOAD Hex overlay/loader utility, and Version 4.5 (or later) of SYSLIB,
Z3LIB, VLIB and DSLIB. These packages are widely available on Z-Nodes and
other archive locations.
Assembly and linking of the basic program consisting of the main CDZSWP.Z80
file and two included files; CDZSWP0.INC and CDZSWP1.INC, is done in the
following two steps:
ZMAC CDZSWP <-- Assembles the files to CDZSWP.REL
ZML CDZSWP,DSLIB/,Z3LIB/,VLIB/,SYSLIB/ <-- links main program with
needed library routines
to form CDZSWP.COM
The Driver files are separately-assembled, and must not be linked with
other routines. The overall size must be 2048 bytes or less, combined data
and code, in the present configuration. Overlays are loaded at 0180H into
the CDZSWP.COM program and must be ORG'd at that address. For flexibility,
it is easiest to assemble the file to a .HEX output, then either overlay the
stub default area in the main program to produce a stand-alone .COM file for
a specific configuration, or load it to a binary driver file for explicit or
default loading by CDZSWP when it is executed. Assemble as:
ZMAC .SRC /H <-- Assemble to .HEX
This file may be overlayed on CDZSWP.COM to produce a new executable (I
suggest with a new name) as:
MYLOAD .COM=CDZSWP, <-- Add
to CDZSWP.COM producing
.COM
To produce a standalone driver module for later loading:
MYLOAD .DRV= <-- load .HEX to .DRV
Configuration of the options in CDZSWP.COM needs a configuration data file
(defaulting to a type of .CFG) for use with Al Hawley's ZCNFG tool. Source
for the data file is in CDZS-CFG.SRC. Also in the package is a minimal
include file needed to define the internal data structures for ZCNFG. This
file, CNFGDEF.LIB, should *NOT* be altered. If no changes are needed to the
configuration file, the default CDZSWP.CFG furnished in this package may be
used. If you wish to reassemble the source, it is accomplished as:
ZMAC CDZS-CFG.SRC <-- Assemble to CDZS-CFG.REL
ZML CDZSWP.CFG=CDZS-CFG <-- Link to create CDZSWP.CFG
SUGGESTED CONVENTIONS:
Each of the overlay samples in this package is named according to a template
as: CD-xxxxx.SRC in source code where "xxxxx" is available to define the
specific versions. A trailing letter of "S" is suggested for SCSI drivers
with possible future versions ending with "I" for IDE, or "C" for Custom. The
suggested default type when drivers are loaded to standalone form is ".DRV".
POSSIBLE IMPROVEMENTS:
As with any project, it is very hard for an engineer to finish a project and
ship product, but this is the first shot. Other things that might be nice to
include in a future version include; revising the screen display to multiple
columns (a la ZFiler) with Size and Date data displayed only for the selected
name, and Tagging ability with Mass Copy ability. An improvement to the
"Find" command is also in order, but these all await a critical level of
interest and adequate time. Til then, enjoy. If you take on the task of
adding enhancements, I would appreciate a copy, particularly of additional
driver modules.
Harold F. Bower
7914 Redglobe Ct.
Severn, MD 21144-1048
USA
*************************** End of DOC File *********************************