11/26/86 window_ The window_ subroutine provides a terminal independent interface to video terminal operations. More specifically, it controls and performs I/O to a window. The window_ subroutine is used in conjunction with the iox_ subroutine call entry points in the window_io_ I/O module. The window_ and video_utils_ subroutines together perform the same functions as the window_call command. The virtual terminal implemented by window_ corresponds closely to common video terminals. The features of the terminal are defined implicitly by the entries below. Not all entries can be supported on all terminals. The result of calling an unsupported feature is the error code video_et_$capability_lacking. Programs can determine whether the device in question supports a given operation by using a get_capabilities control order, described under the window_io_ I/O module. Some entry points require that the current cursor position be defined when they are called. The current position is defined unless a call is made to the write_raw_text entry point, or an asynchronous event changes the window contents. If the current position is not defined, these entry points will return the status code video_et_$cursor_position_undefined. If an asynchronous event changes the state of the window, status will be set for the window. Once window status is set, all calls to window_ on that window will return the status code video_et_$window_status_pending until a get_window_status control order is used to pick up the status. The calling sequences for all the entry points are in the include file window_dcls.incl.pl1. Entry points in window_: (List is generated by the help command) :Entry: bell: 03/07/85 window_$bell Function: This entry activates the terminal alarm. For most terminals, this will be the audible bell. For some it will be a visible signal. Syntax: declare window_$bell entry (ptr, fixed bin (35)); call window_$bell (iocb_ptr, code); Arguments: iocb_ptr is a pointer to an IOCB for a switch attached with window_io_. (Input) code is a standard system error code. (Output) Notes: The current cursor position must be dfined for this call. If the cursor is in some other window on the screen when this call is made, it is moved to the current position in this window. :Entry: change_column: 03/07/85 window_$change_column Function: This entry moves the cursor to a different column on the current line, without changing the line. Syntax: declare window_$change_column entry (ptr, fixed bin, fixed bin (35)); call window_$change_column (iocb_ptr, new_column, code); Arguments: iocb_ptr is a pointer to an IOCB for a switch attached with window_io_. (Input) new_column is the new column. (Input) code is a standard system error code. (Output) Notes: The current cursor position must be defined. :Entry: change_line: 03/07/85 window_$change_line Function: This entry moves the cursor to a new line without changing the column. Syntax: declare window_$change_line entry (ptr, fixed bin, fixed bin (35)); call window_$change_line (iocb_ptr, new_line, code); Arguments: iocb_ptr is a pointer to an IOCB for a switch attached with window_io_. (Input) new_line is the new line. (Input) code is a standard system error code. (Output) :Entry: clear_region: 03/07/85 window_$clear_region Function: This entry replaces the contents of the region specified with spaces, and leaves the cursor at the upper left-hand corner of the region. The region is defined by giving the upper left-hand corner (line and column), and the width and height of the region. Syntax: declare window_$clear_region entry (ptr, fixed bin, fixed bin, fixed bin, fixed bin, fixed bin (35)); call window_$clear_region (iocb_ptr, start_line, start_col, n_lines, n_cols, code); Arguments: iocb_ptr is a pointer to an IOCB for a switch attached with window_io_. (Input) start_line is the number of the line where clearing will begin. (Input) start_col is the number of the column where clearing will begin. (Input) n_lines is the number of lines which will be cleared. (Input) n_cols is the number of columns which will be cleared. (Input) code is a standard system error code. (Output) Notes: The rectangular region described in cleared. The cursor position defined at (start_line, start_col). :Entry: clear_to_end_of_line: 03/07/85 window_$clear_to_end_of_line Function: This entry clears everything to the right of the cursor on the current line to spaces. Positions to the left of the cursor are not affected. The cursor is not moved. Syntax: declare window_$clear_to_end_of_line entry (ptr, fixed bin (35)); call window_$clear_to_end_of_line (iocb_ptr, code); Arguments: iocb_ptr is a pointer to an IOCB for a switch attached with window_io_. (Input) code is a standard system error code. (Output) Notes: The cursor position must be defined. :Entry: clear_to_end_of_window: 03/07/85 window_$clear_to_end_of_window Function: This entry clears all of the window between the cursor and the end of the window. This includes everything to the right of the cursor on the current line, and all lines below the cursor. The cursor is not moved. Syntax: declare window_$clear_to_end_of_window entry (ptr, fixed bin (35)); call window_$clear_to_end_of_window (iocb_ptr, code); Arguments: iocb_ptr is a pointer to an IOCB for a switch attached with window_io_. (Input) code is a standard system error code. (Output) Notes: The current cursor position must be defined. :Entry: clear_window: 03/07/85 window_$clear_window Function: This entry clears the entire window to spaces, and leaves the cursor at home. Syntax: declare window_$clear_window entry (ptr, fixed bin (35)); call window_$clear_window (iocb_ptr, code); Arguments: iocb_ptr is a pointer to an IOCB for a switch attached with window_io_. (Input) code is a standard system error code. (Output) Notes: The cursor position is defined to be at line 1, column 1 after the screen is cleared. :Entry: create: 11/26/86 window_$create Function: This entry creates a new window on the terminal screen. Syntax: declare window_$create entry (ptr, ptr, ptr, fixed bin (35)); call window_$create (terminal_iocb_ptr, window_info_ptr, window_iocb_ptr, code); Arguments: terminal_iocb_ptr is a pointer to an IOCB for the terminal control switch. (Input) Normally this should be video_data_$terminal_iocb. window_info_ptr is a pointer to a standard window_position_info structure, as declared in window_control_info.incl.pl1. (Input) window_iocb_ptr is a pointer to a detached IOCB pointer. (Input) It may be obtained with iox_$find_iocb which must be done before the call to window_$create. code is a standard system error code. (Output) Notes: The window_info_ptr must point to a window_position_info structure, as declared in window_control_info.incl.pl1. If window_position_info.width is set to zero, the window will occupy the full width of the screen. Currently windows must occupy the full width of the screen. If window_position_info.height is set to zero, the remainder of the screen is used. The iocb_ptr is an input argument, iox_$find_iocb may be used to obtain an iocb_ptr for a new switch. :Entry: delete_chars: 03/07/85 window_$delete_chars Function: This entry deletes characters on the current line. Characters to the right of the cursor are moved to the left. Character positions opened up on the right margin are filled with spaces. It is an error to call this entry point if the terminal does not support the delete chars operation. Syntax: declare window_$delete_chars entry (ptr, fixed bin, fixed bin (35)); call window_$delete_chars (iocb_ptr, n_chars, code); Arguments: iocb_ptr is a pointer to an IOCB for a switch attached with window_io_. (Input) n_chars is the number of characters (starting at the current cursor position) that will be removed from the screen. (Input) If n_chars is zero, no action is taken. code is a standard system error code. (Output) Notes: The current cursor position must be defined. The number of characters specified by n_chars are deleted, and the remaining characters on the line, if any, move leftward to occupy the space. :Entry: destroy: 03/07/85 window_$destroy Function: This entry destroys an existing window, leaving its IOCB in a detached state. Syntax: declare window_$destroy entry (ptr, fixed bin (35)); call window_$destroy (window_iocb_ptr, code); Arguments: window_iocb_ptr is a pointer to an IOCB attached with window_$create. (Input) code is a standard system error code. (Output) :Entry: edit_line: 03/07/85 window_$edit_line Function: This entry allows applications to preload the video editor input buffer with a string. Syntax: declare window_$edit_line entry (pointer, pointer, pointer, fixed bin (21), fixed bin (21), fixed bin (35)); call window_$edit_line (iocb_ptr, window_edit_line_info_ptr, buffer_ptr, buffer_len, n_returned, code); Arguments: window_iocb_ptr is a pointer to an IOCB for a switch attached with window_io. (Input) window_edit_line_info_ptr is a pointer to a window_edit_line_info structure, as declared in window_control_info.incl.pl1 (described below). (Input) version is the version number of the structure. (Input) This is currently window_edit_line_version_1. line_ptr is a pointer to the initial text string to be loaded into the input buffer before editing begins. (Input) line_length is the length of the string pointed to by line_ptr. (Input) buffer_ptr is a pointer to a buffer where the users input will be put. (Input) buffer_len is the size of the input buffer. (Input) n_returned is the number of characters in the final output line. (Output) code is a standard system error code. (Output) :Entry: get_cursor_position: 03/07/85 window_$get_cursor_position Function: This entry is used to return the current position of the cursor. If the last operation done to the terminal was in some other window, this will not be the actual position of the cursor on the screen. Syntax: declare window_ $get_cursor_position entry (ptr, fixed bin, fixed bin, fixed bin (35)); call window_$get_cursor_position (iocb_ptr, line, col, code); Arguments: iocb_ptr is a pointer to an IOCB for a switch attached with window_io_. (Input) line is the line number. (Output) col is the column position. (Output) code is a standard system error code. (Output) Notes: The current cursor position must be defined. :Entry: get_echoed_chars: 03/07/85 window_$get_echoed_chars Function: This entry accepts input from the typist, echoing the characters as typed, until either a specified number of characters are read, or a break character is encountered. By default, the break characters are the control characters plus DEL (177 octal). Syntax: declare window_$get_echoed_chars entry (ptr, fixed bin (21), char (*), fixed bin (21), char (1) varying, fixed bin (35)); call window_$get_echoed_chars (iocb_ptr, n_to_get, buffer, n_got, break, code); Arguments: iocb_ptr is a pointer to an IOCB for a switch attached with window_io_. (Input) n_to_get is the number of columns (N) between the cursor and the end of the line. (Input) At most N characters will be returned. buffer is the caller-supplied buffer that holds characters returned. (Input) n_got is the number of characters returned. (Output) Each character is echoed. break is the character that causes the echoing to stop. (Output) This character is not echoed. code is a standard system error code. (Output) Notes: This entry point returns no more than n_to_get characters in buffer. It reads and echoes characters until either (1) it has read n_to_get characters, or (2) it has read a break character. If it stops due to a break character, the break character is returned in break, otherwise break is equal to "". :Entry: get_one_unechoed_char: 03/07/85 window_$get_one_unechoed_char Function: This entry reads a single character, unechoed, from the terminal. Optionally, it can return instead of waiting if there are no characters available. Syntax: declare window_$get_one_unechoed_char entry (ptr, char (1) varying, bit (1) aligned, fixed bin (35)); call window_$get_one_unechoed_char (iocb_ptr, char_read, block_flag, code); Arguments: iocb_ptr is a pointer to an IOCB for a switch attached with window_io_. (Input) char_read is the read character. (Output) If block_flag is "0"b, and no input is typed ahead, then this will be a zero length character string. block_flag if this flag is "1"b, input from the terminal is awaited if none is available. (Input) If it is "0"b, and no input is available, then this entry returns immediately, and sets char_read to "". code is a standard system error code. (Output) Notes: Beware of the PL/I language definition of character string comparisons when using this entry with a block flag of "0"b. In PL/I, both of the following comparisons are true: (" " = " ") ("" = " ") That is, a zero length varying string compares equally to a single space. To test if char_read is nonempty, use an expression like: (length (char_read) > 0) :Entry: get_unechoed_chars: 03/07/85 window_$get_unechoed_chars Function: This entry accepts input from the typist, leaving it unechoed, until either a specified number of characters are read, or a break character is encountered. Syntax: declare window_$get_unechoed_chars entry (ptr, fixed bin (21), char (*), fixed bin (21), char (1) varying, fixed bin (35)); call window_$get_unechoed_chars (iocb_ptr, n_to_get, buffer, n_got, break, code); Arguments: iocb_ptr is a pointer to an IOCB for a switch attached with window_io_. (Input) n_to_get is the number of columns (N) between the cursor and the end of the line. (Input) At most N characters will be returned. buffer is the caller-supplied buffer that holds characters returned. (Input) n_got is the number of characters returned. (Output) Each character is echoed. break is the character that causes the echoing to stop. (Output) This character is not echoed. code is a standard system error code. (Output) Notes: This entry point will read no more than n_to_get characters from the terminal, without echoing them to the typist. The characters are returned in the buffer. Characters are read until either (1) n_to_get characters are read, or (2) a break character is read. If reading stops due to a break character, then the break character is returned in break. Otherwise break is "". :Entry: insert_text: 03/07/85 window_$insert_text Function: This entry inserts text at the current cursor position. Text at the cursor or to the right of the cursor is shifted to the right, to accommodate the new text. It is an error to call this entry if the terminal does not support the insertion of text. Syntax: declare window_$insert_text entry (ptr, char (*), fixed bin (35)); call window_$insert_text (iocb_ptr, text, code); Arguments: iocb_ptr is a pointer to an IOCB for a switch attached with window_io_. (Input) text is the character string to be written. (Input) When converted to output, each character in this string must occupy exactly one print position. The length of this string must be such that characters moved to the right will remain on the current line in the window. If these conditions are not met, the result is undefined. The cursor is left after the last character inserted. code is a standard system error code. (Output) Notes: The current cursor position must be defined. The string "text" must contain only printable ASCII graphics. If it contains any other characters, the status code video_et_$string_not_printable is returned. :Entry: overwrite_text: 03/07/85 window_$overwrite_text Function: This entry writes text on the window in the current cursor location. If there is any text at or to the right of the current cursor position in the window, it is overwritten with the supplied string. Syntax: declare window_$overwrite_text entry (ptr, char (*), fixed bin (35)); call window_$overwrite_text (iocb_ptr, text, code); Arguments: iocb_ptr is a pointer to an IOCB for a switch attached with window_io_. (Input) text is the character string to be written. (Input) This string should consist of only printable ASCII graphics (octal codes 040 through 176 inclusive), and may not be longer than the space remaining on the current line. code is a standard system error code. (Output) Notes: The cursor position must be defined. The string "text" may contain only printable ASCII graphics. If it contains anything else the status code video_et_$string_not_printable is returned. :Entry: position_cursor: 03/07/85 window_$position_cursor Function: This entry moves the cursor to any requested position in the window. It defines the current cursor position if it is undefined. Syntax: declare window_$position_cursor entry (ptr, fixed bin, fixed bin, fixed bin (35)); call window_$position_cursor (iocb_ptr, line, col, code); Arguments: iocb_ptr is a pointer to an IOCB for a switch attached with window_io_. (Input) line is the line number. (Input) col is the column position. (Input) code is a standard system error code. (Output) :Entry: position_cursor_rel: 03/07/85 window_$position_cursor_rel Function: The entry moves the cursor relative to the current location. Syntax: declare window_$position_cursor_rel entry (ptr, fixed bin, fixed bin, fixed bin (35)); call window_$position_cursor_rel (iocb_ptr, line_inc, col_inc, code); Arguments: iocb_ptr is a pointer to an IOCB for a switch attached with window_io_. (Input) line_inc is the change in line number. (Input) If line_inc is a positive number, the cursor is moved down. If it is a negative number, the cursor is moved up. If it is zero, the cursor's line number is not changed. col_inc is the change in column position. (Input) If col_inc is a positive number, the cursor is moved to the right. If it is a negative number, the cursor is moved to the left. If it is zero, the cursor's column position is not changed. code is a standard system error code. (Output) :Entry: scroll_region: 03/07/85 window_$scroll_region Function: This entry scrolls a region up or down a given number of lines. A positive scroll count scrolls the window up, deleting lines from the top of the window and adding new blank lines to the bottom. The cursor's new position is at the beginning of the first new blank line. A negative count scrolls the window down, deleting lines from the bottom and adding lines to the top. The cursor is left at home. If this entry is called and the terminal does not support either scrolling or insert and delete lines, the result is an error status, video_et_$capabilities_lacking. Syntax: declare window_$scroll_region entry (ptr, fixed bin, fixed bin, fixed bin, fixed bin (35)); call window_$scroll_region (iocb_ptr, start_line, n_lines, scroll_distance, code); Arguments: iocb_ptr is a pointer to an IOCB for a switch attached with window_io_. (Input) start_line is the number of the first line of the region. (Input) n_lines is the number of lines that compose the region. (Input) scroll_distance is the distance in lines by which the region will be scrolled. (Input) code is a standard system error code. (Output) Notes: The cursor position is defined to be column one on first_line. The region from first_line for n_lines is scrolled scroll_distance lines, which may be negative. :Entry: sync: 03/07/85 window_$sync Function: This entry synchronizes the process with the typist by writing any pending output to the terminal. Syntax: declare window_$sync entry (ptr, fixed bin (35)); call window_$sync (iocb_ptr, code); Arguments: iocb_ptr is a pointer to an IOCB for a switch attached with window_io_. (Input) code is a standard system error code. (Output) Notes: The calling process is made to wait until the typist types something after the last text output has been transmitted to the terminal. :Entry: write_raw_text: 03/07/85 window_$write_raw_text Function: This entry is used to output a terminal dependent sequence. The current cursor position becomes undefined after this call is made. This entry should not be used to output sequences that put graphics onto the terminal screen, as the video system's internal screen image will become inconsistent. This entry is used for terminal-specific features that cannot be accessed via the video system. Syntax: declare window_$write_raw_text entry (ptr, char (*), fixed bin (35)); call window_$write_raw_text (iocb_ptr, text, code); Arguments: iocb_ptr is a pointer to an IOCB for a switch attached with window_io_. (Input) text is any string of printable ASCII characters to be transmitted to the terminal. (Input) code is a standard system error code. (Output) Notes: Any call to window_$write_raw_text causes the cursor position to become undefined and sets the screen_invalid window status flag. Subsequent calls to write_raw_text will ignore this flag, but all other window_ entrypoints will return the status code video_et_$window_status_pending until the status flag is cleared. It is the responsibility of the application performing the raw output call to perform a get_window_status control order to clear the status flag. :Entry: write_sync_read: 03/07/85 window_$write_sync_read Function: This entry writes a prompt, synchronizes input to the output of the prompt, and reads a response. This entry is useful for queries where it is important to avoid interpreting type-ahead as a response to a question. Syntax: declare window_$write_sync_read entry (ptr, char (*), fixed bin (21), char (*), fixed bin (21), char (1) varying, fixed bin (35)); call window_$write_sync_read (iocb_ptr, prompt, n_to_get, buffer, n_got, break, code); Arguments: iocb_ptr is a pointer to an IOCB for a switch attached with window_io_. (Input) prompt is a string of printable ASCII characters which must fit on the current line. (Input) n_to_get is the number of columns (N) between the cursor and the end of the line. (Input) At most N characters will be returned. buffer is the caller-supplied buffer that holds characters returned. (Input) n_got is the number of characters returned. (Output) Each character is echoed. break is the character that causes the echoing to stop. (Output) This character is not echoed. code is a standard system error code. (Output) Notes: The current cursor position must be defined. This entry overwrites the text string "prompt" at the current cursor position. It then reads characters typed after the prompt has been transmitted to the terminal. The characters are read in the same fashion as the get_unechoed_chars entry point. Any characters read before the prompt is transmitted, are buffered and returned to get_echoed_chars or subsequent get_unechoed_chars calls. ----------------------------------------------------------- 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