P K I N S E R T
Version 6.4

Copyright 7th Illusion, 1990-1991
All Rights Reserved
Released September 22nd, 1991

F R E E W A R E






Software Documentation






7th Illusion
Post Office Box 1334
Station H
Montreal, Quebec
Canada
H3G 2N6

Node 1 (514)338-1193
USRobotics Courier HST 14400 Bps
1:167/[email protected]

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 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.

Pkinsert is released as Freeware. As such, 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.

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 or unregistered
Shareware.




J.S. Morisset
aka Storm Widow
































PKinsert Software Documentation Page 2 of 14


General Requirements

You will need the following software to run Pkinsert.

Pkzip/Pkunzip by PKWare Inc.
SCAN by McAfee Associates (Optional).

Pkinsert should run from any Bbs software shell. Memory requirements
can be kept at a minimum by Pkinserts use of disk swap files. A
ram-disk is highly recommended to optimize speed.

Upgrading

No changes have been made to the configuration file structure since
version 6.0. Just drop-in the Pkinsert.Exe file and you're ready to
go. To upgrade from versions prior to 6.0, you'll have to start from
scratch.

Adjustments to batch files may be necessary. Please review the
Pkinsert.His documentation file for details of new features and bug
fixes.




































PKinsert Software Documentation Page 3 of 14


Pkinsert Options

Pkinsert options can be entered from the command line or using an
environment variable. Environment variable options will over-ride
those of the configuration file, and command line options will
over-ride those of the environment. Both the environment variable and
command line parameters are limited to 128 characters as dictated by
Dos. Parameters are not case sensitive.

Options

/C Pkinsert 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
/CConfig.cnf

/D Pcboard upload description file name and path. Used to
document test failures. (optional)

ie. /DD:\Pcb\Work\Uldesc.1
/D%3

/L Path and file name for standard log file. (optional)

ie. /LC:\Arc\Node3.Log

/N Network node number. Maximum length of three alpha or
numeric characters. (optional)

ie. /Na1

/S Version of Scan you are currently using. Maximum length of
six alpha or numeric characters. (optional)

ie. /S7.6v80

/CONFIG Load Pkinserts configuration module.

ie. /CPkinsert.Cfg /CONFIG

/TEST Re-test an archive. Affects verbose log file results when a
virus is located. (optional)

ie. /TEST

/UPLOAD Test an upload. Affects verbose log file results when a
virus is located. (optional)

ie. /UPLOAD






PKinsert Software Documentation Page 4 of 14


Putting it all together

As mentioned earlier, these options can be entered on the command line
or via an environment variable. To configure Pkinsert for the first
time, follow this first example.

PKINSERT.EXE /CONFIG /CC:\Pkinsert\Pkinsert.Cfg

SET PKINSERT=/Noo1 /S7.6v80 /CCurrent.Cfg /LC:\Pcb\Pkinslog.1
PKINSERT.EXE /CONFIG /CD:\Diff\Diff.Cnf

This second example makes use of the Pkinsert environment variable.
The command line configuration path (D:\Diff\Diff.Cnf) will over-ride
the environment setting (Current.Cfg). When Pkinserts configuration
module loads, it will also use any other options you have set in the
environment (node number, scan version, log path), replacing those
found in the configuration file.

Configuration Module

The first time you load the configuration module, 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 that using the
previously outlined options, it is possible to use a single
configuration file for multiple users.

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

Network Node Number : 0
Network Delay Re-Try Attempts : 5
Drive Letter for Work Space : C:
Minimum Extract Space (% of Zip) : 250
Test Archives : Y
Corrupt Archive Rename Extension : BAD
Scan Archives for Virii : N
McAfee Associates SCAN Version : 0.0V00
Virused Archive Rename Extension : VIR
Rename Corrupt/Virused Archives : Y
Insert Archive Comment : N
Delete Disclaimer File(s) : N
Add File(s) to Archive : N
Make Extended Pass/Fail Log File : N
Make Standard Result/Error Log : N
Maximum Standard Log File Size : 40
Nested Archive Array Size : 4
Wildcard Array Size (w/in Zip) : 50

00/00/00 00:00:00am


Network Node Number

This value can be blank or one to three alpha numeric characters. It
may be over-ridden by a command line or environment parameters.
Pkinsert will use the node number when creating it's work directory.
Networking or Multitasking environments are detected automatically and
record locking will be used when possible.

Network Delay Re-Try Attempts

When Pkinsert tries to open/read/write/etc a file which is already in
use by another user, it will pause for 5 seconds before trying again.
This value will dictate how many times Pkinsert cycles. If Pkinsert
fails, it will attempt to continue when possible or terminate with an
error level.

Drive Letter For Work Space

Enter the drive where Pkinsert will extract archives for testing and
virus scanning. I would suggest a ram-disk which improves Pkinserts
performance. Pkinsert will not instruct Pkzip and Pkunzip to use this
drive. Refer to the PKzip manual for the `PKTMP' environment variable
or change the options in the `Command Line Options' configuration
menu.

Minimum Extract Space (% of Zip)

Pkinsert will check for available disk space before extracting
archives. This value is not calculated like tax. 250% would be



PKinsert Software Documentation Page 6 of 14


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.

Test Archives

Before handling an archive Pkinsert will call Pkunzip to test the
archive. Nested archives are also tested.

Corrupt Archive Rename Extension

