home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / mbug / mbug002.arc / SUPERSUB.DOC < prev    next >
Text File  |  1979-12-31  |  8KB  |  202 lines
  1.             SUPERSUB
  2.  
  3.          A replacement for the CP/M SUBMIT utility
  4.  
  5.  
  6.      One of the most useful programs provided with CP/M is the 
  7. SUBMIT utility, which allows system commands to be read from a 
  8. disk file for automatic processing.  Its command-line 
  9. substitution facility provides a convenient means of developing 
  10. "prototype" command files, with actual parameter substitution 
  11. performed when the command file is invoked.
  12.      There are, however, some shortcomings associated with 
  13. SUBMIT that recur frequently.  Frequently enough to inspire me 
  14. to write my own batch processor, SUPERSUB, that completely 
  15. replaces, and is fully compatible with, the standard SUBMIT 
  16. utility.
  17.  
  18. PROBLEMS WITH SUBMIT
  19.  
  20.      SUBMIT will produce a "garbaged" output file whenever it 
  21. encounters an empty line in the input file.  This is a real 
  22. handicap when attempting to pass command lines to PIP.COM, for 
  23. example, using XSUB (the CP/M2 utility that extends the SUBMIT 
  24. capability to transient programs), since the only way to exit 
  25. PIP is to enter an empty command line (you can enter a control-
  26. "C" as the first character of the line, but this is a "real-
  27. time" function, and cannot be done within a SUBMIT file). 
  28. SUPERSUB generates the necessary zero-length line in the output 
  29. file.
  30.       Another SUBMIT drawback is the constant need to enter an 
  31. editor and create a command file, even for the simplest of 
  32. jobs.  This added step discourages the use of SUBMIT for very 
  33. simple "command stacking" applications. With this in mind, I 
  34. gave SUPERSUB the ability to interactively accept command lines 
  35. from the console.  An additional option allows the entire job 
  36. to be specified on the SUPERSUB command line.
  37.  
  38. COMMAND FILE NESTING
  39.  
  40.      I felt that a nesting capability would be a significant 
  41. feature to add to SUPERSUB.  For example, it would be useful to 
  42. create a submit file called COMPILE.SUB, to facilitate the 
  43. program compilation process, and "clean up" any leftover files.  
  44. COMPILE.SUB might look like this:
  45.  
  46.     BASCOM =$1      ;COMPILE PROGRAM SPECIFIED IN CMD LINE
  47.     L80 $1,$1/N/E      ;LINK THE PROGRAM
  48.     PIP B:=$1.COM      ;MOVE THE OBJECT FILE TO THE B DRIVE
  49.     ERA $1.REL      ;DELETE THE .REL FILE
  50.     ERA $1.COM      ;  AND THE OBJECT FILE
  51.  
  52.      Now let's say I want to compile several programs at once 
  53. (a common situation in applications programming).  Under 
  54. SUBMIT, I would have to type in a SUBMIT invocation for each 
  55. program:
  56.  
  57.    A>SUBMIT COMPILE LEDGER    [COMPILE.SUB executes, operator waits
  58.                  for it to complete, then types:]
  59.    A>SUBMIT COMPILE PAYABLES  [more waiting for COMPILE.SUB, then:]
  60.    A>SUBMIT COMPILE RECVBLES  [and the job is finally done.]
  61.  
  62.      Using SUPERSUB, I can create a file (CMPILALL.SUB) 
  63. containing the commands
  64.  
  65.    SUBMIT COMPILE LEDGER
  66.    SUBMIT COMPILE PAYABLES
  67.    SUBMIT COMPILE RECVBLES
  68.  
  69. and execute the whole thing with the single command line
  70.  
  71.    A>SSUB CMPILALL
  72.  
  73. (Note that I've abbreviated SUPERSUB to SSUB on all my disks; 
  74. SUPERSUB as a name is a bit grandiose anyway).  I can also save 
  75. the trouble of creating CMPILALL.SUB (especially if I want to 
  76. do this only once) and enter the single command line
  77.  
  78.    A>SSUB /COMPILE LEDGER;SSUB COMPILE PAYABLES;SSUB COMPILE RECVBLES
  79.  
  80. or, if the individual command lines to be executed are a bit 
  81. long, I can specify the Interactive mode by entering only a 
  82. slash ("/") on the command line (after the SUPERSUB 
  83. invocation).  SUPERSUB will then prompt for each command line 
  84. with an asterisk.  To continue the previous example,
  85.  
  86.    A>SSUB /
  87.    *COMPILE LEDGER
  88.    *SSUB COMPILE PAYABLES
  89.    *SSUB COMPILE RECVBLES
  90.    *                       [empty line here terminates]
  91.  
  92. ON-LINE HELP FUNCTION
  93.  
  94.      I believe all programs of any complexity should be "self-
  95. instructive" by providing the user a means of typing out, on 
  96. the terminal, the major modes of operation, and any necessary 
  97. command line syntax.  Further, the command line used to invoke 
  98. this "help summary" should be the simplest possible form not 
  99. otherwise used by the program.  In the case of SUPERSUB, this 
  100. is a command line with no arguments at all:
  101.  
  102.    A>SSUB
  103.  
  104. SUBMIT.COM COMPATIBILITY
  105.  
  106.      SUPERSUB is fully compatible with CP/M's SUBMIT utility, 
  107. including command parameter substitution and control-character 
  108. translation:
  109.  
  110.    1) Parameters within the "prototype" file, of the form $1, 
  111.       $2, etc., are substituted from the command line on a one-
  112.       for-one basis.  Parameters are passed through to any 
  113.       nested files.  Two successive dollar-sign characters 
  114.       ("$$") may be used to introduce a single "$" into the 
  115.       output file.
  116.  
  117.    2) An up-arrow symbol ("^") may precede an alphabetic 
  118.       character to insert the associated control-character into 
  119.       the output file.
  120.  
  121. DETAILED INSTRUCTIONS
  122.  
  123.      In addition to the normal SUBMIT mode of operation and 
  124. associated command line usage, SUPERSUB provides two additional 
  125. modes of input: Interactive and Summary.
  126.  
  127.  
  128. SUMMARY MODE
  129.  
  130. Summary mode allows the entire SUBMIT job to be specified in 
  131. the CP/M command line.  This mode is enabled by using the slash 
  132. ("/")character as the first character of the command line. The 
  133. individual submit lines must be seperated with a semicolon. For 
  134. example,
  135.  
  136.      A>SSUB / CRCK *.* F;CRCK B:*.* F;COMPARE CRCKFILE.CRC B:
  137.          ^
  138.          |
  139.           ----> (this space is optional)
  140.  
  141. will create a file of CRC's of all files on A:, then create a 
  142. similar file on B:, then compare the two.  (CRCK, by Keith 
  143. Petersen, and COMPARE, by Ward Christensen, are available from 
  144. the CP/M Users Group).
  145.  
  146. INTERACTIVE MODE
  147.  
  148. You may enter the interactive entry mode by typing 
  149. "SUPERSUB /<CR>" (ie, "SUPERSUB /" with no arguments).  
  150. Supersub will prompt for input with an asterisk, and you may 
  151. then enter SUBMIT lines from the keyboard.  Multiple commands 
  152. may be entered on a line by separating them with semicolons.  
  153. An empty line terminates the input.  Example:
  154.  
  155. A>SUPERSUB /
  156. *CRCK *.* F
  157. *CRCK B:*.* F
  158. *COMPARE CRCKFILE.CRC B:
  159. *                <empty line here>
  160. A>CRCK *.* F            <submit file begins execution>
  161.  
  162. has the same effect as the above SUMMARY mode example.
  163.  
  164. HELP FUNCTION
  165.  
  166. Typing SUPERSUB with no arguments will print the built-in help 
  167. file.
  168.  
  169.  
  170.  
  171.  
  172.  
  173. NOTES
  174.  
  175. 1) Nested SUBMIT runs are only usable up to a maximum of 128 
  176.    nested commands at any one time.  This is a limitation of 
  177.    the CP/M Console Command Processor.
  178.  
  179. 2) If you change the drive specification for the output file, 
  180.    you may want to do the same thing with XSUB (Digital 
  181.    Research's function nine extender).  Within XSUB, find the 
  182.    submit File Control Block (search for "$$$     SUB" within 
  183.    XSUB.COM)  and change the first FCB byte (ie, the byte 
  184.    before the first "$") to:
  185.         0 - to use default drive
  186.         1 - to use drive A:
  187.         2 - to use drive B:
  188.    etc.
  189.  
  190. 3) In SUMMARY and INTERACTIVE modes, passed parameters have no 
  191.    meaning.  When these modes are used, the parameter flag, 
  192.    "$", will be passed through literally to the output file.
  193.  
  194. 4) Zero-length output lines may be created in SUMMARY and 
  195.    INTERACTIVE modes by using two consecutive semicolons.  This 
  196.    is, in effect, a blank logical line.
  197.  
  198. 5) Interactive mode may be aborted by typing control-C as the 
  199.    first character of a line.  Also, all normal CP/M editing 
  200.    characters are available in this mode.
  201.  
  202.