***************************************************************************** * 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 *********************************