1 :Info: window_: 2019-06-01 window_
2
3 The window_ subroutine provides a terminal independent interface to
4 video terminal operations. More specifically, it controls and performs
5 I/O to a window.
6
7 The window_ subroutine is used in conjunction with the iox_ subroutine
8 call entry points in the window_io_ I/O module. The window_ and
9 video_utils_ subroutines together perform the same functions as the
10 window_call command.
11
12 The virtual terminal implemented by window_ corresponds closely to
13 common video terminals. The features of the terminal are defined
14 implicitly by the entries below. Not all entries can be supported on
15 all terminals. The result of calling an unsupported feature is the
16 error code video_et_$capability_lacking. Programs can determine
17 whether the device in question supports a given operation by using a
18 get_capabilities control order, described under the window_io_ I/O
19 module.
20
21
22 Some entry points require that the current cursor position be defined
23 when they are called. The current position is defined unless a call is
24 made to the write_raw_text entry point, or an asynchronous event
25 changes the window contents. If the current position is not defined,
26 these entry points will return the status code
27 video_et_$cursor_position_undefined.
28
29 If an asynchronous event changes the state of the window, status will
30 be set for the window. Once window status is set, all calls to window_
31 on that window will return the status code
32 video_et_$window_status_pending until a get_window_status control order
33 is used to pick up the status.
34
35 The calling sequences for all the entry points are in the include file
36 window_dcls.incl.pl1.
37
38
39 Entry points in window_:
40 List is generated by the help command
41
42
43 :Entry: bell: 1985-03-07 window_$bell
44
45
46 Function: This entry activates the terminal alarm. For most
47 terminals, this will be the audible bell. For some it will be a
48 visible signal.
49
50
51 Syntax:
52 declare window_$bell entry ptr fixed bin 35;
53 call window_$bell iocb_ptr code;
54
55
56 Arguments:
57 iocb_ptr
58 is a pointer to an IOCB for a switch attached with window_io_.
59 Input
60 code
61 is a standard system error code. Output
62
63
64 Notes: The current cursor position must be dfined for this call. If
65 the cursor is in some other window on the screen when this call is
66 made, it is moved to the current position in this window.
67
68
69 :Entry: change_column: 1985-03-07 window_$change_column
70
71
72 Function: This entry moves the cursor to a different column on the
73 current line, without changing the line.
74
75
76 Syntax:
77 declare window_$change_column entry ptr fixed bin fixed bin 35;
78 call window_$change_column iocb_ptr new_column code;
79
80
81 Arguments:
82 iocb_ptr
83 is a pointer to an IOCB for a switch attached with window_io_.
84 Input
85 new_column
86 is the new column. Input
87 code
88 is a standard system error code. Output
89
90
91 Notes: The current cursor position must be defined.
92
93
94 :Entry: change_line: 1985-03-07 window_$change_line
95
96
97 Function: This entry moves the cursor to a new line without changing
98 the column.
99
100
101 Syntax:
102 declare window_$change_line entry ptr fixed bin fixed bin 35;
103 call window_$change_line iocb_ptr new_line code;
104
105
106 Arguments:
107 iocb_ptr
108 is a pointer to an IOCB for a switch attached with window_io_.
109 Input
110 new_line
111 is the new line. Input
112 code
113 is a standard system error code. Output
114
115
116 :Entry: clear_region: 1985-03-07 window_$clear_region
117
118
119 Function: This entry replaces the contents of the region specified
120 with spaces, and leaves the cursor at the upper left-hand corner of the
121 region. The region is defined by giving the upper left-hand corner
122 line and column, and the width and height of the region.
123
124
125 Syntax:
126 declare window_$clear_region entry ptr fixed bin fixed bin fixed
127 bin fixed bin fixed bin 35;
128 call window_$clear_region iocb_ptr start_line start_col n_lines
129 n_cols code;
130
131
132 Arguments:
133 iocb_ptr
134 is a pointer to an IOCB for a switch attached with window_io_.
135 Input
136 start_line
137 is the number of the line where clearing will begin. Input
138 start_col
139 is the number of the column where clearing will begin. Input
140 n_lines
141 is the number of lines which will be cleared. Input
142 n_cols
143 is the number of columns which will be cleared. Input
144 code
145 is a standard system error code. Output
146
147
148 Notes: The rectangular region described in cleared. The cursor
149 position defined at start_line start_col.
150
151
152 :Entry: clear_to_end_of_line: 1985-03-07 window_$clear_to_end_of_line
153
154
155 Function: This entry clears everything to the right of the cursor on
156 the current line to spaces. Positions to the left of the cursor are
157 not affected. The cursor is not moved.
158
159
160 Syntax:
161 declare window_$clear_to_end_of_line entry ptr fixed bin 35;
162 call window_$clear_to_end_of_line iocb_ptr code;
163
164
165 Arguments:
166 iocb_ptr
167 is a pointer to an IOCB for a switch attached with window_io_.
168 Input
169 code
170 is a standard system error code. Output
171
172
173 Notes: The cursor position must be defined.
174
175
176 :Entry: clear_to_end_of_window: 1985-03-07 window_$clear_to_end_of_window
177
178
179 Function: This entry clears all of the window between the cursor and
180 the end of the window. This includes everything to the right of the
181 cursor on the current line, and all lines below the cursor. The cursor
182 is not moved.
183
184
185 Syntax:
186 declare window_$clear_to_end_of_window entry ptr fixed bin 35;
187 call window_$clear_to_end_of_window iocb_ptr code;
188
189
190 Arguments:
191 iocb_ptr
192 is a pointer to an IOCB for a switch attached with window_io_.
193 Input
194 code
195 is a standard system error code. Output
196
197
198 Notes: The current cursor position must be defined.
199
200
201 :Entry: clear_window: 1985-03-07 window_$clear_window
202
203
204 Function: This entry clears the entire window to spaces, and leaves
205 the cursor at home.
206
207
208 Syntax:
209 declare window_$clear_window entry ptr fixed bin 35;
210 call window_$clear_window iocb_ptr code;
211
212
213 Arguments:
214 iocb_ptr
215 is a pointer to an IOCB for a switch attached with window_io_.
216 Input
217 code
218 is a standard system error code. Output
219
220
221 Notes: The cursor position is defined to be at line 1, column 1 after
222 the screen is cleared.
223
224
225 :Entry: create: 1986-11-26 window_$create
226
227
228 Function: This entry creates a new window on the terminal screen.
229
230
231 Syntax:
232 declare window_$create entry ptr ptr ptr fixed bin 35;
233 call window_$create terminal_iocb_ptr window_info_ptr
234 window_iocb_ptr code;
235
236
237 Arguments:
238 terminal_iocb_ptr
239 is a pointer to an IOCB for the terminal control switch. Input
240 Normally this should be video_data_$terminal_iocb.
241 window_info_ptr
242 is a pointer to a standard window_position_info structure, as
243 declared in window_control_info.incl.pl1. Input
244 window_iocb_ptr
245 is a pointer to a detached IOCB pointer. Input It may be obtained
246 with iox_$find_iocb which must be done before the call to
247 window_$create.
248 code
249 is a standard system error code. Output
250
251
252 Notes: The window_info_ptr must point to a window_position_info
253 structure, as declared in window_control_info.incl.pl1. If
254 window_position_info.width is set to zero, the window will occupy the
255 full width of the screen. Currently windows must occupy the full width
256 of the screen. If window_position_info.height is set to zero, the
257 remainder of the screen is used. The iocb_ptr is an input argument,
258 iox_$find_iocb may be used to obtain an iocb_ptr for a new switch.
259
260
261 :Entry: delete_chars: 1985-03-07 window_$delete_chars
262
263
264 Function: This entry deletes characters on the current line.
265 Characters to the right of the cursor are moved to the left. Character
266 positions opened up on the right margin are filled with spaces. It is
267 an error to call this entry point if the terminal does not support the
268 delete chars operation.
269
270
271 Syntax:
272 declare window_$delete_chars entry ptr fixed bin fixed bin 35;
273 call window_$delete_chars iocb_ptr n_chars code;
274
275
276 Arguments:
277 iocb_ptr
278 is a pointer to an IOCB for a switch attached with window_io_.
279 Input
280 n_chars
281 is the number of characters starting at the current cursor
282 position that will be removed from the screen. Input If n_chars
283 is zero, no action is taken.
284 code
285 is a standard system error code. Output
286
287
288 Notes: The current cursor position must be defined. The number of
289 characters specified by n_chars are deleted, and the remaining
290 characters on the line, if any, move leftward to occupy the space.
291
292
293 :Entry: destroy: 1985-03-07 window_$destroy
294
295
296 Function: This entry destroys an existing window, leaving its IOCB in
297 a detached state.
298
299
300 Syntax:
301 declare window_$destroy entry ptr fixed bin 35;
302 call window_$destroy window_iocb_ptr code;
303
304
305 Arguments:
306 window_iocb_ptr
307 is a pointer to an IOCB attached with window_$create. Input
308 code
309 is a standard system error code. Output
310
311
312 :Entry: edit_line: 1985-03-07 window_$edit_line
313
314
315 Function: This entry allows applications to preload the video editor
316 input buffer with a string.
317
318
319 Syntax:
320 declare window_$edit_line entry pointer pointer pointer fixed bin
321 21 fixed bin 21 fixed bin 35;
322 call window_$edit_line iocb_ptr window_edit_line_info_ptr
323 buffer_ptr buffer_len n_returned code;
324
325
326 Arguments:
327 window_iocb_ptr
328 is a pointer to an IOCB for a switch attached with window_io.
329 Input
330 window_edit_line_info_ptr
331 is a pointer to a window_edit_line_info structure, as declared in
332 window_control_info.incl.pl1 described below. Input
333 version
334 is the version number of the structure. Input This is currently
335 window_edit_line_version_1.
336 line_ptr
337 is a pointer to the initial text string to be loaded into the input
338 buffer before editing begins. Input
339
340
341 line_length
342 is the length of the string pointed to by line_ptr. Input
343 buffer_ptr
344 is a pointer to a buffer where the users input will be put. Input
345 buffer_len
346 is the size of the input buffer. Input
347 n_returned
348 is the number of characters in the final output line. Output
349 code
350 is a standard system error code. Output
351
352
353 :Entry: get_cursor_position: 1985-03-07 window_$get_cursor_position
354
355
356 Function: This entry is used to return the current position of the
357 cursor. If the last operation done to the terminal was in some other
358 window, this will not be the actual position of the cursor on the
359 screen.
360
361
362 Syntax:
363 declare window_ $get_cursor_position entry ptr fixed bin fixed bin
364 fixed bin 35;
365 call window_$get_cursor_position iocb_ptr line col code;
366
367
368 Arguments:
369 iocb_ptr
370 is a pointer to an IOCB for a switch attached with window_io_.
371 Input
372 line
373 is the line number. Output
374 col
375 is the column position. Output
376 code
377 is a standard system error code. Output
378
379
380 Notes: The current cursor position must be defined.
381
382
383 :Entry: get_echoed_chars: 1985-03-07 window_$get_echoed_chars
384
385
386 Function: This entry accepts input from the typist, echoing the
387 characters as typed, until either a specified number of characters are
388 read, or a break character is encountered. By default, the break
389 characters are the control characters plus DEL 177 octal.
390
391
392 Syntax:
393 declare window_$get_echoed_chars entry ptr fixed bin 21 char *
394 fixed bin 21 char 1 varying fixed bin 35;
395 call window_$get_echoed_chars iocb_ptr n_to_get buffer n_got
396 break code;
397
398
399 Arguments:
400 iocb_ptr
401 is a pointer to an IOCB for a switch attached with window_io_.
402 Input
403 n_to_get
404 is the number of columns N between the cursor and the end of the
405 line. Input At most N characters will be returned.
406 buffer
407 is the caller-supplied buffer that holds characters returned.
408 Input
409
410
411 n_got
412 is the number of characters returned. Output Each character is
413 echoed.
414 break
415 is the character that causes the echoing to stop. Output This
416 character is not echoed.
417 code
418 is a standard system error code. Output
419
420
421 Notes: This entry point returns no more than n_to_get characters in
422 buffer. It reads and echoes characters until either 1 it has read
423 n_to_get characters, or 2 it has read a break character. If it stops
424 due to a break character, the break character is returned in break,
425 otherwise break is equal to "".
426
427
428 :Entry: get_one_unechoed_char: 1985-03-07 window_$get_one_unechoed_char
429
430
431 Function: This entry reads a single character, unechoed, from the
432 terminal. Optionally, it can return instead of waiting if there are no
433 characters available.
434
435
436 Syntax:
437 declare window_$get_one_unechoed_char entry ptr char 1 varying
438 bit 1 aligned fixed bin 35;
439 call window_$get_one_unechoed_char iocb_ptr char_read block_flag
440 code;
441
442
443 Arguments:
444 iocb_ptr
445 is a pointer to an IOCB for a switch attached with window_io_.
446 Input
447 char_read
448 is the read character. Output If block_flag is "0"b, and no input
449 is typed ahead, then this will be a zero length character string.
450 block_flag
451 if this flag is "1"b, input from the terminal is awaited if none is
452 available. Input If it is "0"b, and no input is available, then
453 this entry returns immediately, and sets char_read to "".
454 code
455 is a standard system error code. Output
456
457
458 Notes: Beware of the PL/I language definition of character string
459 comparisons when using this entry with a block flag of "0"b. In PL/I,
460 both of the following comparisons are true:
461
462 " " = " "
463 "" = " "
464
465 That is, a zero length varying string compares equally to a single
466 space. To test if char_read is nonempty, use an expression like:
467
468 length char_read > 0
469
470
471
472 :Entry: get_unechoed_chars: 1985-03-07 window_$get_unechoed_chars
473
474
475 Function: This entry accepts input from the typist, leaving it
476 unechoed, until either a specified number of characters are read, or a
477 break character is encountered.
478
479
480 Syntax:
481 declare window_$get_unechoed_chars entry ptr fixed bin 21
482 char * fixed bin 21 char 1 varying fixed bin 35;
483 call window_$get_unechoed_chars iocb_ptr n_to_get buffer n_got
484 break code;
485
486
487 Arguments:
488 iocb_ptr
489 is a pointer to an IOCB for a switch attached with window_io_.
490 Input
491 n_to_get
492 is the number of columns N between the cursor and the end of the
493 line. Input At most N characters will be returned.
494 buffer
495 is the caller-supplied buffer that holds characters returned.
496 Input
497
498
499 n_got
500 is the number of characters returned. Output Each character is
501 echoed.
502 break
503 is the character that causes the echoing to stop. Output This
504 character is not echoed.
505 code
506 is a standard system error code. Output
507
508
509 Notes: This entry point will read no more than n_to_get characters
510 from the terminal, without echoing them to the typist. The characters
511 are returned in the buffer. Characters are read until either 1
512 n_to_get characters are read, or 2 a break character is read. If
513 reading stops due to a break character, then the break character is
514 returned in break. Otherwise break is "".
515
516
517 :Entry: insert_text: 1985-03-07 window_$insert_text
518
519
520 Function: This entry inserts text at the current cursor position.
521 Text at the cursor or to the right of the cursor is shifted to the
522 right, to accommodate the new text. It is an error to call this entry
523 if the terminal does not support the insertion of text.
524
525
526 Syntax:
527 declare window_$insert_text entry ptr char * fixed bin 35;
528 call window_$insert_text iocb_ptr text code;
529
530
531 Arguments:
532 iocb_ptr
533 is a pointer to an IOCB for a switch attached with window_io_.
534 Input
535 text
536 is the character string to be written. Input When converted to
537 output, each character in this string must occupy exactly one print
538 position. The length of this string must be such that characters
539 moved to the right will remain on the current line in the window.
540 If these conditions are not met, the result is undefined. The
541 cursor is left after the last character inserted.
542 code
543 is a standard system error code. Output
544
545
546 Notes: The current cursor position must be defined. The string "text"
547 must contain only printable ASCII graphics. If it contains any other
548 characters, the status code video_et_$string_not_printable is returned.
549
550
551 :Entry: overwrite_text: 1985-03-07 window_$overwrite_text
552
553
554 Function: This entry writes text on the window in the current cursor
555 location. If there is any text at or to the right of the current
556 cursor position in the window, it is overwritten with the supplied
557 string.
558
559
560 Syntax:
561 declare window_$overwrite_text entry ptr char * fixed bin 35;
562 call window_$overwrite_text iocb_ptr text code;
563
564
565 Arguments:
566 iocb_ptr
567 is a pointer to an IOCB for a switch attached with window_io_.
568 Input
569 text
570 is the character string to be written. Input This string should
571 consist of only printable ASCII graphics octal codes 040 through
572 176 inclusive, and may not be longer than the space remaining on
573 the current line.
574 code
575 is a standard system error code. Output
576
577
578 Notes: The cursor position must be defined. The string "text" may
579 contain only printable ASCII graphics. If it contains anything else
580 the status code video_et_$string_not_printable is returned.
581
582
583 :Entry: position_cursor: 1985-03-07 window_$position_cursor
584
585
586 Function: This entry moves the cursor to any requested position in the
587 window. It defines the current cursor position if it is undefined.
588
589
590 Syntax:
591 declare window_$position_cursor entry ptr fixed bin fixed bin
592 fixed bin 35;
593 call window_$position_cursor iocb_ptr line col code;
594
595
596 Arguments:
597 iocb_ptr
598 is a pointer to an IOCB for a switch attached with window_io_.
599 Input
600 line
601 is the line number. Input
602 col
603 is the column position. Input
604 code
605 is a standard system error code. Output
606
607
608 :Entry: position_cursor_rel: 1985-03-07 window_$position_cursor_rel
609
610
611 Function: The entry moves the cursor relative to the current location.
612
613
614 Syntax:
615 declare window_$position_cursor_rel entry ptr fixed bin fixed bin
616 fixed bin 35;
617 call window_$position_cursor_rel iocb_ptr line_inc col_inc code;
618
619
620 Arguments:
621 iocb_ptr
622 is a pointer to an IOCB for a switch attached with window_io_.
623 Input
624 line_inc
625 is the change in line number. Input If line_inc is a positive
626 number, the cursor is moved down. If it is a negative number, the
627 cursor is moved up. If it is zero, the cursor's line number is not
628 changed.
629 col_inc
630 is the change in column position. Input If col_inc is a positive
631 number, the cursor is moved to the right. If it is a negative
632 number, the cursor is moved to the left. If it is zero, the
633 cursor's column position is not changed.
634 code
635 is a standard system error code. Output
636
637
638 :Entry: scroll_region: 1985-03-07 window_$scroll_region
639
640
641 Function: This entry scrolls a region up or down a given number of
642 lines. A positive scroll count scrolls the window up, deleting lines
643 from the top of the window and adding new blank lines to the bottom.
644 The cursor's new position is at the beginning of the first new blank
645 line. A negative count scrolls the window down, deleting lines from
646 the bottom and adding lines to the top. The cursor is left at home.
647 If this entry is called and the terminal does not support either
648 scrolling or insert and delete lines, the result is an error status,
649 video_et_$capabilities_lacking.
650
651
652 Syntax:
653 declare window_$scroll_region entry ptr fixed bin fixed bin fixed
654 bin fixed bin 35;
655 call window_$scroll_region iocb_ptr start_line n_lines
656 scroll_distance code;
657
658
659 Arguments:
660 iocb_ptr
661 is a pointer to an IOCB for a switch attached with window_io_.
662 Input
663 start_line
664 is the number of the first line of the region. Input
665 n_lines
666 is the number of lines that compose the region. Input
667 scroll_distance
668 is the distance in lines by which the region will be scrolled.
669 Input
670 code
671 is a standard system error code. Output
672
673
674 Notes: The cursor position is defined to be column one on first_line.
675 The region from first_line for n_lines is scrolled scroll_distance
676 lines, which may be negative.
677
678
679 :Entry: sync: 1985-03-07 window_$sync
680
681
682 Function: This entry synchronizes the process with the typist by
683 writing any pending output to the terminal.
684
685
686 Syntax:
687 declare window_$sync entry ptr fixed bin 35;
688 call window_$sync iocb_ptr code;
689
690
691 Arguments:
692 iocb_ptr
693 is a pointer to an IOCB for a switch attached with window_io_.
694 Input
695 code
696 is a standard system error code. Output
697
698
699 Notes: The calling process is made to wait until the typist types
700 something after the last text output has been transmitted to the
701 terminal.
702
703
704 :Entry: write_raw_text: 1985-03-07 window_$write_raw_text
705
706
707 Function: This entry is used to output a terminal dependent sequence.
708 The current cursor position becomes undefined after this call is made.
709 This entry should not be used to output sequences that put graphics
710 onto the terminal screen, as the video system's internal screen image
711 will become inconsistent. This entry is used for terminal-specific
712 features that cannot be accessed via the video system.
713
714
715 Syntax:
716 declare window_$write_raw_text entry ptr char * fixed bin 35;
717 call window_$write_raw_text iocb_ptr text code;
718
719
720 Arguments:
721 iocb_ptr
722 is a pointer to an IOCB for a switch attached with window_io_.
723 Input
724 text
725 is any string of printable ASCII characters to be transmitted to the
726 terminal. Input
727 code
728 is a standard system error code. Output
729
730
731 Notes: Any call to window_$write_raw_text causes the cursor position
732 to become undefined and sets the screen_invalid window status flag.
733 Subsequent calls to write_raw_text will ignore this flag, but all other
734 window_ entrypoints will return the status code
735 video_et_$window_status_pending until the status flag is cleared. It
736 is the responsibility of the application performing the raw output call
737 to perform a get_window_status control order to clear the status flag.
738
739
740 :Entry: write_sync_read: 1985-03-07 window_$write_sync_read
741
742
743 Function: This entry writes a prompt, synchronizes input to the output
744 of the prompt, and reads a response. This entry is useful for queries
745 where it is important to avoid interpreting type-ahead as a response to
746 a question.
747
748
749 Syntax:
750 declare window_$write_sync_read entry ptr char * fixed bin 21
751 char * fixed bin 21 char 1 varying fixed bin 35;
752 call window_$write_sync_read iocb_ptr prompt n_to_get buffer
753 n_got break code;
754
755
756 Arguments:
757 iocb_ptr
758 is a pointer to an IOCB for a switch attached with window_io_.
759 Input
760 prompt
761 is a string of printable ASCII characters which must fit on the
762 current line. Input
763 n_to_get
764 is the number of columns N between the cursor and the end of the
765 line. Input At most N characters will be returned.
766
767
768 buffer
769 is the caller-supplied buffer that holds characters returned.
770 Input
771 n_got
772 is the number of characters returned. Output Each character is
773 echoed.
774 break
775 is the character that causes the echoing to stop. Output This
776 character is not echoed.
777 code
778 is a standard system error code. Output
779
780
781 Notes: The current cursor position must be defined. This entry
782 overwrites the text string "prompt" at the current cursor position. It
783 then reads characters typed after the prompt has been transmitted to
784 the terminal. The characters are read in the same fashion as the
785 get_unechoed_chars entry point. Any characters read before the prompt
786 is transmitted, are buffered and returned to get_echoed_chars or
787 subsequent get_unechoed_chars calls.
788
789
790 :Internal: history_comment.gi: 2019-06-01 history_comment
791
792 /****^ HISTORY COMMENTS:
793 1) change2019-06-01Swenson, approve2019-06-01MCR10062,
794 audit2019-06-01GDixon, install2019-06-01MR12.6g-0025:
795 Fix typo.
796 END HISTORY COMMENTS */