MULTICS TECHNICAL BULLETIN                               MTB756-2

  To:       MTB Distribution

  From:     Ron Barstad

  Date:     April 13, 1987

  Subject:  Video Support for MOWSE

                 -----------------------------------

  A  description of  the functionality  and external  interfaces of
  Multics software to support video  mode within the Multics Online
  WorkStation   Environment  (MOWSE).    A  description   of  MOWSE
  interfaces  referenced  in  this  document  may  be  found in the
  following MTBs.

       MTB-740  MOWSE Overview
       MTB-741  MOWSE Design, Commands and Subroutines
       MTB-742  MOWSE Background File Transfer (BFT) Facility
       MTB-743  MOWSE Terminal Emulator

  Also referenced is

       MTB-708  Local Echo Negotiation

                 -----------------------------------

  Comments should be sent to the author:

  via Multics Mail:
     RBarstad at System-M

  via Forum:
     >udd>m>jms>mtgs>workstation_working_group (wwg)

  via telephone:
     (HVN) 862-3674 or (602) 862-3674

  _________________________________________________________________

  Multics project  internal documentation; not to  be reproduced or
  distributed outside the Multics project without permission of the
  Director of MDC.


  MTB756-2                                  Video Support for MOWSE

                               CONTENTS

                                                           Page

     1:  Introduction  . . . . . . . . . . . . . . . . . . . . .   1
     2:  Functional Overview . . . . . . . . . . . . . . . . . .   1
     3:  External Interfaces . . . . . . . . . . . . . . . . . .   1
     3.1:  Entry Points in ws_tty_ . . . . . . . . . . . . . . .   2
     3.2:  Workstation Interfaces  . . . . . . . . . . . . . . .  18
     3.2.1:  Control message example . . . . . . . . . . . . . .  18
     3.2.2:  Sending Text Example  . . . . . . . . . . . . . . .  19
     3.2.3:  Control Message Format  . . . . . . . . . . . . . .  19
     3.2.3.1:  Control Message Types . . . . . . . . . . . . . .  19
     3.2.3.1.1:  Break table . . . . . . . . . . . . . . . . . .  20
     3.2.3.1.2:  TTY modes . . . . . . . . . . . . . . . . . . .  20
     3.2.3.1.3:  Control order . . . . . . . . . . . . . . . . .  21
     3.2.3.1.4:  Read count  . . . . . . . . . . . . . . . . . .  21
     3.2.3.1.5:  Text  . . . . . . . . . . . . . . . . . . . . .  21


  Video Support for MOWSE                                  MTB756-2

  1:  INTRODUCTION

  This document  is a short  functional description of  the Multics
  modules to  support video mode in the  Multics Online WorkStation
  Environment  (MOWSE).  For  a description  of MOWSE functionality
  such as  io attachment and  video design considerations  refer to
  the MOWSE  MTBs, especially section 6 of  MTB-741.  A description
  of  the  type  of  echo  negotiation  used  for  video support is
  included  in  the  MOWSE  MTBs  as  well  as  MTB-708 "Local Echo
  Negotiation".   Since  MTB-708  describes  the  meaning  of  such
  functions  as  "read  with  echo",  and  "read  with no echo" and
  others, those descriptions are not repeated here.

  2:  FUNCTIONAL OVERVIEW

  Once  MOWSE  is  invoked  on  the  workstation  and  mowse_i/o is
  attached  via the  attach_mowse command,  and WSTERM  is running,
  video  may be  initiated with  the "window_call  invoke" command.
  This  results   in  video_utils_  making  the   proper  video  io
  attachments and  calling the ws_tty_ entry points  instead of the
  hcs_$tty_ entries.

  The modules described here include

            ws_tty_.pl1
            ws_tty_main_.pl1
            ws_tty_mgr_.pl1
            ws_tty_read_.pl1
            ws_tty_write_.pl1
            ws_trace_.pl1

  and  are  known  collectively  as  simply  "ws_tty_".  The module
  ws_tty_ is in  fact simply the transfer vectors  for all external
  entries.

  3:  EXTERNAL INTERFACES

  Functionally, ws_tty_ is a filter  between tc_io_ and iox_.  Text
  destined for the workstation screen  is reformated by ws_tty_ and
  passed on with a call to  iox_.  Likewise, iox control orders are
  intercepted and some are acted on before or instead of passing on
  to  iox_.  Characters  typed at   the workstation  are passed  to
  ws_tty_  by iox_  and reformated  before being  passed on  to the
  caller of ws_tty_ who requested the characters.


  MTB756-2                                  Video Support for MOWSE

  3.1:  Entry Points in ws_tty_

  ENTRY:  ws_tty_$abort

  This  entry  aborts  current  i/o  and  resets  the read or write
  buffers and stops echo negotiated input.

  USAGE

  dcl ws_tty_$abort entry (ptr, fixed bin, fixed bin, fixed
        bin(35));

  call ws_tty_$abort (iocb_ptr, reset_switch, state, code);

  ARGUMENTS

  iocb_ptr
      points to the I/O control block of mowse_terminal_.  (Input)

  reset_switch
      indicates whether read or write are to be reset.  (Input)
      1 reset read
      2 reset write
      3 reset both read and write

  state
      indicates the tty state.  (Output)
