Disk eXPress

Disk eXPress The SuperCharged Diskette Imaging software for OS/2 and DOS DXP Version 2.34 03/08/94 TABLE OF CONTENTS _________________________________________________________________ 1.0. INTRODUCTION TO Disk eXPress ........................3 1.1. What is Disk eXPress? ..........................3 1.2. Features of Disk eXPress .......................3 1.3. New features in Disk eXPress Version 2 .........4 1.4. New Disk eXPress companion program: Xtract .....4 1.5. What's new in Version 2.10 .....................5 1.6. What's new in Version 2.20 .....................5 1.7. What's new in Version 2.31 .....................5 1.8. What's new in Version 2.32 .....................6 1.9. What's new in Version 2.33/2.34 ................6 2.0. SYSTEM REQUIREMENTS .................................6 3.0. COPYRIGHT NOTICE ....................................6 4.0. WARRANTY ............................................7 5.0. COST OF Disk eXPress ................................7 6.0. CONTENTS OF THIS PACKAGE ............................7 7.0. SYNTAX ..............................................8 7.1. Quick start ....................................8 7.2. Disk eXPress help screens ......................10 8.0. COMMAND LINE SWITCHES DESCRIPTION ...................12 8.1. Regular mode ...................................12 8.2. Extract mode ...................................14 8.3. Diskettes containing bad sectors ...............16 8.4. Batch mode support .............................16 8.5. Disk eXPress real-time bar graph display .......17 9.0. EXAMPLES ............................................18 9.1. Example 1 ......................................18 9.2. Example 2 ......................................19 9.3. Example 3 ......................................19 9.4. Example 4 ......................................20 9.5. Example 5 ......................................20 9.6. Example 6 ......................................21 9.7. Example 7 ......................................21 9.8. Example 8 ......................................22 9.9. Example 9 ......................................22 10.0. ERROR MESSAGES .....................................23 10.1. List of error messages ........................23 10.2. List of error return codes ....................24 11.0. LIMITATIONS ........................................26 2 1.0. INTRODUCTION TO Disk eXPress _________________________________________________________________ 1.1. What is Disk eXPress? Disk eXPress (DXP) allows a diskette image to be created for electronic transmission. Think of it as a way for preparing a diskette to be FAXed like a regular document. Once the diskette image is created, it can be transmitted with the use of a modem on a regular phone line, or any other electronic networks. One area of use is to archive diskette images on hard drives or tapes. This can be useful for companies maintaining an electronic bulletin board service for clients, in which diskette images for the latest hardware drivers, or fixes are available for download. This guarantees the contents of the diskette to be the same as the original -- including all directory structures, date and time stamps of all the files and directories, and the location of any hidden information. For simple file archival purpose, the use of Disk eXPress should be avoided. The user is encouraged to use one of the many fine archive programs available on the market. Disk eXPress is useful for archiving bootable diskettes, diskettes containing hidden information, or files and directory entries containing characters unrecognizable by the usual file system functions. Unlike a file archive program, Disk eXPress requires a diskette drive and a diskette in order to restore any information stored in an image. 1.2. Features of Disk eXPress - Disk eXPress recognizes all standard 512-byte per sector PC style diskettes. This includes 160K, 180K, 320K, 360K, 720K, 1.2M, 1.44M, and the latest 2.88M diskettes. Any internal or external diskette drives connected via DOS or OS/2 block device drivers are recognized (ie: diskette drives accessed via DRIVER.SYS, $FDD5.SYS, etc.) All information on the diskette is saved to a file for electronic transmission, no information is lost! (see /a switch for detail). - Disk eXPress can be used for diskette conversion. For example, a 360K diskette image can be restored onto a 720K, 1.44M, or 2.88M diskette. If someone sends you a bootable 360K diskette image, you can restore it onto a 720K diskette, and the resulting diskette will be bootable. - Advanced virus protection. Disk eXPress detects illegal program modifications whether it's by virus, or bad electronic transmissions. - Multiple 32-bit CRC data protection. The image is protected by several 32-bit CRCs. In some cases, if a non-critical part of the image is modified, the resulting diskette will still be usable. 3 - Upgradability of the self-extracting code. Disk eXPress provides a means to upgrade the self-extracting code within the image file for bug fixes, and future code enhancements upgrade. 1.3. New features in Disk eXPress Version 2 - Disk eXPress is now a dual mode executable file. It runs under both OS/2 and DOS. There is only one version of the executable as opposed to two in the previous release. - Disk eXPress exploits the multi-threading capability when it is run under OS/2. It performs simultaneous disk I/O and data compression. This typically gives 10 to 50% speed up compare to running it under DOS. - Disk eXPress supports long filename for diskette images created under OS/2 with HPFS (High Performance File System) disk partition. - New data compression algorithm based on a modified Lempel-Ziv- Huffman method. Disk eXPress now compresses smaller than version 1, and is also 2 to 3 times faster. The compression rate is comparable to most file archive programs. Compression is dynamic -- non-compressible data is simply stored. - Real-time bar graph display showing current compression rate, disk read/write and compression activities (this capability is limited under DOS). - Self-extracting diskette image is also a dual mode executable. /DOS and /OS2 switches are no longer required (please refer to version 1 documentation). All the extra functions are removed, and are now built-into the extract mode of Disk eXPress itself. - Disk eXPress can now create non-self-extracting image. This is useful for diskette archival purpose on hard drive or tape. - Diskette decompression code is now built-into Disk eXPress. This can be used to decompress version 2 non-self-extracting diskette image or Disk eXPress version 1 and 2 self-extracting images. It has the full set of options, including diskette formatting, conversion, and verification. The decompressor is also fully multi-threaded under OS/2 to yield the fastest diskette extraction time. - The /t switch is added to all the decompressors so that the integrity of the image can be tested before committing the lengthy diskette write process. 1.4. New Disk eXPress companion program: Xtract - Xtract is a dual mode executable. It features all the decompression capability of Disk eXPress, including multi- threading under OS/2. - It is used for distributing non-self-extracting diskette images in which unlimited distribution right is granted for 4 Xtract for non-commercial products and non-profit services after purchasing a licensed copy of Disk eXPress. - Xtract is included in the licensed version of Disk eXPress (not included in the shareware version). 1.5. What's new in Version 2.10 - New /q switch for QuickFormatting diskette. - New /DOS switch to create self-extracting images that run under DOS and OS/2 DOS box ONLY. Reduction of 14K overhead in self-extracting code. - New /s switch in self-extracting image to bypass warning prompt. - Code and compiler optimizations to reduce self-extracting code size by 2K and at the same time, achieve a 10% overall speed up. - Description can now be entered via environment variables (DXPDESC1 to DXPDESC5). - Low level diskette access code has been completely rewritten for the DOS side to allow full functionality of Disk eXPress under OS/2 DOS box. - Prompt for additional selections ("Format once" and "Format all") when a diskette write error is encountered. This allows formatting of just the current track or all subsequent tracks before diskette writes. 1.6. What's new in Version 2.20 - Disk eXPress now reads non-DOS diskette. Diskettes with 512- byte sectors and conform to PC physical diskette formats are supported. - New 32-bit OS/2 version of Disk eXPress is now included. The 32-bit version typically runs 40% faster on the compression / decompression thread and is functionally equivalent to the 16- bit version. It also consumes about the same amount of memory as the 16-bit version when both are run under OS/2 2.x. Note: the 32-bit version will not run under real DOS. However, it can be launched from the DOS box of OS/2 2.1. 1.7. What's new in Version 2.31 - /fs option for sector skew optimization during diskette formatting to allow fastest future diskette read/write speed (available only under OS/2). - Threads priority tuning to achieve 5 to 10% increase in speed (available only under OS/2). - /d switch for displaying description with self-extracting images. 5 - /p switch for specifying pass phrase for encrypting image file. Both the pass phrase and the encryption key are not stored in the image file for increased security. - /w switch for wiping out unused tracks at the end of the diskette during image extraction. - /a switch is extended to allow direct specification of non-DOS diskette. 1.8. What's new in Version 2.32 - Wildcard processing for self-extracting code replacement (/r switch). - Ability to create diskette image from diskette with bad (unreadable) sectors. - Proper saving of image description to a file via I/O redirection (dxp image /d > filename). 1.9. What's new in Version 2.33/2.34 - Bug fix release and change of shareware ordering through BMT Micro. - For a list of bug fixes, please refer to the history file (DXP.HST). 2.0. SYSTEM REQUIREMENTS _________________________________________________________________ IBM PC, PC-AT, PS/1, PS/2 and 100% compatibles. Minimum 256K conventional memory. MS-DOS or PC-DOS version 3.20 or above; OS/2 1.2 or above, including OS/2 Version 2.x, is required. Hard disk is required for storing large image file. User must also provide the necessary program(s) for sending diskette image files through telephone network with the use of a modem, and whatever is necessary with any other electronic networks. 3.0. COPYRIGHT NOTICE _________________________________________________________________ DXP/DXP32 (Disk eXPress) Version 2.34 07/08/94 XTRACT/XTRACT32 (Xtract) Version 2.34 07/08/94 (c) Copyright 1991-94 by Albert J. Shan. All Rights Reserved. No part of this program may be disassembled, modified or altered by any means. 6 4.0. WARRANTY _________________________________________________________________ I, Albert J. Shan, make no warranties, expressed or implied, including, but not limited to, merchantability or fitness for any particular purpose. In no event shall Albert J. Shan be liable for indirect or consequential damages arising from the use of the software program. You are free to redistribute this shareware package in its entirety. No part of this package may be included as part of a commercial package. If you have any questions about commercial distribution of Disk eXPress, I can be contacted at: Albert J. Shan 4620 Granville Avenue Richmond, B.C. CANADA V7C 1E4 or via CompuServe, ID 70730,401 or via Internet, 70730.401@compuserve.com 5.0. COST OF Disk eXPress _________________________________________________________________ The user is granted a 30 days trial period, after which he or she is required to register the product. The cost of a single machine license is $25 U.S. Please refer to the file ORDER.FRM for details. 6.0. CONTENTS OF THIS PACKAGE _________________________________________________________________ The following files are included in this package: DXP.EXE - 16-bit OS/2 and DOS executable DXP32.EXE - 32-bit OS/2 executable DXP.DOC - This documentation DXP.HST - History file ORDER.FRM - Order form README - Last minute information 7 7.0. SYNTAX _________________________________________________________________ 7.1. Quick start The syntax of Disk eXPress is very similar to the COPY command. To create a diskette image, type: dxp drive: filename To create a diskette from an image file, type: dxp filename drive: For example, to create a diskette image from your drive B:, simply type: dxp b: my_image The file "my_image.exe" will be created when Disk eXPress finsihes. To create the diskette from the self-extracting file created above, you type: my_image b: OR dxp my_image.exe b: Disk eXPress allows command switches to be specified anywhere on the command line. Spaces between command line switches are not required. By default, the file extension is ".EXE" regardless of what user specifies. When creating a non-self-extracting diskette image with the /i switch, user is free to choose the file extension. For consistency, the recommended file extension to use is ".DXP". For example, under OS/2 with HPFS drive, a non-self-extracting diskette image can be created as follows: dxp a: "This is diskette 3 of 5.DXP" /i To create the diskette from the image: dxp "This is diskette 3 of 5.DXP" a: /f /v The /f switch tells Disk eXPress to format the diskette a track at a time just before each track write. The /v switch tells Disk eXPress to verify the diskette write after the track is written. 8 Note: When using quotes for HPFS filenames, make sure the quotes are in front and after if you are specifying a full path: INCORRECT: dxp c:\"Disk Image 1.dxp" a: c:\images\"Disk Image 2" a: CORRECT: dxp "c:\Disk Image 1.dxp" a: "c:\images\Disk Image 2" a: To QuickFormat a diskette in drive A:, type: dxp a: /q The /s switch may be used to bypass the QuickFormat warning prompt. You may stop Disk eXPress at any time by pressing Ctrl-C or Ctrl- Break. The BREAK ON/OFF setting under DOS is ignored. If Disk eXPress encounters any cluster marked as bad in the File Allocation Table, you may receive a warning: X bad cluster(s) detected in the File Allocation Table. Disk eXPress will try to recover any unreadable sectors. If any sector is proved to be unreadable, it will store the sector in the diskette image with all zeros. Note: Disk eXPress will not detect bad clusters in advance if you by- pass File Allocation Table (FAT) scanning by specifying the /a switch. Disk eXPress or Xtract cannnot restore a diskette image onto a diskette that contains physically bad sectors. 9 7.2. Disk eXPress help screens Type DXP at the OS/2 or DOS prompt to receive this help screen: Disk eXPress (16-bit OS/2 and DOS) V2.34 07/08/94 SHAREWARE VERSION (c) Copyright 1991-94 Albert J. Shan. All Rights Reserved. Regular mode: DXP [options] [drive:] [d:][path]filename [options] /? Display extract mode help screen /a[c] Read the entire diskette [c = diskette capacity] /d Input diskette image description (5 lines max.) /DOS Output DOS only self-extracting executable /i Output non-self-extracting diskette image /n Disable data compression /p"s" Specify pass phrase "s = pass phrase" /s Suppress overwrite prompt drive Drive letter of the target diskette drive filename Name of output file Valid options with only filename specified: /d Display description in image file /e Edit description in image file /r Replace or add self-extracting code to image file Note: Items enclosed in [] or "" are optional. Diskette must not contain any unreadable sectors. Supported formats: 160K, 180K, 320K, 360K, 1.2M, 720K, 1.44M and 2.88M standard 512-byte sector diskettes. 10 Type DXP /?, and you'll get the help screen for the extract mode: Disk eXPress (16-bit OS/2 and DOS) V2.34 07/08/94 SHAREWARE VERSION *** Type DXP by itself to see the regular mode help screen *** Extract mode: DXP [options] [d:][path][filename] [drive:] [options] /t Test image file integrity only /d Display description in image file /f[s] Format target diskette [sector skew optimization] /p"s" Specify pass phrase "s = pass phrase" /s Suppress overwrite prompt /v Verify ON (system verify plus read and compare) /w Wipe unused tracks /c Convert image onto a higher density diskette (Target diskette must be pre-formatted, and of different form factor. It also overrides /f) filename Name of input file drive Drive letter of the target diskette drive Valid option with only drive specified: /q QuickFormat target diskette Note: Items enclosed in [] are optional. The target diskette must be free of defects (no bad sectors). Supported formats: 160K, 180K, 320K, 360K, 1.2M, 720K, 1.44M and 2.88M standard 512-byte sector diskettes. 11 8.0. COMMAND LINE SWITCHES DESCRIPTION _________________________________________________________________ When Disk eXPress is used under regular mode for making diskette images, the following switches are available: 8.1. Regular mode /a By default, Disk eXPress reads up to the last allocated sector, according to the information it finds in the File Allocation Table (FAT) in order to reduce the size of the image file. However, if there is any deleted files at the end of FAT that you may want to recover later, the default action will prevent you from a successful file recovery. Use /a to tell Disk eXPress to create an exact duplicate of the original diskette by saving ALL disk sectors to the image file. When Disk eXPress detects non-DOS diskette, this switch will be automatically applied. If you suspect automatically diskette sensing is incorrect, you can supply the actual capacity of the diskette by speifying /ac, where c = 160, 180, 320, 360, 720, 1.2, 1.44, or 2.88. Only the first 3 characters are checked, so /a1.44M is equivalent to /a1.4. /d Prompt user to input description for the diskette image. A maximum of 5 lines of 40 characters each can be stored. Disk eXPress bypasses user input, and reads the description from the environment variables DXPDESC1 to DXPDESC5, if there is at least one defined. You can also redirect the decription input from a file like this: C:> type desc.txt | dxp a: image1 /d (Make sure the description text file has exactly 5 lines of text in it.) You can also save the description to a file for editing: C:> dxp image2.exe /d > desc2.txt /DOS By default, Disk eXPress creates self-extracting images that can be run under OS/2 and DOS. By specifying this switch, a DOS only self-extracting image is created. The DOS code has been written so that it will run under OS/2 DOS box with almost no speed penality. This cuts self-extracting code overhead by about 14K. /i Create a non-self-extracting diskette image file. The self- extracting code will not be bundled with the resulting file. Disk eXPress does not enforce any file extension for non- self-extracting diskette image. For consistency, it is 12 recommended to use ".DXP" as file extension. Without specifying this switch, the default file extension will be ".EXE". /n Disable compression. If the contents of the diskette is highly compressed, Disk eXPress may not succeed in compressing the data any further. This can be visually inspected when Disk eXPress is run the first time without the /n switch. If the real-time compression rate is very low (close to 0%), disabling compression is recommended. /p Specify pass phrase for encrypting the image file. Pass phrase can be specified immediately after the switch; otherwise, it will prompt you to type in a pass phrase. The pass phrase must be 4 to 64 characters in length. It is case sensitive and spaces can be embedded. When the pass phrase contains space, it can be specified as: /p"Secret Pass Phrase". Special characters can also be entered by using the Alt-NumPad key sequence. For example, if you wish to use the "beta" character, you can hold down the Alt key, press 225 on the NumPad, and release the Alt key. Once the pass phrase is used, Disk eXPress will automatically encrypt the image data based on the pass phrase. The pass phrase and the encryption key are not stored anywhere in the image file, thus making it impossible for anyone to find out the pass phrase or the encryption key by looking at a binary dump. The self-extracting image will prompt for pass phrase and perform 32-bit CRC checking to make sure the image header and the executable code are not tampered. The self-extracting code will not run if it fails the CRC test. NOTE: Data encryption is only as good as the person who uses it. Better security can be obtained by specifying a longer pass phrase with six characters or more. It is also the user's responsibility to keep the pass phrase in a safe place and make it known to the other users who are also using the Disk eXPress image archives. The encryption algorithm used is by no means bullet proof, and may not resist cryptanalysis. However, it is reasonably complex to prevent the average computer users from deciphering the data. Better result is obtained if the image file is compressed. If you have sensitive data, the use of a more sophisticated encrypter is recommended. /s Suppress any overwrite (y/N) prompt. It assumes an answer of 'y' to all prompts. Three switches are available when no drive letter is specified in regular mode: 13 /d Display the description of the image file. The full path to the diskette image must be specified. /e Edit the description stored in an image file. This is used to correct the description later instead of having to redo the entire image from scratch. It will automatically prompt you for the pass phrase if the image file is encrypted. See the /p switch on bypassing the pass phrase prompt. /r Replace or add extract code to image file. Filename may contain any wildcard characters (ie: ? and *). If /r is used against a self-extracting diskette image, the self- extracting code will be replaced with the one stored within Disk eXPress. No backup file is created if the operation is successful. If used against a non-self-extracting image file, the self-extracting code will be added, and a new file with ".EXE" extension will be created. The ".EXE" file created by this switch is stored in the same location of the original image file. The /DOS, /e, /p and /s switch can be used together with this switch. NOTE: the /e switch does not allow the specification of wildcards. Note: The file extension replacement algorithm simply removes any file extension starting after the last '.' and then appending "EXE". Since it is possible to use multiple '.' under HPFS, the text after the last '.' is discarded. It is advisable to avoid using multiple '.' with HPFS filename, and use a space instead. 8.2. Extract mode Disk eXPress can decode and extract 3 types of images: type 0 (non-compressed), type 1 (Version 1 compression), and type 2 (Version 2 compression), including non-DOS, and encrypted images. When Disk eXPress is used for extracting an image file, the image file can be a non-self-extracting image file, or a self- extracting executable. The full path to the image file must be specified. Wild cards are not allowed. All the switches available in the extract mode of Disk eXPress are identical to the standalone Xtract program. /t Test the integrity of the image only. Disk eXPress performs data decompression (if necessary) and runs through a 32-bit CRC computation on the data stored in the image. It reports the stored and computed CRC values. If these values do not match, the image will be bad. It overrides the specification of a drive letter, /f, /s, /v, and the /c switch. It will prompt for pass phrase if the image file is encrypted. See the /p switch on bypassing the prompt. /d Display the description of the image file. The full path to the diskette image must be specified. 14 /f Format the target diskette. Only standard PC physical diskette formats with 512-byte sectors are supported. If /fs is specified, sector skew optimization is performed to allow the fastest diskette read/write speed in the future. The speed up is anywhere from 10 to 50% depending on the hardware. The formatting time is longer when this option is specified. Sector skew optimization is only available under OS/2, and not available in the shareware release. /p Specify pass phrase for unlocking the file for various operations. Disk eXPress detects encrypted image file, and will automatically prompt for a pass phrase even if this switch is not specified. Pass phrase can specified immediately after the switch to bypass the pass phrase prompt. The pass phrase must be 4 to 64 characters in length. It is case sensitive and spaces can be embedded. When the pass phrase contains space, it can be specified as: /p"Secret Pass Phrase". /s Suppress any overwrite (y/N) prompt. It assumes an answer of 'y' to all prompts. /v Verify on. It performs a track verify via operating system call, follows by a track read, and a byte-by-byte comparison with the original data. The byte-by-byte comparison is added as an extra protection should the CRC test of track verify failed to pick up an error. If disk cache is used under DOS, the byte comparison test may not be valid due to the fact that the cache is supplying the data with no actual read performed on the diskette. Disk eXPress bypasses disk cache when it is run under OS/2. /w Wipe unused tracks on diskette during image file extraction. Unused space at the end of the target diskette is written with hex F6 so that any sensitive data previously written on the diskette are erased. NOTE: this function is not available in self-extracting images. /c Convert the image onto a higher density diskette. The target diskette must be of different form factor (3.5" to 5.25" and vice versa, but not 3.5" 720K to 3.5" 1.44M due to hardware limitations). It requires a formatted diskette, and will automatically override the /f switch. Here is a list of all the diskette conversion possibilities: 160K/180K/320K/360K to 720K/1.44M/2.88M 720K to 1.2M 1.2M to 1.44M/2.88M /q QuickFormat of diskette in drive. This is useful for quickly erasing all files on a DOS formatted diskette. The 15 File Allocation Table (FAT) and all directory entries are erased to zero. Bad sectors and volume serial are preserved after QuickFormatting. 8.3. Diskettes containing bad sectors Starting from version 2.32, Disk eXPress allows the creation of diskette images from diskettes containing unreadable (ie: bad) sectors. When Disk eXPress encounters unreadable sectors, the following message is displayed: Read Error: Abort, Retry, Ignore? (a/R/i): Choose "Retry" to tell Disk eXPress to retry reading the entire track of information in one operation, and will re-prompt for the above message if any of the sectors on the track is unreadable. Choose "Ignore" to tell Disk eXPress to retry reading each sector on the track in sequence. Any unreadable sectors will be saved as 512 bytes of zeros. The image header is updated to notify the extraction code that the image file in question contains unreadable sectors from the previous image built. 8.4. Batch mode support You can use Disk eXPress, Xtract, and self-extracting images in a batch file (.CMD file under OS/2 and .BAT file under DOS). For a list of error return codes, please refer to section 10.2 for details. Normally, all display output is sent to standard out (stdout), and can be redirected to a file. Errors and warning messages are sent to standard error (stderr). You can discard all Disk eXPress output by redirecting both stdout and stderr to NUL (ie: DXP A: MyDisk > NUL 2>NUL). In addition to entering diskette image description via the /d switch, you can also enter the description from within a batch file as shown below: SET DXPDESC1=Disk eXPress SET DXPDESC2=Version 2.34 SET DXPDESC4=(c) Copyright 1991-94 Albert J. Shan dxp a: MyDisk /d SET DXPDESC1= SET DXPDESC2= SET DXPDESC4= Line 3 and 5 are treated as blanks since DXPDESC3 and DXPDESC5 are not specified. Batch mode description editing (/e) is also supported. 16 8.5. Disk eXPress real-time bar graph display One of the new features of Disk eXPress Version 2 is the use of a real-time bar graph display. Disk eXPress and Xtract will exercise the multi-threading capability under OS/2, and you'll see a display similar to the following: 3% 25% 50% 75% 100% Action Rate Track Head ├────────┼─────────┼─────────┼─────────┤ COMPRESS 52% 37 1 █████████████████▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒ The above bar graph depicts 3 concurrent threads: ▒ Read thread. Performs continuous reading of diskette (or disk file if it is in extract mode), and releases the diskette drive (or disk file) for use by another process when reading is finished. ▓ Compression/decompression thread. Compression/decompression is performed as soon as data is available from the read thread. █ Write thread. Compressed data is written to a disk file (or decompressed data written to diskette in extract mode). This can be another diskette drive or any block device. The description under "Action" shows which thread has just started executing. The number under "Rate" shows the current compression rate. It is the percentage reduction with respect to the size of the original data. The numbers under "Track" and "Head" show the current disk track and head where operation is being performed. Since DOS has only one thread of execution, only one bar is updated at any time. Read/Compress/Decompress/Write occurs sequentially. 17 9.0. EXAMPLES _________________________________________________________________ 9.1. Example 1 To pack a 360K diskette in drive B: onto a file called 'disk1' for modem transmission, you type: dxp b: e:\upload\disk1 By default, Disk eXPress will automatically append ".EXE" onto the output file name. If you specify something else as file extension, it will be removed before appending. If the command line syntax is correct, Disk eXPress will first run a self-check for virus/modification, then it will proceed to create the diskette image. You'll receive a screen similar to the following after Disk eXPress is finished: 360K diskette found in drive B: File Allocation Table statistics: Track 33 head 1 contains the last allocated sector, sector 609. 3% 25% 50% 75% 100% Action Rate Track Head ├────────┼─────────┼─────────┼─────────┤ STORE 28% 33 1 ████████████████████████████████████████ 32-bit CRC of diskette image is DB49A615 By default, Disk eXPress will analyze the FAT and save up to the last sector used on the diskette. In the above example, it stops at track 33, head 1, because sector 609 is the last allocated sector. If you have a fragmented diskette, you might receive a screen similar to the following when you run Disk eXPress: 1.44M diskette found in drive A: File Allocation Table statistics: Track 36 head 1 contains the last allocated sector, sector 1319. Disk fragmentation detected: 814 unallocated sectors will be saved in image (61% of total used sectors). The diskette requires compression for maximum storage efficiency. 3% 25% 50% 75% 100% Action Rate Track Head ├────────┼─────────┼─────────┼─────────┤ COMPRESS 48% 16 0 ██████▓▓▒▒▒▒▒▒▒ etc. Running a disk optimization utility on the diskette will help packing files tightly together for maximum storage efficiency. 18 Alternatively, you can copy all the files to another freshly formatted diskette so that the files are packed next to each other. 9.2. Example 2 To save the entire diskette from drive A: (including all the unused sectors) onto the image with compression turned off, you type: dxp /a /n a: e:\upload\disk1 You will see this warning if the file exists: Output file E:\UPLOAD\DISK1.EXE exists, overwrite? (y/N): Default action is 'No' for pressing the 'Enter' key. Type 'y' then 'Enter' to overwrite. To suppress the warning, specify /s on the command line: dxp /a /n a: e:\upload\disk1 /s Notice that you can specify switches anywhere you want on the command line, Disk eXPress will sort them out for you. 9.3. Example 3 To enter a description when creating an image, you type: dxp b: test15 /s /d You'll see: Please enter diskette description: (5 lines max.) ┌────────────────────────────────────────┐ 1: You're then prompted to enter a maximum of five lines of description (40 characters for each line). To enter a blank line, just press Enter. To continue our example, type in the following: Please enter diskette description: (5 lines max.) ┌────────────────────────────────────────┐ 1: Joe, 2: This is the latest beta release of Space 3: Commander. Try it out without a joy 4: stick and let me know how it goes. 5: Regards, John 19 360K diskette found in drive B: File Allocation Table statistics: Track 33 head 1 contains the last allocated sector, sector 609. 3% 25% 50% 75% 100% Action Rate Track Head ├────────┼─────────┼─────────┼─────────┤ STORE 28% 16 1 ███████████████████▓▓▒▒▒▒▒▒▒ etc. 9.4. Example 4 To change the description of the diskette image created in the last example, type: dxp e:\upload\test15.exe /e The /e switch allows description in the image file to be edited. Note: The /r switch (self-extracting code replacement) can also be specified together with the /e switch. 9.5. Example 5 Now that you have the self-extracting image, what are you going to do with it? Simply run it! To unpack the disk image created in example 3, type 'test15' to see the help screen: Disk eXPress Self-Extracting Diskette Image (OS/2 and DOS) Version 2.34 07/08/94 (c) Copyright 1991-93 Albert J. Shan. All Rights Reserved. Usage: TEST15 [/d] [/s] [/t] [drive:] /d Display image description /s Suppress overwrite prompt /t Test image integrity only drive Drive letter of a valid floppy disk drive Note: The target diskette must be formatted and must not have any bad sectors. To finish our example, now type: test15 b: You'll see: ┌────── Diskette Image Description ──────┐ Joe, 20 This is the latest beta release of Space Commander. Try it out without a joy stick and let me know how it goes. Regards, John └────────────────────────────────────────┘ 360K diskette image (Disk eXPress type 2) Diskette in drive B: is about to be overwritten with new information. Do you wish to continue? (y/N) Default action is 'No' for pressing the 'Enter' key. Press 'y' then 'Enter' to start diskette image extraction. The /s switch can be specified to bypass the prompt. The /d switch can be used alone to display the description in the image. 9.6. Example 6 To test the integrity of the diskette image without writing out to the diskette, simply type: test15 /t And you'll see: ┌────── Diskette Image Description ──────┐ Joe, This is the latest beta release of Space Commander. Try it out without a joy stick and let me know how it goes. Regards, John └────────────────────────────────────────┘ 360K diskette image (Disk eXPress type 2) 100% Read 32-bit CRC stored: DB49A615 32-bit CRC computed: DB49A615 Note: /t overrides drive letter specified on the command line. 9.7. Example 7 Now that Joe got the diskette image. He doesn't have a 360K or 1.2M drive (5.25" drive). All he has is a 1.44M 3.5" drive. He also happens to have a spare 720K (low-density) diskette he can use. What can he do? He can use the /c switch in the extract mode of Disk eXPress or Xtract. The /c switch can be used to convert the diskette image from 360K to 720K, and all the data will still be intact, and usable. The diskette used for 21 conversion must be pre-formatted. So, Joe went ahead and formatted the diskette as a 720K diskette, and he types: dxp test15.exe a: /c And receives the following screen (answer y at the prompt): Checking test15.EXE for modifications ... OK. 360K diskette image (Disk eXPress type 2) Diskette in drive A: is about to be overwritten with new information. Do you wish to continue? (y/N) y 720K diskette found in drive A: Converting 360K image onto 720K diskette ... 3% 25% 50% 75% 100% Action Track Head ├────────┼─────────┼─────────┼─────────┤ DECOMPRESS 20 0 █████████▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ etc. 9.8. Example 8 To QuickFormat a diskette, type: dxp a: /q OR xtract a: /q And you'll see: Drive A: is about to be QuickFormatted. Do you wish to continue? (y/N) The default action is 'No' for pressing the Enter key. The /s switch can be used to bypass the warning prompt. Type 'y' and press Enter and you'll see: QuickFormatting 1.44M diskette ... Done. 9.9. Example 9 To build a non-self-extracting, non-DOS diskette image, with pass phrase at the same time, type: dxp a: unixboot.dxp /i /p"FoO BaR" 22 10.0. ERROR MESSAGES _________________________________________________________________ 10.1. List of error messages Disk eXPress incorporates 32-bit CRC checking for itself and the image it creates. In the event of a virus infection or other means of modifications (such as errors in electronic transmissions), the program will abort, and the following message is displayed: *** Executable code has been modified! Here is a run down of major error messages produced by Disk eXPress, Xtract and self-extracting images: (usually a beep followed by one of the following messages) - For bad or not properly formatted diskette during read, write, format or verify (no beep for any Abort, Retry messages): Read Error: Abort, Retry, Ignore? (a/R/i): Write Error: Abort, Retry? (a/R): Write Error: Abort, Retry, Format once, Format all? (a/R/o/f): Format Error: Abort, Retry? (a/R): Verify Error: Abort, Retry? (a/R): *** Bad CRC. *** Sector not found. *** General failure reading drive X: *** Non-standard/unformatted diskette. - When disk is full during image creation (output will be deleted): *** Error writing disk or disk full. - With a write protected diskette during diskette write: *** Diskette is write protected. - When replacing self-extracting code in images with a lower revision level of Disk eXPress: *** Cannot operate on Disk eXPress Vx.xxx image. - When diskette drive is not ready: 23 *** Drive X: not ready. - When drive specified is not available or not a diskette drive: *** Invalid drive/path specified. *** Drive X: is not a floppy drive. - When attempting to replace a version 1 self-extracting header with version 2 by the /r switch: *** Cannot operate on Disk eXPress V1.0xx image. - When Disk eXPress or Xtract is asked to extract an unrecognized image file: *** Problem with file: filename Probable cause of problem: 1. File is not a Disk eXPress image file, 2. Image file has been modified, 3. Image file was created by a special version of Disk eXPress. - When Disk eXPress or Xtract is asked to convert a diskette image to the same form factor diskette: *** Conversion not supported on target diskette. - When pass phrase entered is incorrect upon an image extraction: *** Incorrect pass phrase, operation aborted. - Some error messages returned by Disk eXPress are displayed as: *** Error n, Drive X: In such event, please document the procedure on how to get to the above error, and contact me as soon as possible. 10.2. List of error return codes The following is a list of error return codes produced by Disk eXPress, Xtract, and self-extracting images: Code Number Cause of Error 0 Operation successful, no error found. 1 No operation is performed; such as the displaying of help screens. 2 Incorrect Operating System version. 3 User abort by answering 'N' to a (Y/N) type prompt. 24 4 User press Ctrl-C or Ctrl-Break to abort program. 5 Memory allocation error (Program error). 6 Cannot create thread under OS/2 (check THREADS= in OS/2's CONFIG.SYS). 7 Other system errors. The actual return code is displayed on the screen as: *** Error n, Drive X:. 8-9 Reserved. 10 Drive specified is not a floppy drive. 11 Invalid Drive or path specified. 12 Uncertain media in drive (non-standard/unformatted diskette). 13 Diskette Drive not ready. No diskette in drive, or drive is in used by another program. 14 Diskette is write protected. 15 Disk write error or disk full. 16 CRC Error. Possibily due to bad diskette. 17 Sector not found. Possibility due to bad diskette. 18 Diskette Format error. Possibily due to bad diskette. 19 General failure. Possibily due to unformatted diskette. 20-29 Reserved. 30 Cannot open file. Either it is not found or in used by another program. 31 Bad image file header. Image header failed CRC test. 32 File is corrupted possibily due to error in electronic transimssion or infection by virus. 33 Bad image file CRC. Possibily due to error in electronic transmission. 34 Incorrect image file version. 35 Unknown image type. 36 No files found for /r switch processing. 37-39 Reserved. 40 Diskette and image file mismatch. 41 Cannot format diskette due to diskette/image file mismatch. 42 The diskette capacity specified in /a is not acceptable for the diskette drive. 43 Cannot convert image file to the requested diskette format due to floppy hardware limitation. 44 Cannot QuickFormat diskette because it is not a DOS formatted diskette. 45 Incorrect pass phrase entered for unpacking the image file. 25 11.0. LIMITATIONS _________________________________________________________________ Diskette images created by Disk eXPress version 2 are not compatible with version 1 images. Replacement of version 1 self- extracting code with the /r switch is not allowed. When Disk eXPress is used to create a self-extracting diskette image, the extract code is bundled as an overhead for each image created. The overhead is currently at 25K (11K for DOS only image). This is acceptable, considering the size of any non- trivial diskette image is usually quite large (in the order of several hundred kilo bytes or even mega bytes). 25K should require about two minutes for a 2400 baud modem to transfer, and with a 14.4K V.32bis modem, the transfer time is about 16 seconds. Other limitations include the inability to read a diskette drive over the LAN (limitation of the network driver), and Disk eXPress over any copy protected programs. Another limitation is its inability to read over physically bad sectors. Any suggestions and comments are welcome. Suggestions for new features may eventually be incorporated into a future release.