DEFINE WINDOW

DEFINE WINDOW window-name

 

  AUTO

SIZE   QUARTER
    operand1 * operand2

BASE

  CURSOR  

TOP    LEFT

BOTTOM RIGHT
operand3 / operand4  
  [REVERSED [(CD=background-color)]]
  [TITLE operand5]

CONTROL

WINDOW

SCREEN

FRAMED

[ON] [( CD=frame-color)] [position-clause]
OFF

This document covers the following topics:

For an explanation of the symbols used in the syntax diagram, see Syntax Symbols.

Related Statements: INPUT | REINPUT | SET WINDOW

Belongs to Function Group: Screen Generation for Interactive Processing

DEFINE WINDOW Usage

The DEFINE WINDOW statement is used to specify the size, position and attributes of a window.

A window is that segment of a logical page, built by a program, which is displayed on the terminal screen. There is always a window present, although you may not be aware of its existence: unless specified differently, the size of the window is identical to the physical size of your terminal screen.

A DEFINE WINDOW statement does not activate a window; this is done with a SET WINDOW statement or with the WINDOW clause of an INPUT statement.

Note:
There is always only one Natural window, that is, the most recent window. Any previous windows may still be visible on the screen, but are no longer active and are ignored by Natural. You may enter input only in the most recent window. If there is not enough space to enter input, the window size must be adjusted first.

DEFINE WINDOW Syntax Description

Operand Definition Table:

Operand Possible Structure Possible Formats Referencing Permitted Dynamic Definition
operand1 C S           N P I                 yes no
operand2 C S           N P I                 yes no
operand3 C S           N P I                 yes no
operand4 C S           N P I                 yes no
operand5 C S       A U                       yes no

Syntax Element Description:

Syntax Element Description
window-name The window-name identifies the window. The name may be up to 32 characters long. For a window name, the same naming conventions apply as for user-defined variables, see Naming Conventions for User-Defined Variables in the Using Natural documentation.
SIZE

With the SIZE clause, you specify the size of the window.

Note:
On mainframe computers, Natural requires additional columns for so-called attribute bytes to be able to display data on the screen (on other platforms, such attribute bytes are not needed). Consequently, on mainframe computers the screen area overlaid by a window is wider, and the size of the page segment visible inside a window is smaller than on other platforms.

Example: Assume a window whose size is defined as SIZE 5 * 15 (that is, with a width of 15 columns):

  • On mainframe computers, the screen area overlaid by the window is 16 columns; the size of what is visible inside the window is 14 columns without frame, and 10 columns with frame respectively.

  • On other platforms, the screen area overlaid by the window is 15 columns; the size of what is visible inside the window is 15 columns without frame, and 13 columns with frame respectively.

SIZE AUTO

The size of the window is determined automatically by Natural at runtime. The size is determined by the data generated into the window as follows:

  • The number of window lines will be the number of INPUT lines generated (plus possibly the PF-key lines, message line, and infoline/statistics line).

  • The number of window columns is determined by the longest INPUT line: Natural scans, starting from the ends of the lines, for the rightmost significant byte in a line. This may cause an input-only or modifiable field ( AD=A or AD=M ) to be truncated; to avoid this, you either put a single-character text string after such a field or explicitly set the window size with the following: 

    SIZE operand1 *
            operand2

If you omit the SIZE clause, SIZE AUTO applies by default.

Note:
The title is not part of the window data. Therefore, if the window size has been determined as described above and the title is longer than the window, it will be truncated.

SIZE QUARTER The size of the window will be one quarter of the physical screen.
SIZE operand1 * operand2

The size of the window will be n lines by n columns. The number of lines is determined by operand1, the number of columns by operand2. Neither of the two operands must contain decimal digits.

If the window is FRAMED, the specified size will be inclusive of the frame.

The minimum possible window size is:

  • without frame: 2 lines by 10 columns,

  • with frame: 4 lines by 13 columns.

