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
uncluding:
is
a
valuable
tool
several
any
reasons,
1)
The programmer needn't allocate
JSYS buffers and blocks.
special
COMND
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
utilized to implement commands.
package
is
title CMTEST
search monsym,macsym,CMD
.require sys:macrel,sys:CMD
beg:
LUP:
.EXIT:
RESET
MOVEI P,PDL-1
CALL CMDINI
PROMPT (CMTEST>)
MOVEI A,[FLDDB. .CMKEY,,WRDLST]
CALL RFIELD
MOVE A,(B)
CALL (A)
JRST LUP
;SET UP STACK
;INITIALIZE COMND JSYS
;PROMPT FOR COMMAND
;SPECIFY WE WANT A KEYWORD
;READ COMMAND
;GET ADDRESS OF COMMAND ROUTINE
;EXECUTE THE COMMAND
;GO GET NEXT COMMAND
CONFRM
HALTF
RET
;WAIT FOR END OF LINE
;EXIT COMMAND CAUSES STOP
;GET NEXT COMMAND IF CONTINUE
.RENAM: NOISE (EXISTING FILE)
MOVEI A,[FLDDB. .CMIFI]
CALL RFIELD
MOVEM B,IJFN
NOISE (TO BE)
MOVEI A,[FLDDB. .CMOFI]
CALL CFIELD
MOVEM B,OJFN
MOVE A,IJFN
RNAMF
JSERR
MOVE A,OJFN
RLJFN
JSERR
RET
;SPECIFY INPUT FILE
;GET FILE NAME BEING RENAMED
;REMEMBER IT
;SPECIFY OUTPUT FILE
;GET NEW NAME AND END OF COMMAND
;GET OLD NAME
;RENAME THE FILE
;REPORT IF ERROR
;GET RID OF JFN
;REPORT IF ERROR
;GO BACK FOR NEXT COMMAND
wrdlst: n,,n
t EXIT
T RENAME
n==.-wrdlst-1
CMDSTG
IJFN:
OJFN:
PDL:
END BEG
0
0
BLOCK 200
;ALLOCATE COMND JSYS STORAGE
;INPUT FILE
;OUTPUT FILE
;STACK SPACE
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
your source code.
beginning
of
SEARCH CMD
.REQUIRE SYS:CMD
These two statements make the CMD package available to
program.
5.2
your
Initializing Your Program To Input Commands
Before prompting for the first
execute the following call:
command
in
the
program,
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
JSYS to be reserved.
for
the
COMND
CMDSTG
Put this statement somewhere in your variable area
program.
5.4
of
your
Prompting For A Command
To prompt for a command, or new line of a command,
PROMPT macro, like this:
use
the
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
particular point, use the CONFRM macro, like this:
at
a
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
to be used as the guide words.
5.9
the
parentheses
Keyword Table Entries
A macro called T is available to make it
easy
to
assemble
keyword table entries.
T word,data
The format is
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
specified word elsewhere in your program, like this:
.word:
5.10
code
.
.
.
.
.
.
the
.
.
.
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.
sufficient.
For
this
case,
the
PROMPT
macro
isn't
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
prompt string.
contains
a
pointer
to
the