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.