General Points
--------------

* Calling a command with a parameter of ?? gives help info for the command
* Calling a command with a parameter of ? makes the system prompt for each
     parameter
* Replying ? to a parameter prompt gives help for the parameter
* Parameter values may be given by position or keyword but no positional
     values after keywords
* The parameter line as typed is divided into 'values' at 'visible' commas
     Commas become invisible when enclosed in matching brackets or when
     they appear in quoted strings.  For example these are single values

             abcdef
             ((a+b),(c+d))
             """abc,,,,((([[[{{{"

* Multiple values can be given for the first parameter of a command.  The 
  effect is not visible to the command - although it can indicate that such
  a call is not acceptable - and the action is to call the command repeatedly
  for each value.  Multiple values can be specified either explicitly:

              Command: analyse file1 & file2 & file3

   or by 'wild-carding' a filename:

              Command: analyse *ion

   which would call analyse for each filename that is returned from a call
  of files *ion.
* The case of letters is not significant.  Names of system objects are
  returned in lower case  ie files, groups, users.
* Typing Cntrl Y during parameter acquisition causes an immediate
  return to command level.

Getting values for parameters
-----------------------------

The specifications of the routines which return values to a command are:
%externalroutinespec GET STRING(%stringname vector, %stringname value)
%externalroutinespec GET INTEGER(%stringname vector, %integername value)
%externalroutinespec GET REAL(%stringname vector, %realname value)

 VECTOR describes the parameter required.  A vector has five components
separated by ';':
              prompt ; qualifier ; default ; help ; key

   prompt    produced if the parameter is prompted for
   qualifier defines the acceptable values for the parameter
   default   replaces a null text.  It may itself be null.  If there
             is no default, a ? is written here
   help      the text printed when ? is given in response to a prompt
   key       the 'name' of the parameter.

 The qualifiers provided by the system for integer parameters are:

   any    ie any integer
   m:n    where m and n are integers or null, for example
             1:   means a number greater than zero
             :1  a number less than two
   a sequence of ranges or values, for example
      0:3,5,8,10:12
   options1   null gives 0, * gives -1 and A to Z ( and a to z )
           sets bit 2 ** (char - 'A')
   { route - one day }

 The qualifiers for string parameters are:
                 { *** still being extended *** }
   any    any string
   grouporfileormem   {Analyse}
   grouporfile   (Cherish)
   fileormem   {Copy}
   document   {Deletedoc}
   document1   {Documents - doc no or null}
   files1   {Files}
   filelist   {List}
   file   {Restore}
   date   {dd/mm/yy}
   user   {Tell}
   source   {IMP}
   object   {IMP}
   errors   {IMP}
   device   {List}


An example of a vector is:
    %conststring(255) V = "Users fsys;0:15;?;the number of the file system;FSYS"
and this could be used in the call:
      get integer(v, fsys)

 Fields in a vector may be omitted (from the right by omitting semi-colons ):
      Prompt defaults to Integer ( or String etc )
      Qualifier defaults to any
      Default defaults to ? ie none
      Help defaults to the qualifier
      Key defaults to the prompt

For example

   get integer("", j)   prompts for Integer and accepts any integer value
   get string("Output file;file", file)
   get integer("Number of copies;1:15;1", copies)

Tags for String Qualifiers
--------------------------

String qualifiers may be further described by tags.  Tags follow the qua
qualifier and are separated by commas.  Available tags are:

			uc
			lc
			ornull
			wild
			despace

For example,

       get string("File;file,uc,ornull;;", filename)

obtains a filename or a null string and returns its value in upper case.

Using your own parameter checking routine
-----------------------------------------

 A command writer can nominate his own parameter checking
 routines.  Such a routine checks whether the text supplied for
 parameter 'key' of command 'command' is acceptable.  If it is, the value
 to be used is stored in 'value' and 'flag' set to 0.  Else 'flag'
 should be set non zero.  The specification for each such routine is:

%externalroutine MYSCHECK(%stringname command, key, text,
   %stringname value, %integername flag))

%externalroutine MYICHECK(%stringname command, key, text,
   %integername value, %integername flag))

%externalroutine MYRCHECK(%stringname command, key, text,
   %realname value, %integername flag))

 To nominate your own checking routine in a vector, give its
 name preceded by 'call ':

      "Roman numeral;call checker"

 Providing more extensive HELP information
 -----------------------------------------

 If the command writer wishes to provide more extensive help
 information, or help information for the command as a whole rather
 than at the parameter level, he can either call his own
 routine, which will be passed 'command' and 'key' as parameters,
 or he can call system routine PAMHELP giving as its parameter
 the name of a file in VIEW format, eg

      "Roman numeral;call checker;?;call rnhelp"
 or   "Roman numeral;call checker;?;call pamhelp(ercc04:rnhelpfile)"

 PAMHELP displays the section called 'command' in response to ??
 and subsection 'key' of section 'command' in response to ?

 Miscellaneous Facilities
 ------------------------

%externalroutinespec GET REST OF LINE(%stringname text)

 This returns what remains of the whole parameter string at any time
(non destructively).

%externalroutinespec CHECK STRING(%stringname text, qualifier,
          %stringname value, %integername flag)

%externalroutinespec CHECK INTEGER(%stringname text, qualifier,
          %integername value, %integername flag)

%externalroutinespec CHECK REAL(%stringname text, qualifier,
          %realname value, %integername flag)

These routines use the system qualifiers to check whether 'text'
provides an acceptable value.

The commands CHECK STRING etc allow these routines to be exercised
from the console:

%externalroutine check s %alias "C#CHECKSTRING"
%string(255)txt, qual, val
%integer flag
getstring("Text", txt)
getstring("Qualifier", qual)
checkstring(txt, qual, val, flag)
printstring("Flag =");  write(flag, 1)
printstring("   Value = ") %and printstring(val) %if flag = 0
newline
%end; ! check s

Tony Gibbons 15 Jul 85