home *** CD-ROM | disk | FTP | other *** search
/ DP Tool Club 12 / CD_ASCQ_12_0294.iso / news / 2293 / qcp.doc < prev    next >
Text File  |  1994-02-01  |  43KB  |  1,098 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.                 QCP  --  QEdit(R) Compiler Program
  10.  
  11.  
  12.             A program to ease invocation of compilers
  13.          and other software tools from a function key in 
  14.                         QEdit(R) version 2
  15.  
  16.                      ABRIDGED DOCUMENTATION
  17.  
  18.  
  19.                        Author: Tim Farley
  20.                          Revision: 2.08
  21.                     Date:  November 17th, 1989
  22.  
  23.             QCP is Copyright (C) 1989, by Tim Farley
  24.  
  25.  
  26.          QEdit(R) and QMac are Copyright (C) 1985-1993 by
  27.                        SemWare Corporation
  28.                   All Rights Reserved Worldwide
  29.  
  30.  
  31. DESCRIPTION
  32. -----------
  33. QCP is a program to run compilers & other utilities from within
  34. QEdit 2.08+.  You hit a function key in QEdit, QCP decides which
  35. program to run based on the name of the file you are editing,
  36. runs it, and then "reads" the error messages from the compiler to
  37. tell QEdit how to jump to the errors in your source code.
  38.  
  39. QCP can interface in the same manner to any external utility that
  40. generates redirectable output containing "line numbers" that
  41. refer to your original source file.
  42.  
  43. QCP works in conjunction with QMAC.EXE, also found on your
  44. registered diskette.
  45.  
  46.  
  47. QCP 2.08 Documentation                                    Page 2
  48.  
  49.  
  50. TABLE OF CONTENTS
  51. -----------------
  52. Description ................................................   1
  53. Table Of Contents ..........................................   2
  54. File List ..................................................   3
  55. Quick Installation .........................................   3
  56. Quick Start ................................................   4
  57. Running QCP ................................................   5
  58. Command Line Switches and QCP ..............................   6
  59.      /R -- Read Config Info from Disk ......................   7
  60.      /C -- Configure QCP.EXE's Defaults ....................   7
  61.      /S -- Show QCP.EXE's Current Defaults .................   7
  62.      /W -- Write New Error Output File .....................   7
  63.      /O -- Output File Name ................................   7
  64.      /M -- Macro File Name .................................   8
  65.      file -- File to Compile ...............................   8
  66.      options -- Compiler Options ...........................   8
  67. QEdit Macro Key Customization ..............................   9
  68. Compiler Compatibility .....................................   9
  69.      Custom Compiler Configurations ........................   9
  70.      Compatible Compilers ..................................  10
  71.      I/O Redirection Problems, Tips ........................  12
  72.           Microsoft Fortran 3.x ............................  12
  73.           Microsoft MASM 4.0 ...............................  13
  74.           DBFAST 1.03 ......................................  13
  75.           Norton Guides Database Compiler 1.04 .............  14
  76.           Microsoft Quick Pascal 1.00 ......................  14
  77.      Incompatible Compilers ................................  15
  78. Configuration Via QCP.DAT ..................................  15
  79.      Substitution Strings ..................................  16
  80.      QCP Configuration Commands ............................  16
  81. Summary of Command Line Switches ...........................  17
  82. Summary of Substitution Strings ............................  17
  83. Summary of Configuration Commands ..........................  18
  84. Error Messages .............................................  18
  85. Informative & Warning Messages .............................  20
  86. Acknowledgements & Contacts ................................  21
  87. Revision History ...........................................  22
  88.  
  89.  
  90. QCP 2.08 Documentation                                    Page 3
  91.  
  92.  
  93. FILE LIST
  94. ---------
  95. The following files constitute QCP:
  96.  
  97.      QCP.DOC        - this documentation file
  98.      QCP.EXE        - the QCP program
  99.      QCP.DAT        - the configuration data file
  100.      QCP.TXT        - partial QEdit keyboard file containing
  101.                       sample macros for use with QCP
  102.  
  103. NOTE:  This version of the documentation is slightly abridged to 
  104. fit on the diskette with QEdit.  You can download a longer, more 
  105. detailed documentation file from SemWare's BBS and many other BBS 
  106. systems around the country.
  107.  
  108.  
  109. LICENSE
  110. -------
  111. QCP is part of your QEdit package, and is covered by the QEdit 
  112. license agreement.
  113.  
  114.  
  115.  
  116. QUICK INSTALLATION
  117. ------------------
  118. STEP 0
  119. ------
  120. Set aside your original copies of all the QCP files in a safe 
  121. place.  Always work on a copy, not the original!
  122.  
  123.  
  124. STEP 1
  125. ------
  126. PUT QCP.EXE AND QCP.DAT IN A CONVENIENT DIRECTORY ON YOUR DISK.  
  127.  
  128. QCP.EXE should exist somewhere along your current PATH statement 
  129. so that it can be executed easily.   QCP.DAT can exist in one of 
  130. three places: (1) the current directory,  (2) the same directory 
  131. that QCP.EXE is in, or (3) somewhere along your current PATH 
  132. statement.  
  133.  
  134. If you are going to use the macro creation feature of QCP, and 
  135. this is highly recommended, then make sure QMAC.EXE is accessible 
  136. along your PATH as well.
  137.  
  138. We recommend keeping QCP.EXE (and QCP.DAT, if you use the /R 
  139. option) as well as QMAC.EXE on a RAMdisk, and listing that 
  140. RAMdisk drive letter first in your PATH= environment variable.  
  141. This allows QCP to operate very rapidly, even on relatively 
  142. "slow" systems.
  143.  
  144.  
  145. QCP 2.08 Documentation                                    Page 4
  146.  
  147.  
  148.  
  149.  
  150. STEP 2
  151. ------
  152. EDIT QCP.DAT TO SUIT THE FILE EXTENSION(S) YOU USE AND THE 
  153. COMPILER OR UTILITY PROGRAM THAT SHOULD BE INVOKED FOR EACH ONE.  
  154.  
  155. There are comments in the supplied QCP.DAT to help you 
  156. remember the syntax of commands, as well as several sample 
  157. command lines for popular compilers. 
  158.  
  159. It is assumed that the command line you specify for your compiler 
  160. will redirect the error messages from the compiler to a file, by 
  161. default called ERRORS.LST.  This file can then be loaded into 
  162. QEdit for viewing, but more importantly it is read by QCP in 
  163. order to construct QEdit macros that will move your cursor to 
  164. each error in your file.  So, typically each command line you use 
  165. in QCP.DAT should end with ">$O", which causes the output to be 
  166. redirected to the error file.  
  167.  
  168. If this is the only configuration you are going to use, you will 
  169. probably want to "install" these options into your copy of 
  170. QCP.EXE permanently by typing "QCP /C" at a DOS prompt.   
  171.  
  172.  
  173. STEP 3
  174. ------
  175. ADD THE MACRO DEFINITION(S) FROM QCP.TXT INTO YOUR
  176. QCONFIG.DAT, AND USE QCONFIG TO INSTALL THESE KEY(S) INTO YOUR 
  177. COPY OF QEDIT.
  178.  
  179. Note that the default macro is set up to always create and read 
  180. the ERRORS.LST and ERRORS.MAC file in the CURRENT directory.  If 
  181. you have a RAM disk or other fast disk drive, you will probably 
  182. want to edit the macro definition to put these files there.
  183.  
  184. Within the macro, the /O and /M command line switches for QCP are 
  185. used to make sure the filenames match.  You may want to configure 
  186. these filenames into QCP permanently, and remove the references 
  187. to /O and /M in the macro definition.  
  188.  
  189.  
  190. QUICK START
  191. -----------
  192. Edit a file for which you created a definition in QCP.DAT.  I.e., 
  193. if you defined something for .C, then edit TEMP.C.  Put in a 
  194. deliberate syntax error, something that you know the compiler 
  195. will generate an error message for.  Save the file to disk.
  196.  
  197.  
  198. QCP 2.08 Documentation                                    Page 5
  199.  
  200.  
  201. Now, hit the function key you assigned in QCONFIG.DAT.  QEdit 
  202. will shell out, run QCP, which will run your compiler.  Errors 
  203. will be redirected to ERRORS.LST, and macros created.  When you 
  204. return to QEdit, your file will be in the top window, and your 
  205. error messages will be in the bottom.
  206.  
  207. If your chosen compiler generates compatible error messages (see 
  208. Compiler Compatibility, below), you will be able to hit Alt-1 
  209. through Alt-0 to move to each of the errors your compiler issued, 
  210. both in the source and output windows.  Or, if you are using the 
  211. /W+ mode (rewrite error file), you should be able to just hit 
  212. Shift-F10 to step to each successive error message.
  213.  
  214. And that's all there is to it!  
  215.  
  216. There are some other features of QCP you may want to take 
  217. advantage of, read on to find out about those, as well as how to 
  218. configure QCP's behavior to suit your specific needs.
  219.  
  220.  
  221. RUNNING QCP
  222. -----------
  223. If you are having trouble getting QCP to work as described, more 
  224. than likely your file names are getting out of sync.  Please make 
  225. sure that the file names (1) in your QEdit macro key, (2) in QCP 
  226. itself, and (3) in any batch files you use to run compilers; all 
  227. agree as to where and under what name each file is placed.
  228.  
  229. Also, when compiling this way, a pretty good bit of RAM is 
  230. required, all told.  This is because QEdit, your source file, 
  231. QCP, and your compiler (not to mention a couple copies of the 
  232. stub portion of COMMAND.COM) are all in memory at the same time.  
  233. Check out the ToggleSwap option in QEdit 2.1 if this gets to be a 
  234. problem.
  235.  
  236.  
  237. QCP 2.08 Documentation                                    Page 6
  238.  
  239.  
  240. COMMAND LINE SWITCHES AND QCP
  241. -----------------------------
  242. If you just type QCP at a DOS prompt, it will respond with this 
  243. screen of info.  (Display of defaults removed here to fit the 
  244. screen on a normal page):
  245.  
  246. ----------------------------------------------------------------
  247. QCP:  QEdit Compiler Program  x.yy   dd-mmm-yyyy
  248. Copyright (C) 1989, Tim Farley.  All Rights Reserved.
  249.  
  250. QCP /R[file] /C[file] /S /G /Q /B /W /P /Ichar /Ofile /Mfile /#  FILE  opts...
  251.  
  252. /R        Reads configuration info from specified file.  
  253. /C        Configures defaults into specified copy of QCP.
  254. /S        Shows QCP's current configurable defaults
  255. /G+ /G-   Guess or don't guess a missing file extension
  256. /Q+ /Q-   Create or don't create a QEdit binary macro file
  257. /B+ /B-   Batch mode:  create autoexec macro for QEdit
  258. /W+ /W-   Write or don't write copy of error file
  259. /P+ /P-   Pause or don't pause for keystroke after an error
  260. /Ichar    Char to be Inserted before row/col in output
  261. /Ofile    File to which Output will be redirected
  262. /Mfile    QEdit Macro file name to be generated
  263. /#        i.e. /1 thru /9, uses the specified special
  264.           extension definition instead of the file's extension
  265. FILE      is source file to compile.
  266. opts      are options to be passed to compiler command line
  267.  
  268. /R, /C, and /S are mutually exclusive
  269. If none of them are present, internal defaults are used
  270. ----------------------------------------------------------------
  271.  
  272. All QCP switches MUST precede the file name.  Both "/" and "-" 
  273. are recognized as switch characters. However, each switch must be 
  274. preceded by its own switch character.  Each switch must be 
  275. separated from the others by at least one space.  
  276.  
  277. The switches that contain file names (/M and /O, optionally on /C 
  278. and /R) MUST NOT contain a space between the switch and the file 
  279. name.
  280.  
  281. The boolean switches, like /G and /Q, can have "+" or "-" behind 
  282. them to set the specified switch on or off.  If nothing is behind 
  283. the switch, it is set on.  If any character other than "+" or "-" 
  284. is behind a boolean switch, for instance "=", then the current 
  285. value is TOGGLED.  
  286.  
  287. The most commonly used command line switches are explained in 
  288. detail below:
  289.  
  290.  
  291. QCP 2.08 Documentation                                    Page 7
  292.  
  293.  
  294. /R  -- READ CONFIG INFO FROM DISK
  295. ---------------------------------
  296. When /R is present, QCP will always read its configuration data 
  297. from an external file at run time, overwriting the internal 
  298. defaults.  
  299.  
  300. /C  -- CONFIGURE QCP.EXE'S DEFAULTS
  301. -----------------------------------
  302. The /C option causes QCP to read its configuration data from 
  303. QCP.DAT, and install this info as new defaults into QCP.EXE.  
  304. This allows you to permanently customize your copy of QCP.
  305.  
  306. Please be aware that since /C writes data into the EXE file, it 
  307. is possible for your copy of QCP to be damaged by this operation.  
  308. Make sure you always have a clean, uninstalled copy of QCP safely 
  309. tucked away.
  310.  
  311. In operation on networks, you may not wish to use the /C option, 
  312. if QCP.EXE will be located on a server drive to which you do not 
  313. have write access.  See /R above.
  314.  
  315. /S  -- SHOW QCP.EXE'S CURRENT DEFAULTS
  316. --------------------------------------
  317. The /S option is a companion to /C.  It allows you to see the 
  318. current defaults installed into QCP.EXE.  
  319.  
  320. Note that /R, /C and /S are mutually exclusive.  If you combine 
  321. them on a command line, the last one specified will take control.
  322.  
  323. /W+ or /W-  -- WRITE NEW ERROR OUTPUT FILE
  324. ------------------------------------------
  325. The /W switch controls whether QCP will write a new copy of the 
  326. compiler output file (normally ERRORS.LST).  The purpose of this 
  327. is to insert a certain ASCII character (see /I or ..I) 
  328. immediately to the left of the row and column numbers that QCP 
  329. found in the compiler output.   This allows the "next error" and 
  330. "previous error" macro keys to find row numbers and column 
  331. numbers without having any special knowledge of how the error 
  332. messages are formatted.
  333.  
  334. Since this involves writing a new copy of ERRORS.LST, it can slow 
  335. down the process somewhat, hence the flag to turn it off.
  336.  
  337. /O  -- OUTPUT FILE NAME
  338. -----------------------
  339. The /O option lets you specify the Output file name that will be 
  340. used by QCP.  This filename is substituted for "$O" (see below) 
  341. if present on your target compiler command lines.  This is also 
  342. the file that QCP will read back in after the compiler runs, to 
  343. attempt to locate any error messages.
  344.  
  345.  
  346. QCP 2.08 Documentation                                    Page 8
  347.  
  348.  
  349.  
  350. The Output file name can also be configured with the "..O" 
  351. command in QCP.DAT, however if /O is present it will override the 
  352. value specified in QCP.DAT.
  353.  
  354. The /O command line option is intended so that the filenames used 
  355. can be completely controlled by your QEdit function key macro.  
  356.  
  357. /M  -- MACRO FILE NAME 
  358. ----------------------
  359. The /M option is similar to /O, except it controls the name of 
  360. the binary macro file created by QCP and QMAC for use in finding 
  361. errors in your source code.  This file name is replaced wherever 
  362. "$M" appears in your target command line(s).
  363.  
  364. The macro file name can also be configured using the "..M" 
  365. command in QCP.DAT, however if /M is present it will override the 
  366. value specified in QCP.DAT.
  367.  
  368. On both of the above files, QCP will look for an environment 
  369. variable called TMP, to determine a suitable place to put "temp" 
  370. files.  This is the same as most Microsoft utilities which will 
  371. use the TMP environment variable to locate your RAM disk for 
  372. their use in writing scratch files.  If you invoke QCP with the 
  373. /S switch, you will see the result of this when the three file 
  374. names are listed.
  375.  
  376. You may not want this to happen, especially if you want to insure 
  377. that the file names referred to in your QEdit macro key are the 
  378. same as those used by QCP.  If so, just include a drive and/or 
  379. path specification in the file name.  If you want them always to 
  380. be in the "current" directory, then use ".\" prior to each file 
  381. name. 
  382.  
  383. FILE  -- FILE TO COMPILE
  384. ------------------------
  385. The first non-switch parameter on the QCP command line is assumed 
  386. to be the file you wish to compile.  This is normally generated 
  387. using "CurrentFilename" in a QEdit macro key, but could be typed 
  388. by you.  This can be a full file specification including path.  
  389.  
  390. options  -- COMPILER OPTIONS
  391. ----------------------------
  392. Any parameters past the filename on the QCP command line are 
  393. assumed to be options for the target compiler's command line.  
  394. They are simply passed along, assuming you have put the 
  395. appropriate $1, $2 etc. strings on your compiler command line 
  396. templates in QCP.DAT.  
  397.  
  398.  
  399. QCP 2.08 Documentation                                    Page 9
  400.  
  401.  
  402. All of these options must be delimited on both sides by spaces.  
  403. Note that this is a restriction of QCP that might not be shared 
  404. by your compiler.  
  405.  
  406.  
  407. QEDIT MACRO KEY CUSTOMIZATION
  408. -----------------------------
  409. QCP is normally intended to be invoked from a QEdit macro key.  A 
  410. sample key is provided in QCP.TXT.  You could edit this
  411. before installing it in your QCONFIG.DAT, to make it behave 
  412. differently.
  413.  
  414.  
  415. COMPILER COMPATIBILITY
  416. ----------------------
  417. The macro creation feature of QCP hinges on QCP's ability to read 
  418. the error messages created by your compiler.  By default, QCP 
  419. assumes that your compiler issues error messages in this form:
  420.  
  421.   <text> FILENAME.EXT <non-numeric chars> XX <text> YY <message>
  422.  
  423. where XX is the number of the source line on which the error 
  424. occurred, and YY is the column number on that line.  
  425.  
  426. The default case allows for error messages similar to:
  427.  
  428.           FILENAME.EXT (ROW,COL): MESSAGE
  429.           FILENAME.EXT: ROW: MESSAGE
  430.           "FILENAME.EXT", ROW COLUMN: MESSAGE
  431.           D:\PATH\FILENAME.EXT(ROW): MESSAGE
  432.  
  433. Most all of CURRENT VERSIONS of the compilers put out by 
  434. Microsoft Corporation, and Borland International, and every C 
  435. compiler we know of, can be made to issue error messages in this 
  436. form, and thus will work fine by default.
  437.  
  438.  
  439. CUSTOM COMPILER CONFIGURATIONS
  440. ------------------------------
  441. Non-standard compilers can still be handled by the appropriate 
  442. configuration line in QCP.DAT.  The syntax for this is as follows:
  443.  
  444.           .ext  "command line" "unique string" [ "lead-in string" ]
  445.  
  446. Either single or double quotes can be used, but they must match 
  447. on either end of a given string.  If you need to include a quote 
  448. mark inside one of the strings, use the other type of quote mark 
  449. to delimit it.  Any number of commas and/or spaces (if present) 
  450. between the strings will be ignored.
  451.  
  452.  
  453. QCP 2.08 Documentation                                    Page 10
  454.  
  455.  
  456. Command line is the normal compiler command line that would have 
  457. been on the line by itself.  
  458.  
  459. The unique string is some string that is found in the compiler's 
  460. output ONLY in error message lines.  This typically might be 
  461. something like "***ERROR:".
  462.  
  463. The lead-in string, if present, specifies a string that will 
  464. always be found in an error line to the left of the source line 
  465. number.  It is not mandatory, if not present it will default to 
  466. the same thing as the unique string.  The first numeric 
  467. characters to the right of the lead-in string must be the line 
  468. number.  Keep in mind that the file name itself, the error 
  469. message, or the line of source code itself (if echoed as part of 
  470. the error message) might contain numeric characters that could be 
  471. misinterpreted as a line number.
  472.  
  473. Maximum length of the unique and lead-in strings is 16 characters 
  474. each, they will be truncated if longer.  You CAN include 
  475. substitution strings like $N and $F inside the unique string and 
  476. lead-in string.  The length limitation DOES NOT apply to the 
  477. strings AFTER they are expanded.  The strings ARE NOT case 
  478. sensitive when matching occurs.
  479.  
  480. Example:
  481.  
  482. Your compiler generates error messages like:
  483.  
  484.           ***ERROR:  Syntax error on line 34
  485.  
  486. You would set your unique string to "***ERROR" and your lead-in 
  487. string to "line".
  488.  
  489. Choose your strings carefully, as some compilers generate very 
  490. inconsistent looking error messages.  A common mistake is to try 
  491. to key off the word "error" in the message, which will then cause 
  492. QCP to ignore "warning" messages.
  493.  
  494.  
  495. COMPATIBLE COMPILERS
  496. --------------------
  497. Below are some cases of specific compilers, and the command line 
  498. switches or other actions necessary to make them conform to what 
  499. QCP is expecting.  In many cases, you will want to add or 
  500. subtract switches to or from the sample command lines.  Consult 
  501. your compiler manual.
  502.  
  503.  
  504. QCP 2.08 Documentation                                    Page 11
  505.  
  506.  
  507. Most compilers allow you to specify either just a simple file 
  508. name, or a complete path specification on the command line. Keep 
  509. this in mind when selecting whether to use $F, or $N, or $N.$E, 
  510. etc.  for your filename on the command line.  The way you specify 
  511. the source file name on the command line, can affect how the 
  512. compiler echoes it in error messages.  You may want to experiment 
  513. with this, if you are defining specific unique or lead-in strings 
  514. that involve the filename.
  515.  
  516. COMPILER                   LINE TO PUT IN QCP.DAT
  517. -------------------------  -------------------------------
  518. Clipper by Nantucket, 8/87 .prg  "clipper $N >$O","line "
  519. FoxBase Compiler v2.1      .prg  "foxpcomp -e $F >$O","Error in line "
  520. FST Modula-2 v2.0a         .mod  "m2comp $F >$O","File: $F",", Line"
  521. Microsoft Assembler 5.x    .asm  masm         $F;  >$O
  522. Microsoft BASIC            .bas  bc   /Z      $F;  >$O
  523. Microsoft C 5.x            .c    cl   /c /W3  $F   >$O
  524. Microsoft FORTRAN 4.0      .for  fl   /c      $F   >$O
  525. Microsoft Menu Maker v1.2  .def  "makemenu  $N >$O","Error ("
  526. Microsoft Pascal 4.0       .pas  pas1 /H      $F;  >$O
  527.      Alternative:          .pas  pl   /c /Zz  $F   >$O
  528. Microsoft Quick C 1.01     .c    qcl          $F   >$O
  529. QMac (QEdit macros) 2.x    .qm   "qmac $N.mac $F /B /A- >$O"  "QMAC "
  530. Telix 3.x Script Compiler  .slt  cs           $F   >$O
  531. TopSpeed Modula-2 1.14     .mod  m2 /c        $F   >$O
  532. Turbo Assembler 1.00       .asm  "tasm $F >$O"  "** $F"
  533. Turbo C 2.0                .c    tcc  -c -w   $F   >$O
  534. Turbo Pascal 4.0 & 5.0     .pas  tpc  /q      $F   >$O
  535. Watcom C 6.5               .c    wcl  /c      $F   >$O
  536.  
  537. NOTES:
  538.      The /H switch for Microsoft Pascal is undocumented.
  539.      The Microsoft BASIC and FORTRAN, Clipper and FoxBase command 
  540.           lines have not been tested by us personally.
  541.      Microsoft Menu Maker comes with the Microsoft Mouse.
  542.      We recommend you use the /W+ option when working with 
  543.           Clipper, because of the way that Clipper writes its 
  544.           output.
  545.      
  546. Many compilers will compile files other than the one specified, 
  547. due to an automatic "make" function built into the compiler.  
  548. This can sometimes result in either (1) QCP ignoring error 
  549. messages from the compiler, because they don't pertain to the 
  550. current file or (2) QCP jumping to erroneous error lines in the 
  551. current file, because it was unable to distinguish that they did 
  552. not pertain to the current file.  Some of the compilers that are 
  553. prone to this are Clipper, Turbo Pascal, both of the Modula-2 
  554. compilers, and others.  We plan to address this in a future 
  555. version of QCP.
  556.  
  557.  
  558. QCP 2.08 Documentation                                    Page 12
  559.  
  560.  
  561. Below are some instances where just a simple command line will 
  562. not do the trick.  Even if you do not use one of them, you may 
  563. want to read through them to see what kinds of configuration 
  564. tricks are possible.
  565.  
  566.  
  567. I/O REDIRECTION PROBLEMS, TIPS
  568. ------------------------------
  569. Many of the unusual compiler configurations listed below result 
  570. from problems redirecting the output to the compiler.  If a 
  571. program writes its screen output to the "Standard Output Device" 
  572. under DOS, then the text can be redirected normally, using the 
  573. ">" character followed by a filename on the dos command line.  
  574. However, if the output is written to the "Standard Error Device", 
  575. redirection is impossible using DOS alone.
  576.  
  577. We know of two utilities that can assist with compilers that use 
  578. Standard Error to display error messages.  One is ERROUT.EXE, 
  579. which is a utility Microsoft ships with many of its recent 
  580. compiler products.  
  581.  
  582. The other is CONCOPY.EXE, which is a Freeware product by 
  583. Christopher J. Dunford and The Cove Software Group.  You can get 
  584. it on many BBS systems, including SemWare's.
  585.  
  586. See the sections below for examples of the use of ERROUT and 
  587. CONCOPY with QCP.
  588.  
  589.  
  590. MICROSOFT FORTRAN 3.x
  591. ---------------------
  592. Microsoft Fortran 3.x can work with QCP.  Its error messages look 
  593. like this:
  594.  
  595.           ***** Error XXX,line YY -- ERROR MESSAGE
  596.  
  597. To get this, we define the unique string and lead-in string as 
  598. follows:
  599.  
  600.           .FOR   "for1  $N.$E;  >$O","*****",",line "
  601.  
  602. You may wish to put this command line in a batch file instead of 
  603. invoking it directly, so that you can call up PAS2 and PAS3 of 
  604. the compiler as needed.  If so, be sure to pass $O to the batch 
  605. file as a command line parameter.
  606.  
  607.  
  608. QCP 2.08 Documentation                                    Page 13
  609.  
  610.  
  611. MICROSOFT MASM 4.0
  612. ------------------
  613. Masm produces compatible error messages by default.  
  614.  
  615. Unfortunately, MASM 4.0 writes the error messages to Standard 
  616. Error, so we have to use a utility to redirect it (see above).  
  617. Put one of these two lines in your QCP.DAT:
  618.  
  619.           .ASM   ERROUT  /f $O  MASM  $N.$E;
  620.  
  621.           .ASM   CONCOPY  $O  MASM $N.$E;  
  622.           
  623. The part to the left of MASM causes Standard Error to be redirected to 
  624. the output file.  
  625.  
  626. Later versions of MASM write to Standard Output. 
  627.  
  628.  
  629. DBFAST 1.03
  630. -----------
  631. This dBASE III+ compatible compiler does not generate error 
  632. messages compatible with the default case.  They look like this:
  633.  
  634.           MESSAGE TEXT. Line #:    XX
  635.  
  636. where XX is the line number.  We will define a unique string in 
  637. order to make this work with QCP.
  638.  
  639. Because of the way redirection occurs with DBCOMP, you need to 
  640. use a batch file to run the compiler.  Here is DBC.BAT:
  641.  
  642.           ECHO OFF
  643.           DBCOMP %1 -W -PF
  644.           COPY   %1.ERR %2
  645.           DEL    %1.ERR
  646.  
  647. The -PF switch redirects output to a file.  This file always has 
  648. the same root name as the file being compiled, with an extension 
  649. of "ERR".  The -W switch causes "warning" messages to also be 
  650. issued, which you may or may not desire.  Use this line in 
  651. QCP.DAT:
  652.  
  653.           .PRG  "DBC $N $O","Line #:"
  654.  
  655. which sets both the unique string and the lead-in string to the 
  656. string "Line #:"
  657.  
  658.  
  659. QCP 2.08 Documentation                                    Page 14
  660.  
  661.  
  662. It is important to use $N so that the ".ERR" can be appended in 
  663. the batch file.  Also, make sure you have the DBFAST RAM-resident 
  664. "engine" loaded into memory before you enter QEdit, as it is NOT 
  665. RECOMMENDED to attempt to load it from inside QEdit, since it is 
  666. a TSR program.
  667.  
  668.  
  669. NORTON GUIDES DATABASE COMPILER 1.04
  670. ------------------------------------
  671. The tools supplied with the Norton Guides to create your own 
  672. online help databases can be used with QCP.  However, they 
  673. require both redirection help and a special unique/lead-in 
  674. string.
  675.  
  676. Both of Norton's programs write the error messages to Standard 
  677. Error.  Put one of these two sets of lines in your QCP.DAT:
  678.  
  679.           .NGC  "errout /f $O ngc  $F"  "Line "
  680.           .NGM  "errout /f $O ngml $F"  "Line "
  681.  
  682.           .NGC  "concopy   $O ngc  $F"  "Line "
  683.           .NGM  "concopy   $O ngml $F"  "Line "
  684.  
  685. Norton does not recommend particular extensions for the Database 
  686. source files or the Menu Link Control files.  For the sake of 
  687. this example, we have adopted ".NGC" for the former and ".NGM" 
  688. for the latter.
  689.  
  690.  
  691. MICROSOFT QUICK PASCAL 1.00
  692. ---------------------------
  693. Quick Pascal's command-line compiler also uses Standard Error to 
  694. output error messages.  Put one of the following two lines in 
  695. your QCP.DAT:
  696.  
  697.           .PAS  ERROUT  /f $O  qpl $F
  698.  
  699.           .PAS  "CONCOPY  $O   qpl $F"  "error P"  "$N.$E"
  700.  
  701. Quick Pascal issues "status messages" telling what line it is 
  702. currently compiling, to the console, just as Turbo Pascal does.  
  703. Unfortunately, unlike Turbo Pascal, Quick Pascal does not have a 
  704. /Q switch to turn this off.  
  705.  
  706. As a result, if you use CONCOPY to redirect the output, you will 
  707. get a number of bare carriage returns in the output.  For this 
  708. reason, we recommend you use the /W+ mode of QCP when compiling 
  709. with Quick Pascal.  When the error file is rewritten by QCP, the 
  710. bare carriage returns will be converted to proper line breaks.  
  711. This is also the reason for the unusual Unique and Lead-in 
  712.  
  713.  
  714. QCP 2.08 Documentation                                    Page 15
  715.  
  716.  
  717. strings on the CONCOPY command line above.
  718.  
  719.  
  720. INCOMPATIBLE COMPILERS
  721. ----------------------
  722. The following compilers cannot be made to work with QCP's macro 
  723. generation feature as far as we can tell.  If you can figure out 
  724. a way to make one of these work, we'll be glad to add that 
  725. information to a future version of this DOC file.
  726.  
  727. A86 macro assembler, V3.20 (and earlier) by Eric Isaacson
  728.      Error messages do not include line numbers.  
  729. Microsoft Pascal, v3.32 and earlier
  730.      Error messages are too inconsistently formatted.
  731. Ryan-McFarland FORTRAN version 2.4
  732.      Error messages do not include line numbers.  
  733. Turbo Pascal 3.0 and earlier
  734.      This compiler is an integrated environment only.
  735.  
  736.  
  737. CONFIGURATION VIA QCP.DAT
  738. -------------------------
  739. QCP needs information on the file extensions and compilers you 
  740. use in order to do its job.  You supply this information by 
  741. editing the file QCP.DAT to suit your individual circumstances.  
  742.  
  743. In addition, various options in the way QCP behaves can be 
  744. controlled via lines in QCP.DAT.  This includes those mentioned 
  745. above in the section on command line switches, but also some 
  746. others that you will normally change only rarely.
  747.  
  748. An example QCP.DAT, which contains the same values with which 
  749. QCP.EXE is shipped, is supplied.  You can begin by editing this 
  750. file to suit your requirements.
  751.  
  752. The main content of QCP.DAT is a list of file name extensions, 
  753. followed by the command line that will be executed for each one, 
  754. as follows:
  755.  
  756.      Ext.    Default Command Line
  757.      ----    --------------------
  758.      .asm    masm   $F;  >$O
  759.      .c      tcc -c $F   >$O
  760.  
  761. and so on.
  762.  
  763.  
  764. QCP 2.08 Documentation                                    Page 16
  765.  
  766.  
  767. It is legal to have an entry for a "nothing" file extension.  
  768. Just put a period by itself on a line, followed by at least one 
  769. space, and the command line to use.  
  770.  
  771. Only the first 10 extensions found will be processed.  Any 
  772. additional ones, or duplicate ones, will be ignored.  A warning 
  773. message is issued to help you clean up your QCP.DAT.
  774.  
  775. The raw command lines may not be longer than 64 characters, 
  776. though they can become a full 127 characters long when the $ 
  777. strings are expanded.
  778.  
  779. QCP executes a child copy of COMMAND.COM, which is passed the 
  780. command line to execute.  This means that you can use internal 
  781. DOS commands, batch files and I/O redirection in invoking your 
  782. compiler.  COMMAND.COM is found using the 'COMSPEC' environment 
  783. variable, make sure yours is set correctly.  Putting COMMAND.COM 
  784. on a RAM disk and setting your COMSPEC variable to point to it 
  785. considerably speeds operation of QCP and other programs.  See 
  786. your DOS manual for details.
  787.  
  788.  
  789. SUBSTITUTION STRINGS
  790. --------------------
  791. Various sub-strings, in the form of "$c" where c is some 
  792. character, can be included in compiler command lines, macro key 
  793. templates and the QMAC command line template (see below), in 
  794. order to substitute values at run-time.  They can be included in 
  795. any order.  Some make more sense than others in certain contexts.  
  796. There is a chart listing all of them, with sample values, later 
  797. in this document.
  798.  
  799.  
  800. QCP CONFIGURATION COMMANDS
  801. --------------------------
  802. Some configuration commands can also be included in QCP.DAT to 
  803. customize QCP in special ways.  
  804.  
  805. You need not supply all or any of these commands in QCP.DAT, you 
  806. can mix and match as you see fit.  Any that are not included will 
  807. default to the previously installed values in QCP.EXE.  If more 
  808. than one of the same directive occurs in QCP.DAT, the last one 
  809. takes precedence.
  810.  
  811. See the chart later in this document, as well as QCP.DAT itself, 
  812. for more details.
  813.  
  814.  
  815. QCP 2.08 Documentation                                    Page 17
  816.  
  817.  
  818. Here are some summaries of the various switches, parameters, etc. 
  819. that QCP understands:
  820.  
  821.  
  822. SUMMARY OF QCP COMMAND LINE SWITCHES
  823. ------------------------------------
  824.  
  825. SWITCH      MEANING                   TYPICAL VALUE
  826. ----------  ------------------------  --------------------------
  827.  
  828.  /? or /H   show Help screen
  829.  /C         Configure QCP             /C or /CE:\MYDIR\MYQCP.EXE
  830.  /G         set Guess extension mode  /G+
  831.  /M         set Macro file name       /M.\errors.mac
  832.  /O         set Output file name      /O.\errors.lst
  833.  /P         set Pause after error     /P+
  834.  /Q         set QEdit macro creation  /Q+
  835.  /R         Read config from QCP.DAT  /R or /RE:\MYDIR\MYQCP.DAT
  836.  /S         See defaults              /S
  837.  /W         set reWrite error file    /W+
  838.  
  839.  
  840. SUMMARY OF SUBSTITUTION STRINGS
  841. -------------------------------
  842.  
  843. STRING      MEANING                   TYPICAL VALUE
  844. ----------  ------------------------  --------------------------
  845.  
  846.   $$        single dollar sign        "$"
  847.   $1 to $9  Compiler options          varies with compiler
  848.   $C        source Column number      "1"
  849.   $D        Drive letter              "C"
  850.   $E        Extension of file         "PAS"
  851.   $F        Full filename             "C:\LANG\TURBO\MYFILE.PAS"
  852.   $I        Inserted character        CHR( 255 )
  853.   $K        macro Key number          "1" through "0"
  854.   $L        Lead-in string            "MYFILE.PAS"
  855.   $M        Macro file name           ".\ERRORS.MAC"
  856.   $N        Name of file              "MYFILE"
  857.   $O        Output file name          ".\ERRORS.LST"
  858.   $P        Path (directory) of file  "\LANG\TURBO"
  859.   $R        Result line number        "3"
  860.   $S        Source line number        "124"
  861.   $T        Temp file name            "$QCP$.TMP"
  862.   $U        Unique string             "MYFILE.PAS"
  863.  
  864.  
  865. QCP 2.08 Documentation                                    Page 18
  866.  
  867.  
  868. SUMMARY OF QCP.DAT CONFIGURATION COMMANDS
  869. -----------------------------------------
  870.  
  871. STRING      MEANING                   TYPICAL VALUE
  872. ----------  -----------------------   ---------------------------
  873.  
  874.  ..C        QMac Command line         "QMAC $M $T B N"
  875.  ..G        Guess extension           "ON" or "OFF"
  876.  ..I        Insertion character       "255"
  877.  ..M        Macro file name           ".\ERRORS.MAC"
  878.  ..N        Next error macro          a valid macro
  879.  ..O        Output file name          ".\ERRORS.LST"
  880.  ..P        Previous error macro      a valid macro
  881.  ..Q        QEdit macro template      "ON", "OFF", or valid macro
  882.  ..T        Temp file name            "$QCP$.TMP"
  883.  ..W        reWrite error file        "ON" or "OFF"
  884.  
  885.  
  886. ERROR MESSAGES
  887. --------------
  888. Various error conditions can occur when QCP operates, in which 
  889. case it will issue the following error messages.  Each of these 
  890. will be preceded by "QCP Error:" to remind you that an error
  891. condition has occurred, and followed by a console beep.
  892.  
  893.           QCP.DAT cannot be found
  894.                or
  895.           QCP.EXE cannot be found
  896.  
  897. The data file or executable file could not be found in the 
  898. current directory, the directory the EXE came from, nor anywhere 
  899. along the path.  These can occur as the result of using the /R or 
  900. /C command line switches.
  901.  
  902.           d:\dir\QCP.EXE is corrupted or wrong version
  903.  
  904. You may have more than one QCP.EXE on your disk, or more than one 
  905. version of QCP present.  If that is not true, your copy of QCP 
  906. may have been damaged due to disk error.  Get a fresh copy from 
  907. your backup.
  908.           
  909.           DOS error on execution of target command line
  910.  
  911. Some sort of DOS error (other than out of memory) occurred on 
  912. trying to load the child COMMAND.COM.  This would be very rare, 
  913. but might be caused by an invalid COMSPEC environment variable, 
  914. or an invalid copy of COMMAND.COM.
  915.  
  916.  
  917. QCP 2.08 Documentation                                    Page 19
  918.  
  919.  
  920.           Error reading d:\dir\QCP.DAT
  921.  
  922. This means some sort of DOS error occurred while reading the data 
  923. file, either a bad sector, or premature EOF or something.
  924.  
  925.           File name missing on /O or /M switch
  926.  
  927. You specified /O or /M on the QCP command line without putting a 
  928. filename immediately behind the switch (no spaces).
  929.  
  930.           File name missing
  931.  
  932. After parsing out the various switches, QCP could not find an 
  933. actual file name to pass to your compiler.
  934.  
  935.           I/O problem while attempting to write d:\dir\QCP.EXE
  936.  
  937. Some sort of DOS error occurred while rewriting the defaults in 
  938. QCP.EXE.  This will only occur when you specify the /C command 
  939. line option.  Your copy of QCP.EXE may have been damaged by this, 
  940. get a new copy off your backup disk.
  941.  
  942.           Improper macro continuation line
  943.  
  944. When specifying multi-line QEdit macros in QCP.DAT, by putting 
  945. "&" on the end of the line, QCP does some rudimentary checking.  
  946. If the continuation line begins with a period ("."), it will 
  947. issue this message.  It could also happen if the end of QCP.DAT 
  948. was reached before finishing the macro.  This can occur while 
  949. reading any of the macro template commands in QCP.DAT.
  950.  
  951.           No extensions found in d:\dir\QCP.DAT
  952.  
  953. No lines in the specified copy of QCP.DAT began with a '.', so 
  954. QCP could not find any extensions to parse.
  955.  
  956.           No matching command line found for extension "xxx"
  957.  
  958. There was no extension/command line definition in QCP.DAT that 
  959. matched the extension of the file given on the command line (i.e. 
  960. "xxx").  If you specified /1 through /9 on the command line, then 
  961. there was no matching ..1 through ..9 command in your 
  962. configuration.
  963.  
  964.           Not enough memory to execute command line
  965.  
  966. There was not enough memory to load a child copy of COMMAND.COM 
  967. and execute your target command line.
  968.  
  969.  
  970. QCP 2.08 Documentation                                    Page 20
  971.  
  972.  
  973.           Unrecognized command switch "x"
  974.  
  975. You specified a "/x" switch on the command line that QCP did not 
  976. recognize.  Check the documentation for valid switches.
  977.  
  978.  
  979. Only one of these errors will be displayed during any single run 
  980. of QCP. If any of these error messages were displayed, the DOS 
  981. ERRORLEVEL value will be set to 128 or higher when QCP exits.  
  982.  
  983.  
  984. INFORMATIVE & WARNING MESSAGES
  985. ------------------------------
  986. QCP will also issue various informative messages during 
  987. operation.  These will be preceded by "QCP:" for messages, or 
  988. "QCP Warning:" for warnings.  No beep will sound, nor will the 
  989. ERRORLEVEL be set in these cases, as these are non-fatal 
  990. conditions.  The "press any key to continue" prompt, if enabled, 
  991. will not appear after these messages.
  992.  
  993.           Duplicate definition for "xxx" ignored
  994.  
  995. There is more than one definition line for extension "xxx" in 
  996. your QCP.DAT.  Edit your QCP.DAT so that there is only one.  If 
  997. you need to temporarily disable one definition to use another, 
  998. edit the line so that there is no "." in column 1, and QCP will 
  999. ignore that line.
  1000.  
  1001.           Extension table full, extension "xxx" ignored
  1002.  
  1003. You have more than 10 extension/command line definitions in your 
  1004. QCP.DAT, and QCP ran out of table space.  "xxx" will be the 11th 
  1005. or greater extension defined in the file.  Edit your QCP.DAT so 
  1006. that there are 10 or less definitions.
  1007.  
  1008.           Macro file created for QEdit
  1009.  
  1010. This message appears after QCP is done running QMAC to create a 
  1011. loadable binary macro file for QEdit.  
  1012.  
  1013.           New defaults written to d:\dir\QCP.EXE
  1014.  
  1015. This informs you that QCP has successfully re-written its 
  1016. defaults as requested by /C, and where QCP.EXE was found.
  1017.  
  1018.  
  1019. QCP 2.08 Documentation                                    Page 21
  1020.  
  1021.  
  1022.           Reading configuration from d:\dir\QCP.DAT
  1023.  
  1024. This message just informs you that a configuration is being read 
  1025. to satisfy a /R or /C request, and it tells you where QCP.DAT was 
  1026. found on the disk.
  1027.  
  1028.           Unknown configuration command "..x" ignored
  1029.  
  1030. QCP found a command named "..x" in your QCP.DAT, and did not 
  1031. recognize it.  See elsewhere in this documentation for the list 
  1032. of supported configuration commands.
  1033.  
  1034.           Unmatched " in input line of d:\dir\QCP.DAT
  1035.  
  1036. QCP was trying to read in a command line followed by a unique 
  1037. string and/or a lead-in string, and could not find a matching 
  1038. quote character.  Since you can mix and match single and double 
  1039. quotes, double check your data file to be sure you paired them up 
  1040. correctly.
  1041.  
  1042.  
  1043. ACKNOWLEDGEMENTS & CONTACTS
  1044. ---------------------------
  1045. Source code to QCP is no longer available.
  1046.  
  1047. Special thanks to Tony Tortorelli, Randy Wallin, Gary Speegle, 
  1048. David Chaika, Howard Kapustein and Sammy Mitchell for help in
  1049. tracking down particular compiler command lines that would work 
  1050. with QCP.  Also thanks to Mike Smedley and Jerry Houston for some 
  1051. great ideas on which QCP is based.
  1052.  
  1053. If you have any questions or suggestions, please contact:
  1054.  
  1055. SemWare Corporation
  1056. 4343 Shallowford Road
  1057. Suite C3A
  1058. Marietta, GA  30062-5022
  1059.  
  1060. Voice Phone: (404) 641-9002   9 a.m to 5 p.m. E.T., Mon-Fri.
  1061. BBS:   (404) 641-8968
  1062. FAX:   (404) 640-6213
  1063.  
  1064.  
  1065. QCP 2.08 Documentation                                    Page 22
  1066.  
  1067.  
  1068. REVISION HISTORY
  1069. ----------------
  1070. Version 1.0 - 7-Feb-1989 - Initial release.
  1071.  
  1072. Version 2.0 - 15-Mar-1989 - Substantial revision.
  1073.               Added internal defaults.  
  1074.               Added /R, /H, /? and /S command line switches.
  1075.               Added self-configuration /C option.
  1076.               Added construction of QMAC macros from error output.
  1077.               Added support for environment variable 'TMP'.
  1078.               Additional error checking and status messages.
  1079.               Added "special extensions" for special-purpose macros
  1080.               Added /M and /O cmd line options to make the 
  1081.                 invocation macro more self-contained.
  1082.               Added /Q, made boolean switches more consistent.
  1083.               Documentation file significantly rewritten.
  1084.  
  1085. Version 2.08 - 17-Nov-1989 - Supports QEdit 2.08.
  1086.               Detects column number along with line number.
  1087.               Allows generic "next" and "previous" macros.
  1088.               Allows compilers to be run outside of QEdit, with 
  1089.                 the editor being invoked via an autoexecute macro.
  1090.               Pause after error messages.
  1091.               QEdit macros that QCP writes can now be two lines.
  1092.               Miscellaneous improvements.
  1093.  
  1094.  
  1095.  
  1096.                               *** END ***
  1097.  
  1098.