dsktool

Installing dsktool

Sun, 20 Jul 2008 04:46:19 Z

Before you can install dsktool.rb, ruby must be installed – instructions on how to do this for most operating systems can be found at http://www.ruby-lang.org/en/downloads/

once you have ruby installed, you can download, install and configure dsktool just by opening up a command window and running gem install dsktool

If you are using debian or ubuntu, then you will need to put “sudo” at the start of the command, like so:

jonno@ubuntu:~$ sudo gem install dsktool

If all goes well, you should see a response like so:

Bulk updating Gem source index for: http://gems.rubyforge.org
Successfully installed dsktool-0.4.2
Installing ri documentation for dsktool-0.4.2...
Installing RDoc documentation for dsktool-0.4.2...
jonno@ubuntu:~$

Now check that dsktool.rb is working by typing dsktool.rb -v.

You should be given a version number, like so:

jonno@ubuntu:~$ dsktool.rb -v
dsktool.rb 0.4.2
jonno@ubuntu:~$

if you are running ubuntu, and you get a ‘command not found’ error when you run dsktool.rb, you will need to add the the gems ‘bin’ directory to your default search path. To do this, to do this, edit the file called .bashrc in your home directory (using the text editor of your choice, e.g. nano or gedit), and at the bottom of that file add:

    
    export PATH=$PATH:/var/lib/gems/1.8/bin

Then save .bashrc, and restart your terminal window.

You should now be able to run dsktool.rb.

Next: Getting started with dsktool

Supported File Systems

Sun, 20 Jul 2008 03:53:49 Z

File System	Catalog	Extract	Init	Add	Delete
Apple DOS	YES	YES	YES	YES	YES
Apple Pascal	YES	YES	–	–	–
Apple Pro DOS	YES	YES	–	–	–
CP/M?	YES	YES	YES	YES	YES
NADOL	YES	YES	YES	YES	YES

jonnosan

Mon, 23 Jun 2008 21:59:22 Z

NIB File Format

Mon, 14 Jan 2008 09:56:37 Z

A nib file is 232960 bytes long = 6656 bytes per track.

TRACK      OFFSET (HEX)    OFFSET (DECIMAL)
$00             $0              0
$01             $1a00           6656
$02             $3400           13312
$03             $4e00           19968
$04             $6800           26624
$05             $8200           33280
$06             $9c00           39936
$07             $b600           46592
$08             $d000           53248
$09             $ea00           59904
$0a             $10400          66560
$0b             $11e00          73216
$0c             $13800          79872
$0d             $15200          86528
$0e             $16c00          93184
$0f             $18600          99840
$10             $1a000          106496
$11             $1ba00          113152
$12             $1d400          119808
$13             $1ee00          126464
$14             $20800          133120
$15             $22200          139776
$16             $23c00          146432
$17             $25600          153088
$18             $27000          159744
$19             $28a00          166400
$1a             $2a400          173056
$1b             $2be00          179712
$1c             $2d800          186368
$1d             $2f200          193024
$1e             $30c00          199680
$1f             $32600          206336
$20             $34000          212992
$21             $35a00          219648
$22             $37400          226304

DSK File Format

Mon, 14 Jan 2008 09:53:26 Z

A standard DSK file is 143360 bytes long.
This is 35 tracks, each track is 4096 bytes.

Track       Offset (HEX)    Offset (Decimal)
$00             $0              0
$01             $1000           4096
$02             $2000           8192
$03             $3000           12288
$04             $4000           16384
$05             $5000           20480
$06             $6000           24576
$07             $7000           28672
$08             $8000           32768
$09             $9000           36864
$0a             $a000           40960
$0b             $b000           45056
$0c             $c000           49152
$0d             $d000           53248
$0e             $e000           57344
$0f             $f000           61440
$10             $10000          65536
$11             $11000          69632
$12             $12000          73728
$13             $13000          77824
$14             $14000          81920
$15             $15000          86016
$16             $16000          90112
$17             $17000          94208
$18             $18000          98304
$19             $19000          102400
$1a             $1a000          106496
$1b             $1b000          110592
$1c             $1c000          114688
$1d             $1d000          118784
$1e             $1e000          122880
$1f             $1f000          126976
$20             $20000          131072
$21             $21000          135168
$22             $22000          139264

