P K I N S E R T
Version 6.2

Copyright 7th Illusion, 1990-1991
All Rights Reserved
Released August 10, 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

Node 2 (514)338-1680
GVC Super Modem 2400 Bps













PKinsert Version 6.2 Documentation Page 1 of 20


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 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. I'm not including the source code
since some morons out there would re-release it as their own. I'll be
more than happy to work in any features you wish, just drop me a line.
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. On the other hand this
software was years in development and cost a bundle in pizza. I would
appreciate any support you can afford. Frankly, I haven't seen much
reaction to Pkinsert version 5 which I thought was fairly decent.
Mail any contribution to the address on the front cover.

If you've authored SysOp or Telecommunications oriented software and
are using Pkinsert, I would appreciate if you uploaded me a copy. I
would like to believe the Freeware concept isn't dead. Please don't
send me shareware which isn't fully functional or registered.


J.S. Morisset
aka Storm widow





























PKinsert Version 6.2 Documentation Page 2 of 20


General Requirements

You will need the following software to run Pkinsert.

Pkzip, Pkunzip from PKWare Inc.
Scan from 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

This version is a `drop-in' upgrade for systems already running V6.0
and up. To upgrade from an earlier version, you'll have to start from
scratch. Read the history section at the end of this document for
details of new features and bug fixes.








































PKinsert Version 6.2 Documentation Page 3 of 20


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 are limited to 128 characters as dedicated by Dos.

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.
(optional)

ie. /Dd:\pcb\work\uldesc.1

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

ie. /Ld:\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 Pkinsert will load it's configuration module.

ie. /Cpkinsert.cfg /CONFIG

/TEST Pkinsert will be testing a bulletin board archive.
(optional)

ie. /TEST

/UPLOAD Pkinsert will be verifying an upload.
(optional)

ie. /UPLOAD





PKinsert Version 6.2 Documentation Page 4 of 20


Putting it all together

As mentioned before, these options can be entered on the command line
or via an environment variable. To configure Pkinsert for the first
time, follow the 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

The second example shows the use of the Pkinsert environment variable.
The command line configuration path (d:\diff\diff.cnf) will over-ride
the one set in the environment (current.cfg). When the configuration
module loads, it will use the options you have set in the environment
(node number, scan version, log path), replacing those found in the
configuration file.








































PKinsert Version 6.2 Documentation Page 5 of 20


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 in Dos. 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 Version 6.2 Documentation Page 6 of 20



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 : 2
Wildcard Array Size (w/in Zip) : 80

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-written by a command line or environment option. 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 Version 6.2 Documentation Page 7 of 20


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 the archive Pkinsert will call on 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.6V80'. 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 Version 6.2 Documentation Page 8 of 20


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. If present, these files are deleted
before a new one is created. Pcboard SysOps might recognize this
option as creating Pcbfail.Txt and Pcbpass.Txt. These files could
then be displayed to the user. The names for these files can be
entered later on.

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

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



PKinsert Version 6.2 Documentation Page 9 of 20


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. 2 or 3 is probably
best. You don't see nesting past two 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, machine and disk access speeds.

Zip Wildcard Array Size

This value determines the maximum number of archives a nested archive
may contain. A value of 80 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 Version 6.2 Documentation Page 10 of 20



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 path and name. 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

If the `Extended Pass/Fail Log File' option is enabled, this file will
be used if no errors where encountered. PCBoard SysOps will want this
field set to `Pcbpass.Txt'.

Extended Fail Log File

Same as above, this file will be created if Pkinsert exits with an
error or encounters a corrupt/virused archive. PCBoard SysOps will
want this field set to `Pcbfail.Txt'.

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 first, Test, will be added to the Fail log when the `/TEST' option
is used. SysOps could use this file as a comment advising users to
leave a message to the SysOp asap.

The second, Upload, will be added to the Fail log when the `/UPLOAD'
option is used. This second text file could contain the same message
as the first, but also advise the user that his system might be
contaminated and to take appropriate steps before uploading again.