The maximum possible window size is the size of the physical screen.
BASE With the BASE clause, you determine the position of the window on the physical screen. If you omit the BASE clause, BASE CURSOR applies by default.
BASE CURSOR Places the top left corner of the window at the current cursor position. The cursor position is the physical position of the cursor on the screen. If the size of the window makes it impossible to place the window at the cursor position, Natural automatically places the window as close as possible to the desired position.
BASE TOP/BOTTOM LEFT/RIGHT Places the window at the top-left, bottom-left, top-right, or bottom-right corner respectively of the physical screen.
BASE operand3/operand4

This places the top left corner of the window at the specified line/column of the physical screen. The line number is determined by operand3, the column number by operand4. Neither of the two operands must contain decimal digits.

If the size of the window makes it impossible to place the window at the specified position, you will get an error message.

REVERSED REVERSED will cause the window to be displayed in reverse video (if the screen used supports this feature; if it does not, REVERSED will be ignored).
REVERSED CD= background-color

This will cause the window to be displayed in reverse video and the background of the window in the specified color (if the screen used supports these features; if it does not, the respective specification will be ignored).

For information on valid color codes, see session parameter CD in the Parameter Reference.

TITLE operand5

With the TITLE clause, you may specify a heading for the window. The specified title (operand5) will be displayed centered in the top frame-line of the window. The title can be specified either as a text constant (in apostrophes) or as the content of a user-defined variable. If the title is longer than the window, it will be truncated. The title is only displayed if the window is FRAMED; if FRAMED OFF is specified for the window, the TITLE clause will be ignored.

Note:
If the title contains trailing blanks, these will be removed. If the first character of the title is a blank, one blank will automatically be appended to the title.

CONTROL With the CONTROL clause, you determine whether the PF-key lines, the message line and the statistics line are displayed in the window or on the full physical screen.
CONTROL WINDOW CONTROL WINDOW causes the lines to be displayed inside the window.

If you omit the CONTROL clause, CONTROL WINDOW applies by default.

CONTROL SCREEN CONTROL SCREEN causes the lines to be displayed on the full physical screen outside the window.
FRAMED

By default, that is, if you omit the FRAMED clause, the window is framed.

The top and bottom frame lines are cursor-sensitive: where applicable, you can page forward, backward, left or right within the window by simply placing the cursor over the appropriate symbol (<, -, +, or >; see position-clause below) and then pressing ENTER. If no symbols are displayed, you can page backward and forward within the window by placing the cursor in the top frame line (for backward positioning) or bottom frame line (for forward positioning) and then pressing ENTER.

Note:
If the window size is smaller than 4 lines by 12 (or 13 on mainframe computers) columns, the frame will not be visible.

FRAMED OFF If you specify FRAMED OFF, the framing and everything attached to the frame (window title and position information) will be switched off.
FRAMED (CD=frame-color)

This causes the frame of the window to be displayed in the specified color (if the screen used is a color screen; if it is not, the color specification will be ignored).

For information on valid color codes, see session parameter CD (in the Parameter Reference).

Note:
In Natural for Windows, this specification is ignored.

position-clause The POSITION clause is only evaluated on mainframe computers; on all other platforms it is ignored. For details, refer to Position Clause below.

POSITION Clause

The POSITION clause is only evaluated on mainframe computers; on all other platforms it is ignored.

POSITION

SYMBOL

TOP

[AUTO] [SHORT]

LEFT

BOTTOM RIGHT
    TEXT   [MORE]

LEFT

     
      RIGHT      
OFF

The POSITION clause causes information on the position of the window on the logical page to be displayed in the frame of the window. This applies only if the logical page is larger than the window; if it is not, the POSITION clause will be ignored. The position information indicates in which directions the logical page extends above, below, to the left and to the right of the current window.

If the POSITION clause is omitted, POSITION SYMBOL TOP RIGHT applies by default.

Syntax Element Description:

