旼컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� � � � � � � � � � � � � � � � � � � � � � P K I N S E R T � � Version 6.6 � � � � Copyright 7th Illusion, 1990-1991 � � All Rights Reserved � � Released November 14th, 1991 � � � � F R E E W A R E � � � � � � � � � � � � � � Software Documentation � � � � � � � � � � � � � � 7th Illusion � � Post Office Box 1334 � � Station H � � Montreal QC, Canada � � H3G 2N6 � � � � � � Node 1 (514)338-1193 � � USRobotics Courier HST 14400 Bps � � 1:167/281.0@fidonet.org � � � � Node 2 (514)338-1680 � � GVC Super Modem 2400 Bps � � � � � � � � � � � � � � � � � 읕컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� PKinsert Software Documentation Page 1 of 14 Introduction Pkinsert is an archive manipulation utility designed for SysOps and end users. It can be configured to test archive integrity, scan for viruses, insert and delete disclaimer files within Zip archives, etc. Pkinsert is fully network compatible and when used as a Bbs upload monitor, can create all the result files a SysOp may need. Released as Freeware, there's no need to register and all features are active. I'm well aware of the eternal struggle SysOps face in registering just a small portion of the software they use. :-) I'll answer questions and work in most features you suggest, just drop off a message on my system (long-distance callback validation available). If you use Pkinsert and have authored SysOp or Telecommunications oriented software, I would appreciate if you uploaded me a copy in return. Please don't bother with Crippleware. Supplemental information on installing Pkinsert with PCBoard is available from the PkinsPCB.Doc file. J.S. Morisset aka Storm Widow PKinsert Software Documentation Page 2 of 14 Acknowledgements The following names are either trademarks, registered trademarks, and/or efforts of the person and/or company named. PCBoard Clark Development Company Pkzip/Pkunzip PKWare Inc. SCAN McAfee Associates Upgrading Although you may simply 'drop-in' the new Pkinsert.Exe file, I suggest you run the configuration module to take advantage of version 6.6's new features. The first time you re-configure Pkinsert, it will compensate for any missing values. On exit, a proper version 6.6 configuration file will be created. If you are upgrading from a version prior to 6.0, you will have to start from scratch. Please review the PkinsHis.Doc file for details on new features and bug fixes. PKinsert Software Documentation Page 3 of 14 Pkinsert Parameters Parameters may be entered from the command line or environment variable. Environment parameters will over-ride those of the configuration file, and command line parameters will over-ride those of the environment. Parameters are not case sensitive. Parameter /C Marks Pkinserts configuration file name and path. This variable must be present in the environment or command line for Pkinsert to load successfully. ie. /cD:\Arc\Pkinsert\Pkinsert.cfg /D Pcboard upload description file name and path. Used to document test failures. (optional) ie. /dD:\Pcb\Work\Uldesc.1 /d%3 /N Network node number. Maximum length of three alpha-numeric characters. (optional) ie. /n1A /S Version of Scan you are currently using. Maximum length of six alpha-numeric characters. (optional) ie. /s7.9V84 /CONFIG Load Pkinserts configuration module. ie. PKINSERT.EXE /cPkinsert.Cfg /CONFIG /TEST Re-test an archive (used on Bulletin Boards). Affects verbose log file results when a virus is located. (optional) ie. PKINSERT.EXE /TEST %1 /UPLOAD Process an upload (used on Bulletin Boards). Affects verbose log file results when a virus is located. (optional) ie. PKINSERT.EXE /UPLOAD %1 PKinsert Software Documentation Page 4 of 14 Configuration Module To configure Pkinsert for the first time, follow this first example. PKINSERT.EXE /CONFIG /cC:\Pkinsert\Pkinsert.Cfg Pkinsert will ask you to verify the path and name of the configuration file to create. Pressing the (Esc) key will get you back to Dos. Note - It is possible to use a single configuration file for multiple users/work stations. From the main configuration menu you will have three choices available to you. We will start from the first and explain every item as we go along. All standard editing keys are active. PKinsert Software Documentation Page 5 of 14 �袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴� � Options Menu � � � � Unzip/Temp Files Drive : C Insert Archive Comment : N � � Req Xtract Space (%Zip) : 250 Delete Disclaimer(s) : N � � Add File(s) to Archive : N � � Rename Bad/Virused Zips : Y � � Held Archive Rename Ext : HLD Manage Pass/Fail Log : N � � Keep Result/Error Log : Y � � Test Archive CRC : Y Max. Standard Log Size : 80 � � Corrupt Zip Rename Ext : BAD � � Nested Zip Array Size : 3 � � Scan Archives for Virii : N Zip Wildcard Array Size : 60 � � Virused Zip Rename Ext : VIR � � McAfee Assoc. SCAN Ver : 0.0V00 � � � � Number Taglines to Keep : 10 � � Identification Tagline? � � Generic Tagline � � � 훤袴 11/14/91 袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴 06:06:00am 袴暠 Unzip/Temp Files Drive Enter the drive letter where Pkinsert will extract archives for testing and virus scanning. I strongly suggest a ram-disk which improves Pkinserts performance dramatically. Req Xtract Space (%Zip) Pkinsert will check for available disk space before extracting archives. This value is not calculated like tax - 250% would be translated to 2.5 times the size of the archive. If Pkinsert runs out of disk space during processing, it will rename the archive or exit with an error level. Disk space errors are also reported during archive extraction, but verifying disk space before-hand saves time. Rename Bad/Virused Zips This encompasses more than just file naming. If this option is set to (Y)es Pkinsert will rename archives using the file extensions you entered above. It also assumes you are processing archives on a wildcard such as (*.Zip). When Pkinsert runs across a virused or corrupt archive it will rename it and continue to the next file in the batch. This method is not very selective - Any error reported by Pkzip/unzip or Scan will lead to an archive being renamed. These problems could be caused by a virus, corrupt archive, insufficient disk space, memory, etc. On the other hand, if you have elected not to rename archives you can do your own error checking when Pkinsert exits using errorlevel PKinsert Software Documentation Page 6 of 14 statements in a batch file. The complete list of Pkinsert error levels is available in appendix A. Pkinsert must exit immediately after an error occurs so this option should not be used for batch processing. Held Archive Rename Ext An archive will be renamed (if rename is enabled) to .Hld if a file measures 0 bytes, disk space runs out, or the file is not a valid archive. This provides a method to hold archives which did not fail because of Pkzip/unzip or Scan for later review. Test Archive CRC Before handling an archive, Pkinsert calls Pkunzip to test the archive's integrity. Nested archives (Zips within Zips) are also tested. Corrupt Zip Rename Ext If you choose to have archives renamed, Pkinsert will use this file extension to rename damaged zips. Scan Archives for Virii Pkinsert can use Scan.Exe from McAfee Associates to check archives for viral infection. Although archives are expanded to check for viruses it is unlikely you will 'catch' anything. Virii which can be archived attach themselves to executable code. The files extracted are Scaned and never executed. I've successfully tested this option several times with the Jerusalem Version B and 1701/1704 Version B viruses. I would have tested others but virus code isn't widely available. Virused Zip Rename Ext When a virus is detected, the archive will be renamed using this extension (provided renaming is enabled). McAfee Assoc. SCAN Ver As of this writing the current version of scan is 7.9V84. This field can be blank. If you enter a value here it will be used in several display files where mention of Scan is made. A command line or environment parameter may be used to over-ride this value. Number Taglines to Keep A Tagline is added to each archive comment containing Pkinsert's version number and your personalized information. Taglines from other systems may be kept and appended to your archive comment. This value determines the maximum number of past Taglines to keep. A value of zero may be used to disable this feature. Note - The Test, Scan, or Delete functions must be enabled for PKinsert Software Documentation Page 7 of 14 Pkinsert to pick up the Tagline information. Identification Tagline? Your personalized Tagline. Usually this includes your BBS's name, phone number, and special system features. As the archive travels through various systems, your tagline will remain within the 'Tagline History' (providing other systems keep previous Taglines). Once a system tagline has been embedded into the archive comment, it is still possible to alter it slightly. Pkinsert does not take into account case, spacing, or any non alpha-numeric character. Adding, erasing, or changing the positions of alpha-numeric characters will cause your old tagline to be used in the Tagline History bloc if an archive is re-processed. Note - A Tagline environment variable may be used to over-ride the configuration file value. ie. SET TAGLINE=7th Illusion Telecommunication Services Insert Archive Comment Archives created by Pkzip give us the opportunity to insert an archive comment screen. If you elect to use this option, create a Dos Ascii file which contains your drawing. Delete Disclaimer(s) Certain files, such as !History.Dis are well known to contain advertisements or disclaimer blurbs. You may elect to delete these files automatically from each archive Pkinsert processes. A sample list is included within this archive which you can edit from the next configuration screen. Add File(s) to Archive Same principle as above except this option lets you add files to every archive. I could go on for hours on the reason not to use this feature, including the fact that you are polluting archives, but I'll leave it to your better judgment. Manage Pass/Fail Log Aside from loging results, Pkinsert can also create one of two verbose log files for every session. These text files could then be displayed to the user. The names for these files can be specified later on. In order to properly link with other utilities which use this type of result logging, special handling is necessary. Before appending a Failure report, Pkinsert will rename the Pass Log (if it exists) to the Fail Log name. Therefore an archive could pass a series of tests before calling Pkinsert and still keep those results when Pkinsert fails the archive. PKinsert Software Documentation Page 8 of 14 If an Extended Fail Log already exists, it will be used to append Pkinserts Pass or Fail reports. In this way an archive could Fail a series of tests, pass Pkinserts tests, and overall you would be left with one Fail log file. Keep Result/Error Log This is a standard log file. I would suggest you keep this option set to (Y)es. It's maintenance free thanks to the following option. Max. Standard Log Size Before every session Pkinsert checks the size of it's log. If the size exceeds this value (in Kb), a new one is started. Nested Zip Array Size When Pkinsert is hunting down archives within archives (add infinitum) it monitors it's depth or how 'nested' it is. During this activity Pkinsert also keeps track of file names and locations to know which archives it has followed to the end, and which haven't been checked. Dos machines being what they are, you only get so much memory. This value specifies at what point Pkinsert should start shedding portions of itself to disk. When it comes back from the 'deep' it will pick up these pieces again and process the archives it missed. You can experiment and see what value you prefer. 3 or 4 is probably best. You don't see nesting past three very often. The larger this value is, the more memory Pkinsert will need. Note - Reading swapped information may take a few moments depending on the size of your wildcard array, system and disk access speeds. Zip Wildcard Array Size This value determines the maximum number of archives a nested archive may contain. Theoretically the wildcard array could be set for 999 (max tested was 600), but this would chew up tons of memory and disk swapping would be excruciatingly slow. I've tried to calculate the maximum number of archives a single Zip could hold, but I gave up when I hit 9 to the power of 302. That value corresponded to a wildcard array of 101. Unfortunately, this value also applies to the wildcards you enter on the command line. Therefore (*.Zip) could not exceed the wildcard array size. An error level on exit is set if it does. Wildcards can be avoided easily. See the 'Using Pkinsert' section for details. PKinsert Software Documentation Page 9 of 14 �袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴� � File Location Menu � � � � Ascii Editor : C:\QEDIT\Q.EXE � � � � Standard Log File : C:\PKINSERT\NODE-#.LOG � � Extended Pass Log File : PCBPASS.TXT � � Extended Fail Log File : PCBFAIL.TXT � � � � Virus Comment (Test) : C:\PKINSERT\VIRUSTST.CMT � � Virus Comment (Upload) : C:\PKINSERT\VIRUSULD.CMT � � � � Archive Comment File : C:\PKINSERT\PKINSERT.CMT � � � � Disclaimer(s) Del List : C:\PKINSERT\PKINSDEL.LST � � Add File(s) List : C:\PKINSERT\PKINSADD.LST � � � 훤袴 11/14/91 袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴 06:06:00am 袴暠 Ascii Editor Ascii editor file name and path. Placing the cursor on a line which can be edited, a bar will appear at the bottom of the screen informing you to press F2 to edit the file. Standard Log File File name and path of the Standard log file. Note - Pound (#) signs within TEXT ENTRIES are replaced with the current node number (except in the Tagline field). Node numbers are retrieved from the Pcboard.Sys and/or Door.Sys file in the current directory. If none is available, the node number defaults to zero (0). If you wish to retain ONE configuration file in a MULTI-USER environment, and do not have Pcboard.Sys and/or Door.Sys available, you may configure node numbers using the (/N)ode parameter. Extended Pass and Fail Log Files If the 'Manage Pass/Fail Log' option (1st configuration screen) is enabled, these file names are used to report processing results. Virus Comment (Test) and (Upload) These two text files are used when Pkinsert has created the Failed Log File above and *only* in cases when a virus is found. The contents of (Test) are added to the Fail log when the (/TEST) parameter is used. SysOps could use this file to advise users they should leave a Comment to the SysOp a.s.a.p. so this archive may be PKinsert Software Documentation Page 10 of 14 deleted. Similarly, the contents of (Upload) are added to the Fail log when the (/UPLOAD) parameter is used. This second text file could advise a user that his system might be contaminated and to take appropriate steps before uploading again. If these files do not exist, they will not be used. This way you could have a comment for one function and not the other. Archive Comment File This file should contain your archive comment (Ascii drawing). Enable this feature from the 'Configuration Options' menu. Disclaimer(s) Del List This list is used when the 'Delete Disclaimer(s)' option is enabled. A single filespec should be entered on each line. Archive contents will be compared to this list and matching files will be deleted. Add File(s) List Same principal as above, this file should contain a list of filespecs to insert in every archive. Unlike the delete list, you must include paths for each file. PKinsert Software Documentation Page 11 of 14 �袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴� � Command Line Parameters Menu � � � � Pkzip Del Disclaimer(s) : /dk � � Pkzip Add Files/Comment : /exzk � � � � Pkunzip Test Archive : /t � � Pkunzip Extract Files : /xn /ojhsr � � � � McAfee Associates SCAN : /a /nobreak /nomem /nopause /sub � � � 훤袴 11/14/91 袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴袴 06:06:00am 袴暠 These parameters are passed by Pkinsert when shelling to third party software. If you encounter problems with a new parameter set, please drop me a line so I can adjust Pkinsert accordingly. The options for Scan have been tested with version 7.9V84 and may not work with earlier versions. Pkzip Work File Path When Pkzip handles an archive, it creates a (.!!!) temporary work file. If you have a ram-disk installed, you should edit the above command line parameters instructing Pkzip to use the faster drive. ie. Pkzip Del Disclaimer(s) : /dk /bF:\ Pkzip Add Files/Comment : /exzk /bF:\ Date Stamping Using the (k) parameter, Pkzip will NOT change the file date of an archive. An (o) will set the archive date to the oldest file found within the archive. Eliminating these date parameters will cause the archive date to be updated to the current one. PKinsert Software Documentation Page 12 of 14 Using Pkinsert Using Pkinsert is fairly simple. From the command line or environment variable make sure Pkinsert knows where to find it's configuration file. Then call Pkinsert passing it file names (or wildcards). The parameters, file names, etc can be in any order. You could even enter file names through the environment variable if you wanted. Some examples follow. ie. SET PKINSERT=/cD:\Pkinsert\Pkinsert.Cfg /s7.9V84 PKINSERT.EXE Abc.Zip SET PKINSERT=/n1 /s7.8v82 PKINSERT %1 /cD:\Pkinsert\Pkinsert.Cfg *.Exe Abc-?.New SET PKINSERT=/cC:\Pkinsert\System.Cfg PKINSERT *.Zip *.Exe Abc.Bak SET PKINSERT=/n1 /sVer82 Archive.Zip /c\Arc\Config.Pki PKINSERT PKINSERT /cThisDir.Cnf Test.Zip Undoubtedly most users will want to test complete directories at some point, which may exceed the Wildcard Array size. In this case, an advanced Dos command line could be used. ie. LOOP.BAT ~~~~~~~~ FOR %%A IN (*.Zip) DO PKINSERT %%A or FOR %%A IN (A*.Zip Dbl*.* Abc-?.Zip) DO PKINSERT %%A Any filename preceded with an AT (@) symbol will be expected to contain a list of files to process. Each file specification in this list must occupy a separate line. Wildcarding is accepted. ie. Files.Lst ~~~~~~~~~ D:\Arc\*.Zip Archive.Zip E:\Main\Files\Backup.Z?? \Work\A*.Tmp You may also use a combination of directory pipes. ie. C:\> Dir D:\Arc >>Files.Lst C:\> Dir E:\Main\Files\*.Zip >>Files.Lst Instead of entering redundant directory information you can tell Pkinsert to change drives and directories. Use the (Cd) command followed by a space, or back-slash, and the directory name. PKinsert Software Documentation Page 13 of 14 ie. Files.Lst ~~~~~~~~~ Archive.Zip Cd\Arc *.Zip Cd E:\Main\Files Good*.Zip Bad*.Old Ugly*.$$$ Cd\C:\Temp Backup.Z?? These techniques can be used together for greatest versatility. Note - Normal array size boundaries apply ONLY to wildcards within this list. There is NO LIMIT to the number of filespecs contained in the file list. If you have a directory of several thousand archives you could use a command sequence along these lines: C:\> Dir J:\Uploads\*.Zip >>Files.Lst C:\> Pkinsert @*.Lst Wildcarding is also acceptable for filelist names. PKinsert Software Documentation Page 14 of 14 Appendix A Pkinsert Exit Codes Virus Scan 10 One or More Virii Found 11 Abnormal Termination (Usually Lack of Memory) Pkunzip 20 Zip Failed CRC Check 21 Error in Zip File 22 Insufficient Memory 23 Archive File Missing 24 Illegal Parameters Specified 25 No Files in Archive to Test 26 Disk Full 27 Unexpected EOF in Zip Pkzip 40 Bad File Name or File Specification 41 Error in Zip File 42 Insufficient Memory 43 No Files Found To Delete 44 File Not Found 45 Disk Full 46 Archive Is Read-Only - Cannot Modify 47 Bad or Illegal Parameters 48 Too Many Files in Zip Pkinsert 100 Incorrect Parameters 101 Configuration File Missing 103 Unable To Create Work Directory 104 Invalid Path or No Matching Files 105 Insufficient Drive Space Available 106 Unable To Remove Work Directory 107 Insufficient DOS File Handles 108 Network Delay Timed-Out 109 Unable to Remove Nest Directories 110 Illegal Configuration File Value 111 Illegal Compression Method Used 112 Zero Byte File 113 Unknown Configuration File Format 114 Unable to Locate File; Pkzip/Unzip or Scan 200 Wildcard Array Exceeded