If you choose to have archives renamed (that option is a bit further
down), 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. Most 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.

McAfee Associates SCAN Version

As of this writing the current version of scan is 7.8V82. 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 option may be used to over-ride this value.

Virused Archive Rename Extension

If a virus is detected the archive will be renamed using this
extension (provided renaming is enabled).

Rename Corrupt/Virused Archives

This encompasses more than just file naming. If this option is set to
`Yes' 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 virus or
corrupt archive it will rename the file and continue to the next
archive in the batch. This method is not very selective. Any error
reported by Pkzip/unzip or Scan will lead Pkinsert to rename an
archive. These problems could be caused by a virus, corrupt archive,
insufficient disk space, memory, etc.

On the other hand of you have elected not to rename archives you can
do your own error checking when Pkinsert exits using errorlevel
statements in a batch file. The complete list of Pkinsert error
levels is available in appendix A. This would seem like the ideal
solution except when you are processing on a wildcard as



PKinsert Software Documentation Page 7 of 14


above. When an error is detected, Pkinsert must exit immediately to
report the error, thus skipping the remaining files in the batch.

Insert Archive Comment

Archives created by Pkzip give us the opportunity to insert an archive
comment screen. If this archive is still intact by the time it
reaches you, you should have seen a large `7th Illusion' displayed
when you extracted it. This is an archive comment. If you select to
use this option you should create a Dos Ascii file which contains your
drawing.

Delete Disclaimer File(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.

Make Extended Pass/Fail Log File

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. Pcboard SysOps might recognize this option as creating
Pcbfail.Txt and Pcbpass.Txt. 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.

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.

Make Standard Result/Error Log

This is a standard log file. I would suggest you keep this option set
to `Yes'. It's maintenance free thanks to the following option.

Maximum Standard Log File Size




PKinsert Software Documentation Page 8 of 14


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 Archive 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
those pieces again and do 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. A value of 50 is recommended. Theoretically the
wildcard array could be set for 999, 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.

There is a glitch however. 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. 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\PKINSERT.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

00/00/00 00:00:00pm


Ascii Editor

Ascii editor 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

Path and name of the Standard log file. This value can be over-ridden
by using the `/L' environment or command line option.

Extended Pass Log File
Extended Fail Log File

If the `Extended Pass/Fail Log File' option is enabled, these files
are used to report processing results. PCBoard SysOps will want these
fields set to `Pcbpass.Txt' and `Pcbfail.Txt' respectively.

Virus Comment (Test)
Virus Comment (Upload)

These two 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'
option is used. SysOps could use this file to advise users they
should leave a Comment asap so this archive can be deleted.

Similarly, The contents of Upload are added to the Fail log when the
`/UPLOAD' option 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 one of these files does not exist it will not be used. This way
you could have a comment for one function and not the other.






PKinsert Software Documentation Page 10 of 14


Archive Comment File

This file should contain your archive comment or Ascii drawing.
Enable this option from the Configuration Options menu.

Disclaimer(s) Del List

This list is used when the `Delete Disclaimer(s)' option is active. A
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, list the files you would like inserted into
every archive. Unlike the delete list you should include paths to
each file.









































PKinsert Software Documentation Page 11 of 14



Command Line Parameters Menu

Archive Test : /t
Unzip Archive for Scan : /xn /ojhsr
McAfee Associates SCAN : /a /nobreak /nomem /nopause /sub
Delete Disclaimer(s) : /dk
Add File(s) and Comment : /exzk

00/00/00 00:00:00pm


If you encounter problems with a new command, please drop me a line so
I can adjust Pkinsert accordingly.

The options for Scan have been tested with version 7.6V80+ 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. Delete Disclaimer(s) : /dk /bF:\
Add File(s) and Comment : /exzk /bF:\































PKinsert Software Documentation Page 12 of 14


Using Pkinsert

By now you should have a fairly clear idea of what Pkinsert does.
Using Pkinsert is fairly simple. From the command line or environment
variable make sure Pkinsert knows where to find it's configuration
file, and call Pkinsert passing it file names or wildcards.

The options, file names, etc can be in any order. You could even
enter file names through the environment variable if you wanted.

ie. SET PKINSERT=/N1 /S7.8v82
PKINSERT %1 *.Zip /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 /CPkins.Cnf Test.Zip

Undoubtedly most SysOps will want to test complete directories, which
may exceed the Wildcard Array size. In this case, an advanced Dos
command line should be used.

ie. LOOP.BAT
~~~~~~~~
FOR %%A IN (*.Zip) DO PKINSERT %%A
or
FOR %%A IN (A*.Zip Dbl*.* Abc-?.Zip) DO PKINSERT %%A



























PKinsert Software Documentation Page 13 of 14


Odds 'n Ends

Tagline Environment Variable

This feature has stuck around since Version 3.2 and I still find it
fun to use. At one point I was using a utility to cycle funny
taglines, now I've settled on a standard one. Pkinsert will grab the
value assigned to the Tagline variable and insert is as part of the
archive comment.

ie. SET TAGLINE=7th Illusion Telecommunication Services

Locating Tagline Signatures

Pkinsert taglines can be located within the archive comment by their
unique 4 byte signature, immediately following a Cr/Lf sequence.

In HEX the signature is: FF 08 xx FF [tagline]







































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
200 Wildcard Array Exceeded