UPON Phrase

UPON new-window

1. The UPON phrase is used to update a floating window that is not the current floating window. In this phrase new-window is a USAGE HANDLE or PIC X(10) data item that contains a valid floating window handle. The floating window specified by new-window becomes the current window for the duration of the DISPLAY statement.
2. If you create a new floating window while in the scope of the UPON phrase, the new window becomes the current window after the DISPLAY statement terminates. Otherwise, the window that was current before the DISPLAY UPON statement executed is restored to the current window. For example, if the main application window is current and you execute:

   DISPLAY FLOATING WINDOW UPON MAIN-WINDOW, ...

   when the DISPLAY statement terminates, the new floating window becomes the current window, instead of the main application window.

   Note: new-window is always the current window for the entire remaining DISPLAY statement, even if you mix DISPLAY formats. For example:

   DISPLAY SUBWINDOW UPON WINDOW-1, 
      AT 0504, LINES 5, SIZE 30, BOXED
      "Line 1", LINE 1,
      "Line 2", LINE 2.

   The above code creates a new subwindow in WINDOW-1 and then displays two lines in the new subwindow. The UPON WINDOW-1 phrase applies to both the DISPLAY SUBWINDOW operation and the display of the subsequent text items because they are all specified in one DISPLAY statement.

3. When you mix several DISPLAY formats, the logic to determine the current window is applied sequentially through the statement. Here is a complex example:

   DISPLAY FLOATING WINDOW UPON WINDOW-1
      LINES 10, SIZE 40, BOXED, 
      HANDLE IN WINDOW-99;
      "Line 1", LINE 1,
      "Line 2", UPON WINDOW-2, LINE 2
      "Line 3", LINE 3.

   In this example, the new floating window (WINDOW-99) is created with WINDOW-1 as its parent (because of the first UPON phrase). Normally, this UPON phrase would cause "Line 1" to display in WINDOW-1 too, but the DISPLAY FLOATING WINDOW operation causes the new window to become the current window. So, "Line 1" is shown in WINDOW-99 instead. This would apply to "Line 2" also, but it specifies its own UPON phrase, so it displays in WINDOW-2. "Line 3" also displays in WINDOW-2 because that was the last window specified. At the end of the DISPLAY statement, the new floating window, WINDOW-99, is made the current window.