The Programmer's Guide to TRSDOS Version 6 - Tim Mann's Home ...

8.13 USING @PARAM
The @PARAM SuperVisor Call is used in practically all DOS library commands and utilities
as well as filters, drivers, and languages. Since you are already familiar with the DOS
commands, you should recognize the wide range of input syntax parsed and interpreted by
@PARAM. The SVC is used to decode TRUE/FALSE parameters (by either entering or not
entering a parameter word), YES/NO parameters (by using PARM=Y or PARM=N), ON/OFF
parameters (by using PARM=ON or PARM=OFF), decimal values (by entering PARM=ddddd),
hexadecimal values (by entering PARM=X'xxxx'), and character string values (by entering
PARM="characterstring"). Parameter entries can be made in either upper case or lower case
- even with hexadecimal digits (A-F equally acceptable as a-f).
The system parses a complex parameter string that may be composed of many parameters -
each separated from the other by a comma. The interpreted entries are passed back to
@PARAM caller according to the parameter table designed by the programmer. Version 6
supports two types of parameter tables. The first type is the fixed width table which was
supported under Version 5.
The second type is a variable width table that supports additional information. In the
following discussions, we will first illustrate the former table. You should have already
read the information in chapter 7 covering the @PARAM SuperVisor Call.
Let's assume we have an application that offers the user varying options to set up the
function of the application. In BASIC, this may be the number of files or protected
memory size. In BACKUP, this may be the diskette master password or date range of files
to select. In SETCOM, this may be whether CTS is to be honored. How do we get this
information to the program? We could prompt the user by a prompt message for each and
every parameter that needs to be determined. Experienced users soon get tired of prompts.
Inexperienced users get extremely frustrated when the system requires an inflexible
syntax for the entry of options. How can everyone be satisfied - from novice to expert?
Why, by using @PARAM.
We will propose a hypothetical application requiring the determination of five options:
1. A length field used in ascertaining the number of print columns of output. This
should default to 80 to denote an 80 column printer if no entry is made. The
range should be limited to 32-255.
2. A module specification field to indicate whether line feeds are to be added
after carriage return, removed after carriage return, or no checking is to be
performed.
3. A title field to be placed on each page of output. In addition, paging is to be
suppressed if no titling is desired. Furthermore, the default is to incorporate
paging unless otherwise specified by the user.
4. A prompting specification to note whether prompts for changing paper are to be
made at the appropriate time if sheet paper is used or omitted if tractor feed
paper is used. The default should be no prompting.
5. A translation option for converting a character on output. This should default
to no translation.
The first thing required by the system designer is to designate "words" for the command
line parameters. They should be chosen to be as easily remembered as possible. They
should be greatly correlated in definition to the function they are specifying.
Additionally, abbreviations should be considered in addition to the full "word". Thought
should be given to using words whose first character is different for each parameter so
as to provide single character abbreviations. However, if any parameter is omnipotent,
care should be exercised in designating an abbreviation.
8-30