Home Page

Mon, 14 Jan 2008 09:47:15 Z

dsktool.rb is a command line tool + libraries (all in ruby) for manipulating DSK format images used by Apple 2 emulators.

How Tos

Installing dsktool
Getting started with dsktool
Cataloging Disk Images
Extracting Files From Disk Images
Initializing Disk Images
Adding Files To Disk Images

Technical Details

Supported File Systems
DSK File Format
NIB File Format

External Links

Adding Files To Disk Images

Mon, 31 Dec 2007 12:54:52 Z

Currently (as of version 0.4.2) only NADOL and Apple DOS images can have files added to them.

To add a file to an existing image, use the ”-a” or ”—add” command, followed by the name of the file to add.

For Apple DOS files, the default file type is a Text File?. If you wish to add some other file type, you can use the ”-t” or ”—filetype”, followed by EITHER a single letter (A for AppleSoft BASIC File?, B for a Binary File?, I for Integer BASIC File?, T for Text File?) or else a hex number that indicates the Apple DOS file type.

Example 1: adding a text file to an existing DOS image.

jonno@ubuntu:~/disks$ echo "This is a test"> test.txt
jonno@ubuntu:~/disks$ dsktool.rb --add test.txt SCRATCH.DSK
jonno@ubuntu:~/disks$ dsktool.rb -c SCRATCH.DSK
SCRATCH.DSK
sector order:   physical
filesystem:     dos
 A 0256 HELLO
 T 0256 TEST.TXT
jonno@ubuntu:~/disks$ dsktool.rb -e test.txt SCRATCH.DSK
This is a test
jonno@ubuntu:~/disks$

Example 2: copying the HELLO file from an existing DOS image to a new image.

jonno@ubuntu:~/disks$ dsktool.rb -e HELLO --raw -o HELLO ADT131.dsk
jonno@ubuntu:~/disks$ dsktool.rb --init dos33 --add HELLO -t A newdisk.dsk
jonno@ubuntu:~/disks$ dsktool.rb -e HELLO newdisk.dsk
10 PRINT CHR$ (4)"BRUN ADT" 
10
jonno@ubuntu:~/disks$

For Binary Files on Apple DOS images, you can use the ”-b” or ”—base” to set the “base address” (the address where DOS will load the file into when the file is BLOADed or BRUNed).

Example 3: adding a binary file to a DOS image, and setting the base address

jonno@ubuntu:~/disks$ dsktool.rb --add a.out --filetype B --base $2000 SCRATCH.DSK
jonno@ubuntu:~/disks$ dsktool.rb -c SCRATCH.DSK
SCRATCH.DSK
sector order:   physical
filesystem:     dos
 B 0512 A.OUT
 A 0256 HELLO
 T 0256 TEST.TXT
jonno@ubuntu:~/disks$

Extracting Files From Disk Images

Mon, 31 Dec 2007 12:08:28 Z

The -e or—extract option extracts a single file from a disk image.

The extracted file will either be displayed on the screen, or it can be written to a file by using the ”-o” or ”—output” command to specify a filename to extract the file into.

Example 1: – Cataloging a DOS 3.3 disk and then showing a Text file

jonno@ubuntu:~/disks$ dsktool.rb -c computist_starter_kit_v2.02.dskcomputist_starter_kit_v2.02.dsk
sector order:   physical
filesystem: dos
 T 0256 CAPTURE
 T 0768 CHANGES
 B 0256 CHECKBIN
 B 0256 CHECKSOFT
 A 2560 COMPUTIST'S STARTER KIT 2.02
 A 5376 CONTROLLER WRITER
 A 4352 CORE DISK SEARCHER
 B 0512 CSAVER
 A 9472 DISKEDIT
 B 1024 DOC VIEWER
 T 7936 DOC.CONTROLLER WRITER
 B 4352 DOC.CORE DISK SEARCHER
 B 13312 DOC.DISKEDIT
 B 7168 DOC.DOS ALTERER
 B 23552 DOC.SUPER IOB
 B 11264 DOC.THE NIBBLER
 A 7680 DOS ALTERER
 T 0256 FAST.CON
 B 0256 IOB.OBJ0
 T 0512 NEWSWAP.CON
 B 0256 OBJ.LINE 10
 B 0256 OBJ.TITLE SEQUENCE
 B 1024 PIC.TITLE
 B 0256 SEARCH.OBJ
 T 0512 STANDARD.CON
 T 0256 START
 A 3840 SUPER IOB
 T 0512 SWAP.CON
 A 4352 THE NIBBLER
