==============================================================================
Disk Change Directory v3.0              (c)1995-1998 Roger de Reus 13-NOV-1998
==============================================================================
DCD (disk change directory) is `yet another' smart  change directory.  You ask
why?  Well, because I could not find a program which does what I want.  So, if
you are a command line  junkie who wants  to enhance productivity: here is  my
version, which I donate to the public domain.  The  package may be distributed
freely in  its  entirety only  (i.e., you should  have  received  three files:
dcd.cmd, dcd.doc,  and  dcd.diz).  Changes  to   the code   are allowed  under
condition that the files are saved under another name and clearly documented. 

Disclaimer: DCD.CMD is supplied on an as-is basis.  The author of this program 
            is not responsible for any damage (loss of data etc.) caused by 
            the (mis)use of this program.  No claim as to the proper 
            functioning of this program is made (although I do my best, of 
            course). Usage at your own risk. 

OK, let's get down to it. 


INSTALLATION. 

DCD.CMD requires OS/2 and REXX  and should be located  somewhere on your path.
First you build a file DCD.LST which  contains the directory structure of your
drives.  This file  will be placed  in the same  directory as where DCD.CMD is
located.  (If you saved DCD.CMD under another name, say MYCD.CMD, a file named
MYCD.LST will be created.  Alternate list files can  be specified as well, see
later.)  You can  then  use DCD to hop   around from one  directory to another
across drives ad libitum (or  open an arbitrary  directory as desktop folder).
Optionally, (GNU's)   grep.exe  can be used to   match  wildcards in directory
names. 


USAGE. 

  DCD [-?|-help] [-scan|-rescan <drives>] [-option] <-n>|<[dir]> 

The "[dir]"  part of the input is  required when you want  to  move to another
directory. [dir] is the partial or full directory name.  The input may contain
blanks (although the input is stripped from leading and trailing blanks, drive
letters, path names, and regular expressions.   When the input  is of the form
-n (with  n a positive  integer),  you will be  brought   n levels up  in  the
directory tree. 

Examples: 

   dcd c:\foo    match occurrences of "\foo" on drive "c:" 
   dcd fo        match occurrences of "fo" on current drive 
   dcd foo       match occurrences of " foo" on current drive 
   dcd foo bar   match occurrences of " foo bar" on current drive 
   dcd foo\bar   match occurrences of "foo\bar" on current drive 
   dcd d:..\..   go to `grandparent' of current directory on drive "d:" 
   dcd -2        go up two levels in directory tree 
   dcd e:        change to drive "e:" 
   dcd %home%    change to directory set by environment variable "home" 


OPTIONS. 

The default  behavior of  DCD  can be  changed   by using  options.  Arguments
starting `-' or `/' are recognized as options.  Options may be abbreviated and
are  not case  sensitive.  Options and  their  arguments are separated  by the
blank character.  A full list of options  is given below (the capitalized part
of the options is the minimum required to recognize the option):

   -?             short help
   -Help          long help
   -Global        global change directory: match directories on all drives
   -Local         local change directory: stay on current drive (default)
   -SElect        user select mode: query for multiple matches (default)
   -Next          round-robin mode: do not query, jump to next match
   -RR            synonymous with -next
   -ROundrobin    synonymous with -next
   -PUshdir       push current dir into environment variable DCD_Push (or
                  MYDCD_Push if you renamed DCD.CMD to MYDCD.CMD)
   -POpdir        jump to last directory set by -pushdir
   -POPStack      display stack (DCD_Push environment variable)
   -DIRectory     switch to directory [dir], stay on command line
   -FOLder        open directory [dir] as folder on desktop
   -DESKtop       open desktop folder [dir]; DCD tries to determine the boot
                  drive; [dir] is a subdirectory of \Desktop. Usage of this 
                  option requires scanning of the boot drive
   -FGfolder      try to open folder in foreground (folder gets focus)
   -BGfolder      try to open folder in background (cmdline keeps focus)
   -FGDesktop     try to open desktop folder in foreground (folder gets focus)
   -BGDesktop     try to open desktop folder in background
   -LIst <file>   use alternate directory listing from <file>; full qualified
                  path name must be given for <file>
   -LST           synonymous with -list
   -Scan          scan <drives> and exit program
        <drives>  one or more drive letters separated by whatever you want, or
                  not separated at all; all drives must be accessible or in use
   -REScan        as -scan; however, data in DCD.LST will be retained and
                  scanned drives will be refreshed
   -Partialmatch  require partial match of directory name (default)
   -Fullmatch     require full match of directory name
   -UPpercase     directory search not case sensitive, i.e., [dir] converts to
                  uppercase (default)
   -LOWercase     directory search case sensitive (e.g., dcd foo will not
                  match a directory named FOO). Note that drive letters should
                  be entered as uppercase characters
   -/             convert \ in [dir] to /
   -\             convert / in [dir] to \
   --             do not convert \ or / (default)
   -Expression    search for <dir>, useful if <dir> begins with -.
   -NOGREP        do not use grep for wildcard matching.
   -REGEX         force grep with <dir> as regular expression.
   -GREPOpt <opt> pass <opt> to grep command (multiple -grepopt concatenate).
   -COLO[U]R      attempt to color your world...
   -STAtus        display status
   -Version       display version number 