|     0 unknown
      1 ignored
      2 listening
      5 dialed

  code
      is a standard status code.  (Output)

|     A code of error_table_$no_io_permission  means that WSTERM is
|     not connected.  The code  error_table_$no_iocb is returned if
|     the iocb pointer is null.  In addition the code may be any of
|     those  returned  by  iox_$control   for  the  control  orders
|     "get_terminal_emulator_state"  and "abort".  A  non-zero code
|     means that the abort was not sent to the workstation.
|
| PROTOCOL
|
|      ws_tty_                       wsterm
|      ------                        ------
|      ABT       ------------------> (flush i/o buffers)


  Video Support for MOWSE                                  MTB756-2

  ENTRY:  ws_tty_$attach

  This  entry "attaches"  video mode   to WSTERM  by informing  the
  workstation software that synchronous mode is required to support
  video and sends WSTERM a list  of the break characters.  The iox_ |
  control order "set_video_mode" is also called to inform mowse_io_ |
  that video mode has been invoked.                                 |

  USAGE

  dcl ws_tty_$attach entry (ptr, char(*), fixed bin(71), fixed bin,
        fixed bin(35));

  call ws_tty_$attach (iocb_ptr, name, event, state, code);

  ARGUMENTS

  iocb_ptr
      points to the I/O control block of mowse_terminal_.  (Input)

  name
      is the channel name and must be "mowse.".  (Input)

  event
      is not used.  (Input)

  state
      indicates the tty state.  (Output)
      0 unknown                                                     |
      1 ignored
      2 listening
      5 dialed

  code
      is a standard status code.  (Output)

      A code of error_table_$no_io_permission  means that WSTERM is |
      not connected.  The code  error_table_$no_iocb is returned if |
      the iocb pointer  is null.  Either of these  codes means that |
      the  enter sync  mode request   was not  sent to  WSTERM.  In |
      addition  the   code  may  be   any  of  those   returned  by |
      iox_$control        for       the        control       orders |
      "get_terminal_emulator_state"   and   "set_video_modes"   and |
      iox_$modes.                                                   |

  NOTES

  The modes "force,^crecho,^lfecho" are set by this entry.          |


  MTB756-2                                  Video Support for MOWSE

