home *** CD-ROM | disk | FTP | other *** search
/ Amiga Elysian Archive / AmigaElysianArchive.iso / newc_dev / ucd.lha / UCD / UCD.lha / UCD.doc < prev    next >
Text File  |  1992-09-17  |  18KB  |  522 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.                                    UCD v1.0
  7.                                 --------------
  8.  
  9.  
  10.  
  11.  
  12.                               A small utility by
  13.  
  14.                            Uffe Holst Christiansen.
  15.                           --------------------------
  16.  
  17.  
  18.  
  19.  
  20.                   Copyright (C) Uffe Holst Christiansen, 1992
  21.                              All rights reserved
  22.  
  23.                              Freely distributable
  24.                               S H A R E W A R E
  25.  
  26.  
  27.  
  28.  
  29. Author
  30. ------
  31.         Uffe Holst Christiansen
  32.         Kollegiebakken 9, 816
  33.         DK 2800 Lyngby
  34.         Denmark
  35.  
  36.  
  37. Shareware notice
  38. ----------------
  39. UCD is shareware and if you use (and hopefully also like it) you have the
  40. moral duty to send me a contribution. The amount I would suggest for a con-
  41. tribution is $10. See later for more information about distribution etc.
  42.  
  43.  
  44. Contents at line:
  45. --------
  46.  29 - Author
  47.  37 - Shareware notice
  48.  44 - Contents
  49.  72 - UCD - what is it?
  50.  85 - Archive UCD.lha contents
  51.  96 - Why UCD?
  52. 110 - How does UCD work?
  53. 124 - The format of UCD.dirs
  54. 152 - Usage
  55. 157 - How to use it
  56. 161   - Create directory structure file
  57. 188   - Append to directory structure file
  58. 212   - Make directory structure file
  59. 266   - Installation of directory structure file
  60. 286   - Storing directory structure file
  61. 304   - Changing directory
  62. 334   - Help
  63. 339 - Return codes
  64. 346 - Sample files
  65. 361 - Additional notes
  66. 408 - Limitations
  67. 440 - Future updates
  68. 475 - Distribution and copyright
  69. 500 - Final note
  70.  
  71.  
  72. UCD - what is it?
  73. -----------------
  74. UCD is kind of a CD utility capable of doing something the AmigaDOS CD com-
  75. mand not is able to do. It is - like CD - a CLI only utility.
  76.  
  77. UCD has the ability to change directory to a directory not in the current
  78. directory.
  79.  
  80. UCD also has the ability of keeping track of the directory structure of more
  81. than one volume at the same time, i.e. you can directly change directory to
  82. a directory in another volume without specifying the volume.
  83.  
  84.  
  85. Archive UCD.lha contents
  86. ------------------------
  87. The LhA archive contains the following files:
  88.  
  89.         UCD             The executable program. This file is imploded.
  90.         UCD.doc         The documentation file (you're reading it).
  91.         UCD.dirs        A sample directory structure file containing the
  92.                         directory structure of my pre-harddrive Workbench.
  93.         UCD.make        A sample make file to use with the switch -m or -M.
  94.  
  95.  
  96. Why UCD?
  97. --------
  98. Everybody knows the Amiga is the PC superior, but unfortunately for us much
  99. very good software is accessible for PCs. Anybody with just a very little
  100. knowledge about PCs have heard of Norton, and maybe even seen an utility
  101. called NCD. What I like best about NCD is it ability to change the directory
  102. to a directory not in the current directory, and I have never come across a
  103. utility capable of exactly that for the Amiga.
  104.  
  105. And why should the PC have something the Amiga hasn't?
  106.  
  107. And they should not, and that is the reason for the existence of UCD.
  108.  
  109.  
  110. How does UCD work?
  111. ------------------
  112. UCD scans the directory structure and stores it in a file called UCD.dirs,
  113. which it places in a UCD directory in RAM:
  114.  
  115. UCD the uses this directory structure file to locate a directory to change
  116. to.
  117.  
  118. If you don't want to do a directory structure scan every time you reboot, UCD
  119. can be instructed to store UCD.dirs in SYS:t (NOTE, it will be located in
  120. SYS:t - not in t:). At reboot UCD can be instructed to install this UCD.dirs
  121. in RAM:UCD.
  122.  
  123.  
  124. The format of UCD.dirs
  125. ----------------------
  126. When scanning the directory structure UCD builds the directory structure file
  127. UCD.dirs which contains the directory structure information needed by UCD.
  128.  
  129. An example:
  130.  
  131. Let us assume we in the volume DH0: have the directory devs containing the
  132. subdirectories keymaps, printers and clipboards:
  133.  
  134.         devs (dir)
  135.              keymaps (dir)
  136.              printers (dir)
  137.              clipboards (dir)
  138.  
  139. Using UCD to create the directory structure file produces the following for
  140. devs and its subdirectories:
  141.  
  142.         devs    DH0:devs
  143.         keymaps DH0:devs/keymaps
  144.         printers        DH0:devs/printers
  145.         clipboards      DH0:devs/clipboards
  146.  
  147. The actual format is:
  148.  
  149.         <directory><tab><volume:path/directory><new line>
  150.  
  151.  
  152. Usage
  153. -----
  154. USAGE: UCD [-<A|a|C|c|d|F|f|h|M|m|s|?>|?] [volume:|dir|file]
  155.  
  156.  
  157. How to use it
  158. -------------
  159. Now follows a description of the different possibilities you have with UCD.
  160.  
  161. -c,-C   Create directory structure file
  162.         -------------------------------
  163.         To create the directory structure file UCD.dirs you use the switch -c
  164.         or -C.
  165.  
  166.         USAGE: UCD -c volume:
  167.  
  168.                 This will create UCD.dirs for 'volume:'.
  169.  
  170.         USAGE: UCD -C volume:
  171.  
  172.                 This will create UCD.dirs for 'volume:' and it will in addi-
  173.                 tion store UCD.dirs in SYS:t for future use.
  174.  
  175.         Example: UCD -c dh0:
  176.  
  177.                 This scans the directory structure for dh0: and stores it in
  178.                 RAM:UCD/UCD.dirs, it will not be stored in SYS:t.  To do that
  179.                 you must use the switch -C.
  180.  
  181.         Please notice the create switches (-c, -C) will delete an already
  182.         existing UCD.dirs in RAM:UCD. The switch -C also deletes UCD.dirs in
  183.         SYS:t.
  184.  
  185.         NOTICE: The -C switch will change the file stored in SYS:t.
  186.  
  187.  
  188. -a,-A   Append to directory structure file
  189.         ----------------------------------
  190.         To append a directory structure to the directory structure file
  191.         UCD.dirs you use the switch -a or -A.
  192.  
  193.         USAGE: UCD -a volume:
  194.  
  195.                 This appends directory structure information of 'volume:' at
  196.                 the end of the UCD.dirs currently located in RAM:UCD.
  197.  
  198.         USAGE: UCD -A volume:
  199.  
  200.                 This switch will after appending the directory structure in-
  201.                 formation of 'volume:' on RAM:UCD/UCD.dirs store the directory
  202.                 structure file in SYS:t.
  203.  
  204.         Example: UCD -A dh1:
  205.  
  206.                 This will scan the directory structure for dh1: and appending
  207.                 it to RAM:UCD/UCD.dirs before storing UCD.dirs in SYS:t.
  208.  
  209.         NOTICE: The -A switch will change the file stored in SYS:t.
  210.  
  211.  
  212. -m,-M   Make directory structure file
  213.         -----------------------------
  214.         To make a directory structure file UCD.dirs you use the switch -m
  215.         or -M.
  216.  
  217.         This is actually a combination of creating and appending. If you have
  218.         an harddrive with for example 5 partitions (DH0: through DH4:) you
  219.         normally will have to do the following to make a directory structure
  220.         file containing information of all five partitions:
  221.  
  222.                 UCD -c DH0:
  223.                 UCD -a DH1:
  224.                 UCD -a DH2:
  225.                 UCD -a DH3:
  226.                 UCD -A DH4:
  227.  
  228.         Notice I use the switch -A in stead of -a for the last scan. By using
  229.         the switches this way I only store UCD.dirs in SYS:t once.
  230.  
  231.         The above process of scanning many partitions is a little bit annoy-
  232.         ing if you often have to rescan the directory structure. It could of
  233.         course be stored as a batch file.
  234.  
  235.         An easier way is to make a file containing the following information:
  236.  
  237.                 DH0:
  238.                 DH1:
  239.                 DH2:
  240.                 DH3:
  241.                 DH4:
  242.  
  243.         Please notice it is important the file don't contain any additional
  244.         spaces, tabs etc. Only new lines between the entries are accepted.
  245.         We could for example save the file as s:UCD.make.
  246.  
  247.         Now it is possible to do a scan of all partitions with the command:
  248.  
  249.                 UCD -m s:UCD.make
  250.  
  251.         USAGE: UCD -m file
  252.  
  253.                 This scans the volumes mentioned in 'file'.
  254.  
  255.         USAGE: UCD -M file
  256.  
  257.                 This scans the volumes mentioned in 'file', and will after-
  258.                 wards store UCD.dirs in SYS:t.
  259.  
  260.         The switches -m and -M will change the UCD.dirs currently located in
  261.         RAM:UCD. The -M switch will in addition change the UCD.dirs in SYS:t.
  262.  
  263.         NOTICE: The -M switch will change the file stored in SYS:t.
  264.  
  265.  
  266. -s      Installation of directory structure file
  267.         ----------------------------------------
  268.         If you after a reboot have the directory structure file located in
  269.         SYS:t you install it in RAM:UCD with the switch -s (setup).
  270.  
  271.         USAGE: UCD -s
  272.  
  273.                 This installs the UCD.dirs located in SYS:t in RAM:UCD. It is
  274.                 not possible to use UCD without the directory structure file
  275.                 installed in RAM:UCD.
  276.  
  277.         Please notice that setting up the UCD system using the switch -s will
  278.         delete an already existing UCD.dirs in RAM:t.
  279.  
  280.         It is possible to reinstall the UCD.dirs directory structure file in
  281.         SYS:t if you want to. That could maybe be necessary if you have ap-
  282.         pended directory structure information of some floppies (using the -a
  283.         switch), and no longer want UCD to take effect of this information.
  284.  
  285.  
  286. -d      Storing directory structure file
  287.         --------------------------------
  288.         Have you made a directory structure file without storing it in SYS:t
  289.         and decide you want to do this, it can be done using the switch -d
  290.         (d as in Disk).
  291.  
  292.         USAGE: UCD -d
  293.  
  294.                 This stores UCD.dirs located in RAM:UCD in SYS:t.
  295.  
  296.         This is actually the reverse of using the setup switch -s.
  297.  
  298.         Please notice that this will delete an already existing UCD.dirs in
  299.         SYS:t.
  300.  
  301.         NOTICE: The -d switch will change the file stored in SYS:t.
  302.  
  303.  
  304. -f,-F   Changing directory
  305.         ------------------
  306.         Well, changing the directory is actually the purpose of UCD, so how
  307.         how do you do that?
  308.  
  309.         USAGE: UCD dir
  310.  
  311.                 This will change the directory to 'dir' if 'dir' can be found
  312.                 in the directory structure file UCD.dirs.
  313.  
  314.         USAGE: UCD -f dir
  315.  
  316.                 This will do the same as 'UCD dir', but the -f switch is
  317.                 necessary if the first character in 'dir' is a dash.
  318.  
  319.         USAGE: UCD -F dir
  320.  
  321.                 This will change the directory to 'dir' if 'dir' can be found
  322.                 in the directory structure file. The difference between the
  323.                 -F switch and the -f switch is that the -F switch is case sen-
  324.                 sitive, i.e. 'UCD -F dir' is not the same as 'UCD -F Dir'. The
  325.                 -f switch will treat 'UCD dir' and 'UCD Dir' as the same di-
  326.                 rectory to change to.
  327.  
  328.         Example: UCD include
  329.  
  330.                 This will in my environment change the directory to 'DH3:lc/
  331.                 include' whatever the current directory is.
  332.  
  333.  
  334. ?,-?,-h Help
  335.         ----
  336.         The switches -h, -? or just ? prints a very short help to the screen.
  337.  
  338.  
  339. Return codes
  340. ------------
  341. Upon success zero is returned. Upon failure one is returned regardless of
  342. type of failure, except the switch -s returns 5 (WARN) upon failure, see the
  343. section with "Additional notes".
  344.  
  345.  
  346. Sample files
  347. ------------
  348. Two sample files accompany UCD.
  349.  
  350. The first file UCD.dirs contain the directory structure of my old workbench
  351. disk. The disk was defragmented and reorganized and the directory scan took
  352. 20 seconds and had a memory consumption of 30 k. UCD.dirs was made using 'UCD
  353. -c DF1:'. Depending on the fragmentation of the disk, the number of directo-
  354. ries and the number of files a scan can take much longer.
  355.  
  356. The second file UCD.make is the file I have placed in s: to do a scan of all
  357. my partitions on my harddrive. I use the command 'UCD -m s:UCD.make' to do
  358. the directory structure scan.
  359.  
  360.  
  361. Additional notes
  362. ----------------
  363. The files UCD.dirs located in RAM:UCD and/or SYS:t is protected from
  364. deletion. The only reason for this is that I always use RAM: for temporary
  365. files and I decided to protect it from deletion so I still can use the syntax
  366. 'Delete RAM:* ALL' to delete "all" files in RAM: including subdirectories
  367. without deleting UCD.dirs.
  368.  
  369. If you want to edit (or delete) UCD.dirs you therefore have to make it
  370. writable:
  371.  
  372.         protect UCD.dirs +wd
  373.  
  374.  
  375. I would suggest that you place UCD in c:. If you only have an floppy disk
  376. environment I would suggest you do the following to the startup-sequence:
  377.  
  378.         MakeDir RAM:c
  379.         Copy c:UCD RAM:c
  380.         Protect RAM:c/UCD -d
  381.         Path RAM:c
  382.  
  383. This will place UCD in RAM:c and as long as you don't have a 'Path c:' before
  384. the 'Path RAM:c' it will load the UCD located in RAM:c in stead of the one
  385. located in c:.
  386.  
  387. I would suggest that you include something like the following in you startup-
  388. sequence:
  389.  
  390.         Mount RAD:
  391.         Dir >NIL: RAD:
  392.         UCD -s
  393.         If WARN
  394.           UCD -m s:UCD.make
  395.           UCD -a RAD:
  396.         Else
  397.           UCD -a RAD:
  398.         EndIf
  399.  
  400. First I mount the recoverable ram drive and redirect the directory of RAD: to
  401. NIL:. Then I setup the UCD system using the switch -s. If UCD.dirs does not
  402. exists in SYS:t UCD returns 5 (WARN) and upon WARN I let UCD scan the wanted
  403. devices using the -m switch and a make file placed in s: and called UCD.make,
  404. and then I scan the directory structure of RAD:. If UCD -s succeeded I just
  405. scan the directory structure of RAD:.
  406.  
  407.  
  408. Limitations
  409. -----------
  410. Of course it is very possible you have more than one directory with the same
  411. name located different places on a harddrive. UCD will always choose the
  412. first scanned directory.
  413.  
  414.         This was actually the reason for the -F switch which make it possible
  415.         to distinguish two directories with different cases.
  416.  
  417.         You can also decide in which order to scan different volumes and
  418.         thereby maybe give one directory a higher priority than another di-
  419.         rectory with the same name located on another volume.
  420.  
  421.         It is of course also possible to edit the directory structure file in
  422.         an text editor deleting unwanted entries of directories.
  423.  
  424. UCD does NOT accept wildcards - yet.
  425.  
  426. Due to some problems with allocating memory UCD uses quite a lot of memory
  427. when scanning the directory structure. My intention was to free it when I no
  428. longer needed it, but (I don't know why) it didn't work. But it will be freed
  429. when the scan (or scans if using -m of -M) are finished.
  430.  
  431.         Scanning my harddrive with five partitions, about 300 directories and
  432.         3000 files uses about 220 k of memory and takes less than 45 seconds,
  433.         and produces a directory structure file less than 8000 bytes.
  434.  
  435. NOTICE: It is only the switches -C, -c, -A, -a, -M and -m which have quite a
  436.         large memory consumption. The amount of memory needed are dependent
  437.         of the number of directories being scanned.
  438.  
  439.  
  440. Future updates
  441. --------------
  442. I will in the future try and optimize the code a little and hopefully also
  443. make it a bit shorter. Hopefully I will also be able to figure out why it is
  444. impossible for me to free the allocated memory when I no longer need it.
  445. Luckily it now are freed automatic at exit.
  446.  
  447. UCD does not support wildcards, but I intend in the near future to include an
  448. ability for wildcards in UCD. Wildcards will really make it much nicer to
  449. with.
  450.  
  451. Additional things I'm thinking about including:
  452.  
  453.         An ability to setup the UCD system with another directory structure
  454.         file than the one in SYS:t (-S).
  455.  
  456.         An ability to append a directory structure file at the in of the
  457.         directory structure file currently in RAM:UCD (-(?)).
  458.  
  459.         An ability of storing a directory structure file under another name
  460.         than SYS:t/UCD.dirs (-w).
  461.  
  462.         An ability to optimize the directory structure file, i.e. UCD finds
  463.         directories mentioned more than once, and removes the unwanted ones
  464.         (-O, -o).
  465.  
  466.         An ability of removing directory reference in the directory structure
  467.         file (-R, -r).
  468.  
  469. Well, if a new version of UCD will be placed in the public domain will depend
  470. on the response I receive after having released UCD v1.0. If a new version of
  471. UCD will be placed in the public domain it hopefully will happen through Fred
  472. Fish's public domain library.
  473.  
  474.  
  475. Distribution and copyright
  476. --------------------------
  477. UCD may be freely copied and distributed as long as no charges are made other
  478. than to cover the time, copying costs and mailing costs. Please don't distri-
  479. bute UCD without its accompanying doc file. Preferably distribute it along
  480. with its archive UCD.lha or just as the archive.
  481.  
  482. UCD is copyright Uffe Holst Christiansen, 1992, and it and its accompanying
  483. doc file may not in any way be modified or changed. Archiving and crunching
  484. are allowed.
  485.  
  486. UCD is shareware, so if you use UCD you have the moral duty to pay the $10
  487. shareware fee.
  488.  
  489. UCD may be included in a commercial program without written permission from
  490. the author, if a fee of $100 are paid. The doc file still has to accompany
  491. UCD, and no extra charges may be added for the inclusion of UCD in the com-
  492. mercial program.
  493.  
  494. UCD may be freely distributed on coverdisks, within user groups and it may
  495. freely be included in public domain libraries.
  496.  
  497. I encourage everybody to distribute UCD.
  498.  
  499.  
  500. Final note
  501. ----------
  502. I assume no responsibility of damage done to your hardware or software which
  503. the use of UCD may cause. UCD is used totally on your own responsibility.
  504.  
  505. The above is just for the record. I don't expect UCD to do any damage to
  506. hardware or software. I have used UCD for some time with no problems, and my
  507. harddrive has been scanned at least 100 times and it still works perfectly.
  508. I think a bug with UCD causing a software failure was fixed when I decided
  509. not to try not to free the allocated memory used when scanning.
  510.  
  511. Please send bug reports, shareware fees and suggestions for future updates of
  512. UCD to:
  513.  
  514.         Uffe Holst Christiansen
  515.         Kollegiebakken 9, 816
  516.         2800 Lyngby
  517.         Denmark
  518.  
  519.  
  520.  
  521.                      S U P P O R T   S H A R E W A R E
  522.