CMD ___ 1.0 OVERVIEW The CMD package makes it very easy for MACRO programs use the COMND JSYS in order to provide the MACRO program's user to be able to type TOPS20 style commands to the program, including all standard TOPS20 features such as recognition, question mark, CTRL/H etc. The CMD package is a valuable tool several reasons, uncluding: 1) The programmer needn't allocate any special COMND JSYS buffers and blocks. 2) The programmer needn't provide initialization code to set up pointers and blocks for the COMND JSYS. 3) The programmer needn't provide special code to handle "cleaning up" associated with reparsing and error returns. In general, all the program must do when using CMD, is supply the field-specific data for the individual parts of the command being parsed. CMD does most of the rest. 2.0 NONGOAL The CMD package does not attempt to provide any method of generating entire command languages, such as structure trees. It only provides primitives from which such things as structure trees may be designed. 3.0 SAMPLE RUN The following is a typescript of the running of a program called CMTEST, which features two commands, EXIT and RENAME. The program uses the CMD package. @RUN CMTEST CMTEST>? ONE OF THE FOLLOWING: EXIT RENAME CMTEST>RENAME (EXISTING FILE) FOO.ERT.1 (TO BE) ZOT.BAR CMTEST>EXIT ? CONFIRM WITH CARRIAGE RETURN CMTEST>EXIT @ Page 2 4.0 PROGRAM LISTING The following program listing shows how the CMD package is utilized to implement commands. title CMTEST search monsym,macsym,CMD .require sys:macrel,sys:CMD beg: RESET MOVEI P,PDL-1 ;SET UP STACK CALL CMDINI ;INITIALIZE COMND JSYS LUP: PROMPT (CMTEST>) ;PROMPT FOR COMMAND MOVEI A,[FLDDB. .CMKEY,,WRDLST] ;SPECIFY WE WANT A KEYWORD CALL RFIELD ;READ COMMAND MOVE A,(B) ;GET ADDRESS OF COMMAND ROUTINE CALL (A) ;EXECUTE THE COMMAND JRST LUP ;GO GET NEXT COMMAND .EXIT: CONFRM ;WAIT FOR END OF LINE HALTF ;EXIT COMMAND CAUSES STOP RET ;GET NEXT COMMAND IF CONTINUE .RENAM: NOISE (EXISTING FILE) MOVEI A,[FLDDB. .CMIFI] ;SPECIFY INPUT FILE CALL RFIELD ;GET FILE NAME BEING RENAMED MOVEM B,IJFN ;REMEMBER IT NOISE (TO BE) MOVEI A,[FLDDB. .CMOFI] ;SPECIFY OUTPUT FILE CALL CFIELD ;GET NEW NAME AND END OF COMMAND MOVEM B,OJFN MOVE A,IJFN ;GET OLD NAME RNAMF ;RENAME THE FILE JSERR ;REPORT IF ERROR MOVE A,OJFN ;GET RID OF JFN RLJFN JSERR ;REPORT IF ERROR RET ;GO BACK FOR NEXT COMMAND wrdlst: n,,n t EXIT T RENAME n==.-wrdlst-1 CMDSTG ;ALLOCATE COMND JSYS STORAGE IJFN: 0 ;INPUT FILE OJFN: 0 ;OUTPUT FILE PDL: BLOCK 200 ;STACK SPACE END BEG Page 3 5.0 SPECIFIC FEATURES AVAILABLE WITH CMD 5.1 Telling MACRO And LINK That You Are Using The Package Include the following two statements near the beginning of your source code. SEARCH CMD .REQUIRE SYS:CMD These two statements make the CMD package available to your program. 5.2 Initializing Your Program To Input Commands Before prompting for the first command in the program, execute the following call: CALL CMDINI The CMDINI routine should be called only once per running of the program. 5.3 Allocating Storage For The Command Database The following statement causes the database for the COMND JSYS to be reserved. CMDSTG Put this statement somewhere in your variable area of your program. 5.4 Prompting For A Command To prompt for a command, or new line of a command, use the PROMPT macro, like this: PROMPT (FOO) The PROMPT macro causes the text in parentheses to be output as the prompt for the command line. Page 4 5.5 Reading A Field Of A Command Load AC1 with the address of a COMND JSYS function block and call the RFIELD routine. The following example shows how to read an input filespec: MOVEI A,[FLDDB. .CMIFI] CALL RFIELD The RFIELD routine returns with the result of the COMND JSYS in AC1 and AC2. For the above example, a JFN would be returned in AC2. The RFIELD routine handles all details such as reparsing and errors. 5.6 Inputting The End Of The Command To require the typist to end the command line at a particular point, use the CONFRM macro, like this: CONFRM 5.7 Inputting A Field Of A Command Followed By End Of Line Since it is common to input a field followed by end of line, the CFIELD routine is supplied, which is exactly like RFIELD, except it inputs end of line after the field. The call is as follows: CALL CFIELD 5.8 Guide Words To put guide words in a command, make the following call: NOISE (words) The NOISE macro causes whatever text is in the parentheses to be used as the guide words. 5.9 Keyword Table Entries A macro called T is available to make it easy to assemble keyword table entries. The format is T word,data Page 5 where "word" is the keyword, and "data" is specific data for the keyword. The T macro creates a word in memory whose left half points to the ASCIZ representation of the word, and whose right half points to a word containing the data. The "data" argument defaults to ".word". Hence in the common case, where the data for a keyword is the macro tag for the suuport code for that keyword, the call may be given like this: T word This call requires you to have the support code for the specified word elsewhere in your program, like this: .word: code . . . . . . . . . 5.10 Special Other Details The FLDDB. macro (defined in MONSYM), and the chaining facility of function descriptor blocks generally provides enough flexibility for creativity of command language designs. However, for the more devious, the following is revealed: 5.10.1 Error Processing - If a user error is made, the CMD module normally prints an error message and allows the user to correct the mistake (with ^H) or issue another command. If you want your program to do its own error processing, you may call a routine called RFLDE instead of RFIELD. RFLDE has an error return, like this: CALL RFLDE ;+1 return means error ;+2 return means success Your error return should transfer off to code which prints some sort of error message. Then transfer to CMDER1, like this: JRST CMDER1 CMDER1 takes responsibility for reprompting for the command line on which the error occured, and allowing the user to correct or retype the erroneous line. Page 6 5.10.2 GTJFN Block - The GTJFN argument block is called CJFNBK. Note that to set up a default filespec, you merely need to put a pointer to the default spec in the function descriptor block, so for setting up defaults, you don't need to explicitly reference CJFNBK. 5.10.3 Command State Block - The COMND JSYS's command state block is called SBK. Since the CMDINI routine sets it up, you normally shouldn't have to reference it. 5.10.4 Custom Prompting - Sometimes, the prompt for a command wants to be computed during the running of the program. For instance, a game program might want to type YOUR FIFTH MOVE: as its prompt. For this case, the PROMPT macro isn't sufficient. The general prompting routine is call DPROMPT. It is important that your program call it, or use the PROMPT macro. Otherwise, reparsing (the magic that happens when typist deletes parsed characters) won't happen correctly. That is, don't just call RFIELD with the .CMINI function! For the above example, suppose the game program had created the desired string and stored it in an area of memory tagged with MOVMES. The program may type the prompt like this: HRROI A,MOVMES CALL DPROMPT The DPROMPT routine assumes A contains a pointer to the prompt string.