| PROTOCOL
|
|      ws_tty_                       wsterm
|      ------                        ------
|      ESM       ------------------> (set default break table, e.g.
|                                     only non-printing chars.)
|                                    (prepare for sync io)
|      (verify) <------------------- SME


  Video Support for MOWSE                                  MTB756-2

  ENTRY:  ws_tty_$detach

  This  entry "detaches"  video mode  from WSTERM  by informing the
  workstation software that synchronous  communication is no longer
  required.    Asynchronous   communication   is   established  for
  non-video mode.  The iox_  control order "set_video_mode" is also |
  called to inform mowse_io_ that video mode has been revoked.      |

  USAGE

  dcl ws_tty_$detach entry (ptr, fixed bin, fixed bin, fixed
        bin(35));

  call ws_tty_$detach (iocb_ptr, dflag, state, code);

  ARGUMENTS

  iocb_ptr
      points to the I/O control block of mowse_terminal_.  (Input)

  dflag
      is not used.  (Input)

  state
      indicates the tty state.  (Output)
      0 unknown                                                     |
      1 ignored
      2 listening
      5 dialed

  code
      is a standard status code.  (Output)

      A code of error_table_$no_io_permission  means that WSTERM is |
      not connected.  The code  error_table_$no_iocb is returned if |
      the iocb pointer  is null.  Either of these  codes means that |
      the  exit  sync  mode  request  was  not  sent to WSTERM.  In |
      addition  the   code  may  be   any  of  those   returned  by |
      iox_$control        for       the        control       orders |
      "get_terminal_emulator_state" and "set_video_modes".          |
                                                                    |
  PROTOCOL                                                          |
                                                                    |
       ws_tty_                       wsterm                         |
       ------                        ------                         |
       XSM       ------------------> (prepare for async io)         |
       (verify) <------------------- SMX                            |


  MTB756-2                                  Video Support for MOWSE

  ENTRY:  ws_tty_$event

  This entry simply sets the tty state and returns.

  USAGE

  dcl ws_tty_$event entry (ptr, fixed bin(71), fixed bin, fixed
        bin(35));

  call ws_tty_$event (iocb_ptr, event, state, code);

  ARGUMENTS

  iocb_ptr
      points to the I/O control block of mowse_terminal_.  (Input)

  event
      is the event channel name.  (Input)

  state
      indicates the tty state.  (Output)
|     0 unknown
      1 ignored
      2 listening
      5 dialed

  code
      is a standard status code.  (Output)

|     The code error_table_$no_iocb is returned if the iocb pointer
|     is null.

  NOTES

  This entry is  not believed to be needed but  is retained in case
  the event should  need to be passed to  hcs_$tty_event.  There is
  only one known video call to this entry and it appears redundant.


  Video Support for MOWSE                                  MTB756-2

  ENTRY:  ws_tty_$order

  This  entry  performs  the  specified  control  order  on the i/o
  switch.

  USAGE

  dcl ws_tty_$order entry (ptr, char(*), ptr, fixed bin, fixed
        bin(35));

  call ws_tty_$order (iocb_ptr, order, info_ptr, state, code);

  ARGUMENTS

  iocb_ptr
      points to the I/O control block of mowse_terminal_.  (Input)

  order
      is the name of the control order.  (Input)

  info_ptr
      is  null or  points to  the data  whose form  depends on  the
      control order.  (Input)

  state
      indicates the tty state.  (Output)
      0 unknown                                                     |
      1 ignored
      2 listening
      5 dialed

  code
      is a standard status code.  (Output)

      A code of error_table_$no_io_permission  means that WSTERM is |
      not connected.  The code  error_table_$no_iocb is returned if |
      the     iocb      pointer     is     null.       The     code |
      error_table_$unimplemented_version   is   returned   if   the |
      structure  pointed to  by info_ptr   is found  to contain  an |
      obsolete            version.              The            code |
      error_table_$undefined_order_request   is  returned   if  the |
      control order is unsupported.  Any  of these codes means that |
      the control  order was not  processed.  In addition  the code |
      may  be  any  of  those  returned  by  iox_$control  for  the |
      specified control order (if passed on) and iox_$modes for the |
      control order "modes".                                        |

  NOTES

  The  following list  of control  orders are  supported.  With two
  exceptions, these orders are  passed to mowse_io_ for processing.
  The  first  exception  is  that  control  orders  which involve a


  MTB756-2                                  Video Support for MOWSE

  structure  containing a  version  indicator  are checked  for the
  current version.  In the second exception, the modes order passes
  the new modes to mowse_io_ via iox_$modes after changing the data
  from a structure to a character string.

| Control orders passed on to mowse_io_

