
 


		    ======  Make Dir! v1.0 =======
				 by
			  Jacek Jadwiszczak
		    ==============================


 Contents:
1. Licensing conditions

2. How do the subdirectories work?
    2.1 Subdirectories on other computers
    2.2 Tree structure on c64 disk
    2.3 What are the differences

3. More details....
    3.1 Compatibility with software
    3.2 Hardware and subdirectories
    3.3 DOs and DON'Ts

4. Using "Make Dir!"

5. Subdirectories and programming
    5.1 Basic
    5.2 Assembly language






    1. Licensing conditions
   -------------------------

"Make Dir! v1.0" is a software with payment option. It means, you can feel
free to copy it, use it and give it away, BUT WITH NO CHARGES FOR IT.
Also do not make improved versions of the executable, please;if you find a way
to improve the "Make Dir!",just send the author a note and it'll be used in the
next release, with full credits given to you. As the author has no control
over your use of this software,he can't bear the responsibility for all results
of using the "Make Dir!".

And what does "the payment option" means? Well,if you find this program useful
and worth of future improvements, send just one american dollar to the author.
It is not the obligatory charge for using the "Make Dir!" and YOU decide if $1
is too much for it. Additional suggestions and opinions will stimulate the
author to create next version of the "Make Dir!", so feel free to express your
point of view. Money will allow to improve author's equipment, so if you decide
to send it, just put the one dollar bill into an envelope with your remarks and
post it to:

			     Jacek Jadwiszczak
			  ul. Drzewieckiego 30/16
			      54-129 Wroclaw
				  Poland

For fast contact E-mail:

		     JJADWISZ at ict-pwr.wroc.edu.pl

		      ---------------------------
The whole method of creating and using subdirectories with 1541/71 disk
drive is designed by Jacek Jadwiszczak.
		      ---------------------------

I would like to thank Piotr Szopinski, Marko Makela and Mariusz Wosko for
helping me in my work on the "Make Dir!"; without them it would be much
harder.
								  JJ.






    2. How do the subdirectories work?
   ------------------------------------

    2.1 Subdirectories on other computers
	(or very short info about them)

The MS-DOS,Amiga OS,and many other systems have got some build-in commands for
creating and using the subdirectories. Generally, the subdirectories help you
keep your data in order: you can keep them in groups sorted by subject, date,
or in any other way. The whole "subdir affair" needs three tools:

	   1. for creating new subdirectory
	   2. for using it (changing the current dir, reaching the data in it)
	   3. for deleting non-wanted ones

When you see the directory of a 1541/71 disk, it is one and only list of files
saved on it. Each subdirectory is a simillar structure, but it may be a number
of them on the same disk. All of them  are connected in so called "tree 
structure"; it means, every subdirectory has a ROOT and may have the next
(sub-sub-) directory inside. Here is the sample of such a structure:

     MAIN (root) --
		   |
		    -- subdir1 --
				 |
			      -------
			     |       |
			  subdir2  subdir3

Every directory may have some files placed in it right beside other subdirs.
The first directory created in formatting process is called THE ROOT or THE
MAIN DIRECTORY as you can't erase it or make directory placed over it. Most
systems place the ".." file in each subdirectory. That means: "upper dir", and
when you want to go out of current subdir (f.e. from "subdir3" to "subdir1"),
you are changing current directory to ".." (in MS-DOS it is: "cd ..").




    2.2 Tree structure on c64 disk

Up till now, only 1581 and some of the CMD drives allowed you to use subdirs.
Now, it is possible with 1541/71 disk drive without any DOS (Disk Operating
System) or Kernal changes, thanks to easy-to-use c64 subdirectory system based
on a "Make Dir!" program and the LOAD operation.

Imagine, your directory of 1541/71 disk would be like this:

128  "binary stuff"     PRG
12   "data 1"           SEQ
69   "data 2"           SEQ
2    "documents" <dir>  PRG
23   "data 3"           SEQ

Where "documents" is a subdirectory made using the "Make Dir!" (in it you can
keep f.e. this and not only this documentation of software you are using).
To change the current dir just type:

		    load "dir name",drive,1      <and press RETURN>

where "dir name" is the name of subdirectory you want to get in, and drive is
an address of disk-drive. In this sample it could be: load "documents",8,1.
When the drive stop, new directory will be like:

0    ".."        <dir>  PRG<
32   "more data"        SEQ
2    "tools dox" <dir>  PRG
2    "game trick"<dir>  PRG

As you have already noticed all files with <dir> are subdirectories. The ".."
means "upper" directory, and when you type: load "..",8,1 you will change the
current directory to the main. Here is the "tree" of our sample disk:

   -----------------<----------------
  |                                  |
main ---- "binary stuff"             |
	  "data 1"                   |  ---------<------------
	  "data 2"                   | |                      |
	  "documents" <dir>  --->   ".."        <dir>         |
	  "data 3"                  "more data"               |
				    "tools dox" <dir> --->   ".."     <dir>
				    "game trick"<dir>

And this is subdirectory "tree":

		       ----- tools dox
		      |
