02/26/86 command_query_ The command_query_ subroutine is the standard system procedure invoked to ask the user a question and to obtain an answer. It formats the question and then signals the condition command_question. System conditions are described in the Programmer's Reference Manual. The default handler for this condition simply returns control to the command_query_ subroutine, which writes the question on a specified I/O switch. It then reads from another I/O switch to obtain the answer. Several options have been included in the commmand_query_ subroutine to support the use of a more sophisticated handler for the command_question condition. Since this procedure can be called with a varying number of arguments, it is not permissible to include a parameter attribute list in the declaration. Entry points in command_query_: (List is generated by the help command) :Entry: command_query_: 02/26/86 command_query_ Function: is the standard system procedure invoked to ask the user a question and to obtain an answer. Formats the question and then signals the condition command_question. Syntax: declare command_query_ entry options (variable); call command_query_ (info_ptr, answer, caller, control_string, arg1, ..., argN); Arguments: info_ptr is a pointer to the query_info structure described in "Info Structure" below. (Input) answer is the response (char(*) or char (*) varying) read from the I/O switch user_input. (Output) Leading and trailing blanks plus the newline character have been removed. caller is the name (char(*)) of the calling procedure. (Input) It can be either varying or nonvarying. control_string is an ioa_ subroutine control string (char(*)). (Input) This argument is optional. See "Notes" below. argi are ioa_ subroutine arguments to be substituted into control_string. (Input) These arguments are optional. They can only be used if the control_string argument is given first. See "Notes" below. Info structure; The following is the query_info structure (found in the include file query_info.incl.pl1): dcl 1 query_info aligned, 2 version fixed bin, 2 switches aligned, 3 yes_or_no_sw bit(1) unaligned, 3 suppress_name_sw bit(1) unaligned, 3 cp_escape_control bit(2) unaligned, 3 suppress_spacing bit(1) unaligned, 3 literal_sw bit(1) unaligned, 3 prompt_after explanation bit (1) unaligned, 3 padding bit(29) unaligned, 2 status_code fixed bin(35), 2 query_code fixed bin(35), 2 question_iocbp ptr, 2 answer_iocbp ptr, 2 repeat_time fixed bin(71), 2 explanation_ptr ptr, 2 explanation_len fixed bin (21); Structure elements: version is the version number of this structure. (Input) The version number must be set by the caller and identifies the format of the structure. The current version is a static variable named query_info_version_6 in query_info.incl.pl1. yes_or_no_sw indicates whether an answer of a particular form is expected. (Input) "0"b accepts any answer. "1"b accepts only a yes or no answer. suppress_name_sw controls whether the name of the calling procedure appears in the question. (Input) "0"b includes name and following colon. "1"b omits name and colon. cp_escape_control controls whether the command_processor_ escape mechanism is enabled for this call. (Input) "00"b obeys the static default. "01"b allows lines to begin with ".." but does not interpret them as command_processor_ escapes. "10"b disallows escape, ignores default. "11"b allows escape, ignores default. suppress_spacing controls the insertion of a newline before the question and two spaces after it. (Input) "0"b inserts extra space. "1"b omits extra space. literal_sw is "1"b to suppress any special interpretation of characters (for example, "..") and suppress stripping of leading whitespace. prompt_after_explanation is "1"b to repeat the original question after printing any explanation indicated by a non-null explanation argument. padding is unused space. (Input) status_code is either the standard status code that prompted the question or 0. (Input) query_code is additional arbitrary qualifying information passed by the caller of command_query_. (Input) It is intended for use by specialized handlers for command_question. question_iocbp is an iocb pointer for the I/O switch over which the caller wants the question to be written. (Input) A null pointer indicates that the of the user_i/o switch is to be used by default. answer_iocbp is an iocb pointer for the I/O switch from which the caller wants the answer to be read. (Input) A null pointer indicates that the user_input switch is to be used by default. repeat_time is the number of seconds to wait for an answer before repeating the question on the switch pointed to by question_iocbp. (Input) A value less than 30 indicates that the question is not to be repeated. explanation_ptr is a pointer to a string to be printed if the user answers "?". (Input) explanation_len is the length of the explanation string. (Input) Notes: The question prepared by the command_query_ subroutine has the format: caller: message where the message is constructed by the ioa_ subroutine from the control_string and argN arguments. If the control_string and argN arguments are not given, the message portion of the question is omitted. If the user answers with a single question mark (?), the explanation_ptr field is examined. If it is non-null and explanation_len is greater than 0, the explanation string pointed to is printed and the user is expected to answer again. Otherwise, the string "Answer: " is printed and the user is expected to answer again. In an absentee process with the yes_or_no_sw on, an answer other than than yes, no or "?" causes the absentee process to signal command_query_error. Case insensitive "yes", "y", "no", and "n" are acceptable responses to a yes or no question. If the answer to a question begins with "..", and the cp_escape feature is enabled for the question, the rest of the answer following the ".." is passed to the command processor. Control then returns to command_query_, which prompts with "Answer: " after the command has been executed. The cp_escape feature is normally enabled in the standard Multics environment; a subsystem, however, can elect to turn it off, either globally or for a particular question. The prompt of "Answer: " is used rather than repeating the question because the question may be quite long and take significant time to print. If it is necessary to see the question again, answering "..repeat_query" repeats it. :Entry: set_cp_escape_enable: 03/05/85 command_query_$set_cp_escape_enable Function: This entry sets the static default switch that allows or disallows the command processor escape feature. It also returns the previous value for the switch. Since escapes are disabled initially, it is necessary to call this entry to enable the feature. This entry is called by process_overseer_, which sets it so that the escape is permitted in a normal Multics environment. Syntax: declare command_query_$set_cp_escape_enable entry (bit(1) aligned, bit(1) aligned); call command_query_$set_cp_escape_enable (new_value, old_value); Arguments: new_value is the new value for the default. (Input) "0"b feature is disabled by default. "1"b feature is enabled by default. old_value is the old value of the default. (Output) If it has never been set, it is "0"b. :Entry: yes_no: 02/26/86 command_query_$yes_no Function: This entry asks the user for a yes or no answer. Syntax: dcl command_query_$yes_no entry options (variable); call command_query_$yes_no (yes_sw, query_code, caller, explanation, question, arg1, ..., argN); Arguments: yes_sw is a bit (1) return value, ON for "yes" or "y" and OFF for "no" or "n", case insensitive. (Output) Other answers are not accepted from the user. query_code is a standard status code. (Input) If it is nonzero, the question is preceded by the corresponding error message. caller is the character string name of the calling program. (Input) explanation is an explanation of the question, printed when the user answers "?". (Input) The explanation is an ioa_ control string, in which parameters are replaced by the values of the argN arguments. For a description of control strings, see the ioa_ subroutine. question is the question, also in the form of an ioa_ control string. (Input) Parameters are replaced by the same argN arguments as for the explanation. argN are character string arguments to the ioa_ control strings specified by explanation and question. (Input) Notes: The same arguments are substituted in both explanation and question control strings. Each control string can use ^s to skip particular arguments. ----------------------------------------------------------- Historical Background This edition of the Multics software materials and documentation is provided and donated to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. as a contribution to computer science knowledge. This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology, Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL and BULL HN Information Systems Inc. to the development of this operating system. Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970), renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture for managing computer hardware properly and for executing programs. Many subsequent operating systems incorporated Multics principles. Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. . ----------------------------------------------------------- Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without fee is hereby granted,provided that the below copyright notice and historical background appear in all copies and that both the copyright notice and historical background and this permission notice appear in supporting documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining to distribution of the programs without specific prior written permission. Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc. Copyright 2006 by BULL HN Information Systems Inc. Copyright 2006 by Bull SAS All Rights Reserved