|           abort
|           debug_on
|           debug_off
|           flush_subchannel
|           get_editing_chars
|           get_event_channel
|           get_foreign_terminal_data (version checked first)
|           get_mowse_info
|           get_output_conversion
|           get_special
|           get_terminal_emulator_state (version checked first)
|           line_length
|           put_to_sleep
|           quit_disable
|           quit_enable
|           read_status
|           resetread
|           resetwrite
|           send_local_message
|           send_message
|           set_editing_chars
|           set_output_conversion (version checked first)
|           set_special
|           set_terminal_data (version checked first)
|           set_term_type
|           start
|           store_id
|           store_mowse_info
|           terminal_info (version checked first)
|           trace_on
|           trace_off
|           write_status

| Control orders returned with error_table_$undefined_order_request

|           get_input_conversion
|           get_input_translation
|           get_output_translation
|           set_input_conversion
|           set_input_translation
|           set_output_translation

| Control orders with special processing


  Video Support for MOWSE                                  MTB756-2

            modes                                                   |
                 the  mode "force" is  appended to the  input modes |
                 string before passing on to iox_$modes             |
            printer_off                                             |
                 The foreground control message  for printer off is |
                 sent to WSTERM.                                    |
            printer_on                                              |
                 The foreground  control message for printer  on is |
                 sent to WSTERM.                                    |
            set_echo_break_table                                    |
                 The echo  break table is converted  to a character |
                 string  and  sent  to  WSTERM  with the foreground |
                 control message Set Break Table.                   |


  MTB756-2                                  Video Support for MOWSE

  ENTRY:  ws_tty_$read

  This entry reads unechoed characters from the workstation.

  USAGE

  dcl ws_tty_$read entry (ptr, ptr, fixed bin(21), fixed bin(21),
        fixed bin(21), fixed bin, fixed bin(35));

  call ws_tty_$read (iocb_ptr, buffer_ptr, offset, n_chars_to_read,
        n_chars_read, state, code);

  ARGUMENTS

  iocb_ptr
      points to the I/O control block of mowse_terminal_.  (Input)

  buffer_ptr
      points to caller's buffer.  (Input)

  offset
      is the offset in caller's buffer to start at.  (Input)

  n_chars_to_read
      is the maximum number of characters to return.  (Input)

  n_chars_read
      is the actual number of characters returned.  (Output)

  state
      indicates the tty state.  (Output)
|     0 unknown
      1 ignored
      2 listening
      5 dialed

  code
      is a standard status code.  (Output)

|     A code of error_table_$no_io_permission  means that WSTERM is
|     not connected.  The code  error_table_$no_iocb is returned if
|     the iocb  pointer is null.  The  code error_table_$bad_arg is
|     returned if  n_chars_to_read is less than  zero.  In addition
|     the code may be any of those returned by iox_$control for the
|     control  order  get_terminal_emulator_state.   Any  of  these
|     codes means that the read was not performed.

| NOTES
|
| This entry is not called by video and is probably redundant.


  Video Support for MOWSE                                  MTB756-2

  ENTRY:  ws_tty_$read_echoed

  This entry reads echoed characters from the workstation.  Echoing
  stops  on  a  break  character  or  when  the  character count is |
  satisfied.                                                        |

  USAGE

  dcl ws_tty_$read_echoed entry (ptr, ptr, fixed bin(21), fixed
        bin(21), fixed bin(21), fixed bin(21), fixed bin, fixed
        bin, fixed bin(35));

  call ws_tty_$read_echoed (iocb_ptr, buffer_ptr, offset,
        n_chars_to_read, n_chars_read, echoed, screen_left, state,
        code);

  ARGUMENTS

  iocb_ptr
      points to the I/O control block of mowse_terminal_.  (Input)

  buffer_ptr
      points to caller's buffer.  (Input)

  offset
      is the offset in caller's buffer to start at.  (Input)

  n_chars_to_read
      is the maximum number of characters to return.  (Input)
      If  equal to  zero, no   read is  actually performed  and the |
      return is immediate.                                          |

  n_chars_read
      is the actual number of characters returned.  (Output)

  echoed
      is  the  number  of  characters  echoed  by  the  workstation |
      (Output)                                                      |

  screen_left
      is the space left on line (Input)
      is  used to switch  local (workstation) echo  on and off.   A |
      positive value means turn echo on;  a zero means to turn echo |
      off.                                                          |

  state
      indicates the tty state.  (Output)
      0 unknown                                                     |
      1 ignored
      2 listening
      5 dialed


  MTB756-2                                  Video Support for MOWSE

  code
      is a standard status code.  (Output)