main --- documents ---|
		      |
		       ----- game trick

To decrease the amount of blocks taken for subdirectory, the ".." have a length
equal ZERO BLOCKS. It is also scratch-protected,erasing it would destroy a path
to data placed in main and other directories. As you have probably noticed one
subdir takes 3 blocks:

		       2 for "subdir name"<dir>
		       0 for ".."         <dir>
		       1 for the first sector of the new directory.

The more files will be placed in subdir, the more blocks whole dir will take
(just like a standard directory would grow up). The only limit for amount of
subdirectories on disk is the number of free blocks and DOS limit for files:
1541/71 DOS can handle not more than 144 files, and it's up to you how many of
them will be subdirs (in fact the method of creating subdirs will give a little
more files allowed on disk).
The "name"<dir> is the standard file, which you can rename, change its position
in directory, and so on...
For scratching the subdirectories REMOVE option in "Make Dir!" is recommended.





    2.3 What are the differences ?

Here will be some differences between 1541/71 and 1581 or MS-DOS subdirectories
pointed out:

First of all, you are not using any "cd" ("Change Dir") command, which would be
included in c64 Basic commands. It would be no problem to add it to the Basic 
2.0, but that would be the real limit for using non-Basic programs together 
with subdirectories.

You can't set the path for searching the programs/data on disk. In this system
every subdir depends only on upper one, and you can't use, for example:
	   load "/documents/game trick/lemmings",8,1
There is only ONE change of current subdir allowed in one load command.

To create and delete subdirectories you need the "Make Dir!", but though it
also allows to change dir, it is not necessary to do it from inside the
"Make Dir!".







    3. More details...
   --------------------

    3.1 Compatibility with software

Every subdirectory created by "Make Dir!" is seen by DOS as a standard list
of files on disk. You can load, save, rename and erase any programs in it,
using your favorite utilities or straight from Basic editor. That is the
reason, all software is able to use subdirectories. Even if it has not im-
plemented "change dir" option, you can change the current dir into needed one 
before running the program you want to use.
You must remember, there are TWO exceptions:

- programs reading data straight from tracks and sectors of disk
- GEOS system

First one will work properly, but will not see any subdirectory (as it is not
using the DOS). GEOS doesn't like CBM files on its disks (manual-book says it
is not recommended to keep CBM and GEOS files on the same disk) and it has a
bit different way of storing data on disk (info block). But when you create
the subdir on a GEOS disk, it'll work though it will not be easy to change
the dir from DeskTop. It is possible to create "Make Dir!" system for GEOS, so
send your opinions about it, please.


    3.2 Hardware and subdirectories

The whole idea of this method is to not change ANYTHING on a hardware way, so
you don't have to worry about your electronics skills. All routines are written
for c64, and will work on c128 only in 64 mode. I was not able to create "Make
Dir! 128", because of no publications about c128 memory mapping available in
Poland. Perhaps in future releases will be c128 version included.

"Make Dir!" and the subdirectories made by it were checked on the c128D (with
built in 1571 drive) and the c64 with 1541 drive.

It may be some problems with cartridges like Action Replay, which changes the
Basic error vector after every operation. In that case you'll get error message
after every change dir typed in Basic editor, and it might force you to plug
out the cartridge for running Basic programs using subdirs (but it depends on
kind of your cartridge and the program). It has no influence on changing the
current dir in direct mode, though the error message will be displayed.




    3.3 DOs and DON'Ts


				 ===== DO =====

    Always use 1 as the secondary address in LOAD, or you get no result.

    Use properly formatted disks. When you get too many error-messages,
    format the disk again.

    Try to avoid saving with replace ("@: "). Saving with "@:", 1541/71 DOS
    might not be able to release all blocks that become unused, and you may
    lose some blocks of free disk space.

    Always remove only ONE subdirectory at once. 
    
    

				===== DON'T =====

    Never ever erase ".." file. To get rid of non-wanted dir use "Remove"
    option in "Make Dir!".

    Do not VALIDATE the disk with subdirectories on it! VALIDATE and COLLECT
    will recover the BAM based on the files in the current directory, and 
    after that every time you create a file, it may overwrite some of the 
    existing files. I'm working on a new "validate" (like special "validate"
    routine for GEOS disks), and I hope it will be available in the next
    release of "Make Dir!".

    Do not remove subdirectories with files in it. Always scratch all files
    and subdirectories inside it and then erase it (see: "Using 'Make Dir!'"), 
    or the blocks used by the files/sub-subdirs will not be freed.
    
    You can use the '*' in the name of subdir you want to change into, but 
    DON'T USE IT IN THE NAME OF THE DIR TO REMOVE or not all blocks will be 
    made free. 
    (example: 'my*' will erase: 'my dir', 'myth' and 'my trash' directories,
     but only the first will be removed properly and you lose 2 or more blocks
     from your disk).






    4. Using "Make Dir!"
   ----------------------

