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 (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:

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

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:

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.

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

PCBDescribe will accept descriptions contained in FILEID.DIZ files found in the archive being tested. The FILEID.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!

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

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

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.

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.

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:

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.

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:

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.

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: