{
{   A parameter dialog manager is a procedure called by the SCL interpreter
{ during parameter evaluation to obtain parameter values, corrections, etc.
{ for screen or desktop style interactions.
{
{       parameter_dialog_manager (SUPPORT, COMMAND_OR_FUNCTION_NAME,
{         ONLINE_MANUAL_NAME, PARAMETER_DESCRIPTION_TABLE, CANCEL, STATUS)
{
{ SUPPORT: (input)  This parameter specifies the procedures to be called for
{       various parameter dialog support activities.  Each field of the record
{       points to the procedure that implements a particular support request.
{       For those requests that return a pointer to some object (e.g.
{       "message" or "representation"), the pointer becomes invalid upon making
{       another support request.
{
{
{       The following requests ask for the corresponding messages from the
{       command's or function's "help module" to be returned.
{
{             support.GET_BRIEF_HELP (MAX_MESSAGE_LINE, MESSAGE, STATUS)
{
{       MAX_MESSAGE_LINE: (input)  This parameter specifies the maximum size a
{             line of the message can be.
{
{       MESSAGE: (output)  This parameter specifies the returned message.  The
{             message has the same structure as that returned by the
{             osp$format_help_message request.  NIL is returned is there is no
{             such message.
{
{       STATUS: (output)  This parameter specifies the request status.
{
{
{             support.GET_FULL_HELP (MAX_MESSAGE_LINE, MESSAGE, STATUS)
{
{       MAX_MESSAGE_LINE, MESSAGE, STATUS: See above.
{
{
{             support.GET_PARAMETER_PROMPT (PARAMETER_NUMBER, MAX_MESSAGE_LINE,
{                   MESSAGE, STATUS)
{
{       PARAMETER_NUMBER: (input)   This parameter specifies the number of the
{             command's or function's parameter being interrogated.
{
{       MAX_MESSAGE_LINE: See above.
{
{       MESSAGE: See above, except that NIL is not returned.  If there is no
{             prompt defined for the parameter, one is constructed from the
{             "nominal" name of the parameter.
{
{       STATUS: See above.
{
{
{             support.GET_PARAMETER_ASSIST_PROMPT (PARAMETER_NUMBER,
{                   MAX_MESSAGE_LINE, MESSAGE, STATUS)
{
{       PARAMETER_NUMBER, MAX_MESSAGE_LINE, MESSAGE, STATUS: See above.
{
{
{             support.GET_PARAMETER_HELP (PARAMETER_NUMBER, MAX_MESSAGE_LINE,
{                   MESSAGE, STATUS)
{
{       PARAMETER_NUMBER, MAX_MESSAGE_LINE, MESSAGE, STATUS: See above.
{
{
{       The following request asks for the "source" representation of the
{       specifications for all of the command's or function's parameters.
{
{             support.GET_ALL_PARAMETER_SPECS (INCLUDE_ADVANCED_ITEMS,
{                   MAX_REPRESENTATION_LINE, REPRESENTATION, STATUS)
{
{       INCLUDE_ADVANCED_ITEMS: (input)  This parameter specifies whether the
{             representation should include "advanced" parameters and keywords.
{
{       MAX_REPRESENTATION_LINE: (input)  This parameter specifies the
{             maximum size a line of the representation can be.
{
{       REPRESENTATION: (output)  This parameter specifies the returned
{             representation.  The representation has the same structure as
{             that returned by the clp$convert_data_to_string request.
{
{       STATUS: See above.
{
{
{       The following request asks for the "source" representation of the
{       specification for a particular command or function parameter.
{
{             support.GET_PARAMETER_SPEC (PARAMETER_NUMBER,
{                   INCLUDE_ADVANCED_KEYWORDS, MAX_REPRESENTATION_LINE,
{                   REPRESENTATION, STATUS)
{
{       INCLUDE_ADVANCED_KEYWORDS: (input)  This parameter specifies whether
{             the representation should include "advanced" keywords.
{
{       PARAMETER_NUMBER, MAX_REPRESENTATION_LINE, REPRESENTATION, STATUS:
{             See above.
{
{
{       The following request asks for the evaluated form of the value for a
{       particular command or function parameter.  This request can also be
{       used to determine whether a parameter was specified (and evaluated)
{       prior to calling the parameter dialog manager.
{
{             support.GET_PARAMETER_VALUE (PARAMETER_NUMBER, VALUE, STATUS)
{
{       PARAMETER_NUMBER:  See above.
{
{       VALUE: (output)  This parameter specifies the parameter value.
{
{       STATUS:  See above.
{
{
{       The following request asks for the "source" representation of the
{       value for a particular command or function parameter.  This request
{       should only be used for a parameter that has been evaluated (e.g.  via
{       a "support.EVALUATE_PARAMETER" request).
{
{             support.GET_PARAMETER_VALUE_SOURCE (PARAMETER_NUMBER,
{                   MAX_REPRESENTATION_LINE, REPRESENTATION, STATUS)
{
{       PARAMETER_NUMBER, MAX_REPRESENTATION_LINE, REPRESENTATION, STATUS:
{             See above.
{
{
{       The following request asks for the text of the default expression for a
{       command or function parameter to  returned.
{
{             support.GET_PARAMETER_DEFAULT (PARAMETER_NUMBER, TEXT, STATUS)
{
{       PARAMETER_NUMBER: See above.
{
{       TEXT: (output)   This parameter specifies the text of the default
{             expression.  If the parameter has no default, NIL is returned.
{             If the parameter has a "default variable" associated with it
{             and that variable is defined, its value is returned.  Otherwsie
{             the parameter's default expression is returned.
{
{       STATUS: See above.
{
{
{       The following request asks for an expression for a command or
{       function parameter to be evaluated.  If support.CHANGE_EXPRESSION_SAVE
{       is available (non-NIL) this request saves parameters according to the
{       most recent call made to it.  In that request's absence or if it is
{       not called, expression results are saved for parameters.  Also, if
{       that request is available and the attempt to evaluate the expression
{       fails, the source of the expression is saved for the parameter.
{
{             support.EVALUATE_PARAMETER (PARAMETER_NUMBER, TEXT, STATUS)
{
{       PARAMETER_NUMBER: See above.
{
{       TEXT: (input)   This parameter specifies the text of the expression
{             to be evaluated.
{
{       STATUS: See above.
{
{
{       The following request asks that the default specification for a
{       command or function parameter be restored, i.e. that any explicitly
{       specified value be erased.
{
{             support.RESTORE_PARAMETER_DEFAULT (PARAMETER_NUMBER, STATUS)
{
{       PARAMETER_NUMBER, STATUS: See above.
{
{
{       The following request asks that all command or function parameters
{       be verified.  This includes evaluation of default specifications for
{       optional parameters and checking that all required parameters have been
{       given.  All user supplied values for parameters must have been
{       evaluated via "support.EVALUATE_PARAMETER" requests.
{
{             support.VERIFY_ALL_PARAMETERS (ERROR_LOCATOR, STATUS)
{
{       ERROR_LOCATOR: (output)  This paramter specifies which, if any,
{             command or function parameter was in error, and is only
{             meaningful when STATUS is abnormal.  It may indicate the
{             particular parameter that was incorrect, or that the error
{             is not specific to any parameter.
{
{       STATUS: See above.
{
{
{       The following request asks that if there is an online manual defined
{       for the command, that it be invoked for an explanation of the command
{       or function.
{
{             support.EXPLAIN (EXPLANATION_AVAILABLE, STATUS)
{
{       EXPLANATION_AVAILABLE: (output)  This parameter specifies whether
{             sufficient information was available to call up an online
{             manual for the command or function.
{
{       STATUS: See above.
{
{
{       The following request asks that all of the names of the command or
{       function be returned.
{
{             support.GET_ALL_NAMES (NAMES, STATUS)
{
{       NAMES: (output)  This parameter specifies all of the names of the
{             command or function.
{
{       STATUS: See above.
{
{
{       The following request asks that the source of the command or
{       function be returned.  The source is the full path of a library
{       or catalog, a command utility's name, or $SYSTEM.
{
{             support.GET_SOURCE (SOURCE_STRING, SOURCE_STRING_SIZE, STATUS)
{
{       SOURCE_STRING: (output)  This parameter specifies a string representing
{             the source of the command or function.
{
{       SOURCE_STRING_SIZE: (output)  This parameter specifies the "trimmed"
{             size of SOURCE_STRING.
{
{       STATUS: See above.
{
{
{       Support.HELP_MODULE is a pointer to the help module for the command or
{       function.  NIL indicates there is no help module.
{
{
{       The following request is only available (its pointer is not NIL) if the
{       command or function has been called for the purpose of "editing" its
{       parameter list (e.g.  via clp$edit_command_parameter_list).  It enables
{       the parameter dialog manager to control what is saved for a parameter's
{       value: the expression as supplied by the user, or the result of
{       evaluating that expression.  When this request is available
{       support.EVALUATE_PARAMETER will save the source of the expression for
{       the parameter even if it could not be successfully evaluated.  This
{       enables the user to construct a parameter list that doesn't evaluate
{       correctly now, but will (presumably) when it is actually used.
{
{             support.CHANGE_EXPRESSION_SAVE (SAVE_EXPRESSION_SOURCE, STATUS)
{
{       SAVE_EXPRESSION_SOURCE: (input) This parameter specifies whether the
{             source of expressions should be saved for parameters (TRUE) or
{             the results of expressions should be saved (FALSE).
{
{       STATUS: See above.
{
{
{       The following request asks for a nested parameter dialog to occur.
{       This is intended for use with record types but could be used for other
{       purposes also.  The effect of this request is to recursively call the
{       parameter evaluation procedure which will, in turn, recursively call
{       dialog manager.  Once this nested dialog is completed, the source
{       representation of the resulting parameter list is returned.
{
{             support.NESTED_DIALOG (TEXT, DIALOG_PDT, DIALOG_TITLE,
{                   MAX_REPRESENTATION_LINE, REPRESENTATION, STATUS)
{
{       TEXT: (input)   This parameter specifies the text of the expression
{             representing the current value of the record.
{
{       DIALOG_PDT: (input)  This parameter specifies the Parameter Description
{             Table for the nested dialog.
{
{       DIALOG_TITLE: (input)  This parameter specifies the string to be used
{             to label the dialog for the record fields.
{
{       MAX_REPRESENTATION_LINE, REPRESENTATION, STATUS:
{             See above.
{
{
{       Support.NESTED_DIALOG_TITLE is a pointer to the "title" to be used for
{       a nested dialog, e.g. one resulting from a call to support.ZOOM_RECORD.
{       NIL indicates this is not a nested dialog.
{
{
{ COMMAND_OR_FUNCTION_NAME: (input)  This parameter specifies the name of the
{       command or function on behalf of which the parameter dialog is to be
{       carried on.
{
{ ONLINE_MANUAL_NAME: (input)  This parameter specifies the name of the online
{       manual that is assumed to contain a description of the command or
{       function.
{
{ PARAMETER_DESCRIPTION_TABLE: (input)  This parameter specifies the "Parameter
{       Description Table" (PDT) of the command or function for which a dialog
{       is to take place.  This is the "unbundled" (internal) form of the PDT.
{
{ CANCEL: (output)  This paramter specifies whether cancellation of execution
{       of the command was requested by the user (TRUE) or not (FALSE).
{
{ STATUS: (input, output)  On input this parameter specifies the status of
{       parameter evaluation up to the point of calling the parameter dialog
{       manager.  On output this parameter specifies the completion status of
{       the parameter dialog.
{