|     A code of error_table_$no_io_permission  means that WSTERM is
|     not connected.  The code  error_table_$no_iocb is returned if
|     the iocb  pointer is null.  The  code error_table_$bad_arg is
|     returned if  n_chars_to_read is less than  zero.  In addition
|     the code may be any of those returned by iox_$control for the
|     control  order  get_terminal_emulator_state.   Any  of  these
|     codes means that the read was not performed.
|
|     A  code of  error_table_$improper_data_format is  returned if
|     the  control messages  from WSTERM  are out  of sequence.  In
|     this case the read may have been partially completed.
|
|     If WSTERM returns more characters than asked for, sub_err_ is
|     called  with  the  code  error_table_$no_operation.   If  the
|     actual  number of  characters read  disagrees with  the count
|     from   WSTERM,  then  sub_err_   is  called  with   the  code
|     error_table_$unable_to_do_io.  In  these cases the  input may
|     be truncated to fit the callers buffer.
|
|     Any  other error code  resulting from io  is returned with  a
|     call to sub_err_.

| NOTES
|
| If screen_left is  >0, then a RWE control is  sent to WSTERM with
| the number  of characters to  read the minimum  of screen_left or
| n_chars_to_read.  No attempt is made  to read the characters that
| will be sent by WSTERM.
|
| If  screen_left is  equal to  zero, no  RWE control  is sent, but
| rather   the  input   from  the    previous  RWE   is  read   via
| iox_$get_chars.


  Video Support for MOWSE                                  MTB756-2

  PROTOCOL                                                          |
                                                                    |
       ws_tty_             wsterm                                   |
       ------              ------                                   |
  screen_left >0                                                    |
       RWE(count)---------->(switch to read and echo on screen)     |
       (count=min(screen,n_chars_to_read))                          |
                                                                    |
  screen_left =0                                                    |
       (read)   <---------- EEI(count,chars)                        |
                           (input returned when either              |
                            1. break character input                |
                            2. count satisfied                      |
                            3. output to write received             |
                            4. quit condition                       |
                            5. WS screen display limit)             |
                                                                    |


  MTB756-2                                  Video Support for MOWSE

  ENTRY:  ws_tty_$read_with_mark

  This entry is like read but a  mark is set to indicate the end of
| input.   If  the  previous  write  had  set  the mark, this entry
| returns the mark index.

  USAGE

| dcl ws_tty_$read_with_mark entry (ptr, char(*), bit (1) aligned,
|       fixed bin(21), fixed bin(21), fixed bin, fixed bin(35));

| call ws_tty_$read_with_mark (iocb_ptr, buffer, never_block,
|       n_chars_read, mark_index, state, code);

  ARGUMENTS

  iocb_ptr
      points to the I/O control block of mowse_terminal_.  (Input)

  buffer
      is the caller's buffer.  (Input)

| never_block
|     is  a  flag  indicating  if  WSTERM  should  block  on input.
|     (Input)
|     "1"b  =  do  not  block,  return  any  input  (even  if null)
|     immediately.
|     "0"b  = block  until input  complete (count  satisfied, timer
|     runout).

  n_chars_read
      is the actual number of characters returned.  (Output)
      If equal to zero, the read will still be performed.

  mark_index
      is an index in the returned string.  (Output)
|     If the mark is set at all, it  is always 1.  If not set it is
|     zero.

  state
      indicates the tty state.  (Output)
|     0 unknown
      1 ignored
      2 listening
      5 dialed

  code
      is a standard status code.  (Output)

