AG93-05A documentation inaccuracies/omissions

[jcooperddtd@…]

Documentation for window_ is inaccurate/incomplete in the following ways:

Page 3-264, GET CHARS OPERATION states:

"This operation returns exactly one character, unechoed, regardless of the size of the caller's buffer."

This is incorrect since window_io_iox_$get_chars echoes typed characters by default. This section also fails to explain that echoing can be controlled by the undocumented printer_on/printer_off CONTROL OPERATION.

Missing printer_on/printer_off CONTROL OPERATION:

The documentation for window_io_iox_$control fails to describe the printer_on and printer_off commands which enable or disable echoing of typed characters when window_io_iox_$get_chars is used. The documentation for these commands should describe them as needing no extra data to be passed to the control call (i.e., pass null ()).

[Eric Swenson]

Milestone renamed

[Gary Dixon]

The documentation for window_io_ Get Chars Operation is inaccurate in several respects. While it may have been accurate when window_io_ was initially released, the current get_chars operation returns more than one character per call, and selectively echoes those characters (or not depending upon use of the printer_on/printer_off control order) as they are read and returned to the caller of iox_$get_chars. Code for window_io_iox_$get_chars is shown below:

get_chars:
     entry (Iocb_ptr, Buffer_ptr, Buffer_len, N_returned, Code);

          Code = 0;
          N_returned = 0;

          iocb_ptr = Iocb_ptr -> iocb.actual_iocb_ptr;
          attach_data_ptr = iocb_ptr -> iocb.attach_data_ptr;

          attach_data.discard_output = "0"b;
          attach_data.lines_written_since_read = 0;

          if Buffer_len = 0 | Buffer_ptr = null () then
               return;

/* Read all the characters the user has typed so far. */
          do char_count = 1 by 1;
               call window_$get_one_unechoed_char (iocb_ptr, char_varying, "0"b /* don't block */, Code);
               if Code ^= 0 then
                    return;

/* No more characters. */
               if length (char_varying) = 0 then do;
                    N_returned = char_count - 1;
                    return;
               end;

               substr (Buffer, char_count, 1) = char_varying;

/* If we are supposed to echo, try echoing through put_chars.
   This is pretty weird, but gets output conversions done. */

               if ^attach_data.suppress_echo then do;
                    char_nonvarying = char_varying;
                    call iox_$put_chars (iocb_ptr, addr (char_nonvarying), 1, Code);
                    if Code ^= 0 then
                         return;
               end;
          end;

          return;

As demonstrated by this code, the "do char_count = 1 by 1" loop continues reading characters using window_$get_one_unechoed_char until a nonzero Code value is returned, or until no character is available from input typed by the user (until length(char_varying) = 0).

Each of the read characters is echoed back to the terminal via iox_$put_chars unless the printer_off control order has set attach_data.suppress_echo to "1"b.

The documentation errata for Get Chars Operation should update description of this operation in those respects.