home *** CD-ROM | disk | FTP | other *** search
/ Columbia Kermit / kermit.zip / d / k20cmd.doc < prev    next >
Text File  |  2020-01-01  |  9KB  |  315 lines
  1.  
  2.  
  3.  
  4.                 CMD                ___
  5.  
  6.  
  7.  
  8. 1.0  OVERVIEW
  9.  
  10. The CMD package makes it very easy for  MACRO  programs  use
  11. the  COMND JSYS in order to provide the MACRO program's user
  12. to be able to type TOPS20 style  commands  to  the  program,
  13. including  all standard TOPS20 features such as recognition,
  14. question mark, CTRL/H etc.
  15.  
  16. The  CMD  package  is  a  valuable  tool  several   reasons,
  17. uncluding:
  18.  
  19. 1)      The programmer needn't allocate  any  special  COMND
  20.         JSYS buffers and blocks.
  21.  
  22. 2)      The programmer needn't provide  initialization  code
  23.         to set up pointers and blocks for the COMND JSYS.
  24.  
  25. 3)      The  programmer  needn't  provide  special  code  to
  26.         handle  "cleaning  up" associated with reparsing and
  27.         error returns.
  28.  
  29. In general, all the program  must  do  when  using  CMD,  is
  30. supply  the  field-specific data for the individual parts of
  31. the command being parsed.  CMD does most of the rest.
  32.  
  33.  
  34.  
  35. 2.0  NONGOAL
  36.  
  37. The CMD package does not attempt to provide  any  method  of
  38. generating  entire  command  languages,  such  as  structure
  39. trees.  It only provides primitives from which  such  things
  40. as structure trees may be designed.
  41.  
  42.  
  43.  
  44. 3.0  SAMPLE RUN
  45.  
  46. The following is a typescript of the running  of  a  program
  47. called CMTEST, which features two commands, EXIT and RENAME.
  48. The program uses the CMD package.
  49.  
  50. @RUN CMTEST
  51. CMTEST>? ONE OF THE FOLLOWING:
  52.  EXIT     RENAME
  53. CMTEST>RENAME (EXISTING FILE) FOO.ERT.1 (TO BE) ZOT.BAR
  54. CMTEST>EXIT ? CONFIRM WITH CARRIAGE RETURN
  55. CMTEST>EXIT 
  56. @
  57.                                                       Page 2
  58.  
  59.  
  60. 4.0  PROGRAM LISTING
  61.  
  62. The following program listing shows how the CMD  package  is
  63. utilized to implement commands.
  64.  
  65. title CMTEST
  66. search monsym,macsym,CMD
  67. .require sys:macrel,sys:CMD
  68.  
  69. beg:    RESET
  70.         MOVEI P,PDL-1                   ;SET UP STACK
  71.         CALL CMDINI                     ;INITIALIZE COMND JSYS
  72. LUP:    PROMPT (CMTEST>)                ;PROMPT FOR COMMAND
  73.         MOVEI A,[FLDDB. .CMKEY,,WRDLST] ;SPECIFY WE WANT A KEYWORD
  74.         CALL RFIELD                     ;READ COMMAND
  75.         MOVE A,(B)                      ;GET ADDRESS OF COMMAND ROUTINE
  76.         CALL (A)                        ;EXECUTE THE COMMAND
  77.         JRST LUP                        ;GO GET NEXT COMMAND
  78.  
  79. .EXIT:  CONFRM                          ;WAIT FOR END OF LINE
  80.         HALTF                           ;EXIT COMMAND CAUSES STOP
  81.         RET                             ;GET NEXT COMMAND IF CONTINUE
  82.  
  83. .RENAM: NOISE (EXISTING FILE)
  84.         MOVEI A,[FLDDB. .CMIFI]         ;SPECIFY INPUT FILE
  85.         CALL RFIELD                     ;GET FILE NAME BEING RENAMED
  86.         MOVEM B,IJFN                    ;REMEMBER IT
  87.         NOISE (TO BE)
  88.         MOVEI A,[FLDDB. .CMOFI]         ;SPECIFY OUTPUT FILE
  89.         CALL CFIELD                     ;GET NEW NAME AND END OF COMMAND
  90.         MOVEM B,OJFN
  91.         MOVE A,IJFN                     ;GET OLD NAME
  92.         RNAMF                           ;RENAME THE FILE
  93.          JSERR                          ;REPORT IF ERROR
  94.         MOVE A,OJFN                     ;GET RID OF JFN
  95.         RLJFN
  96.          JSERR                          ;REPORT IF ERROR
  97.         RET                             ;GO BACK FOR NEXT COMMAND
  98.  
  99. wrdlst: n,,n
  100.         t EXIT
  101.         T RENAME
  102. n==.-wrdlst-1
  103.  
  104. CMDSTG                                  ;ALLOCATE COMND JSYS STORAGE
  105. IJFN:   0                               ;INPUT FILE
  106. OJFN:   0                               ;OUTPUT FILE
  107. PDL:    BLOCK 200                       ;STACK SPACE
  108.  
  109. END BEG
  110.                                                       Page 3
  111.  
  112.  
  113. 5.0  SPECIFIC FEATURES AVAILABLE WITH CMD
  114.  
  115. 5.1  Telling MACRO And LINK That You Are Using The Package
  116.  
  117. Include the following two statements near the  beginning  of
  118. your source code.
  119.  
  120.         SEARCH CMD
  121.         .REQUIRE SYS:CMD
  122.  
  123. These two statements make the CMD package available to  your
  124. program.
  125.  
  126.  
  127.  
  128. 5.2  Initializing Your Program To Input Commands
  129.  
  130. Before prompting for  the  first  command  in  the  program,
  131. execute the following call:
  132.  
  133.         CALL CMDINI
  134.  
  135. The CMDINI routine should be called only once per running of
  136. the program.
  137.  
  138.  
  139.  
  140. 5.3  Allocating Storage For The Command Database
  141.  
  142. The following statement causes the database  for  the  COMND
  143. JSYS to be reserved.
  144.  
  145.         CMDSTG
  146.  
  147. Put this statement somewhere in your variable area  of  your
  148. program.
  149.  
  150.  
  151.  
  152. 5.4  Prompting For A Command
  153.  
  154. To prompt for a command, or new line of a command,  use  the
  155. PROMPT macro, like this:
  156.  
  157.         PROMPT (FOO)
  158.  
  159. The PROMPT macro causes the text in parentheses to be output
  160. as the prompt for the command line.
  161.                                                       Page 4
  162.  
  163.  
  164. 5.5  Reading A Field Of A Command
  165.  
  166. Load AC1 with the address of a COMND JSYS function block and
  167. call the RFIELD routine.  The following example shows how to
  168. read an input filespec:
  169.  
  170.         MOVEI A,[FLDDB. .CMIFI]
  171.         CALL RFIELD
  172.  
  173. The RFIELD routine returns with the result of the COMND JSYS
  174. in  AC1  and  AC2.   For  the  above example, a JFN would be
  175. returned in AC2.  The RFIELD  routine  handles  all  details
  176. such as reparsing and errors.
  177.  
  178.  
  179.  
  180. 5.6  Inputting The End Of The Command
  181.  
  182. To  require  the  typist  to  end  the  command  line  at  a
  183. particular point, use the CONFRM macro, like this:
  184.  
  185.         CONFRM
  186.  
  187.  
  188.  
  189.  
  190. 5.7  Inputting A Field Of A Command Followed By End Of Line
  191.  
  192. Since it is common to input a field followed by end of line,
  193. the  CFIELD  routine  is  supplied,  which  is  exactly like
  194. RFIELD, except it inputs end of line after the  field.   The
  195. call is as follows:
  196.  
  197.         CALL CFIELD
  198.  
  199.  
  200.  
  201. 5.8  Guide Words
  202.  
  203. To put guide words in a command, make the following call:
  204.  
  205.         NOISE (words)
  206.  
  207. The NOISE macro causes whatever text is in  the  parentheses
  208. to be used as the guide words.
  209.  
  210.  
  211.  
  212. 5.9  Keyword Table Entries
  213.  
  214. A macro called T is available to make it  easy  to  assemble
  215. keyword table entries.  The format is
  216.  
  217.         T word,data
  218.                                                       Page 5
  219.  
  220.  
  221. where "word" is the keyword, and "data" is specific data for
  222. the  keyword.   The  T  macro creates a word in memory whose
  223. left half points to the ASCIZ representation  of  the  word,
  224. and whose right half points to a word containing the data.
  225.  
  226. The "data" argument  defaults  to  ".word".   Hence  in  the
  227. common  case,  where the data for a keyword is the macro tag
  228. for the suuport code for that keyword, the call may be given
  229. like this:
  230.  
  231.         T word
  232.  
  233. This call requires you to have  the  support  code  for  the
  234. specified word elsewhere in your program, like this:
  235.  
  236. .word:  code
  237.         .   .   .
  238.         .   .   .
  239.         .   .   .
  240.  
  241.  
  242.  
  243.  
  244. 5.10  Special Other Details
  245.  
  246. The FLDDB.  macro (defined  in  MONSYM),  and  the  chaining
  247. facility  of  function  descriptor blocks generally provides
  248. enough  flexibility  for  creativity  of  command   language
  249. designs.   However,  for  the more devious, the following is
  250. revealed:
  251.  
  252.  
  253.  
  254. 5.10.1  Error Processing - If a user error is made, the  CMD
  255. module  normally prints an error message and allows the user
  256. to correct the mistake (with ^H) or issue  another  command.
  257. If you want your program to do its own error processing, you
  258. may call a routine called RFLDE instead  of  RFIELD.   RFLDE
  259. has an error return, like this:
  260.  
  261.         CALL RFLDE
  262.          ;+1 return means error
  263.         ;+2 return means success
  264.  
  265. Your error return should transfer off to code  which  prints
  266. some  sort  of error message.  Then transfer to CMDER1, like
  267. this:
  268.  
  269.         JRST CMDER1
  270.  
  271. CMDER1 takes responsibility for reprompting for the  command
  272. line  on  which  the error occured, and allowing the user to
  273. correct or retype the erroneous line.
  274.                                                       Page 6
  275.  
  276.  
  277. 5.10.2  GTJFN Block - The GTJFN  argument  block  is  called
  278. CJFNBK.   Note that to set up a default filespec, you merely
  279. need to put a pointer to the default spec  in  the  function
  280. descriptor block, so for setting up defaults, you don't need
  281. to explicitly reference CJFNBK.
  282.  
  283.  
  284.  
  285. 5.10.3  Command State Block - The COMND JSYS's command state
  286. block  is  called SBK.  Since the CMDINI routine sets it up,
  287. you normally shouldn't have to reference it.
  288.  
  289.  
  290.  
  291. 5.10.4  Custom Prompting - Sometimes,  the  prompt   for   a
  292. command  wants  to  be  computed  during  the running of the
  293. program.  For instance, a game program might want to type
  294.  
  295.         YOUR FIFTH MOVE:
  296.  
  297. as its prompt.   For  this  case,  the  PROMPT  macro  isn't
  298. sufficient.
  299.  
  300. The general  prompting  routine  is  call  DPROMPT.   It  is
  301. important  that  your  program  call  it,  or use the PROMPT
  302. macro.  Otherwise, reparsing (the magic  that  happens  when
  303. typist  deletes  parsed  characters) won't happen correctly.
  304. That is, don't just call RFIELD with the .CMINI function!
  305.  
  306. For the above example, suppose the game program had  created
  307. the desired string and stored it in an area of memory tagged
  308. with MOVMES.  The program may type the prompt like this:
  309.  
  310.         HRROI A,MOVMES
  311.         CALL DPROMPT
  312.  
  313. The DPROMPT routine assumes A  contains  a  pointer  to  the
  314. prompt string.
  315.