MAILMAN: User Question & Answer Driver and Validator    ICR (1149)

NOTICE!  NOTICE!  NOTICE!

XMAREAD supported calls are being RETIRED.  Use FileMan's ^DIR instead.

^XMAREAD contains the following application programmer functions:

$$READ^XMAREAD(prompt,question_type,default,anti-illegals_flag,.help_array) is
a question and answer driver that will allow the caller to specify a question
type, a prompt and a default.

$$CHECK^XMAREAD(question_type,string-to-be-tested) is a silent form of
$$READ^XMAREAD, e.g. it does not ask questions.




$$READ^XMAREAD(prompt,question_type,default,anti-illegals_flag,.help_array)

This function is a question and answer driver that will allow the caller to
specify a question type, a prompt and a default.  The senders' exact input or
the default (except in the case where a "Yes" or "No" question is answered) is
returned to the caller.  All basic input checking is completed without
changing or setting any variables.

Suggestions for Improvement to this interface are welcomed.


The way the function is used is as follows:

Usage: S X=$$READ^XMAREAD(A,B,C,D,.E)

Where: A (prompt) is a string that will be used as a prompt
B (question_type) is a question type C (default) is the default
answer to the questions
D (no_illegals_flag) If non-zero, do not store illegal characters
E (.help_array) is the array of help text (leading period is
required!)


There are four different types of questions (second parameter):

U      Abort (This question type will always append the message
"Enter <RET> to continue, "^" to abort")
F      Free Text
N      Number
Y      Yes or No


Illegal characters are control characters and any of these:
@^!()#~_-=%$|[]\""><


The value returnable for each type is:

Type   Handling

U      Whatever the user types -- the caller must interpret it.

F      A string of 3-30 characters which does not contain any control
characters or @, ^, !, (, ), #, -, _, =, %, $, |, [, ], \,", <, >.  If the
third parameter is non-zero and not null or the variable XMREADNO exists,
special characters are allowed.  Otherwise only numbers, spaces and letters
are accepted.

N      Only integers are acceptable inputs.

Y      Any leading substrings of "Yes" or "No" are acceptable.  In either
case, "1" is returned for Yes, "0" for No.



$$CHECK^XMAREAD(Y,Z)

This function is the same as $$READ^XMAREAD, except it does not ask questions.
It merely puts any answers through a validity check.

Usage: S X=$$CHECK^XMAREAD(Y,Z)

Where: Y = The Type (U,N,F, or Y)
Z = The input to be validated

If the input is valid, the null string is returned.  If the input is NOT
valid, a text string which documents why the string is not valid is returned.