Syntax Element Description
POSITION SYMBOL Causes the position information to be displayed in form of symbols: More: < - + >. The information is displayed in the top and/or bottom frame line.
TOP/BOTTOM Determines whether the position information is displayed in the top or bottom frame line.
AUTO Is only applicable if the logical page is fully visible in the window as far as its horizontal size is concerned, that is, if only a minus sign character (-) and/or a plus sign character (+) are to be displayed. In this case, AUTO automatically switches from the symbols to the words Top, Bottom and More respectively.
SHORT Causes the word More: before the symbols < - + > to be suppressed.
LEFT/RIGHT Determines whether the position information is displayed in the left or right part of the frame line.
POSITION TEXT Causes the position information to be displayed in text form. The information is displayed in the top and/or bottom frame line with the words More,Top and Bottom. The text is language-dependent and may also be displayed in another language if the language code is set accordingly.
POSITION TEXT MORE Suppresses the words Top and Bottom and only displays the word More where applicable, i.e., in the top or bottom frame line or both.
LEFT/RIGHT Determines whether the position information is displayed in the left or right part of the top frame line.
POSITION OFF Causes the position information to be suppressed; no position information will be displayed.

Protection of Input Fields in a Window

The following rules apply to input fields (with AD=A or AD=M) which are not entirely within the window:

  • Input fields whose beginning is not inside the window are always made protected.

  • Input fields which begin inside and end outside the window are only made protected if the values they contain cannot be displayed completely in the window. Please note that in this case it is decisive whether the value length, not the field length, exceeds the window size. Filler characters (as specified with the profile parameter FC) do not count as part of the value.

If you wish to access input fields thus protected, you have to adjust the window size accordingly so that the beginning of the field/end of the value is within the window.

Invoking Different Windows

A DEFINE WINDOW statement must not be placed within a logical condition statement block. To invoke different windows depending on a condition, use different SET WINDOW statements (or INPUT statements with a WINDOW clause respectively) in a condition.

DEFINE WINDOW Example

** Example 'DWDEX1': DEFINE WINDOW                                      
************************************************************************
DEFINE DATA LOCAL                                                       
01 #I (P3)                                                              
END-DEFINE                                                              
*                                                                       
SET KEY PF1='%W<<' PF2='%W>>' PF4='%W--' PF5='%W++'                     
*                                                                       
DEFINE WINDOW WIND1                                                     
       SIZE QUARTER                                                     
       BASE TOP RIGHT                                                   
       FRAMED ON POSITION SYMBOL AUTO                             
*                                                                       
SET WINDOW 'WIND1'                                                      
FOR #I = 1 TO 10                                                        
  WRITE 25X #I 'THIS IS SOME LONG TEXT' #I                              
END-FOR                                                                 
*                                                                       
END

Output of Program DWDEX1:

                                        +------------------------More:     + >+
> r                                     ! Page      1                         !
All    ....+....1....+....2....+....3.. !                                     !
  0010 ** Example 'DWDEX1': DEFINE WIND !                             1 THIS  !
  0020 ******************************** !                             2 THIS  !
  0030 DEFINE DATA LOCAL                !                             3 THIS  !
  0040 01 #I (P3)                       !                             4 THIS  !
  0050 END-DEFINE                       !                             5 THIS  !
  0060 *                                !                             6 THIS  !
  0070 SET KEY PF1='%W<<' PF2='%W>>' PF !                             7 THIS  !
  0080 *                                ! MORE                                !
  0090 DEFINE WINDOW WIND1              +-------------------------------------+
  0100        SIZE QUARTER                                                     
  0110        BASE TOP RIGHT                                                   
  0120        FRAMED ON POSITION SYMBOL AUTO                                   
  0130 *                                                                       
  0140 SET WINDOW 'WIND1'                                                      
  0150 FOR #I = 1 TO 10                                                        
  0160   WRITE 25X #I 'THIS IS SOME LONG TEXT' #I                              
  0170 END-FOR                                                                 
  0180 *                                                                       
  0190 END                                                                     
  0200                                                                         
       ....+....1....+....2....+....3....+....4....+....5....+... S 19   L 1