By default, DCD will try to match a directory on the current disk, if no drive
is specified in  the  input.  If multiple matches  exist,   the user  will  be
prompted for her/his/its choice.   If one or more  full matches are found, one
may  hit the enter  key to switch to  the suggested directory.  Another choice
may be `Esc',  which exits  the program without  further action.   The maximum
number of choices is  limited to 36 (0-9,A-Z) or  one less than the  number of
rows on the screen, whatever is smaller.  If the  maximum number of choices is
exceeded, DCD will  issue warning messages, but these  will most likely scroll
off  your screen.  Anyway, if so  many possibilities exist, you should specify
your directory more precise,   or use the -next mode.    If no match to   your
directory is found in  the list, an attempt to   switch to the  directory (and
drive) directly will  be made.  Finally, if all  fails a suggestion  to rescan
your disk drives is made.

Examples: 

   dcd foo             change to *foo* on current drive, prompt if necessary 
   dcd -g foo          change to *foo* on all drives, prompt if necessary 
   dcd -f foo          change to foo (and only foo) on current drive, prompt 
   dcd -n foo          change to next *foo* on current drive, do not prompt 
   dcd -n -g foo       change to next *foo* on all drives, do not prompt 
   dcd -n d:foo        change to next *foo* on drive d:, do not prompt 
   dcd -g d:foo        change to *foo* on drive d:, global setting overridden 
   dcd -\ foo/bar      similar to dcd foo\bar 
   dcd -e -dir-        change to *-dir-* 
   dcd -s c:D:e;f.ghi  scan drives c: d: e: f: g: h: i: 
   dcd -re fg          scan and update drives f: and g: 
   dcd -g -fol rtu     open *rtu* (anywhere on system) as desktop folder
   dcd -desk rtu       open and change to desktop folder *rtu* (this could be
                       C:\Desktop\OS!2 System\Startup)


REGULAR EXPRESSIONS. 

For those who think that  DCD's mechanism of finding  directories is not smart
enough,    a regular expression search   is  implemented as  well.  By default
GREP.EXE will be  called if the  <dir> string contains the wildcard characters
`?' or `*'.  Before calling GREP, the <dir> string will be translated to mimic
OS/2's wildcard  handling mechanism   for   GNU-grep.  This behavior   can  be
disabled by using  the -regex option.  This  option forces the usage of  grep,
and passes the <dir> string untranslated.  This may  be useful if one wants to
use other flavors  of grep than  GNU's version (hint:  `set dcd=-regex' if you
want to use grep  exclusively for matching  directory  names).  If you  do not
have grep.exe on your system, the -nogrep option will disable grep.  Instead a
single drive will be scanned,  which is quite a kludge,  so I cannot recommend
this.   (This is  because  I do  not feel like  writing  the  code for regular
expression matching when it already exists.)  Options may be passed to grep by
using -grepopt <option>.  The  string passed to grep on  repeated use of  this
option contains the concatenated <option1> <option2> etc. 

Examples: 

   dcd foo*bar           change to dir ending on bar and containing foo 
   dcd -regex foo.*bar$  as above for GNU grep 
   dcd -nogrep foo?bar   scan local drive and find directory *\foo?bar 
                         (i.e., directory names starts with foo, ends with 
                         bar, with one letter in between). 


CUSTOMIZING. 

