The UTIL$CQUAL_CONFIRM_ACT routine prompts the user for
confirmation, using the optional prompt routine if present, and
returns an indication of the user's response.
Format
UTIL$CQUAL_CONFIRM_ACT [prompt_string_1] [,prompt_string_2]
[,prompt_rtn] [,current_form]
1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most utility routines return a
condition value in R0. Condition Values Returned lists condition
values that this routine returns.
2 – Arguments
prompt_string_1
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by descriptor
Longword address of a prompt string descriptor. The prompt is
used when prompting to a terminal device, and the current prompt
form is UTIL$K_CQF_SHORT.
prompt_string_2
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by descriptor
Longword address of a prompt string descriptor. The prompt is
used when prompting to a terminal device, and the current prompt
form is UTIL$K_CQF_LONG.
prompt_rtn
OpenVMS usage:procedure
type: longword (unsigned)
access: function call
mechanism: by value
Longword address of a user-supplied routine for prompting and
accepting user input. The user routine is responsible for end-of-
file processing and must return RMS$_EOF when appropriate.
current_form
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read write
mechanism: by reference
This optional parameter supplies the initial prompt form to be
displayed to the user. If present, this parameter receives the
form of the last prompt displayed. The following table shows the
valid prompting form values:
Table 3-2 Prompting Form Values
Value Description
UTIL$K_CQF_SHORT Use prompt_string_1.
UTIL$K_CQF_LONG Use prompt_string_2.
UTIL$K_CQF_UNSPECIFIED None specified; use default.
3 – Description
UTIL$CQUAL_CONFIRM_ACT prompts the user for confirmation. You
must supply at least one prompt string to this routine. If you
supply both strings, you should have an expanded and condensed
form of the prompt. The condensed form should be supplied through
the prompt_string_1 parameter; the expanded form through prompt_
string_2. The prompt string supplied by prompt_string_1 is
initially used if the prompt_string_1 is present, does not have a
length of zero, and either:
o The current_form parameter is not specified
o The current_form parameter is specified and contains:
- UTIL$K_CQF_SHORT
- UTIL$K_CQF_UNSPECIFIED
- A value greater than UTIL$K_CQF_MAX_FORM
The prompt string supplied by prompt_string_2 is used initially
if prompt_string_2 is present, does not have a length of zero,
and either:
o prompt_string_1 is not present or has a length of zero
o The current_form parameter is specified and contains the value
UTIL$K_CQF_LONG
Once the initial form is displayed, the user can switch between
the two forms by responding to the prompt with either CONDENSED
or EXPANDED. The user can only switch to another form if there
was a prompt string provided for that form. Responding with
either CONDENSED or EXPANDED causes a reprompt to occur, even
if the current display form was not switched.
If a prompt routine is provided, the routine is called with the
address of the prompt string descriptor in the first parameter,
and the string descriptor address to receive the user's response
in the second parameter. The routine returns a success status or
RMS$_EOF.
If an unsuccessful status other than RMS$_EOF is received, then
UTIL$CQUAL_CONFIRM_ACT exits without processing any response
in the response buffer (the second parameter that was passed to
the prompt routine). UTIL$CQUAL_CONFIRM_ACT returns the status
received from the user prompt routine. The prompt routine is
responsible for end-of-file processing, and must return RMS$_EOF
when appropriate. If an optional prompt routine is provided, it
should be provided for all calls to UTIL$CQUAL_CONFIRM_ACT. Not
doing so can cause unpredictable end-of-file processing.
When the user is prompted, they may respond with the following:
Table 3-3 Prompt Responses
Positive Negative
Stop Stop Switch
Response Response Processing Prompting Prompts
YES NO QUIT ALL CONDENSED
TRUE FALSE Ctrl/Z EXPANDED
1 0
<Return>
NOTE
Entering ALL assumes that subsequent files are a positive
response from the user, and no further prompting occurs.
The routine UTIL$CQUAL_FILE_MATCH properly handles this
response. Since UTIL$CQUAL_CONFIRM_ACT does not contain
context from a previous call, callers of this routine
should not call UTIL$CQUAL_CONFIRM_ACT if the user has
previously responded ALL unless the application needs
explicit confirmation on certain items.
The user can use any combination of uppercase and lowercase
letters for word responses. Word responses can be abbreviated
to one or more letters (for example, T, TR, or TRU for TRUE), but
these abbreviations must be unique.
After a valid response is received from the user, the procedure
returns the current_form parameter. The current_form parameter
contains the last form presented to the user if it was specified
and write access is permitted.
4 – Condition Values Returned
SS$_NORMAL Positive answer.
LIB$_NEGANS Negative answer.
UTIL$_QUIPRO Quit processing.
UTIL$_QUICONACT Continue processing, but cease prompting.
LIB$_INVARG Invalid argument list (no prompt strings).
SS$_ACCVIO Access violation (on user routine address).
Any unsuccessful return from RMS, SYS$ASSIGN, $QIOW, or from the
user-supplied routine (other than RMS$_EOF).