|     A code of error_table_$no_io_permission  means that WSTERM is
|     not connected.  The code  error_table_$no_iocb is returned if
|     the iocb  pointer is null.  The  code error_table_$bad_arg is


  Video Support for MOWSE                                  MTB756-2

      returned if  n_chars_to_read is less than  zero.  In addition |
      the code may be any of those returned by iox_$control for the |
      control  order  get_terminal_emulator_state.   Any  of  these |
      codes means that the read was not performed.                  |
                                                                    |
      A  code of  error_table_$improper_data_format is  returned if |
      the  control messages  from WSTERM  are out  of sequence.  In |
      this case the read may have been partially completed.         |
                                                                    |
      If WSTERM returns more characters than asked for, sub_err_ is |
      called  with  the  code  error_table_$no_operation.   If  the |
      actual  number of  characters read  disagrees with  the count |
      from   WSTERM,  then  sub_err_   is  called  with   the  code |
      error_table_$unable_to_do_io.  In  these cases the  input may |
      be truncated to fit the callers buffer.                       |
                                                                    |
      Any  other error code  resulting from io  is returned with  a |
      call to sub_err_.                                             |
                                                                    |
  PROTOCOL                                                          |
                                                                    |
       ws_tty_             wsterm                                   |
       ------              ------                                   |
     blocked read                                                   |
       RNE(block,count)--->(switch to non-echo, initiate count)     |
       (read)  <---------- UIC(count,chars)                         |
                           (input returned when                     |
                            1. timer runnout)                       |
       (buffered)<-------- UIC(count,chars) ...                     |
       (buffered)<-------- ENI(count,chars)                         |
                           (input returned when                     |
                            1. count satisfied                      |
                            2. screen output recieved               |
                            3. break character input                |
                            4. quit condition                       |
                            5. WS screen display limit              |
                                                                    |
     no block read (for re-sync)                                    |
       RNE(noblock,count)-->(switch no non-echo, initiate count)    |
       (read)   <---------- UIC(count,chars) (buffered)             |
       ...                 ...                                      |
       (read)   <---------- UIC(count,chars) (buffered)             |
       (read)   <---------- ENI(count,chars)                        |
                            (up to count chars sent                 |
                             immediately even if count =0)          |


  MTB756-2                                  Video Support for MOWSE

  ENTRY:  ws_tty_$write

  This  entry  displays  the  caller's  text  by  sending it to the
| workstation.  The write mark is also  turned off by this entry so
| that a following read_with_mark call will not find the mark set.

  USAGE

  dcl ws_tty_$write entry (ptr, ptr, fixed bin(21), fixed bin(21),
        fixed bin(21), fixed bin, fixed bin(35));

  call ws_tty_$write (iocb_ptr, buffer_ptr, offset,
        n_chars_to_write, n_chars_written, state, code);

  ARGUMENTS

  iocb_ptr
      points to the I/O control block of mowse_terminal_.  (Input)

  buffer_ptr
      pointer to caller's buffer.  (Input)

  offset
      is the offset in caller's buffer to start at.  (Input)

  n_chars_to_write
      is the maximum number of characters supplied.  (Input)

  n_chars_written
      is the actual number of characters written.  (Output)

  state
      indicates the tty state.  (Output)
|     0 unknown
      1 ignored
      2 listening
      5 dialed

  code
      is a standard status code.  (Output)

|     A code of error_table_$no_io_permission  means that WSTERM is
|     not connected.  The code  error_table_$no_iocb is returned if
|     the iocb  pointer is null.  The  code error_table_$bad_arg is
|     returned if n_chars_to_write is  less than zero.  In addition
|     the code may be any of those returned by iox_$control for the
|     control  order  get_terminal_emulator_state.   Any  of  these
|     codes means that the write was not performed.
|
|     Any io error code will be passed to sub_err_.


  Video Support for MOWSE                                  MTB756-2

  ENTRY:  ws_tty_$write_whole_string

  This entry is  the same as write.  It displays  the caller's text
  by sending it to the workstation.  This entry has a mark_set flag |
  that  indicates if  the following  read_with_mark should  set the |
  mark on input.                                                    |

  USAGE

  dcl ws_tty_$write_whole_string entry (ptr, char(*), bit(1), fixed
        bin(21), fixed bin, fixed bin(35));

  call ws_tty_$write_whole_string (iocb_ptr, string, mark_flag,
        n_chars_written, state, code);

  ARGUMENTS

  iocb_ptr
      points to the I/O control block of mowse_terminal_.  (Input)

  string
      is the caller's character string to write.  (Input)

  mark_flag
      indicates whether read_with_mark is to set a mark.  (Input)   |
      "0"b don't set mark
      "1"b set mark

  n_chars_written
      is the actual number of characters written.  (Output)

  state
      indicates the tty state.  (Output)
      0 unknown                                                     |
      1 ignored
      2 listening
      5 dialed

  code
      is a standard status code.  (Output)

      A code of error_table_$no_io_permission  means that WSTERM is |
      not connected.  The code  error_table_$no_iocb is returned if |
      the iocb  pointer is null.  The  code error_table_$bad_arg is |
      returned if n_chars_to_write is  less than zero.  In addition |
      the code may be any of those returned by iox_$control for the |
      control  order  get_terminal_emulator_state.   Any  of  these |
      codes means that the write was not performed.                 |
                                                                    |
      Any io error code will be passed to sub_err_.                 |


  MTB756-2                                  Video Support for MOWSE

  3.2:  Workstation Interfaces

  The  ws_tty_ modules  communicate with  the workstation  software
  (WSTERM)  via calls to  iox_.  Actually these  calls to iox_  are
  calls to  mowse_io_ which itself  uses iox_ to  exchange messages
  with the MOWSE software on the workstation which in turn talks to
  WSTERM.

  There are  two basic means  by which ws_tty_  and WSTERM exchange
  data.  The  most common method is via  specific control messages.
  These  control   messages  are  sent  to  WSTERM   with  an  iox_
  "send_message"  control order  and  fetched  from WSTERM  with an
  iox_$get_chars call.  Control messages are for exchanging control
  data concerning the workstation  environment and also for reading
  user entered text.

  The  second method of  communication is for  writing text to  the
  workstation  screen.   This  is  done  by  ws_tty_  with calls to
  iox_$put_chars.   Using  this  method  of  writing  text  to  the
  workstation guarantees that plain text written to the screen will
  not  be missinterpreted as  a control message.   Control messages
  and  written text  are identified  by WSTERM  by their  different
  min-cap ids.

| A user signaled quit condition changes the way these messages are
| handled.  When the quit (break)  is signaled, WSTERM flushes data
| i/o but continues to read and respond to control messages.

  3.2.1:  CONTROL MESSAGE EXAMPLE

  Suppose we want ws_tty_ to send  the control message to WSTERM to
  exit sync  mode.  The control message text  is "XSM000000".  To
  send this we first append  the foreground control message min-cap
  id to the front of the message.

   control_message = FG_CONTROL_MESSAGE || "XSM000000"

  Then using

   call iox_$control(iocb_ptr, "send_message", mowse_io_message_ptr,
                      code);

   where mowse_io_message_ptr ->
         mowse_io_message.version = mowse_io_info_version_1;
         mowse_io_message.channel = FG;
         mowse_io_message.io_message_ptr = addr(control_message);
         mowse_io_message.io_message_len = 10;

  will send  the message to WSTERM.  (The  constants and structures
  are defined in the mowse include files.)  Then when WSTERM does a


  Video Support for MOWSE                                  MTB756-2

  getdata  it  will  find  the  text  "XSM000000"  with the minor
  capability field set to FG_CONTROL_MESSAGE.

  3.2.2:  SENDING TEXT EXAMPLE

  But if we want ws_tty_ to send the plain text "hello world", this
  is the procedure when we set

   term_message = "hello world";

   call iox_$put_chars (iocb_ptr, addr(term_message), 11, code);

  Then WSTERM will  see the text "hello world" with  the min cap of
  FG_TERMINAL_DATA.

  Likewise,  ws_tty_  reads  data  from   WSTERM  with  a  call  to
  iox_$get_chars.

  3.2.3:  CONTROL MESSAGE FORMAT

  The  following  description  of  the  control  messages  does not
  include  the FG_CONTROL_MESSAGE  byte  appended  to the  front of
  messages sent from ws_tty_ to WSTERM.

      byte:   1   2    3    4   5   6..size+5
            --------------------------------------------
            | message id | size   | data ...           |
            --------------------------------------------

  message id
      is  a 3 character  field identifing the  message type and  is
      defined below.

  size
      is the  number of bytes  of data and  is zero if  there is no
      data.  This  is a two  byte (16 bit)  unsigned binary number.
      The largest  data size is  therefore 2**16-1 or  65535 bytes.
      (The size  field is interpreted slightly  differently for the
      read  type messages.   See the  discussion of  the read  data
      "count" below.)

  data
      may  or may  not be  present  depending  on the  type and  is
      defined below.


  MTB756-2                                  Video Support for MOWSE

  3.2.3.1:  Control Message Types

  The functionality of the following controls is detailed in MTB741
  section  6  and  MTB708.   These   message  ids  are  defined  in
  ws_control_ids.incl.pl1.

  message type               message  direction     data
                                id  ws_tty_:WSTERM
  ---------------------------- ---- --------------  ---------------
  Abort                         ABT        ->       -
  Enter Sync Mode               ESM        ->       break table
  Sync Mode Entered             SME       <-        -
  Exit Sync Mode                XSM        ->       -
  Sync Mode Exited              SMX       <-        -
  End Echoed Input              EEI       <-        text
  End Non-echoed Input          ENI       <-        text
  Read with No Echo             RNE        ->       count
  Read With Echo                RWE        ->       count
  Set Break Table               SBT        ->       break table
  Set TTY Modes                 STM        ->       tty modes
  Echoed Input Chars            EIC       <-        text
  Unechoed Input Chars          UIC       <-        text
  Printer On                    PON        ->       -
  Printer Off                   POF        ->       -
  Order                         ORD        ->       control order
  -----------------------------------------------------------------

  3.2.3.1.1:  Break table

  The  break table  format is   simply the  list of  printing ASCII
  characters that are to be  interpreted as causing break on input.
  The nonprinting control characters (octal 000 to 037 and 177) are
  always break characters.  If the break table is null, that is the
  size is zero, there are no  break characters.  If the break table
  size is -1 break-all mode is indicated and no break table data is
  present.

  3.2.3.1.2:  TTY modes

  The  TTY  modes  data  is  a  six  byte  field which contains the
  following values:
        data byte     contents
          -----       ----------
            1         mode switches, to be further defined as needed
            2         kill character (default is @)
            3         erase character (default is #)
            4         literal next character (default is )
            5         maximum column or line length (default is 80)
            6         max lines or page length (default is 23)


  Video Support for MOWSE                                  MTB756-2

  3.2.3.1.3:  Control order

  The data field of the Order  control message is the ascii text of
  the order as passed to ws_tty_ plus any relevant data specific to
  the control  order.  No control orders are  currently required to
  be  passed  to  WSTERM,  but  this  mechanism  will allow for the
  possibility in the future.

  3.2.3.1.4:  Read count

  The count in RNE and RWE is a two byte or 16 bit field containing
  an integer of the number of  characters to read.  In the unlikely
  event that  the read count  exceeds this 64K  field, ws_tty_ will
  make repeated reads until the count is satisfied.

  The size field is interpreted  differently for the read messages. |
  The two byte "size field" is a  one byte flag field followed by a |
  one byte size  field.  (The value of the size  will always be 2.) |
  The flag byte is used to communicate special read requirements to |
  WSTERM.  One flag is currently defined.                           |
                                                                    |
       dcl 1 read_flags unaligned,                                  |
             2 MBZ         bit (1), /* this bit gets truncated */   |
             2 no_block    bit (1), /* left-most bit to WSTERM */   |
             2 pad         bit (7);                                 |
                                                                    |
  If set, the no_block flag  requests WSTERM to return the contents |
  of  its  input  buffer  immediately.   In  this  case if WSTERM's |
  keyboard  input buffer  were empty,  a count  of zero  and a null |
  string would be returned.  If  the buffer contains characters but |
  no break  character, then those characters are  returned.  If the |
  buffer does  contains a break character, then  the characters are |
  returned immediately in the same fashion as a normal read.        |
                                                                    |
  The no_block  flag is required because  this is the only  way for |
  ws_tty_ to determine whether there is indeed no user input at the |
  time of the read request.   Some applications, notably emacs, use |
  this "feature" to determine if there has been any type-ahead.     |

  3.2.3.1.5:  Text

  Text data is  simply a string of ASCII characters,  one per byte.
  The number of characters is given by the message size.