PKinsert Version 6.2 Documentation Page 11 of 20


If neither of these files exist they will not be used.

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 Version 6.2 Documentation Page 12 of 20



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








!!! WARNING !!!




This section wouldn't be complete without a warning. Watch where you
put your fingers here. Don't fumble with these values unless you're
well acquainted with Pkzip/unzip and Scan. 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.


























PKinsert Version 6.2 Documentation Page 13 of 20


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.6V80
PKINSERT %1 *.Zip /Cd:\pkinsert\pkinsert.cfg *.Exe Abc-?.New

SET PKINSERT=/Cc:\pkinsert\system.cfg
PKINSERT *.Zip *.Exe Abc.Bak

SET PKINSERT=/N1 /S00v80 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. FOR %A IN (*.Zip) DO PKINSERT %A
FOR %A IN (A*.Zip;Dbl*.*;Abc-?.Zip) DO PKINSERT %A

`%%A' should be used if this command is to reside in a batch file.




























PKinsert Version 6.2 Documentation Page 14 of 20


PCBoard Installation

My system runs on Pcboard therefore Pkinsert is strongly tailored for
this software. Bellow you'll find information to help you set up
Pkinsert quickly under Pcboard.

You will only need one configuration file. Using environment
variables you can control unique configurations for every node.


Options Menu

Test Archives : Y
Rename Corrupt/Virused Archives : N
Make Extended Pass/Fail Log File : Y

00/00/00 00:00:00pm


File Location Menu

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

00/00/00 00:00:00pm

Don't include paths for the extended pass and fail logs. They'll be
created in the directory Pkinsert is called from.

PCBoard Version 14.5

AUTOEXEC.BAT
------------
@ECHO OFF
SET PKTMP=H:
SET TAGLINE=7th Illusion Telecommunication Services
SET PKINSERT=/S7.6V80 /Ndos

ie. PKTMP Used to tell Pkzip/unzip to create work files on
drive H:
TAGLINE Tagline added to the archive comment by Pkinsert.
/S7.5V80 Version of Scan currently using.
/Ndos Default node number.

BOARD.BAT (Node 1)
---------
@ECHO OFF
SET NODE=1

ie. Node number for this partition/work station.





PKinsert Version 6.2 Documentation Page 15 of 20


PCBTEST.BAT
-----------
@ECHO OFF
STRIPAV /R %1
D:\PKINSERT\PKINSERT /CD:\PKINSERT\NODE.CFG /D:\PKINSERT\NODE...
...%NODE%.LOG /N%NODE% %1 /%2

ie. Before calling Pkinsert I strip archives of any AV info.

Pkinsert will use the communal configuration file and
over-ride the values for the node number and log file. I can
use the `NODE' environment variable to avoid tailoring my
batch files for every node.

%1 Contains the path and file name of the archive.

%2 Will be assigned a value of `UPLOAD' if PCBoard is
shelling to test an upload. Using the Test command will
leave this value blank. Pkinsert will ignore any
forward slash or option which is not assigned a value.

PCBoard Version 14.5a

AUTOEXEC.BAT
------------
@ECHO OFF
SET PKTMP=H:
SET TAGLINE=7th Illusion Telecommunication Services
SET SCAN=7.6V80
SET PKINSERT=/S%SCAN% /Ndos

BOARD.BAT (Node 1)
---------
@ECHO OFF
SET NODE=1

PCBTEST.BAT
-----------
@ECHO OFF
STRIPAV /R %1
SET PKINSERT=/S%SCAN% /N%NODE% /LD:\PKINSERT\NODE%NODE%.LOG
D:\PKINSERT\PKINSERT /CD:\PKINSERT\NODE.CFG %1 /%2 /D%3

Pcboard V14.5a has added a value of `TEST' to %2 when shelling for a
systems archive test. %3 contains the name and path of the archive
description file (for uploads only).

I've had to split the Pkinsert options between the command line and
environment variable since their combined length usually exceeds 128
characters.







PKinsert Version 6.2 Documentation Page 16 of 20


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