"Make Dir!" is a LOAD & RUN file, so there is no difference from running it and
any other PRG file. It is menu-driven program: to move bar use cursor keys and
to choose an option strike RETURN. To avoid terrible disk-drive head bouncing
(when you f.e. try to read dir with no disk in drive) "Make Dir!" changes some
flags in drive RAM; instead of irritating noises there'll be silence and the
drive LED will be flashing fast, when in few seconds nothing comes better, an
error-message will be displayed.
The whole program is easy to use, so just few words about each option:

CHANGE DRIVE - allows to change the address of device used as input/output.
	       Accepts numbers between 7 and 30, so there shouldn't be any
	       problems with using drives other than 8. If choosen drive is not
	       present, an error message will be displayed and if you decide
	       to abort operation "Make Dir!" will restore old drive number
	       and go back to the main menu.
DISPLAY CURRENT DIR - shows directory. When it is bigger than the screen, you
	       will be asked to press any key.The "arrow left" key will get you
	       back to the main menu without having to read through the whole
	       directory, any other combination will continue displaying.
CHANGE DIR   - lets you to change the current directory (it can be used to
	       create tree-structure on your disk).
MAKE NEW DIR - big routine creating new subdirectory. First, the current dir
	       will be read (the bigger it is, the more time whole operation 
	       takes), and if there is less than 3 blocks free, "Make Dir!" 
	       will display: MINIMUM DISK SPACE REQUIRED: 3 BLKS! and get you 
	       back to the main menu.
REMOVE DIR   - option for scratching subdirectories. Always erase all files in
	       subdir and then go to the "upper" dir and scratch it.
	       For instance:

			   "dir to scratch" <dir> ---->   ".."      <dir>
							  "file 1"
							  "file 2"

	       First erase "file*", then use 'load "..",8,1' (or use "CHANGE
	       DIR" in "Make Dir!") and then use option "REMOVE DIR" and enter
	       "dir to scratch" as a filename of subdir to erase.
CREDITS      - very short info about author and version of "Make Dir!".
LEAVE...     - RESET! When you have plugged in cartridge:
	       Action Replay, Final or Black Box, this option will activate
	       your box in expansion port and there will be no need to use the
	       button on the cartridge. In any other case it'll be standard
	       RESET.

Some general remarks:

The name of a subdirectory can have up to 10 letters, and when you are asked to
enter the name, "Make Dir!" will not let you enter more than 10 chars. Also
cursor keys and other non-ASCII are ignored. You can use DELETE key as it is
described in c64 manual-book (INSERT is not implemented in "Make Dir!") and
when you try to enter no chars (empty name), program will take it as a cancel
and get you back to the main menu. You can't enter the '*' letter in some of 
the names and "Make Dir!" will not let you do that displaying an error message.

Most of errors which can occur during disk operations are displayed in window
with its full description and you can retry or abort operation.





    5. Programming and subdirectories.
   ------------------------------------

This chapter is for those users who want to implement subdirs into their
programs. In few words: here is the way to use (not to create) subdirectories
inside a program.


	5.1 Basic

Using subdirs in Basic is very simple, as the method of <dir> was designed
specially for working with Basic. Generally, there is no difference between
changing directory in direct mode and doing it from inside the Basic program.
Here is a sample program to change the current directory:

10 input "Enter the name of subdirectory you want to get into: ";a$
20 load a$,8,1
30 print "The new directory is ";a$
40 end

More advanced in programming should know that return from changing-dir-routine
is done by jump to Basic routine "get the next command" ($a7ae). In that way,
there is possible to execute whole Basic program.


	5.2 Assembly language

Now few words about using subdirs in AL... It is almost the same idea like
using them in Basic, but all action is done with Kernal routines. The main
thing is to load the file with name of subdir you want to get in into right
memory area, and that's the reason you should use 1 as a secondary address.
The "work" routines are loaded in $0100-$0200 addresses, and you should
remember about it if you are using stack for your purposes. In that case you
have to copy your data from $0100-$0200 into another area, and put it back
after changing directory. As the whole routines have been designed to be easy
to use in Basic or direct mode, in ML you must change the $0300/$0301 vector
into an address where you want to get back after changing directory. Here is
an example in Turbo Assembler code:

      * = $1000

      sei

      ldx #<back              ;change $0300/$0301 vector
      ldy #>back
      stx $0300
      sty $0301

      lda #$01                ;prepare for load from device 8 with secondary
      tay                     ;address 1
      ldx #$08
      jsr $ffba
      lda #$09
      ldx #<name
      ldy #>name
      jsr $ffbd
      lda #$00                ;0 for load
      jsr $ffd5

back  jsr $fda3               ;here will the control be given back after
      lda #<$e38b             ;changing directory
      sta $0300
      lda #>$e38b
      sta $0301
      cli
      rts                     ; END of routine

name .text "documents"        ; the name of subdirectory


If you want to use machine language, and if your program returns to BASIC, or
when you finish your program with RTS, you MUST RESTORE THE PROPER VALUE OF
$0300/$0301 VECTOR: $e38b !!
Otherwise the Basic interpreter will crash.

						   ----------- The End. :)