If you are not satisfied with the  default settings (-local -select -uppercase
-partialmatch  --), then you want to  consider setting an environment variable
which name is the file name of the command  file without extension (e.g., 'set
DCD=-\' for  d:\usr\bin\dcd.cmd and 'set   GCD=-global -\' for c:\gcd.cmd)  or
change  the DCD.Startup string near  the beginning of  the  command file.  The
command line input overrides the setting of the environment variable, which on
its  turn overrides the DCD.Startup string.   Only options should be passed to
DCD this way. 


CONTACTING THE AUTHOR.

For comments, improvements, bug  fixes, or aob, feel  free to send  e-mail to:
Roger de Reus (reus@mic.dtu.dk).

==============================================================================
Acknowledgements: 
Thanks to J.R. Sguin for minor changes and implementing a real rescan option. 

==============================================================================
Known bugs:
- The option // apparently terminates command line input.  REMEDY: use -/
- If folder already opened on desktop, -bgfolder will bring the folder to the
  foreground.
- REXX SysFileTree chokes on AFS mounted drives (.Yesterday/.Yesterday) (MOT)
  This means that DCD -scan fails on these drives. REMEDY: since the file 
  containing the directory structure is human readable and contains just one 
  directory entry on each line, it is straightforward to construct this file, 
  either by manually editing or by writing your own code to scan AFS mounted 
  drives. 
  This bug (try dir /s :-) was reported before FixPack17 for Warp v3 was 
  released.
- No corrections are made (and ever  will be) for displayed lines which are 
  longer than the width of the screen, spilling part of the output.

==============================================================================
Improvements I can think of (any comments/volunteers?): 
- None at the moment. To my feeling the code became so extensive and usage so
  flexible (and loading on my old PC so slow) that I do not feel the need to 
  enlarge the program any further.
- Well, maybe allow dcd mydir\.. type of things?
- Well, maybe port to other OS's (or just rewrite the whole thing in ANSI C)? 

==============================================================================
History: 
13Nov98: v3.0 (just renamed) and uploaded to hobbes.nmsu.edu and ftp.leo.org
12Oct98: v2.01b6
         added -FGDesktop and -BGDesktop options
22Sep98: v2.01b5
         fixed existing dir prevailed over matched list
         fixed case (in)sensitivity of -rr mode introduced in v2.00b3
18Sep98: v2.01b4
         multiple entries separated by ';' for push/pop
         added -colour option as synonym for -color
         added -fgfolder and -bgfolder
         -n option works with -folder while staying in current dir
         open folders using ..\.. form now works
         allow change to non-valid drives if specified dir exists
         do not require list file if specified dir exists
         added -status option
         added -popstack option
         strip leading spaces from command line input
05Jan98: v2.01b3
         strip spaces from DCD environment variable and DCD.Startup string
18Nov97: v2.01b2
         opening folder of existing dir fixed
24Oct97: v2.01b1
         added -directory, -folder, and -desktop options
11Aug97: v2.00 released 
25Jun97: v2.00b6 
         allow switching to existing dir on non-scanned drives
17Apr97: v2.00b5 
         added -pushdir and -popdir (using DCD_PUSH environment variable)
05Feb97: v2.00b4 
         display DCD Errors always on new line 
17Dec96: v2.00b3 
         fixed rescan to avoid double drives (bug introduced by me:-) 
   	 display real dir names instead of upcase for -upper 
   	 replaced -$debug option by -$trace option to set trace level 
         use default queue instead of DCDQ for grep operations
Endof96: v2.00b2
         adapt dcd.doc to new changes
         wrong translation of * (\* --> .*) for grep
         added -$debug option, just in case...
Endof96: v2.00b1
         add -<n> option to go <n> times `up' in the directory tree
         add -expression option (could enter extra space as well...)
         fixed bug in Test_Dots (Dir -> DCD.Dir)
         add color option (requires ansi on)
   	 input allowed after (re)scan (dcd -rescan c newdir)
         strict sort of drives before scanning
         Modifications by J. R. Sguin (cd897@freenet.carleton.ca)
          - drives are validated against accessed drive list
          - implemented rescan merge into prior DCD.LST
         enlarge uppercase to entire cp850
         added (limited) wildcard support
         do not verify drive on grep -regex?
         do not strip leading blanks from input (so, separator is *1* blank)
   	 display allowed abbreviations in uppercase (-help)
         adapt help to new changes
         add more wildcard support through grep
         bold face help abbreviations
24Apr96: v1.05; added -LIST option; prompt for missing input
06Jan96: v1.04; usage of environment variable to configure startup behavior
         added DCD.Startup to configure startup behavior more transparent
25Sep95: v1.03; added -LOWercase and -UPpercase options
20Sep95: v1.02; added -\, -/, and -- options
19Sep95: v1.01; allow forward slashes in directory names
15Sep95: change version to 1.00; submit to hobbes.nmsu.edu and ftp.leo.org
28Aug95: DCD_Scan use SysFileTree(Drive'\') iso SysFileTree(Drive'\*')
         say if CmdLin ignored
23Aug95: t\o matched t\okay, but also subdirectories with o (t\okay\oops)
         bag out after displaying version
         separate error messages if no (full) match
09Aug95  decided we are at beta test level
08Aug95: echo user input
18Jul95: proposal best match wrong (if then if else if --> added do; end)
17Jul95: alpha  version  v0.1
=============================== end of DCD.DOC ===============================