Tagline Signature

Starting with V6.2, Pkinsert taglines can be located by their unique 4
byte signature immediately following a Cr/Lf sequence.

In HEX the signature is: FF 08 xx FF







































PKinsert Version 6.2 Documentation Page 17 of 20


Pkinsert History in Reverse Order

Version 6.2
Released August 10, 1991

Reason for Upgrade
~~~~~~~~~~~~~~~~~~
Matthew Cooley reported an incompatibility problem with the new
PCBoard V14.5a (Beta) features.

New Features
~~~~~~~~~~~~
/D Command line option. Path to Pcb upload description file.
/TEST Command line option.
Zero byte file errorlevel code 112.
Standard tagline signature developed. In HEX: FF 08 xx FF .

Bugs Squashed
~~~~~~~~~~~~~
If a virus was found and rename was disabled, Pkinsert would not clean
it's work directories.

Version 6.1
Released August 2, 1991

Split code from 3 to 5 modules.

Pkinsert will display any size status file. V6.0 was limited to 6k.

If Pass/Fail extended logs exist, Pkinsert will delete them before
creating a new one. This saves 2 lines in the Pcbtest.Bat file.

Process error codes from Add and Delete functions. They are the ones
which can report if archive is read-only.

Clean-up work directories before Add and Delete functions. This gives
Pkzip a bit more room to create it's work file.

Check files for unique 4 byte Zip signature. This is more reliable
than using file name extensions. No matter what name an archive
carries, Pkinsert will test it.

New Errorlevel code 111 for illegal archive compression used.

Pkinsert code stands at 2,461 lines in five Quick Basic V4.5 modules
and 108,814 bytes compiled.

Version 6.0
Released July 25, 1991

There's been so many features added, I can't remember them all. The
following where the major ones.

Total revamp of the configuration module.



PKinsert Version 6.2 Documentation Page 18 of 20


Pkinsert will process `nested' archives.
Verbose log files based on results.
Configurable disk swapping.
Exit with Dos error levels.
etc.

The current code stands at 2,260 lines in Quick Basic V4.5.

Special thanks to Steve Greenspon, aka Doodle Bug, for his
suggestions, testing, and listening to me rant and rave about the
latest sub or function. (grin)

Version 5.1
Released April 27, 1991

Fixed an incompatibility problem with COUNTRY.SYS. Thanks to Yan Wolf
from Top 50 BBS in Paris, France for his help in tracking down this
problem.

Version 5.0
Released March 13, 1991

10k Smaller and much faster! New features include ...

- Random work directory names.
- 0 byte files are no longer processed.
- Complete activity logging to disk.
- All options can be toggled on or off.
- Configuration path may be entered by environment variable or command
line.
- Various configuration file names may be used.
- PKinsert will change drives and directories as it handles archives
for shorter DOS commands.
- PKinsert may add the virus scanner version to the archive comment.
- Compatible with Digital Research DOS 5.0 (actually, this is what
prompted this new release).

Version 4.02

Fixed the colours in PKinserts logo. Also fixed a variable I had
forgotten about. PKinsert will now process numerous file specs again!
. PKTMP environment variable is now external.

Version 4.00

PKinsert now works with DOS4! 😉 Corrupted archives are caught and
renamed. Virus checking is also possible using McAfee Associates'
SCAN.EXE program. Work drive can be selected for quicker processing
on a RAM Drive. Configuration is now internal. No more messin'
around with a word processor. And last but not least PKinsert goes
COLOUR!
Version 3.20

Added support for DOSv4.0. Uses prodoor's TAGLINE environment



PKinsert Version 6.2 Documentation Page 19 of 20


variable. Will now skip the archive test if set to [N]o.

Version 3.1

Got rid of a few bugs. The timer feature in v3.0 wasn't working and I
got rid of it. Also shortened much of PKinsert's output. Error
trapping is also much improved! Let's hope it won't need it.


















































PKinsert Version 6.2 Documentation Page 20 of 20


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
255 Error From The Pits of Hell!