====== File Testing & Viewing Utilities ======
The utilities described in this section are used primarily in your 
PCBTEST.BAT and PCBVIEW.BAT files.  Each section describes the utilities in 
detail.

===== PCBDescribe =====
PCBDescribe (PCBDESC.EXE) checks uploaded files for FILE_ID.DIZ files 
provided by the program author.  If the uploaded file contains a description 
file, it will replace the description that the user supplied with the one 
provided in the file.

PCBDescribe is compatible with the following archive formats and requires the 
specified program to uncompress the description files when found:

^File Extension^Requires^
|**ARC**|PKXARC|
|**ARJ**|ARJ|
|**LZH**|LHA|
|**PAK**|PAK|
|**ZIP**|PKUNZIP|

==== Installing PCBDescribe ====
PCBDescribe is used inside of the PCBTEST.BAT file, which is run to test each 
upload to the system.  Place the PCBDESC.EXE file in your default \PCB 
directory and insert the following line toward the top of your PCBTEST.BAT:

    IF %2==UPLOAD PCBDESC %1 %3

There is only one option; if you would like to have an additional line in the 
description showing the date of the oldest and newest files in the archive, 
use this command instead:

    IF %2==UPLOAD PCBDESC /D %1 %3

The word UPLOAD in the above example is case sensitive.  Make sure you type 
it in uppercase letters.  Also, make sure that you have a copy each of the 
required unarchive programs (PKUNZIP, ARJ, LHA, PAK, PKXARC) according to the 
types of files you expect to receive.  These unarchive programs should be 
placed either in your default \PCB directory, or in a subdirectory referenced 
by your PATH.

PCBDescribe can be the first thing in your PCBTEST.BAT file; it will only 
operate on ZIP, ARJ, LZH, PAK and ARC files (as well as self-extracting 
versions of those files).

==== Protecting Your System From DOS Reserved Words ====
PCBDescribe will watch for harmful DOS reserved words such as CON, AUX, PRN, 
CLOCK$, COMx, LPTx, and, if found in the archive, will rename the file by 
incrementing the last letter of the filename by one.  The following 
illustrates what the filenames will be renamed to:

|*.ARC|->|*.ARD|
|*.ARJ|->|*.ARK|
|*.EXE|->|*.EXF|
|*.LHA|->|*.LHB|
|*.PAK|->|*.PAL|
|*.ZIP|->|*.ZIQ|

Once the filename has been renamed, a line will be added to the description 
of the file indicating the reason for the rejecting. Finally, PCBDescribe 
will exit to DOS with an errorlevel of 5 to indicate a problem with the file 
so further testing of the file can be avoided saving the system from a lockup 
that could occur if you have a testing program which does not watch for DOS 
reserved words.

It is recommended that immediately after the execution of PCBDescribe, you 
insert a line in the PCBTEST.BAT file which reads:

    IF ERRORLEVEL == 5 GOTO END

At the bottom of your PCBTEST.BAT file have a line which has nothing but :END 
on it.  This will allow PCBDescribe's errorlevel 5 to signal that the rest of 
the testing process should be skipped.  For more information on testing 
errorlevels in batch files, refer to your DOS manual.

==== Errorlevels Returned ====
PCBDescribe will return errorlevels to your batch file to indicate what it 
has done.  These errorlevels can be tested and used for your own purposes.  
The following values are returned:

0**|No processing performed|
1**|File was not a supported archive or contents were damaged|
2**|Description was updated (found a FILE_ID.DIZ or DESC.SDI)|
3**|Description was updated (no description file found but the line showing the newest and oldest dates was added to the description).|
4**|Found description file but unable to process.  This could occur if the program to uncompress the archive is not found.|
5**|Found a DOS reserved word, renamed the file, modified the description.  No further actions have been taken nor should be taken by other programs.|

==== The Description File ====
PCBDescribe will accept descriptions contained in FILE_ID.DIZ files found in 
the archive being tested.  The FILE_ID.DIZ file is an ASCII text file, and 
can contain up to 10 lines of 45 characters each.  The first line of this 
file is the program name and version, and the following lines describe the 
function of the program.  It is recommended that formatting codes (such as 
ASCII line drawing characters) NOT be used.

PCBDescribe will also detect and use descriptions contained in DESC.SDI files 
if they are present.  No other description file formats are supported.

**ATTENTION!** The FILE_ID.DIZ file format is intended for the program author's 
use in providing a coherent description of the program.  In this way, the 
author and the SysOp can be assured that the program will be properly 
described when uploaded to a BBS.  DO NOT use this file for BBS advertising!

===== TESTFILE =====
Used to determine the extension of a filename and exit with an errorlevel.

