home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 9 Archive / 09-Archive.zip / dskxtr12.zip / dskxtrct.txt < prev    next >
Text File  |  1998-07-06  |  16KB  |  390 lines
  1. DSKXTRCT and DSKCOMPR - Version 1.2 - 7/4/1998
  2. Copyright 1997, 1998 by Alan B. Arnett
  3. Contact: Alan.Arnett@ibm.net
  4.  
  5.  
  6. Table of Contents
  7.  
  8. 1. Description
  9. 2. Special Notes and Restrictions
  10. 3. General Notes
  11. 4. Program Operation and Usage
  12. 5. Future Considerations
  13. 6. Program history
  14. 7. Credits and Appreciations
  15. 8. Package contents
  16. 9. Copyright and Disclaimers
  17.  
  18.  
  19. 1. Description
  20.  
  21. The DSKXTRCT and DSKCOMPR programs work with DSK diskette image
  22. files associated with the IBM programs, SAVEDSKF and LOADDSKF.
  23. (See notes below for a brief explanation of the SAVEDSKF and
  24. LOADDSKF utilities.)
  25.  
  26. DSKXTRCT extracts the original files from DSK files into a
  27. subdirectory, avoiding the need to recreate diskettes. This is
  28. useful if the desire is to copy the original files onto a hard
  29. drive without creating intermediate diskettes.  One of the major
  30. purposes for DSKXTRCT is to create a hard drive subdirectory
  31. directly from IBM fixpak DSK files that can be used to apply the
  32. fixpak, bypassing the creation of diskettes.
  33.  
  34. DSKCOMPR compares the files in DSK files to a target subdirectory
  35. or diskette. This is useful for verifying that LOADDSKF correctly
  36. created the diskette.  The compare of a DSK file to a diskette is
  37. a case where DSKCOMPR fills a need not satisfied by LOADDSKF.
  38.  
  39.  
  40. 2. Special Notes and Restrictions
  41.  
  42. Duplicate CSF_DSK files (and other files) with DSKXTRCT: When
  43. using DSKXTRCT to create a single directory from multiple DSK
  44. files, duplicate files will not be replaced without the user's
  45. permission, either by command line option or screen prompt.  Be
  46. aware that IBM fixpak diskette images frequently contain a file
  47. identifying the diskette name and number.  This file may be named
  48. the same on each diskette image, as an example: "CSF_DISK".  If
  49. one of the command options to replace or skip all duplicates is
  50. not used, the user will be prompted for each attempt to replace
  51. this file.  The user may respond to each duplicate file, or at
  52. anytime, choose to replace or skip any further duplicate files. 
  53. Note that in the creation of a subdirectory for fixpak files,
  54. DSKXTRCT emulates the process of creating diskettes and then
  55. performing an XCOPY to a subdirectory with the '/s' parameter in
  56. which all needed subdirectories would be created and any
  57. duplicate files would be overwritten.
  58.  
  59. Duplicate CSF_DSK files (and other files) with DSKCOMPR: When
  60. using DSKCOMPR to compare multiple DSK files to a single
  61. directory, duplicate files that have been replaced or skipped
  62. will show as errors.  These mismatched files may not be a concern
  63. if the DSK files are IBM fixpak files.  See the above description
  64. of "Duplicate CSF_DISK files with DSKXTRCT". 
  65.  
  66. While DSKXTRCT can extract the DSK files to a diskette, this is
  67. individual file level operation.  Any diskette internal data such
  68. as boot records, reserved fields or other nonstandard diskette
  69. attributes not directly contained within a normal file will not
  70. be handled.  LOADDSKF is better/faster/safer for creating
  71. diskettes.  Once the diskette has been recreated, DSKCOMPR can be
  72. used to verify that the individual files have been created
  73. correctly.
  74.  
  75. A word about the year 2000.  I have done some initial
  76. investigation of the y2k issues surrounding the DSK file images
  77. and the files contained within, and my initial sense is that
  78. there will be no problem with the file dates, but I have not done
  79. any testing to verify this.  I plan to perform some testing, and
  80. do what I can to be sure that the correct date and time are
  81. propagated to the extracted files.  The only y2k problem I can
  82. foresee is in the section of code that retrieves the date from
  83. the DSK directory entry and formats it for the system function
  84. that sets an output file's modification date.  For now, and until
  85. I can do some testing and decide to implement any changes, y2k
  86. compliance remains a potential restriction.  There is no
  87. guarantee or warranty that these programs will ever by y2k
  88. compliant.  Having added the previous sentences for the benefit
  89. of any lawyers, do keep in mind that I use this program myself,
  90. and I want it to handle dates correctly for me.
  91.  
  92.  
  93. 3. General Notes
  94.  
  95. DSKXTRCT was written to fulfill two needs.  First, to eliminate
  96. the need to create diskettes from IBM fixpak DSK files.  With
  97. DSKXTRCT, a subdirectory containing the original files can be
  98. created directly from the DSK files and the SERVICE process then
  99. can be changed to use this subdirectory.  Second, to enable the
  100. storage of product diskette backups on large storage media such
  101. as ZIP or SYQUEST drives using the SAVEDSKF program and still
  102. have access to the original files when needed without having to
  103. recreate the diskettes.
  104.  
  105. DSKCOMPR was written as a companion program, as a result of bbs
  106. exchanges/complaints about diskette errors that sometimes went
  107. undetected when LOADDSKF recreated fixpak diskettes.
  108.  
  109. Neither DSKXTRCT nor DSKCOMPR can process a DSK file that has
  110. been created by SAVEDSKF using the compression option.  This
  111. doesn't seem to be a serious restriction as all the DSK files
  112. currently distributed by IBM are created in a non-compressed
  113. format.  This restriction should be kept in mind if the user
  114. wants to use SAVEDSKF to create personal DSK files from
  115. diskettes.
  116.  
  117. While DSKXTRCT and DSKCOMPR verify the checksum data stored in
  118. the DSK file, the checksum is only a 32 bit sum of every 16 bits
  119. in the DSK file and some double or triple bit errors may not be
  120. detected.  This is a limitation of the checksum stored on the DSK
  121. file.  Furthermore, there is only one checksum for the entire
  122. diskette image, so there is no way to determine which files in
  123. the DSK file are corrupted.  The /CRCX flag allows the processing
  124. of the DSK file to ignore the checksum error, but this is very
  125. risky and is not recommended.
  126.  
  127. IBM utilities SAVEDSKF and LOADDSKF: IBM uses these two utilities
  128. for handling correction and device driver diskettes made
  129. available for the users of many of their products. SAVEDSKF reads
  130. a diskette and creates a single file with all the information
  131. needed to recreate an exact copy of the original diskette.
  132. LOADDSKF is used to recreate a diskette from the DSK files. This
  133. SAVEDSKF/LOADDSKF process allows an entire diskette image to be
  134. transferred electronically and recreated by the recipient. These
  135. utilities can be found on many web sites or bulletin boards
  136.  
  137.  
  138.  
  139. 4. Program Operation and Usage
  140.  
  141. Both programs have similar command line parameters. The source
  142. parameter is required for all operations, and the target
  143. parameter is required for extract and compare operations, but not
  144. for 'view file list' and 'checksum only'. The other parameters
  145. are optional. 'View file list' and 'checksum only' disable the
  146. extract and compare operations, but they may be specified
  147. together.  If file replace or skipping parameters are not
  148. provided on the command line, the user will be prompted as
  149. needed. Parameters may be specified in any order and are not case
  150. sensitive.
  151.  
  152. Two general command syntax are provided for each program, the
  153. first for normal operation, and the second for viewing a list of
  154. files contained in the DSK files and/or performing checksum
  155. verification of the DSK files.
  156.  
  157.                                                                 
  158. DSKXTRCT /s:<mask> /t:<sdir> [/l:<file>] [m:<mode>] [/ra|/rn]
  159. [/lr|/ls|/la] [/c] [/q] [/crc] [/crcx]
  160.                                                                 
  161. DSKXTRCT /s:<mask> /v [/l:<file>] [m:<mode>] [/lr|/ls|/la] [/c]
  162. [/q] [/crc] [/crcx]
  163.  
  164.                                                                 
  165. DSKCOMPR /s:<mask> /t:<sdir> [/l:<file>] [m:<mode>] [/lr|/ls|/la]
  166. [/c] [/q] [/crc] [/crcx]
  167.                                                                 
  168. DSKCOMPR /s:<mask> /v [/l:<file>] [m:<mode>] [/lr|/ls|/la] [/c]
  169. [/q] [/crc] [/crcx]
  170.  
  171.  
  172. /s:<source file name or mask> - (required) the source file name
  173. or mask of the DSK diskette image files to be extracted or
  174. compared. If a mask is used, the specific directory supplied will
  175. be searched and each DSK image file found will be processed, but
  176. no subdirectory trees will be searched to find more mask files. 
  177. The mask needs to be restrictive enough to bypass non-DSK files,
  178. as these will cause errors and possible program termination.
  179.                                                                 
  180. Example: "/s:c:\storage\os2warp4\xrm005\*.?dk"
  181.  
  182. /t:<target directory or drive> - (required for extract and
  183. compare operations, but not for 'view file list' or 'checksum
  184. testing' operations) the target directory or diskette drive for
  185. processing. During extract processing, this subdirectory and any
  186. additional subdirectories will be created if they do not already
  187. exist. To extract files to the current directory, use "/t:.", but
  188. note that any applicable subdirectory structure defined in the
  189. DSK file will still be created.  
  190.                                                                 
  191. Example: "/t:c:\temp\xrm005"
  192.  
  193. /l:<log file name> - (optional) overrides the default log file
  194. name and may specify a full drive and path qualification.  The
  195. default log file names are dskxtrct.log and dskcompr.log and are
  196. created in the current directory at the time the program is
  197. invoked.  Note this can cause an error if the program is invoked
  198. while the current directory is set to a CD-ROM or a network drive
  199. to which the user is unable to write.
  200.                                                                 
  201. Example: "/l:c:\temp\xrm005\mylog.log"
  202.  
  203. /m:<message level> - (optional) sets control for message output.
  204. Message levels include:
  205.      NONE - suppress all messages except errors and warnings
  206.      STD - print normal messages (default)
  207.      FILES - print the names and file sizes of individual files
  208. as they are created or compared.
  209.                                                                 
  210. Example: "/m:files"
  211.  
  212. /c - (optional) lists any comments contained in the DSK file.
  213.  
  214. /v - (optional) generates a list of file names and sizes instead
  215. of creating or comparing files. The target parameter is
  216. unnecessary when using this parameter and is ignored if provided.
  217. This parameter provides the same operation in both DSKXTRCT and
  218. DSKCOMPR.
  219.  
  220. /lr - (optional) replace the log file if a duplicate is found.
  221.  
  222. /la - (optional) append to the log file if a duplicate is found.
  223.  
  224. /ls - (optional) skip writing to the log file if a duplicate is
  225. found.
  226.  
  227. /q - (optional) quiet mode, bypass writing messages to the
  228. screen, if the log file is successfully being used.  This
  229. parameter has no effect if '/ls' is used or if 'skip' was
  230. specified to a 'replace log file' prompt.
  231.  
  232. /ra - (optional) replace ALL duplicate files found by DSKXTRCT in
  233. the target subdirectory.
  234.  
  235. /rn - (optional) replace NO duplicate files found by DSKXTRCT in
  236. the target subdirectory.
  237.  
  238. /crc - (optional) perform only checksum testing bypassing extract
  239. or compare.  Note that checksum testing is done by default. This
  240. parameter provides the option of performing only the checksum
  241. testing.  The target parameter is unnecessary when using this
  242. parameter and is ignored if provided.  This parameter provides
  243. the same operation in both DSKXTRCT and DSKCOMPR.
  244.  
  245. /crcx - (optional) ignore any checksum errors during extract and
  246. compare and process all DSK files even if a checksum error is
  247. detected.
  248.  
  249. A return code is used at program completion to indicate the
  250. results of processing and can be tested in command files
  251. (messages should indicate the cause of any warnings or errors):
  252.  
  253.      0 - successful completion.
  254.      4 - some minor error(s) occurred, ie, a subdirectory wasn't
  255. found during compare.
  256.      8 - a serious but non-terminal error occurred, ie, a file
  257. was not created or did not compare.
  258.      16 - a terminal error occurred, ie, an invalid parameter, or
  259. a system error.
  260.  
  261. Examples of program execution:
  262.  
  263.      dskxtrct /s:\fixpacks\xr_m005.?dk /t:\temp\xrm005 /ra
  264. /m:file /lr 
  265.  
  266.      dskcompr /s:\fixpacks\xr_m005.1dk /t:a: /l:compare1.log
  267.  
  268.  
  269. 5. Future considerations
  270.  
  271. While I will entertain suggestions or comments on these programs,
  272. I do not provide any assurances that I will enhance or correct
  273. any of these programs in the future.  This project is done as a
  274. hobby and for fun.  Having said that, the following list contains
  275. points I am considering working on if and when the time and the
  276. mood present themselves.  But I do use these programs myself, and
  277. do want to make some of the enhancements listed below.  The list
  278. is not ordered in any strict priority, but my favorite
  279. enhancements are at the beginning.  I will entertain suggestions
  280. on the priority of these items and for other items, but again I
  281. reserve the final right to decide what, if anything, gets done
  282. and when.  Let me know if you found these programs useful.
  283.  
  284. - combine DSKXTRCT and DSKCOMPR into one program.
  285.  
  286. - allow selection of extract and compare (immediately afterwards)
  287. in the same invocation.
  288.  
  289. - allow an initial checksum pass of all input files, continuing
  290. to extract and/or compare only if all files pass checksum
  291. verification.
  292.  
  293. - add support for parameters to be input from a parameter file.
  294.  
  295. - build a GUI front end for program invocation.
  296.  
  297. - implement any needed Y2K support in handling file dates.
  298.  
  299. - add message id numbers to all messages and create in index of
  300. messages in the documentation to fully explain the meaning of
  301. each message.
  302.  
  303. - add internal logic control to better control program
  304. termination under non-critical conditions and add options to
  305. control the sensitivity of program termination to different error
  306. levels.
  307.  
  308. - improve DSK file detection logic to allow skipping of non-DSK
  309. files found by source file mask.  
  310.  
  311. - add a /fixpak parameter to automate the handling of duplicate
  312. "CSF_DISK" files and possibly override some of the defaults for
  313. this specific condition.
  314.  
  315. - add file selection by name or mask of files to be extracted
  316. from the DSK file.
  317.  
  318. - add to the 'replace/skip' file prompts the option to specify a
  319. different file name or location.
  320.  
  321. - report skipped and/or replaced files separately from other FILE
  322. level messages.
  323.  
  324. - add the option to make the default log file location the target
  325. directory rather than the current directory. This can be done now
  326. by specifying a fully qualified log file name.
  327.  
  328. - add the option to suppress creation of subdirectories defined
  329. in the DSK file so all files are extracted into the target
  330. directory.
  331.  
  332. - add support for compressed DSK files.
  333.  
  334.  
  335. 6. Program history
  336.  
  337. Version 1.2                                                     
  338. - added checksum verification and messages to both programs.
  339. - added return code to DSKCOMPR exit.
  340. - added return code message to both programs.
  341.  
  342. Version 1.1                                                     
  343. - corrected/refined code based on feedback from beta testing.
  344.  
  345. Version 1.0                                                     
  346. - beta testing version.
  347.  
  348.  
  349. 7. Credits and appreciations
  350.  
  351. I want to express my appreciation to Frank McKenney for his
  352. testing and for his extensive and valuable suggestions.   Frank's
  353. postings also gave me the idea for the compare program.  I also
  354. want to thank my brother Steve Arnett for his encouragement and
  355. initial testing. 
  356.  
  357.  
  358. 8. Package contents
  359.  
  360. This package contains 4 files:
  361. DSKXTRCT.EXE - the extraction program
  362. DSKCOMPR.EXE - the compare program
  363. DSKXTRCT.TXT - this documentation file
  364. SUMMARY.TXT - summary of program functionality.
  365.  
  366.  
  367. 9. Copyright and disclaimers
  368.  
  369. The DSKXTRCT and DSKCOMPR programs are freeware.  The author
  370. retains the copyright to these programs, but you are free to use
  371. them with the only restrictions that you not reverse engineer
  372. them. Furthermore, you are free to distribute them to anyone
  373. else, as long as all files contained in the package are kept
  374. intact and unmodified and any charge is only for copying and
  375. distribution. 
  376.  
  377. DSKXTRCT and DSKCOMPR are provided as is.  No warranties or
  378. guaranties, either expressed or implied, are provided that these
  379. programs will function as intended.
  380.  
  381. The programs LOADDSKF and SAVEDSKF are copyrighted by IBM.
  382.  
  383.  
  384.  
  385. (PLEASE DO NOT DISTRIBUTE ANY BETA FILES YOU MAY FIND ON BULLETIN
  386. BOARDS, CONTACT THE AUTHOR FOR THE LATEST PRODUCTION CODE.)
  387.  
  388.  
  389.  
  390.