Welcome to the Wonderfully Ancient World of CP/M 80 and
The Wonderfully Modern World of Apple 2 Disk Images and Ruby and Everything
dsktool.rb and dskexplorer.rb for Windows (and other) Users
Introduction

dsktool.rb is a command line tool + libraries (all in ruby) written by Jonno Downes for manipulating DSK format images used by Apple 2 emulators. dsktool.rb also comes with dskexplorer.rb which will run in your web browser and let you view Apple 2 disk images in the current directory. Usage for both dsktool.rb and dskexlorer.rb is listed in the dsktool.rb program documentation and the dskexplorer.rb program documentation respectively.

dsktool.rb supports Apple 2 CP/M disk images for READ/WRITE operations. More information about disk image support in dsktool.rb is listed in the dsktool.rb program documentation.

Bad News and Good News

Since dsktool.rb is written in the ruby programming language it cannot be run unless ruby is installed on your computer. You can think of it as being similar to interpreted BASIC in that it needs to run from within another program. But ruby is infinitely more advanced than interpreted BASIC.

You might be better to think of it as being similar to java in that it runs on many platforms and shares other characteristics, some which are discussed at the following link:

http://en.wikipedia.org/wiki/Model-view-controller

But unlike java which must be compiled to be run, ruby programs can be viewed in a text editor. Ruby is a scripting language also sharing characteristics with the less advanced but capable perl scripting language from the Unix world.

Like java, ruby installs many files. On a Windows XP machine this can take a large amount of disk space. For example, on my Windows XP machine the installation in the zip file in the Links section below, once complete, added the following under the C:\ruby\ directory: 
22411 File(s)     89,761,286 bytes
9404 Dir(s)  86,741,917,696 bytes free
Double that amount for unzipping the zip file installation in the Links section below. If you don't have that amount of space you can't install this.

That's the bad news. The good news is that if you are familiar with command line utilities and especially if you work with Apple 2 CP/M you will find dsktool.rb and dskexplorer.rb useful tools for your collection.

More good news for users of other modern computer systems like Linux Ubuntu as well as Windows XP users is that dsktool.rb should run on all systems that support ruby.

<< Back to Top

Getting Started

The download for the zip file installation of dsktool.rb for Windows (and other) users is in the following Links section.Below the links is a summary of how to install and run all this. Html documentation is also provided in the docs directory in the zip file (and on the http://www.cpm8680.com/ website). You can load these into your favourite web browser by clicking on them from within Windows Explorer.

Links

The zip file installation of dsktool.rb for Windows (and other) users can be downloaded from http://www.cpm8680.com/ at the following link:

If you have a slow Internet connection you may not wish to do so.

More information about dsktool.rb is available at the following links:

Information specific to dskexplorer.rb which comes with dsktool.rb:

More information about Jonno Downes' peekbot project:

<< Back to Top

Installing dsktool.rb (in Windows XP)

This installation assumes that you don't have ruby installed.

If you already have ruby installed you can skip the ruby installation. It won't work anyway. You may need to remove ruby and any other ruby programs if the rest of the installation fails. Advanced installations of ruby are beyond the scope of this document.

The version of dsktool.rb that is included in the zip file installation needs the following steps to be installed on a Windows XP Machine. Other systems that ruby supports will follow similar steps: After installing ruby, the gem installer that comes with ruby is used from the Windows command prompt to install the rest of dsktool.rb. The following is given for users who will install on their C: drive.

Summary
If you don't wish to keep the installation files after successfully installing dsktool.rb just remove the entire C:\dsktool\install directory.

In Windows Xp, two batch files are provided to run dsktool.rb and dskexplorer.rb. These are used by typing dsktool.rb or dskexplorer.rb followed by their respective command line switches and options and since ruby is on path they can be used from the Windows XP command line in any directory.

<< Back to Top

Running dsktool.rb (in Windows XP)

Included in the installation zip file is an Apple CP/M disk image which you can use to perform some post-installation tests with to make sure dsktool.rb is working correctly.

Two simple non-destructive tests can be performed; catalog the disk image and extract a file from the disk image.

To catalog the disk image: 
dsktool.rb -c SoftcardCPM.dsk

SoftcardCPM.dsk
sector order:   physical
filesystem:     cpm
   APDOS.COM   1664
     ASM.COM   8192
CONFIGIO.BAS   7424
    COPY.COM   1024
   CPM56.COM  10752
     DDT.COM   5120
DOWNLOAD.COM    512
    DUMP.ASM   4224
    DUMP.COM    512
      ED.COM   6656
  FORMAT.COM   2304
  GBASIC.COM  25600
    LOAD.COM   1792
  MBASIC.COM  24576
     PIP.COM   7424
    RW13.COM   2304
    STAT.COM   6144
  SUBMIT.COM   1280
    XSUB.COM    768
To extract a file from the disk image: 
dsktool.rb -e APDOS.COM -o foo.com --raw SoftcardCPM.dsk

Directory of C:\cpmtools
04/12/2008  09:07 PM             1,664 foo.com

<< Back to Top

Running dskexplorer,rb (in Windows Xp)

If you have never run a browser based application from your local computer (many Windows users haven't) this may seem a little strange. Ruby starts-up dskexplorer.rb and it prompts you to point your web browser to an intranet address.

You will see a message like the following: 
[2008-12-06 14:29:50] INFO  WEBrick 1.3.1
[2008-12-06 14:29:50] INFO  ruby 1.8.6 (2007-09-24) [i386-mswin32]
point your browser at http://localhost:6502/
[2008-12-06 14:29:50] INFO  WEBrick::HTTPServer#start: pid=1428 port=6502
To make things a little easier for Windows XP users, the installation zip file has Windows cmd files in place to start-up your browser and then start dskexplorer.rb. If your browser starts before dskexplorer.rb click on refresh on your browser when dskexplorer.rb starts.

Just click-on the \dsktool\dskroot.cmd from Windows explorer to start dskbrowser.rb in your root directory (usually C:\)

Click-on the \dsktool\dskcwd.cmd to start dskbrowser.rb in the \dsktool\ directory.

You can also type these commands in a command window.

Make sure when you close your browser that you also close dskbrowser.rb's Windows cmd window or dskbrowser.rb will continue to run its service. On the other hand you may wish to leave dskbrowser.rb running between browser sessions so I will leave the further exploration of dskbrowser.rb and dsktool.rb and Apple 2 disk images in general up to you.

<< Back to Top

Licence and Copyright

This program is Copyright (c) 2007 Jonno Downes <jonno@jamtronix.com>.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

<< Back to Top

Caveat Emptor

This document was created and formatted by hand by Bill Buckels. Its contents are either part of dsktool.rb or provide additional information about using dsktool.rb.

Bill Buckels has no warranty obligations or liability resulting from this document's use in any way whatsoever. If you don't agree then don't read it.