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