home *** CD-ROM | disk | FTP | other *** search
/ Media Share 9 / MEDIASHARE_09.ISO / pcboard / pcbdesc4.zip / PCBDESC.DOC < prev    next >
Text File  |  1992-12-01  |  9KB  |  191 lines
  1.                              PCBDESC Version 4.00
  2.                Automatic Upload Description Insertion for PCBoard
  3.  
  4.     Copyright (c) 1992 by Clark Development Co., Inc.  All Rights Reserved
  5.  
  6.  
  7.         PCBDESC.EXE checks uploaded files for FILE_ID.DIZ (Description In
  8. Zipfile) files provided by the program author.  If the uploaded file
  9. contains a description file, it will replace the user supplied description
  10. with the one provided in the file.
  11.  
  12.         Also, PCBDESC can optionally append a line to the description
  13. showing the number of files and the dates of both the oldest and the newest
  14. files in the zipfile.
  15.  
  16. INSTALLING PCBDESC:
  17.         PCBDESC *REQUIRES* PCBoard version 14.5a or higher BBS software to
  18. operate.  Earlier versions of PCBoard, or other BBS software packages are NOT
  19. compatible with PCBDESC.
  20.  
  21.         PCBDESC is used inside of the PCBTEST.BAT file, which is run to test
  22. each upload to the system.  Place the PCBDESC.EXE file in your default \PCB
  23. directory, and insert the following line into PCBTEST.BAT:
  24.  
  25.                   IF %2==UPLOAD PCBDESC %1 %3
  26.  
  27.         And it's ready to go.  There is only one option; if you would like
  28. to have an additional line in the description showing the date of the oldest
  29. and newest files in the ZIP, then use this command instead:
  30.  
  31.                   IF %2==UPLOAD PCBDESC /D %1 %3
  32.  
  33.         The word "UPLOAD" in the above example is case sensitive.  Make sure
  34. you type it in uppercase letters.  Also make sure that you have a copy of
  35. PKUNZIP.EXE available in your default \PCB directory, or in a subdirectory
  36. referenced by your PATH.
  37.  
  38.         PCBDESC can be the first thing in your PCBTEST.BAT file; it will only
  39. operate on ZIP and self-extracting EXE format ZIP files.
  40.  
  41.         Beginning with the 2.10 release PCBDESC will watch for DOS reserved
  42. words such as CON, AUX, PRN, CLOCK$, COMx, LPTx, and, if found in the ZIP file,
  43. will RENAME the file to filename.ZIQ (adding one to the last letter of the
  44. filename) and it will then leave a one line addition in the UPDESC file
  45. indicating the reason for the rejecting.  Finally, it will exit to DOS with an
  46. errorlevel of 5 to indicate a problem with the file so that further testing
  47. of the file can be AVOIDED saving the system from a lockup that could occur if
  48. you have a testing program that does not watch for DOS reserved words.  NOTE:
  49. none of the other functions of PCBDESC will be performed if a reserved word is
  50. found.  You should write your test batch files so that no other functions are
  51. performed by any other programs either.
  52.  
  53.         It is recommended that immediately after the execution of PCBDESC you
  54. insert a line in the PCBTEST.BAT file that reads:
  55.  
  56.                   IF ERRORLEVEL == 5 GOTO END
  57.  
  58.         Then have a line at the bottom of the PCBTEST.BAT file that has nothing
  59. but ":END" on it.  This will allow PCBDESC's errorlevel 5 to signal that the
  60. rest of the testing process should be skipped.
  61.  
  62. ERRORLEVEL RETURNS:
  63.         PCBDESC will return errorlevels to your batch file to indicate what
  64. it has done.  These errorlevels can then be tested and used for your own
  65. purposes.  Return values are as follows:
  66.  
  67.         0     =    No processing performed
  68.         1     =    File was not a ZIP/EXE file or ZIP contents were damaged
  69.         2     =    Description was updated (due to FILE_ID.DIZ or DESC.SDI)
  70.         3     =    Description was updated (no FILE_ID but dates were added)
  71.         4     =    Found description file but unable to process
  72.         5     =    Found a DOS reserved word in the ZIP file, file renamed,
  73.                    description modified, no further actions have been taken
  74.                    nor should be taken by other programs.
  75.  
  76.  
  77. THE DESCRIPTION FILE:
  78.         PCBDESC will accept descriptions contained in FILE_ID.DIZ files
  79. found in the ZIP being tested.  The FILE_ID.DIZ file is an ASCII text file,
  80. and can contain up to 10 lines of 45 characters each.  The first line of
  81. this file is the program name and version, and the following lines describe
  82. the function of the program.
  83.  
  84.         It is recommended that formatting codes (such as ASCII line drawing
  85. characters) NOT be used.  However, beginning with version 4.00 PCBDescribe
  86. will now recognize some forms of 'formatting' by detecting these high ASCII
  87. characters and will attempt to protect formatted lines from being word
  88. wrapped.
  89.  
  90. -----------------------------------------------------------------------------
  91.         ATTENTION!  The FILE_ID.DIZ file is intended for the program
  92. author's use in providing a coherent description of his program.  In this
  93. way, the author and the sysop can be assured that the program will be
  94. properly described when uploaded to a BBS.  DO NOT use this file for BBS
  95. advertising - such use is in violation of the copyright associated with the
  96. FILE_ID.DIZ file.
  97. -----------------------------------------------------------------------------
  98.  
  99.         PCBDESC will also detect and use descriptions contained in DESC.SDI
  100. files if they are present.  No other description file formats are supported.
  101.  
  102.  
  103. REVISION HISTORY:
  104.         Version 1.00 - Original Release
  105.  
  106.         Version 1.10 - Maintainence Release
  107.         -----------------------------------
  108.         If a stray description file was left in the default directory,
  109.         PCBDESC could stick on it.  Fixed.
  110.  
  111.         And to prevent problems for those who insist on using PCBDESC with
  112.         the wrong BBS software:
  113.         Added testing for improper version of PCBoard software.
  114.         Added testing for proper filespecs on command line.
  115.  
  116.         Updated documentation to include the exit codes returned by PCBDESC.
  117.  
  118.         Version 1.11 - Bug Fix Release
  119.         ------------------------------
  120.  
  121.         Error 53 at 4626 caused by incorrect call to PKUNZIP.  Sorry about
  122.         that, folks.  Fixed.
  123.  
  124.         Version 2.00 - Rewrite in C
  125.         ---------------------------
  126.         Made the program both smaller and faster
  127.  
  128.         Fixed a problem with running on Alloy Slave Cards
  129.  
  130.         Changed date line from "Latest File Date in ZIP: MM/DD/YY" to "Files: #
  131.         Oldest: MM/DD/YY  Newest: MM/DD/YY"
  132.  
  133.         Added ERRORLEVEL 2 if a description file was found and processed
  134.  
  135.         PLEASE NOTE:
  136.         ------------
  137.         Previous recommended usage was:   PCBDESC [/D] %1 %3
  138.         Current recommend usage is now:   IF %2 == UPLOAD PCBDESC [/D] %1 %3
  139.  
  140.         The change avoids running PCBDESC if PCBoard's "TEST" command is being
  141.         used instead of executing an upload test procedure.
  142.  
  143.  
  144.         Version 2.01 - Minor fix
  145.         ------------------------
  146.         Removed the FILE_ID.DIZ or DESC.SDI files after reading them.  Not
  147.         deleting them caused no harm, they could not be re-used, but the
  148.         change was made just to make the running more transparent.
  149.  
  150.  
  151.         Version 2.02 - Minor change
  152.         ---------------------------
  153.         Old errorlevels:
  154.         2     =    Description was updated (file_id or dates added to desc)
  155.         3     =    Found description file but unable to process
  156.  
  157.         New errorlevels:
  158.         2     =    Description was updated (due to FILE_ID.DIZ or DESC.SDI)
  159.         3     =    Description was updated (no FILE_ID but dates were added)
  160.         4     =    Found description file but unable to process
  161.  
  162.         Version 2.03 - Minor fix
  163.         ------------------------
  164.         Errorlevel 3 was being returned to indicate file dates were added to
  165.         the description even if you did not use the /D parameter to insert
  166.         the file dates.  Fixed.
  167.  
  168.         Version 2.04 - Minor fix
  169.         ------------------------
  170.         FILE_ID.DIZ files are only supposed to be up to 10 lines in length.  A
  171.         34 line file managed to lock PCBDescribe up.  Fixed.
  172.  
  173.         Version 3.00 - Added new capability
  174.         -----------------------------------
  175.         Added the ability to detect and REJECT a zip that has a DOS reserved
  176.         word in it.
  177.  
  178.         Version 3.01 - Minor fix
  179.         ------------------------
  180.         PCBDescribe could crash on some OS/2 installations.  The same fix
  181.         that OS2PATCH.ZIP provided for the PCB145.EXE file has been applied
  182.         to the PCBDESC.EXE file.
  183.  
  184.         Version 4.00 - Added new capability
  185.         -----------------------------------
  186.         Added the following abilities:  1) Removal of PCBoard @-macros, 2)
  187.         Removal of control codes, 3) Awareness of certain forms of 'formatting'
  188.         which allows the formatting to remain intact.  Also, improved the
  189.         ability to maximize spacing (when word wrapping) to reduce the number
  190.         of lines in the output.
  191.