                                  DOSLink v1.0
                                  ~~~~~~~~~~~~

This is the manual for DOSLink (which also includes LinkMain), which was
written by and is copyright to Darren Hazelton (Red Haze) in May 1996, in
South Australia. It is designed to create an equivalent for the symbolic
links in Unix, for DOS.

If you read about this utility in Trax Weekly issue 58, you might be able to
skip the following section, which is basically a copy of the article I wrote
for that magazine. However you may wish to read it anyway.


What is it Useful For?
~~~~~~~~~~~~~~~~~~~~~~

A major use which I personally have for this program is to organise music
module files in a decent way. The reason this program is very useful, is
because it allows you to make `links.'

A link is simply a reference to a file somewhere on your computer, that makes
it appear in this new place AS WELL as the old place, taking very little disk
space to `duplicate' the file.

All popular operating systems have this feature, with the notable exception
of DOS. On Unix systems they are called `symbolic links', on the Mac they
have `shadows', Windows 95 and NT have another name for them, and similarly
with OS/2. Regardless of the name, they all achieve the same goal of making
more than one access point to a particular file (or directory on some
operating systems).

Now, to answer the original question - What is it useful for?

Imagine you have a large number of files - for example music or graphics -
which you collect and put on your computer. Sooner or later you are going to
have so many that if you stored them all in the same directory you wouldn't
have a clue how to find a particular picture.

The answer is to break up this clutter into separate categories.

This can either be based on the type of file (e.g. style of music or its
format), its creator (e.g. a popular musician who has released lots of
music), its quality (e.g. all your really good music could go into one
directory), its place of release (e.g. many songs get released at demo
parties or various competitions), or a million-and-one other categories you
might think of.

Without file links, however, you have to pick ONE of those categories to put
each song into, unless you feel like wasting a lot of disk space duplicating
files.

Of course, if you're running a nice OS - i.e. not DOS - then you'll have no
problem making these links, but there are many die-hard DOS users out there
(like me) who don't normally have this ability.

With DOSLink you can put each file into one of the directories you choose,
and then make links of the files into all the directories you also want to
make them appear in. Unfortunately I haven't implemented directory links yet,
since they could cause major problems.

If you don't see the use of DOSLink by now, then try reading this section
again. :)


System Requirements
~~~~~~~~~~~~~~~~~~~

You will need at least an XT running MS-DOS 5.0 or later, or an operating
system which emulates it. If the links don't seem to work, don't hesitate to
email me (address at the end of the document) to tell me what's happening. I
have only tested DOSLink on MS-DOS 6.22. I see no reason why DOSLink can't be
loaded high, but haven't tested it.

You also need enough conventional memory to load up all the linking
information, or else DOSLink will quit before loading them all. Allow 23kb
plus about 3 times more memory than the size of the list file.

Perhaps I will support EMS in later versions to save conventional memory.


How DOSLink Works
~~~~~~~~~~~~~~~~~

When you are linking files with DOSLink, you must specify a directory to link
files into, then the full path to any files you want to appear in that
directory.

For example, if you had the directory D:\MODS\BEST, and the files linked into
it were D:\MODS\IMPULSE\COOL.IT and C:\COMMAND.COM and ran DOSLink, then
there are two new files in D:\MODS\BEST, which are COOL.IT and COMMAND.COM.
As soon as a program tries to load COOL.IT from this directory, DOSLink will
actually instruct DOS to load the file D:\MODS\IMPULSE\COOL.IT for the
program.


How to Use DOSLink
~~~~~~~~~~~~~~~~~~

Once you have created a file which contains all the links you wish to create
(using LinkMain), you can run it with the following command:

DOSLINK <list file> 

where <list file> is the name of the file listing the links. If it is not
specified, `DOSLINK.LST' is assumed. For example to use my list for the
Freedom CD, I use:

DOSLINK freedom.lst

The links will be loaded, and if there are any errors (such as running out of
conventional (640k) memory, or if a file or directory doesn't exist) then
DOSLink will quit with an appropriate error message.

If loading is successful, DOSLink will report the number of directories which
have had files linked to them, and any links which were in the list should
now exist. Please remember that COMMAND.COM will not list the linked files in
a DIR command - read the `Quirks' section below for more information.

To quit DOSLink and terminate the links, simply type EXIT at the command
prompt which was run by DOSLink at start-up. The message `Quitting DOSLink.'
will be displayed when it shuts down.

You can also type:

DOSLINK /?

to get help.


How to Use LinkMain
~~~~~~~~~~~~~~~~~~~

Firstly, what does LinkMain do? It automates the creation and maintenance of
the link list files for use in DOSLink. Link list files are simply text files
containing information that DOSLink can interpret when linking files. This
means you can use any standard text editor to make/alter the lists if you
want. However, I specifically created LinkMain to do all the hard stuff for
you.

To create a new list file, use:

LINKMAIN NULL <new list name>

Where <new list name> is the name of the new list file. This file will only
be created if you use `Save', or 'Quit and save.' You can change the name of
this file with the `Change output file name.'

To alter an existing list file, use:

LINKMAIN <existing list> <output list>

Where <existing list> is the name of the existing list, and <output list> is
the file which will be written to with the alterations. If you don't specify
<output list>, it is assumed to be `NEW.LST'. The reason you can have a
different output list to the input list is in case you want to test the new
alterations before overwriting your original file. This file will only be
written to if you use `Save', or 'Quit and save.' You can change the name of
this file with the `Change output file name.'

If you don't specify any arguments, LinkMain will attempt to load
`DOSLINK.LST', and will save changes into `NEW.LST'.

Here is a brief explanation of each function in LinkMain:

