PC Open 18

home *** CD-ROM | disk | FTP | other *** search

/ PC Open 18 / pcopen18_giallo.iso / Msdos / GfxCheck / GFXCHK.DOC < prev next >

Wrap

Text File | 1997-05-05 | 23.8 KB | 526 lines

┌──────────────────────────────────────────┐ │ G F X C h e c k │ │ GIF/JPEG/BMP Graphics Checking Utility │ └──────────────────────────────────────────┘ Version 1.23 (c) Copyright 1997 - ZT Technologies Techical Support: Herbert Bushong Blackbeard's BBS 318-468-3385 (V34+) ┌────────────────────┐ │ 1. Introduction: │ └────────────────────┘ GFXCheck was developed to provide the cyberspace community with a means of validating GIF, JPEG and BMP graphics files without the need for actually firing up a graphics file viewer. While there are similar utilities available for GIF files, they are generally dated, run only under DOS and do nothing to validate JPEG (currently the leading graphics file format technology) or BMP files. GFXCheck was designed to address these specific issues. While GFXCheck obviously cannot determine the subjective quality of an image, it can detect many common defects and corruption that can occur in graphic files being transferred by a variety of media. ┌────────────────────────────┐ │ 2. Features of GFXCheck: │ └────────────────────────────┘ ∙ Native versions for both 16-bit DOS and 32-bit OS/2! ∙ Automatically identifies (by signature) GIF87a and GIF89a GIF files, JFIF 1.x format JPEG files, and Windows, OS/2 1.x and OS/2 2.x format BMP files. ∙ Validates graphics files for proper format and construction (e.g. invalid structure, unexpected end of file, etc.). ∙ Trims any extraneous bytes from the end of the graphic file. ∙ Rejection of graphics files based upon image parameters (e.g. width, height and/or number of colors). These can be set individually for GIF, JPEG and BMP graphic formats. ∙ Logging of existing GIF and JPEG comments. ∙ User-defined stripping and/or insertion of GIF and JPEG comments. ∙ User-defined disposition of defective or rejected graphic files. ∙ Updates BBS file descriptions (PCBoard-format or similar) with a user- configurable information string. ∙ User-selectable process logging to a disk file. ∙ Written completely in C for optimal speed, using Watcom C/C++ 11.0. ┌──────────────────────────────────────────────────────────┐ │ 3. Files Included in the GFXCheck Distribution Archive │ └──────────────────────────────────────────────────────────┘ GFXCHK.EXE GFXCheck file checker program (16-bit DOS). GFXCHK2.EXE GFXCheck file checker program (32-bit OS/2). GFXCHK.DOC This file. SAMPLE.CFG Sample configuration file. GIF.TPL Sample GIF comment template. JPEG.TPL Sample JPEG comment template. SUPPORT.DOC List of authorized support sites for my shareware. HISTORY.DOC GFXCheck revision history in reverse order. REGISTER.FRM Registration form for GFXCheck and other software. FILE_ID.DIZ Internal description file. When you unzip the distribution archive, you should see my PKZIP authenticity verification stamp, and a '-AV' after every file in the archive: # PNP757 ZT Technologies If there are any files missing or added, or the -AV stamp is missing, the archive has been tampered with. ┌───────────────────────────┐ │ 4. Program Requirements │ └───────────────────────────┘ To the best of my knowledge, this program will run on most any machine, as it uses no specific hardware or operating system features. I have personally tested GFXCheck under OS/2 Warp 3.0, DOS 6.20, DESQview and Windows for Workgroups 3.11, although I don't expect problems under other configurations given they conform to the general requirements of GFXCheck. GFXCheck requires DOS 3.x and higher (or OS/2 2.0 and higher for GFXCheck/2), as it uses DOS SHARE-compatible file reads and writes. GFXCheck's memory requirements are very small (less than 100K) and should run merrily under most any upload or file processing software, in many cases without any need for swapping. ┌───────────────────┐ │ 5. Registration │ └───────────────────┘ GFXCheck is not free; nor is GFXCheck crippled to force registration. GFXCheck is fully functional, and will always remain so. The only variation with the registered copies is no time delay and beg message. Why register? Besides a clean conscience, you will get a registration key that will work for all future versions of GFXCheck, and will remove the delay and beg message at the end of execution. The registration fee for your unique key is $20 for hobbyist use. The registration fee for commercial use, defined if you use GFXCheck in the course of a commercial business or for profit (e.g. CD-ROM production, more than 10 BBS nodes, etc.), is $30. Refer to the file REGISTER.FRM for more registration information. Please print the file REGISTER.FRM and fill it out. You can print out the form by issuing the following command from the DOS prompt: TYPE REGISTER.FRM > PRN ┌───────────────────────────────────────┐ │ 6. License, Warranty and Disclaimer │ └───────────────────────────────────────┘ I'll keep this part short and sweet, and dispense with the legal-ese: License: You are allowed to use GFXCheck for 30 days, after which you must either register GFXCheck or stop using it completely. Decompiling, disassembly or any other form of reverse-engineering GFXCheck for any purpose is prohibited. GFXCheck registration is a license for your use of GFXCheck; I retain ownership of the software. A single registration applies to a single enterprise (e.g. BBS, CD-ROM mastering company) regardless of the number of computers used. If you run two or more distinct BBS systems on the same computer (with different names), you require two or more GFXCheck registrations. GFXCheck registrations are not transferrable; you cannot sell your registration to another person. Warranty: There isn't one. The only thing I'll guarantee is that GFXCheck will take up disk space, and will disappear when deleted. Disclaimer: I'm not responsible for anything bad that happens. GFXCheck works for me, but I cannot be held responsible for it not working on your computer or doing any damage to hardware or software. If these conditions aren't agreeable with you, then the best thing to do is delete GFXCheck right now. I'll do my best to help any user (registered or not) that wants to use GFXCheck, and I'll act on bug reports quickly, but I simply cannot and will not be responsible for anything bad, like lost data, disk crashes, or whatever else you can think of. ┌───────────────────┐ │ 7. Installation │ └───────────────────┘ GENERAL INSTALLATION: ───────────────────── Make a subdirectory on your hard drive. For the purposes of this document, we'll call it "D:\GFXCHK". Unarchive the GFXCheck distribution archive into this subdirectory. You've more than likely already made it this far, if you're reading this file. <grin> The GFXCheck program opens a few files at once for various reasons. I would recommend that you have a minimum of FILES=30 per node in your system CONFIG.SYS file for a DOS single-node system, since GFXCheck is often run in conjunction with your BBS and upload or file processing software. If you are running under a DOS network or a multitasking operating system, you should already have DOS's SHARE.EXE loaded. You must have SHARE loaded (or running an operating system that has SHARE functionality, such as OS/2 or Novell) in order to take advantage of the file sharing and locking methods used by the GFXCheck program to prevent data loss. (If you are running a single- node system without a multitasker, SHARE is not needed). Edit the sample configuration file to suit your needs. Proper configuration will require you to refer to this section and the section titled "Configuration", which has an in-depth explanation of each configuration parameter and its function. It might be wise to fire up your printer for this document. Note that for the GFXCheck program, you can obtain a limited program syntax screen simply by executing the program without any command-line switches. COMMAND-LINE SWITCHES: ────────────────────── As a bare minimum, GFXCheck requires two command line parameters: one for the GFXCheck's configuration file (-C switch) and another for the graphic file(s) to test (-F switch). For example, the following command lines are both valid: D:\GFXCHK\GFXCHK.EXE -Cd:\gfxchk\gfxchk.cfg -Fd:\path\graphic.ext GFXCHK.EXE -Cgfxchk.cfg -Fd:\path\graphic.ext The second command line will work if your GFXCheck subdirectory is part of your system's PATH. In order to find the configuration file, GFXCheck will first try to open the configuration file as passed. If that fails, GFXCheck will then try to open the same file in the same directory that GFXCHK.EXE is in (unless an explicit path has been passed on the command line as in the first example). If you want GFXCheck to update file descriptions, the corresponding description file must be passed on the command line using the -D switch: GFXCHK.EXE -Cgfxchk.cfg -Fd:\path\graphic.ext -Dd:\path\desc.lst Note that GFXCheck will modify only descriptions for graphic file(s) that it has processed; descriptions for any other files will be retained without change. Further, if no matching description is found, GFXCheck will not add a description; it will log the fact that a description is missing in its log file. GFXCheck by default will check all graphics files passed to it. If you only want to extract image parameters and skip validation, add the -I command line switch. This will greatly speed processing if you do not need to perform any checking at that time. For example, if you only want to update your BBS descriptions, this switch would make the process quicker. Do not use this switch under normal testing conditions in your file/upload processor. The -R command line switch forces GFXCheck to restore the graphic file date and time stamps. By default, if GFXCheck updates the file (by trimming extraneous bytes), the date will be changed to reflect the date of modification. Lastly, GFXCheck normally sounds a beep on error. If this is not desired, the -Q switch will silence GFXCheck during operation. INSTALLATION INTO YOUR BBS UPLOAD PROCESSOR: ──────────────────────────────────────────── GFXCheck is designed to operate like most any other file checker, such as virus checkers, etc.. Generally, it will operate on a subdirectory of files that have already been extracted by the upload processing system or will be passed a specific graphic file to check. The best application for GFXCheck is to be executed as a graphic file test utility where just graphic files are passed to it by the calling program, e.g.: D:\GFXCHK\GFXCHK.EXE -Cd:\gfxchk\gfxchk.cfg -Fd:\path\graphic.ext In the case of UpLoadProcessor (2.10 or higher), the command line is simply: D:\GFXCHK\GFXCHK.EXE -Cgfxchk.cfg -F@FILE@ In the absence of a feature to execute checkers solely for graphic files in the calling program, GFXCheck can be configured similar to a virus-scanning program, since at that point in time the files are already extracted from the upload being processed. Depending upon how your upload processor operates, the command lines and configuration can be different. If your upload processor executes the file testers from the directory where the files are located (UpLoadProcessor is an example of this behavior, although it can pass specific graphic files to GFXCheck), the command line can be simply: D:\GFXCHK\GFXCHK.EXE -Cd:\gfxchk\gfxchk.cfg -F*.* GFXCheck also supports list files when preceeded by a '@' character (e.g. -F@FILE.LST) for the file command-line switch parameter. The list file must have one filespec per line, standard DOS wildcards are permitted. Any line in the list starting with a semicolon will be considered a comment and skipped. Note that if you use GFXCheck in this manner, you should turn off the FAIL_UNKNOWN configuration switch to prevent unknown (non-graphic) format files from triggering a failure. ┌────────────────────┐ │ 8. Configuration │ └────────────────────┘ The sample configuration file included in the distribution archive is heavily commented, but some additional information is provided below: LOG_FILE GFXCheck will write process and error information to a log file, if desired. This parameter is the path/filename of the log file for GFXCheck to record its activities. Comment out if you don't want any disk logging. If you need support for GFXCheck, the first thing you will have to have is a log file, so it is recommmended that you configure one. LOG_MODE Assuming the a log file is configured, GFXCheck can write two types of logs: VERBOSE and TERSE. TERSE logs little more than pass and fail, while VERBOSE offers more detailed information on the files being checked. GOOD_ERRLEV The errorlevel that GFXCheck is to return to the operating system if no errors were found in any file processed. If commented out, this value will default to 0, since most upload and file processors assume non-zero errorlevels to be program execution errors, not information. This value must be between 0 and 255, inclusive. FAIL_ERRLEV The errorlevel that GFXCheck is to return to the operating system if one or more graphic files checked is defective. This value defaults to 1. This value must be between 0 and 255, inclusive, or -1. If -1 is specified, the GFXCheck error code of the file is returned to the operating system. Note that if multiple files are processed, the result code of the last file processed will be returned (which could be 0 if no error was encountered). It is recommended that a fixed failure errorlevel be used unless you ensure GFXCheck processes files individually, where the return code/errorlevel is meaningful. FAIL_UNKNOWN GFXCheck will normally fail a non-graphic file as an unknown format. Setting this parameter to NO will prevent this. This can be useful for third party processors that pass an entire directory of various files to file checking programs without specifically delineating graphic files. DISPOSITION This parameter defines how GFXCheck dispositions defective graphic files. Three options are available: NONE (if GFXCheck is to leave the defective file alone), RENAME (if GFXCheck is the rename the file to .BAD) or DELETE (self-explanatory). The default is NONE. Note that the disposition will be applied to description processing if in process. If the disposition is set to RENAME, the filename will be renamed in the description file; if DELETE, the file's description will be deleted. TRIM_EOF With this option enabled, GFXCheck will trim any extraneous bytes from the end of a GIF or JPEG graphic file, saving disk space and easing the job of your duplication checking software, if any. If commented out, trimming will be enabled. GIF_MIN_RES, JPEG_MIN_RES and BMP_MIN_RES The minimum acceptable image resolution GFXCheck is to accept for graphic files in the format "WIDTH x HEIGHT x COLORS"; this can be set for the two formats independently via the two configuration keywords. If a particular element of the image value is set to 0, GFXCheck will not use that element in the evaluation. Setting to 0x0x0 will disable the image resolution check entirely and will prevent rejection based upon resolution. ALLOW_GIFLITE If GFXCheck is to accept GIF files that have been compressed with GIFLITE, set this to YES. Otherwise, set it to NO or comment out the line. GIFLITE poses problems to duplication checking systems such as that in ULP, ZDCS, etc. due to it's variable user-defined compression ratio. A user could conceivably compress the same image several times, producing several files that would be the same image but mathematically different. Default is NO. GIF_INFO_FMT, JPEG_INFO_FMT and BMP_INFO_FMT GFXCheck can update BBS directory listings with an information line for good GIF, JPEG and/or BMP files. The following lines define the format for the informational line using various @-macros. Recognized @-macros are: @BOARDNAME@ BBS name (from key file) @SYSTIME@ System time @SYSDATE@ System date @SYSOPNAME@ BBS sysop's name (from key file) @SERIAL@ GFXCheck serial number (from key file) @VERSION@ GFXCheck revision number @FILENAME@ Filename being processed @FORMAT@ Format of the file ("GIF87a", "GIF89a", "JPEG" or "BMP") @OSIZE@ Original file size @NSIZE@ New file size @WID@ GIF/JPEG/BMP image width @HGT@ GIF/JPEG/BMP image height @COL@ GIF/JPEG/BMP number of colors @SCOL@ GIF/JPEG/BMP number of colors (shortened form) @COMP@ GIF compression ("GIFLITE" or "None") INFO_POS This defines where the inserted text will be placed, as an appended line (NEW_LINE) or on the first line (FIRST_LINE) by itself. The default value is NEW_LINE. SEC_DESC_COL If GFXCheck is to update BBS directory listings with an information line, the following defines the column for the secondary desc character. The defaults is 32, matching PCBoard's default value. SEC_DESC_CHAR If GFXCheck is to update BBS directory listings with an information line, this defines the secondary desc character. The default is '|', matching PCBoard's default character. CMT_LOG_FILE GFXCheck can extract the current comment from the graphics file and log it to a log file if this information is of any interest. Comment out if no comment logging is desired. This cannot be the same file defined as the LOG_FILE paramter! GIF_STRIP_CMT and JPEG_STRIP_CMT GFXCheck can strip the current comment from a GIF or JPEG graphics file. If you want any existing comment stripped, enable one or both parameters. GIF_CMT_TPL and JPEG_CMT_TPL GFXCheck is fully capable inserting a new comment into a graphics file; note that in the process of doing so, GFXCheck will strip any previous comment. The comments are designed as a template using the same @-variables as the information lines and can be individually configured for GIF and JPEG files. If no comments are to be inserted, comment out the parameters. Since many graphics viewers do not like high ASCII, use only plain text in your comment templates. Note that in keeping with the GIF standards, if a comment is inserted into a GIF87a GIF file, it will be changed to GIF89a, the format that supports comments. ┌──────────────────────────────────┐ │ 9. BBS Application Information │ └──────────────────────────────────┘ UPLOADPROCESSOR: ──────────────── The correct configuration setup for GFXCheck within UpLoadProcessor 2.10 (or higher) is as a graphics file checker. In the "GIF/JPEG File Testing" menu of ULPSM, set up the GIF and JPEG file checker command lines as follows: Checker command: c:\gfxchk\gfxchk -Cgfxchk.cfg -F@FILE@ Successful errorlevel: 0 (must match GOOD_ERRLEV setting) Run in a window: Doesn't matter...<N>o might be a little faster In addition, ULP users should not allow GFXCheck to reject based upon resolution, as ULP has that ability internally. Set the GIF_MIN_RES and JPEG_MIN_RES parameters to "0x0x0". As ULP has it's own GIF/JPEG information line functionality, it is not possible to have GFXCheck update the file description. GENERIC BATCH FILE: ─────────────────── The following generic batch file (modeled after PCBTEST.BAT) will autodetect the compression format of the archive using TESTFILE.EXE (a utility provided by Clark Development with their PCBoard BBS Software) and verify any graphical uploads with GFXCheck: @Echo off cls if exist pcbpass.txt del pcbpass.txt if exist pcbfail.txt del pcbfail.txt REM - Intercept GIF, JPEG and BMP files for test... d:\pcb\testfile %1 gif jpg bmp if errorlevel 98 goto ARCHIVE_TEST d:\gfxchk\gfxchk -cgfxchk.cfg -f%1 -d%2 if errorlevel 0 goto GFX_OK echo ERROR: File failed GFXCheck file check... > pcbfail.txt goto END :GFX_OK echo File passed GFXCheck file check... > pcbpass.txt goto END REM - Your upload processing software goes here for general archives... :ARCHIVE_TEST e:\programs\ulp2\ulp -Ce:\programs\ulp2\ulp.cfg -F%1 -M%2 -D%3 -T0 :END exit OTHER SOFTWARE: ─────────────── If you are using a BBS file and/or upload processing system other than those described above, please provide information regarding your implementation details for inclusion in this documentation. Thanks! ┌──────────────────────────────┐ │ 10. The Future of GFXCheck │ └──────────────────────────────┘ GFXCheck will be supported as long as I'm poking around cyberspace (which could be quite a while...once it's in your blood, it's hard to shake it <g>). Thanks for giving GFXCheck a try! ┌────────────────────────┐ │ 11. Acknowledgements │ └────────────────────────┘ The Graphics Interchange Format(c) is the Copyright property of CompuServe Incorporated. GIF(sm) is a Service Mark property of CompuServe Incorporated. (Standard verbage required by CompuServe) ┌────────────────────────────┐ │ Appendix A: Error Codes │ └────────────────────────────┘ The following is a list of the error codes that GFXCheck puts in the log file to indicate the various errors detected in GIF, JPEG and BMP files (if the FAIL_ERRLEV parameter is set to -1, this will also be the operating system errorlevel). Since many of these errors are structural in nature, they may not be of any interest to the average user, but here they are anyway: 1 Unknown format (e.g. not a GIF or JPEG file) 2 Does not meet minimum resolution defined 3 Unexpected end of file (short file) 10 Error in GIF file header 11 Error in GIF image descriptor 12 No image in GIF file 13 GIF version conflict (e.g. GIF89a extensions in GIF87a file) 14 GIFLITEd GIF file (only if ALLOW_GIFLITE is set to "no") 20 JPEG duplicate start of image marker 21 JPEG duplicate APP0 application marker 22 Error in JPEG APP0 application block 23 JPEG duplicate start of frame marker 24 Error in JPEG start of frame block 25 Error in JPEG Huffman table block 26 Invalid marker in JPEG file 27 Missing a required marker in JPEG file 28 No image in JPEG file 29 Error in JPEG quantization table block 30 Error in JPEG restart interval block 31 Invalid or unknown JPEG marker 40 Error in BMP file header 41 Invalid number of planes in BMP 42 Invalid compression in BMP 43 Invalid colors used value in BMP ┌─────────────────────────────────────┐ │ Appendix B: Command Line Summary │ └─────────────────────────────────────┘ GFXCHK2 -Cconfig.ext -Fd:\path\graphic.ext [-Dd:\path\descrip.ext] [-I] [-R] [-Q] -C filename of the configuration file -F full path and filename of the graphic file(s) to be checked -D full path and filename of the description file to be updated [optional] -I extract image parameters only (no checking) [optional] -R retain original graphic file date stamp(s) [optional] -Q quiets beep on error [optional]