=== Syntax ===

    TESTFILE [filename] [ext] [ext] ... [ext]

==== Command Line Parameters ====

|**[filename]**|The filename you want to check to determine the extension. If you are using TESTFILE in your PCBVIEW or PCBTEST batch files, specify %1 for the filename.|
|**[ext]**|These parameters reference the filename extensions you want to check for.  If the filename you specify matches one of the extensions you enter as a parameter, PCBoard will exit with a unique errorlevel.  By testing the errorlevel returned, you can determine the extension of the filename.|

==== Description ====
When you are passing a filename as a parameter to a batch file, quite often 
it is useful to know the extension of the file. Once you know the extension 
of the file, you can perform special processing.  For example you may want to 
treat files that end in .TXT different from those that end with .ZIP or .ARJ.

To determine the extension of the file, you must specify the filename to test 
and the extension that you want to test on the command line when you execute 
TESTFILE.  The errorlevel that is returned will determine the extension of 
the file.

==== Errorlevels Returned ====
The errorlevel returned by TESTFILE is based on the placement of the 
extension on the command line.  The following example illustrates:

    TESTFILE FILENAME.TXT ZIP ARJ LHA TXT

If you type this line at a DOS command prompt, TESTFILE will return an 
errorlevel of 4.  Why 4?  The reason that errorlevel 4 is returned is that it 
is the fourth extension specified on the command line.

What if the extension of the file is not specified on the command line as 
shown in the following example?

    TESTFILE CONFIG.SYS ZIP ARJ LHA TXT

In this situation, TESTFILE will return an errorlevel of 98. You will not 
know the file extension, but you will know that it is not one you included on 
the command line.

=== Example ===
Assuming you are using the following batch file named TESTIT.BAT

    @echo off
    testfile %1 zip arj gif
    if errorlevel==98 goto notknown
    if errorlevel==3 echo GIF file specified.
    if errorlevel==2 echo ARJ file specified.
    if errorlevel==1 echo ZIP file specified.
    goto end
    
    :notknown
    echo Could not determine extension.
    
    :end

the following table will show the response for the value you pass as %1 to 
the batch file:

^%1 Parameter^Response From Batch File^
|**TEXTEDIT.ZIP**|ZIP file specified.|
|**TEXTEDIT.EXE**|Could not determine extension.|
|**WOODGRAN.ARJ**|ARJ file specified.|
|**README.TXT**|Could not determine extension.|
|**SCENE.GIF**|GIF file specified.|

===== VIEWZIP =====
This utility is designed to be used in PCBVIEW.BAT.  The ZIP filename you 
specify as the first parameter will be examined. If the file is a valid ZIP, 
a list of the files contained in the archive will be written to PCBVIEW.TXT.  
When PCBoard returns from PCBVIEW.BAT, it checks to see if PCBVIEW.TXT 
exists.  If it does, the contents of the file are displayed to the caller. 
Using this method, your callers will be able to see a list of files in an 
archive.

=== Example ===
In the PCBVIEW.BAT that is supplied with your copy of PCBoard, you will see 
the following line:

    viewzip %1

Upon returning from PCBVIEW, a report resembling the following will be 
displayed:

^Filename^Length^Method^SF^Size Now^Date^Time^
|INSTALL.EXE|40517|DeflateX|3%|39219|15 May 92|09:29|
|PCB145.EXE|134833|DeflateX|0%|133740|09 Sep 92|11:28|
|PCBDISK1.EXE|43774|DeflateX|0%|43633|15 May 92|10:05|
|FILE_ID.DIZ|245|DeflateX|13%|213|08 Sep 92|12:07|
|**Total:** 4|**219369**| |**1%**|**216805**| | |

===== VIEWARCH =====
This utility is designed to be used in PCBVIEW.BAT.  The ARC filename you 
specify as the first parameter will be examined. If the file is a valid ARC 
file, a list of the files contained in the archive will be written to 
PCBVIEW.TXT.  When PCBoard returns from PCBVIEW.BAT, it checks to see if 
PCBVIEW.TXT exists.  If it does, the contents of the file are displayed to 
the caller.  Using this method, your callers will be able to see a list of 
files in an archive.

=== Example ===
In the PCBVIEW.BAT that is supplied with your copy of PCBoard, you will see 
the following line:

    viewarch %1

Upon returning from running PCBVIEW on a file with an ARC extension, a report 
resembling the following will be put in PCBVIEW.TXT and displayed by PCBoard:

^Filename^Length^Method^SF^Size Now^Date^Time^
|PC-PR.EXE|69,776|Squashed|28%|49,824|14 Jan 91|10:40|
|**Total:** 1|**69,776**| |**28%**|**49,824**| | |