`Add a directory' - Specify a new directory that you want to put links into.

`Add a file' - Specify the path to a file that you want to link into a
               directory.

`Mass-add files' - Link files into a directory using wildcards.

`Edit a directory name' - Change the path to a directory you have made links
                          into.

`Edit a file name' - Change the path to a file used for a link.

`List directories' - List the directories you have made links into.

`List files in a directory' - List the paths to files used as links in a
                              directory.

`Remove a directory' - Remove a directory you have put links into, along with
                       all the links in it.

`Remove a file' - Remove a file used as a link from a directory.

`Remove duplicate files' - Gets rid of any files which would cause repeated
                           filenames in a directory. (To avoid an infinite
                           loop.)

`Change output file name' - Change the list file which will be written to by
                            `Save' and `Quit and save'.

`Save' - Save the current link information into the output filename.

`Quit and save' - Save the current link information then quit.

`Quit without saving' - Quit without saving the current link information to
                        the output filename.


You don't have to specify the full path to a file from within LinkMain when
you are creating links, because the path will be interpreted as a relative
path and the full path will be determined automatically.

If you want to try editing your own list files, try making some with LinkMain
first, so you can understand the format. DOSLink is case insensitive.

You can also type:

LINKMAIN /?

to get help.


Tips and Tricks
~~~~~~~~~~~~~~~

One major use I have for DOSLink is to make the Freedom CD (which is full of
demos and music) easier to use. For (a random) example, I linked in all the
Necros songs from Freedom into my hard disk's \MODS\NECROS directory,
allowing me to delete all the songs I already had on hard disk which were
also sitting in Freedom's \MUSIC\ARTISTS\NECROS directory, without losing
access to any of those songs from my hard disk. I saved a lot of space this
way.

I also have a \MODS\BEST directory for all the really cool songs I have,
which is has no files in it, but I have used DOSLink to convince programs
like Cubic Player that they are actually there.

Please note that links to files cannot be written to or deleted. This is just
for the safety of your computer. You can, however, write to or delete a file
which has links to it.


Quirks
~~~~~~

Once thing you may notice about making file links is that COMMAND.COM doesn't
see linked files with a DIR command, whereas 4DOS does. Maybe I'll eventually
support COMMAND.COM, but it's not really necessary since most archivers,
music players, and trackers seem to work with the links.

Also, DOSLink seems to be disabled under Windows 3.x, even in a DOS window.
:( Fortunately, as soon as you quit Windows DOSLink starts working again. I'm
not sure why this happens... Any ideas?

Linking files from a CD-ROM works fine, but if you link a file onto a CD-ROM,
that file will appear in ALL directories on that drive, even if you specified
a particular directory for it to be in.

Executables linked into a directory on the DOS `PATH' will not run - on
MS-DOS 6.22 it generates a `Bad Command or filename' error. Noting the
capital `C', it is very peculiar!

If you are editing your own list files, then make sure you don't have two
files of the same name linked into one directory. Otherwise your computer
will get into an infinite loop. (Well not really infinite...) You can use the
feature `Remove duplicate files' in LinkMain to get around this easily.

DOSLink will not let you use links to links, since the file must be present
during start-up for it to become a link.

You may be able to cause a 'Heap Error' when you are using LinkMain, which
refers to memory corruption. Please try to repeat the error, and report it to
me as a bug.


Disclaimer
~~~~~~~~~~

DOSLink is guaranteed only to take up space on your computer. Any extra
functionality should be considered a bonus. By using DOSLink you are agreeing
that you will not take action against me over any damage caused by or in
conjunction with the use of DOSLink.


Legal Stuff
~~~~~~~~~~~

All Trademarks mentioned in this document are owned by their respective
owners.

DOSLink, LinkMain and this document cannot be altered in any way without the
written permission of Darren Hazelton. No fees may be charged for DOSLink
except the nominal cost of distribution, unless other written arrangements
have been made with me. You may copy DOSLink as many times as you want, and
distribute it as much as you want. By using DOSLink you are agreeing to these
terms and conditions.


Contact Details
~~~~~~~~~~~~~~~

If you find any bugs, or have any comments or suggestions, send them to:

redhaze@smug.student.adelaide.edu.au

I try to read my email every weekday, but I can't always get time to read it.


Greetings
~~~~~~~~~

Greets go to:

        Pulse/POP       Thanks for all the tips on ASM coding, especially
                        the ones you gave me during lectures ;)

	Da Schemer/FTS	Keep on coding...

	Spoony/FTS	Oooooer the BBS is alive again! (Morbid Incite)

        Josh/TBK        Learn to code in asm :)

        iCEWATER        Fix up ya home page. Coven 96 isn't THAT far away.

        ...Anyone else I can't be bothered greeting in preference to getting
        sleep. :)


Thanks also to the Great `I Am' for Your grace in sending Your Son for us
all. I know where I would be going without You.


Future Development
~~~~~~~~~~~~~~~~~~

In between coding this, learning for exams, and coding 2 or 3 other programs,
and organising Coven 96, I may be able to improve DOSLink. Future
improvements may be:

	EMS support for link information.

	100% assembler conversion of DOSLink. (It's about 50/50 C++/Asm)

	Much nicer interface for LinkMain. (When I get BC++ 5.0)

        Supporting COMMAND.COM's `DIR' command.


Final Words
~~~~~~~~~~~

I don't ask for money for DOSLink, since I get a lot of benefit for myself
from it. Perhaps you could be nice and send me some email if you appreciate
DOSLink, since I would like to find out the kind of people using DOSLink, and
for what purpose.

I hope you find DOSLink as useful as I do! And I hope you don't encounter any
bugs that may remain - for your own sake. :) Remember it's still an early
version number, however.

Until next we meet, goodbye.

Red Haze.