jonno@ubuntu:~/disks$ dsktool.rb -e changes computist_starter_kit_v2.02.dsk
    In the starter kit, there have been some changes. These changes are listed below.

1...The differences between version 2 and version 2.01 is that in
the print routine prompts in version 2 asked for left and right
margins, and version 2.01 now asks for left and right indent.
It (version 2.01) now asks for maximum characters per line and it
also shows what should normally be entered for this. It also
shows the usual number of lines per page.

2...The differences between version 2.01 and 2.02 is that the
program "Controller Writer" and its document file are now
included on the Starter Kit.

jonno@ubuntu:~/disks$

For “tokenised” files (Applesoft Basic?, Integer Basic?,[[SCASM],NADOL Files?), the default behavior is to detokenise the file (i.e. into the format that it would show in if you did a LIST command on the Apple).

Example 2 – displaying the “HELLO” Applesoft Basic? file from a deprotected “Temple of Apshai” disk image:

jonno@ubuntu:~/disks$ dsktool.rb -e hello  http://jamtronix.com/dsks/apshai.dsk.gz
5 REM  TEMPLE 20920
6 REM  MODIFIED FOR TITLES
20 POKE 103,1: POKE 104,96
25 POKE 24576,0
30 PRINT CHR$ (4)"RUN TITLE" 
jonno@ubuntu:~/disks$

If for some reason, it is desired to have the original file extracted unaltered then the ”-r” or ”—raw” option can be added to the ”—extract” command.

Example 3 – extracting the “HELLO” Applesoft Basic? file from a deprotected “Temple of Apshai” disk image into a raw file:

jonno@ubuntu:~/disks$ dsktool.rb -e hello  -o hello.bin --raw http://jamtronix.com/dsks/apshai.dsk.gz
jonno@ubuntu:~/disks$ hexdump -C hello.bin
00000000  64 00 14 60 05 00 b2 20  54 45 4d 50 4c 45 20 32  |d..`... TEMPLE 2|
00000010  30 39 32 30 00 2e 60 06  00 b2 20 4d 4f 44 49 46  |0920..`... MODIF|
00000020  49 45 44 20 46 4f 52 20  54 49 54 4c 45 53 00 41  |IED FOR TITLES.A|
00000030  60 14 00 b9 31 30 33 2c  31 3a b9 31 30 34 2c 39  |`...103,1:.104,9|
00000040  36 00 4e 60 19 00 b9 32  34 35 37 36 2c 30 00 63  |6.N`...24576,0.c|
00000050  60 1e 00 ba e7 28 34 29  22 52 55 4e 20 54 49 54  |`....(4)"RUN TIT|
00000060  4c 45 22 00 00 00 4c 00  00 00 00 00 00 00 00 00  |LE"...L.........|
00000070  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
*
00000100
jonno@ubuntu:~/disks$

Next: Initializing Disk Images

Apple DOS

Mon, 31 Dec 2007 12:07:01 Z

http://en.wikipedia.org/wiki/Apple_DOS

Apple Pro DOS

Mon, 31 Dec 2007 12:06:22 Z

http://en.wikipedia.org/wiki/Apple_ProDOS

Apple Pascal

Mon, 31 Dec 2007 12:06:05 Z

http://en.wikipedia.org/wiki/Apple_Pascal

Initializing Disk Images

Mon, 31 Dec 2007 12:03:24 Z

To create a new DSK image, use the ”-I” or ”—init” commands. You must specify the file system to be used. As of version 0.4.1, only DOS 3.3 and NADOL file systems can be created, and the Sector Ordering? will always be “physical”.

Example 1 – creating an uncompressed DOS 3.3 DSK:

jonno@ubuntu:~/disks$ dsktool.rb -I dos33 test.dsk
jonno@ubuntu:~/disks$ ls -l test.dsk
-rw-r--r-- 1 jonno jonno 143360 2007-12-30 20:51 test.dsk
jonno@ubuntu:~/disks$

Example 2 – creating a compressed DOS 3.3 DSK:

jonno@ubuntu:~/disks$ dsktool.rb --init dos33 test.dsk.gz
jonno@ubuntu:~/disks$ ls -l test.dsk.gz
-rw-r--r-- 1 jonno jonno 7290 2007-12-30 20:53 test.dsk.gz
jonno@ubuntu:~/disks$

Example 3 – creating an uncompressed NADOL DSK and cataloging it.

jonno@ubuntu:~/disks$ dsktool.rb -cI nadol nadoltest.po
nadoltest.po
sector order:   physical
filesystem:     nadol
 16128 NADOL
jonno@ubuntu:~/disks$

Next: Adding Files To Disk Images

Getting started with dsktool

Mon, 31 Dec 2007 11:52:03 Z

Once you’ve finished Installing dsktool, the first thing to learn is how to get help.
type “dsktool.rb -h” for a list of all commands dsktool understands.

Here’s what happens when try it with the curent version (0.4.2):

jonno@ubuntu:~$ dsktool.rb -h
dsktool.rb

Synopsis
--------
Manipulate DSK format files (as used by Apple 2 emulators)

Usage
-----
dsktool.rb [switches] <filename.dsk>

 -a | --add FILENAME       (*) add file
 -b | --base BASE          use BASE as address to load Binary File
                           this will add 2 bytes to the start of file
                           BASE should be a hex number
                           (can be prefixed with $, 0x, or nothing)
 -B | --bootcode FILENAME  FILENAME gets written to track 0, sector 0
                           FILENAME should be compiled to run at $0801
                           FILENAME can be up to 4Kb in size.
 -c | --catalog            display catalog
 -d | --dump FILENAME      hex dump
 -D | --diskdump           hex dump of entire disk
      --delete FILENAME    (*) delete named file
 -e | --extract FILENAME   extract file by name (either to stdout,
                           or file specified by --output)
 -h | --help               display this message
 -I | --init FILESYSTEM    initialise the disk with the specified filesytem
                           DSK will be created if it doesn't exist.
                           FILESYSTEM can be : prodos,dos33,nadol,pascal,none
 -l | --list FILENAME      monitor style listing (disassembles 65C02 opcodes)
 -o | --output FILENAME    specify name to save extracted file as
 -r | --raw                don't convert files to ASCII
 -S | --showtrace          show full stack trace on any error
 -t | --filetype FILETYPE  file type for file being added.
                           Can be a single letter (A/I/B/T) or number.
                           Default for DOS 3.3 is 0x00 (Text)
 -T | --tokenise           (*) tokenise input file before adding
 -v | --version            show version number
 -x | --explode            extract all files

  (*) options marked with an asterisk are only available for
      file systems that have READ/WRITE support.

       Currently supported filesystems:
               Apple Pascal         (read only)
               DOS 3.3              (READ/WRITE)
               NADOL                (READ/WRITE)
               ProDOS 8             (read only)

       Supports 16 sector DSK images
       files with extension .gz will be read & written using gzip
       input files can be URLs

examples:

       dsktool.rb -c http://jamtronix.com/dsks/apshai.dsk.gz
       dsktool.rb --list fid -o fid.lst DOS3MASTR.dsk
       dsktool.rb --extract "COLOR DEMOSOFT" DOS3MASTR.dsk
       dsktool.rb -e HELLO -o HELLO.bas DOS3MASTR.dsk
       dsktool.rb -x DOS3MASTR.dsk.gz -o /tmp/DOS3MASTR/
       dsktool.rb --add STARTUP -T nadol.po
       dsktool.rb --add c:\src\dosdemo\a.out -t B -b $2000 dosdemo.dsk
       dsktool.rb --init dos33 new_dos_disk.dsk.gz
       dsktool.rb --I none -B /tmp/a.out demo1.dsk

jonno@ubuntu:~$

Most commands have both a “short” form, consisting of one dash followed by single letter, and a “long” form consisting of two dashes followed by a full word. For example, the help command can be accessed either by ”-h” or ”—help”.

Next: Cataloging Disk Images

Cataloging Disk Images

Sun, 30 Dec 2007 11:33:42 Z

The catalog command is accessed with either ”-c” or ”—catalog”.

Here is an example, showing the contents of an ADTPro disk image:

jonno@ubuntu:~/ADTPro-1.0.3/disks$ dsktool.rb --catalog ADTPRO-1.0.3.PO
ADTPRO-1.0.3.PO
sector order:   physical
filesystem:     prodos
volume name:    ADTPRO.1.0.3
 12544   SYS : $2000    ADTPRO
 13428   SYS : $2000    ADTPROAUD
 15365   SYS : $2000    ADTPROETH
 10240   SYS : $2000    BASIC.SYSTEM
 16509   SYS : $0       PRODOS
  1220   BAS : $801     STARTUP
jonno@ubuntu:~/ADTPro-1.0.3/disks$

Here’s another example, which demonstrates that dsktool can access images hosted remotely (by providing the full URL) and also how dsktool can handle images compressed with gzip :

jonno@ubuntu:~/ADTPro-1.0.3/disks$  dsktool.rb -c http://jamtronix.com/dsks/apshai.dsk.gz
http://jamtronix.com/dsks/apshai.dsk.gz
sector order:   physical
filesystem:     dos
 B 0256 ASCII
*B 2304 DATA1
*B 2304 DATA2
*B 2304 DATA3
*B 2304 DATA4
*A 13312 DM
 A 0256 HELLO
 A 0256 HELLO.OLD
*A 17408 INN
*B 0768 OBJ.1
*B 5888 OBJ.2
 B 2304 SHAPE1
 B 2304 SHAPE1.OLD
 B 2304 SHAPE2
 B 2304 SHAPE2.OLD
 B 2304 SHAPE3
 B 2304 SHAPE3.OLD
 B 2304 SHAPE4
 B 2304 SHAPE4.OLD
 B 2560 TEMPLE OF APSHAI RWTS
*A 4352 TITLE
 B 0512 TITLESHAPES
jonno@ubuntu:~/ADTPro-1.0.3/disks$

Next: Extracting Files From Disk Images

NADOL

Sun, 30 Dec 2007 10:35:31 Z

NADOL – Nibbles Away Disk Optimized Language

NADOL is a DOS and interpreted language created for the “Nibbles Away III” disk copy utility.

NADOL images are 35 track, 16 sector. In order to use these images in Apple Win, you must use the .po file extension. I have not tested under other emulators.

A NADOL disk has a catalog at track $00, sector $03 to track $00, sector $09

CATALOG FORMAT

Each entry in the catalog consists of $10 bytes, which are:

$00-$0B – filename – if file is deleted, first byte will be $FF. If first byte is $00, this catalog slot is empty.
$0C-$0D – filesize (low byte first)
$0E – track of track sector list sector
$0F – sector of track sector list sector

TRACK/SECTOR LIST FORMAT

pairs of track/sectors in order. up to 128 entries (assumes that no file can be > 128 sectors)

SECTOR USAGE BITMAP

The sector usage bitmap is at Track $00, Sector $2, from bytes $20 .. $65

There are two bytes for each track. The first (low) byte records usage of sectors $00..$07, the second (high) byte records usage of sectors $08..$0F. The high order bit represents the lowest sector (i.e. bit 7 in the low byte represents sector $00, bit 0 in the high byte represents sector $0F). If the bit is set, that means the sector is in use.

External links:

http://www.textfiles.com/apple/DOCUMENTATION/nibbles.away.iii.txt
Deckard’s NADOL page (site is in french, scanned documents are english)