OS/2 Shareware BBS: 18 REXX/18-REXX.zip/rexxlb.zip/RXWINDOW.INF

OS/2 Help File | 1994-02-07 | 28KB | 839 lines

ΓòÉΓòÉΓòÉ 1. Introduction ΓòÉΓòÉΓòÉ

RXWINDOW is a REXX function package that can help give your REXX programs a
text-mode window interface. It is designed for use in a full-screen or PM text
window session in OS/2. While it does not offer the usability advantages of a
GUI ("Graphical User Interface"), it is much easier for most users to program.
So it is well-suited for the common usage of REXX in prototyping and rapid
development.

You can program the windows to allow for menu selection or user input of
multiple data fields. The functions provided are sufficient for implementing
many different styles of user interaction.

In addition to going through the individual function descriptions in this
chapter, you should take a look at the example programs provided in the SAMPLES
subdirectory of the distribution disk. See SAMPLES.DOC for a list of the
pertinent sample programs.

RXWINDOW software and documentation is Copyright (c) 1993-4 by Quercus Systems.
All rights reserved.

RXWINDOW is a component of the Personal REXX and REXXLIB products of Quercus
Systems. It is commercial software, not Shareware. Except when included with
the REXXLIB demo package, every copy must be appropriately licensed from
Quercus Systems. Please do not copy without a license.

For more information contact:

   Quercus Systems
   P. O. Box 2157
   Saratoga, CA 95070

   Phone: [phone]
   Fax:  [phone]
   BBS:  [phone]

   Online support is available on CompuServe (GO QUERCUS)


ΓòÉΓòÉΓòÉ 2. Registering RXWINDOW Functions ΓòÉΓòÉΓòÉ

RXWINDOW functions are contained in the RXWIN30.DLL file. To make the RXWINDOW
function package available to for use in your programs, you should first be
sure that RXWIN30.DLL is included in one of the directories in your OS/2
LIBPATH. This enables the system to locate the RXWINDOW function package when a
REXX program makes use of the functions it contains.

Second, you have to register RXWINDOW functions with OS/2 by using the
RXFUNCADD() built-in function. The DLL name to use is RXWIN30, and the entry
point is RXWINDOW. This entry point is the same for all functions. A special
function called W_REGISTER() has been provided to make all the necessary
registration calls for you. There is a corresponding W_DEREGISTER() function
for deregistering all functions. Therefore, the following can be used to
properly register all functions:

call rxfuncadd 'w_register', 'rxwin30', 'rxwindow'
call w_register

The best time to do this is in a STARTUP.CMD file rather than in each REXX
program that uses RXWINDOW.


ΓòÉΓòÉΓòÉ 3. Windowing Functions Overview ΓòÉΓòÉΓòÉ

This section describes the windowing functions available when RXWINDOW is
loaded. The functions are divided into three groups: window control functions,
field-related functions, and other I/O functions.


ΓòÉΓòÉΓòÉ 3.1. Window Control Functions ΓòÉΓòÉΓòÉ

W_OPEN()
  Opens a new window and returns the window handle.

W_CLOSE()
  Permanently closes a window and removes all related information.

W_BORDER()
  Displays a border for a window.

W_HIDE()
  Temporarily suppresses display or updating of a window.

W_UNHIDE()
  Restores a previously "hidden" window.

W_MOVE()
  Changes the screen position of a window.

W_KEYS()
  Alters the behavior of cursor control keys and Enter key during a call to
W_READ.

W_SIZE()
  Utility that returns the height and width of a window; analogous to the
SCRSIZE() function.

W_ISWINDOW()
  Indicates whether a given handle represents a valid, currently open window.


ΓòÉΓòÉΓòÉ 3.2. Field-Oriented Functions ΓòÉΓòÉΓòÉ

W_FIELD()
  Defines a named input area within a window into which data can be entered.

W_UNFIELD()
  Removes an input field from a window.

W_READ()
  Reads user input from all currently defined input fields.

W_ISFIELD()
  Indicates whether a given name is a field defined in a specified window.

W_FIELDSET()
  Allows respecification of field characteristics such as screen attributes,
pad character, and protection status.


ΓòÉΓòÉΓòÉ 3.3. Other Window I/O Functions ΓòÉΓòÉΓòÉ

W_ATTR()
  Sets the screen attributes of a portion of a line in a window.

W_CLEAR()
  Clears a window or a portion of a window; analogous to the SCRCLEAR()
function.

W_GET()
  Reads user input from a specified input area in the window.

W_PUT()
  Displays a character string in a window, with optional display attribute and
pad character.

W_SCRPUT()
  Writes text and attributes to a window; analogous to the SCRPUT() function.

W_SCRREAD()
  Reads text and attributes to a window; analogous to the SCRREAD() function.

W_SCRWRITE()
  Writes text to a window; analogous to the SCRWRITE() function.


ΓòÉΓòÉΓòÉ 4. Full Function Descriptions ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 4.1. W_ATTR ΓòÉΓòÉΓòÉ

W_ATTR(window,row,col,length,attr)

Sets the screen attributes of a portion of a line in a window. Always returns
1.

Window is the window handle as returned by W_OPEN.

Row and col are the row and column numbers within the window at which the
string is to be written. (The upper left corner of the window is 1,1.)

Length is the number of character positions affected. The output is truncated
at the right edge of the window and does not wrap around.

Attr is the display attribute to be used. The default is as defined by the
W_OPEN call.


ΓòÉΓòÉΓòÉ 4.2. W_BORDER ΓòÉΓòÉΓòÉ

W_BORDER(window,[top],[right],[bottom],[left],[attr])

Displays a border for window. Always returns 1.

Each side of the window may be defined separately as a double line (2), a
single line (1), or no lines (0). Specify top, right, bottom, and left as a
number from 0 to 2. The default for each is 2.

Attr is the display attribute of the border. The default is as defined by the
W_OPEN call.

You may change the border of a window at any time. Note that the border is
written within the window, on the first and last lines and in the first and
last columns. This means that you can write labels or other information on the
border. But it also means that character strings and data fields may
inadvertently extend into the border.


ΓòÉΓòÉΓòÉ 4.3. W_CLEAR ΓòÉΓòÉΓòÉ

W_CLEAR(window,[attr],[char],[row],[col],[height],[width])

Clears a window or a rectangular region within a window. The region can be
filled with any desired character and display attribute. Always returns 1.

Window is the window handle as returned by W_OPEN.

Attr is the display attribute to use in the cleared area. The default is as
defined by the W_OPEN call.

Char is the character to fill in the area. The default is a blank.

Row and col define the row and column within the window of the upper left
corner of the rectangular area. The default for each is 1.

Height and width define the height and width of the area to be cleared. The
defaults are the number of rows and columns remaining in the window.  W_CLEAR
is analogous to the SCRCLEAR() function.


ΓòÉΓòÉΓòÉ 4.4. W_CLOSE ΓòÉΓòÉΓòÉ

W_CLOSE(window)

Permanently closes window and removes all related information. The screen
contents under the window are restored to what they were before the window was
opened. Any input fields previously defined with W_FIELD are undefined. All
buffers and control blocks are released. Always returns 1.

You should close a window as soon as you are finished with it in order to allow
room for other windows.


ΓòÉΓòÉΓòÉ 4.5. W_FIELD ΓòÉΓòÉΓòÉ

W_FIELD(window,field_name,row,col,length,[attr],[pad],[options],[subst])

Defines a named input area within a window into which data can be entered.
Returns 1 if successful, 0 if the field would be positioned outside the window.

Window is the window handle as returned by W_OPEN.

The data is read with the W_READ function. The field is not actually displayed
on the screen until W_READ is called.

Field_name is the name assigned to the field. The same name should not be used
for different fields. Alphabetic case is ignored (even if field_name is
specified as a literal string, as it normally would be). This name is used to
associate both input and output data with a particular field via a REXX
variable of the same name.

Row and col are the row and column numbers within the window at which the
string is to be written. (The upper left corner of the window is 1,1.)

Length is the number of characters in the field. The field is truncated at the
right edge of the window and does not wrap around.

Attr is the display attribute to be used. The default is as defined by the
W_OPEN call.

Pad is the character to fill in the area. The default is a blank.

Options specifies field options. It can be:

N  (Non-protected), the default. The field is not protected against updates.

P  (Protected). The field is protected against updates. When the cursor is
   moved with TAB or other keys, it will skip over protected fields.

Subst specifies that a field should be hidden, and all characters entered in
the field from the keyboard should be displayed as the given substitute
character. This could be a space or any other character. If this argument is a
null string or omitted, the field will not be hidden.

This function may fail if insufficient memory is available to store control
information, or if you accidentally define a field that falls outside of the
window.  If W_FIELD fails, a value of 0 will be returned. A value of 1
indicates successful operation.


ΓòÉΓòÉΓòÉ 4.6. W_FIELDSET ΓòÉΓòÉΓòÉ

W_FIELDSET(window,field_name,[attr],[pad],[options],[subst])

Allows respecification of field characteristics such as screen attributes, pad
character, and protection status.

Window is the window handle as returned by W_OPEN.

Field_name is the name assigned to the field in a call to W_FIELD.

Attr is the display attribute to be used. The default is the current attribute
of the field.

Pad is the character to fill in the area. The default is the current pad
character.

Options specifies field options. It can be:

N  (Non-protected). The field is not protected against updates.

P  (Protected). The field is protected against updates. When the cursor is
   moved with TAB or other keys, it will skip over protected fields.

Subst specifies that a field should be hidden, and all characters entered in
the field from the keyboard should be displayed as the given substitute
character. This could be a space or any other character. If this argument is a
null string or omitted, the field will not be hidden.


ΓòÉΓòÉΓòÉ 4.7. W_GET ΓòÉΓòÉΓòÉ

W_GET(window,row,col,length,[string],[attr],[pad],[activate])

Reads user input from a specified input area in a window and returns input
string.

Window is the window handle as returned by W_OPEN.

Row, col, and length specify the position and size of the input area.  This
area will be truncated if necessary at the right edge of the window; it does
not wrap around.

String, if specified, defines the initial contents of the input area.  (Note:
The following characters should not be used as part of the value of string:
ASCII 0, ASCII 10 (line feed), ASCII 13 (carriage return), and ASCII 26
(end-of-file).) If no data is actually entered, this value will be returned.

Attr is the display attribute to be used. The default is as defined by the
W_OPEN call.

Pad characters may be used, either in addition to or instead of a display
attribute, in order to indicate visually the size of the field. Any pad
characters at the end of the string (but not elsewhere) are removed before the
value is returned. The default pad character is a blank.

Activate determines which keys are used to indicate that data entry is
complete:

N  (Normal), the default, means that only the Enter and Esc keys finish the
   operation. When Enter is pressed, the contents of the data field will be
   returned as a string. When Esc is pressed, a null string will be returned.

F  (Function-keys) means that in addition to the Enter and Esc keys, function
   keys and other special keys (other than the editing keys described below)
   also end the operation. Any data entered will always be returned.

   When W_GET is called, control does not return to the REXX program until data
   entry is complete. A code for the key that ended the operation will be
   placed in the REXX variable _ACTIVATION_KEY; this code is the same as
   provided by the INKEY function.  The name of the key that ended the
   operation is placed in the REXX variable _ACTIVATION_KEYNAME.

   The key names that can be returned in _ACTIVATION_KEYNAME are:

   ENTER
   ESC
   F1 ... F12
   S-F1 ... S-F12
   C-F1 ... C-F12
   A-F1 ... A-F12
   PGUP, PGDN
   OTHER (for any other activation key)

Notes:

o A number of editing keys are available for entering input while W_GET is
  active:

   Backspace           delete character to the left of cursor
   Del                 delete character under the cursor
   Home                position cursor at start of input area
   End                 position cursor at end of input (excluding pad)
   Cursor Left         move cursor left
   Cursor Right        move cursor right
   Ctrl-End            delete from cursor to end of field
   Ctrl-Home           delete all characters in field
   Ctrl-Cursor Left    position cursor at start of previous word
   Ctrl-Cursor Right   position cursor at start of next word
   Ins                 toggle overtype/insert mode

o When W_GET is called, overtype mode is in effect. It is indicated by a line
  cursor. A box cursor indicates insert mode. If you toggle modes with the Ins
  key, that mode remains in effect as long as the window is open or until Ins
  is pressed again.

o Data entered is removed from the screen when W_GET returns. If you want data
  to remain displayed, you should call W_SCRWRITE to redisplay the data.

o To avoid removal of trailing blanks in the input, specify a null character
  ('00'x) as the pad character.

o W_GET is intended for reading a single data item at a time. If you want to
  enter several lines of data at a time, use W_FIELD to define the input fields
  and W_READ to read in the data.


ΓòÉΓòÉΓòÉ 4.8. W_HIDE ΓòÉΓòÉΓòÉ

W_HIDE(window,[option])

Temporarily inhibits the display of further data written to the window and
removes the window from the screen, making whatever was behind the window
visible. Optionally, the window can be left visible even though no further data
is displayed. Always returns 1.

Window is the window handle as returned by W_OPEN.

Option can be:

A  (All), the default. All data in the window becomes invisible.

N  (New). Only new data written to the window is invisible. This is useful for
   making multiple updates to a window without a "painting" effect being
   conspicuous.


ΓòÉΓòÉΓòÉ 4.9. W_ISFIELD ΓòÉΓòÉΓòÉ

W_ISFIELD(window,field_name)

Indicates whether a given name is a field defined in a specified window.
Returns 1 if the field is defined, otherwise 0.

Window is the window handle as returned by W_OPEN.

Field_name is the name assigned to the field.


ΓòÉΓòÉΓòÉ 4.10. W_ISWINDOW ΓòÉΓòÉΓòÉ

W_ISWINDOW(window)

Indicates whether a given handle represents a valid, currently open window.
Returns 1 if the window is open, otherwise 0.

Window is the window handle as returned by W_OPEN.


ΓòÉΓòÉΓòÉ 4.11. W_KEYS ΓòÉΓòÉΓòÉ

W_KEYS(window,[tab_option],[enter_option],[keyboard_option])

Controls various aspects of cursor and keyboard operations with the W_GET and
W_READ functions for the specified window. Always returns 1.

Window is the window handle as returned by W_OPEN.

Tab_option can be either:

J  (Jump) causes the cursor to automatically jump from one field to another
   when W_READ is used with multiple fields in a window. A jump occurs when a
   character is typed in the last position of a field, or when the Cursor Left
   or Cursor Right keys are used at the left or right end of the field. Word
   tab functions (Ctrl-Cursor Right and Ctrl-Cursor Left) also cause jumps
   between fields.

N  (No jump) does not jump the cursor between fields except when the Cursor Up,
   Cursor Down, Tab, or Shift-Tab keys are used. This is the default.

Enter_option affects how the Enter key behaves during a W_READ:

A  (Any field) causes the Enter key to act as an activation key when the cursor
   is in any field. This is the default.

L  (Last field) causes the Enter key to act as an activation key only when the
   cursor is in the last field of a window (as defined by the order of W_FIELD
   calls). When the cursor is in any other field, the Enter key causes it to
   jump to the next field.

Keyboard_option can be:

E  (Enhanced) allows the F11, F12, and dedicated keypad keys on the IBM
   Enhanced Keyboard to act as activation keys. In addition, the key codes of
   certain keys on the dedicated keypad of the Enhanced Keyboard (such as
   PageUp/PageDown) are distinct from codes of keys on the numeric keypad.
   (There is no effect on the behavior of keys that do not cause activation.)

F  (Fold) is like E, except that key codes are "folded" so that, if you have an
   Enhanced Keyboard, analogous keys on the numeric and dedicated keypads have
   the same codes. This is the default option.


ΓòÉΓòÉΓòÉ 4.12. W_MOVE ΓòÉΓòÉΓòÉ

W_MOVE(window,row,col)

Restores the contents of the screen under the window at its current location,
and redraws the window at a new location. Returns 1 if successful, 0 if window
would be positioned off screen.

Window is the window handle as returned by W_OPEN.

Row and col are the row and column numbers in the coordinate system of the
entire screen of the new upper left corner of the window. The window cannot be
moved to a new position if that would cause any part of the window to extend
beyond the screen boundaries.


ΓòÉΓòÉΓòÉ 4.13. W_OPEN ΓòÉΓòÉΓòÉ

W_OPEN(row,col,height,width,[attr])

Opens a new window, and returns the window handle.

The window handle must be specified in all of the remaining functions to
identify the window in question. A maximum of 5000 windows can be open at one
time. If W_OPEN fails because the maximum number of windows is already open, or
there is insufficient memory, a null string will be returned.

Row and col are the screen coordinates of the upper left corner of the window.
(The upper left corner of the screen is 1,1.)

Height and width are the dimensions of the window in character rows and
columns. If part of the window would be off the screen, the height and width of
the window will be adjusted to fit. (Note that you can open a window larger
than 25 * 80, but only if your display is configured so that it uses more than
25 lines and 80 columns.)

All parts of the window for which a screen attribute is not explicitly provided
will use attr. The default for attr is 7. For information on how to specify
attr, refer to the description of the SCRWRITE() function.


ΓòÉΓòÉΓòÉ 4.14. W_PUT ΓòÉΓòÉΓòÉ

W_PUT(window,row,col,[string],[length],[attr],[pad])

Displays a character string in a window, with optional display attribute and
pad character. Always returns 1.

Window is the window handle as returned by W_OPEN.

Row and col are the row and column numbers within the window at which the
string is to be written. (The upper left corner of the window is 1,1.)

String is the character string to be written. If not specified, the null string
is assumed.

Length is the number of characters to be written. The default is the length of
string. The output is truncated at the right edge of the window and does not
wrap around.

Attr is the display attribute to be used. The default is as defined by the
W_OPEN call.

The default pad character is a blank.

Note: W_PUT is included primarily for compatibility with an earlier version of
RXWINDOW. W_SCRWRITE, described later in this section, is the preferred method
for writing to a window.  There are two differences between W_PUT and
W_SCRWRITE:


                     W_PUT                     W_SCRWRITE

                     Output is truncated at    Output wraps if
                     right edge of window.     necessary.

                     Like other windowing      Like REXXLIB SCRxxxx
                     functions, attr precedes  functions, pad precedes
                     pad.                      attr.


ΓòÉΓòÉΓòÉ 4.15. W_READ ΓòÉΓòÉΓòÉ

W_READ(window,[field_name],[activate],[changes])

Reads user input from any currently defined input fields. At least one such
field must have been defined.

Window is the window handle as returned by W_OPEN.

If field_name is specified, it designates the field in which the cursor is
initially to be positioned. Alphabetic case is ignored (even if field_name is
specified as a literal string, as it normally would be). If a field_name isn't
specified, the cursor is initially positioned in the first field defined for
window.

Activate determines which keys are used to indicate that data entry is
complete:

 N  (Normal), the default, means that only the Enter and Esc keys finish the
    operation.

    If Enter is pressed, the data currently in each field will be assigned to
    the corresponding REXX variable. If Esc is pressed, W_READ terminates but
    does not set any REXX variables.

 F  (Function-keys) means that in addition to the Enter and Esc keys, function
    keys and other special keys (other than the editing keys described in
    connection with W_GET) also end the operation. Any data entered will always
    be returned.

    In addition to the field variables, the following special variables are
    set:

    _ACTIVATION_KEY               contains the code for the key that ended
                                  W_READ, if activate is F.

    _ACTIVATION_KEYNAME           contains the name, in uppercase, of the key
                                  that ended W_READ, if activate is F. (See
                                  W_GET for a list of key names.)

    _ACTIVATION_FIELD             contains the name, in uppercase, of the field
                                  that the cursor was in when the function was
                                  terminated, unless activate is N and the
                                  Escape key was used.

 W_READ returns 0 if activate is N and the read is terminated by the Esc key.
 Otherwise, W_READ returns 1.

 Changes, if specified, is the name of a REXX stem that will be set to the list
 of names of fields that have been changed. For instance, if changes is 'list',
 then LIST.0 will contain the number of changed fields, and LIST.1, etc., will
 contain the names of the changed fields.

 Notes:

 o While W_READ is active, the user has the same editing keys available as with
   W_GET. In addition, the Tab and Shift-Tab keys can be used to go to the next
   or previous fields. The up and down cursor keys have the same effect.  See
   W_KEYS for how you can control the behavior of the editing keys during a
   W_READ.

 o At the time W_READ is called, each defined field is filled with the current
   value of the REXX variable having the same name. The pad character and
   attribute byte associated with the field are used in displaying this value.
   If the REXX variable is undefined, only pad characters will be displayed.

   If field_name is the same as a REXX compound variable, the usual rules will
   be applied to determine the value. For instance, if field_name is specified
   as age.person and the REXX variable person has the value fred, then the
   value of age.fred is used. This will be the same result as if field_name had
   been specified as age.fred (provided fred itself is not a defined REXX
   variable).

 o When W_READ terminates and the value of field_name is set, this value will
   usually be that of the variable associated with the field. However, because
   of the REXX compound variable rules, data can be assigned to different
   variables if this process happens to change any component, except the stem,
   of a compound name. For instance, if you have a field whose name was
   specified as person and the REXX variable person is assigned the new value
   mary, then the data for the age.person field will be assigned to the REXX
   variable age.mary. (Since the assignments are made in the order the fields
   are defined, this presumes that the person field is defined before the
   age.person field.)


ΓòÉΓòÉΓòÉ 4.16. W_SCRPUT ΓòÉΓòÉΓòÉ

W_SCRPUT(window,row,col,string,[option])

Displays a string of text, attributes, or both in a window. Always returns 1.

Window is the window handle as returned by W_OPEN.

Row and col are the row and column numbers within the window at which the
string is to be written.  The upper left-hand corner of the window is 1, 1.

String is the string of text, attributes, or both which is to be written. If
the string is too long to fit on the line of the window where it starts, it
will wrap around to following lines, up to the end of the window.

Option can be:

 T  (Text), the default. The string contains only text characters. Attributes
    already present do not change.

 A  (Attributes). The string contains only attribute characters. Text already
    present does not change.

 B  (Both). The string consists of character-attribute pairs. The attribute
    character follows the text character in each pair. LENGTH(string)/2 screen
    positions are written.

 W_SCRPUT is analogous to the SCRPUT() function.


ΓòÉΓòÉΓòÉ 4.17. W_SCRREAD ΓòÉΓòÉΓòÉ

W_SCRREAD(window,row,col,length,[option])

Reads and returns a string of text, attributes, or both from a window.

Window is the window handle as returned by W_OPEN.

Row and col are the row and column numbers within the window at which reading
begins.  The upper left-hand corner of the window is 1, 1.

Length is the number of screen positions in the window to read. If the data to
be read extends beyond the end of the line, the function will wrap around to
following lines up to the end of the window.

Option can be:

 T  (Text), the default. Only text characters are read.

 A  (Attributes). Only attribute characters are read.

 B  (Both). Character-attribute pairs are read. The attribute character follows
    the text character in each pair. Length pairs are read, for a total result
    length of 2*length.

 Only data which has been written to the window with RXWINDOW functions is read
 by W_SCRREAD.

 W_SCRREAD is analogous to the SCRREAD() function.


ΓòÉΓòÉΓòÉ 4.18. W_SCRWRITE ΓòÉΓòÉΓòÉ

W_SCRWRITE(window,row,col,[string],[length],[pad],[attr])

Writes a text string to the screen at the specified row and column of a window.
Always returns 1.

Window is the window handle as returned by W_OPEN.

Row and col are the row and column numbers within the window at which the
string is to be written.  The upper left-hand corner of the window is 1, 1.
(Note that, unlike the SCRWRITE() function, row and col must be specified with
W_SCRWRITE.)

String is truncated (or padded with pad) to the given length. Characters are
written to the screen using the attribute attr. Text is not truncated at the
right edge of the window, but instead wraps from line to line.

The default for string is the null string.

The default for length is the length of string.

The default for pad is a blank.

The default for attr is as defined by the W_OPEN call.  W_SCRWRITE is analogous
to the SCRWRITE() function.


ΓòÉΓòÉΓòÉ 4.19. W_SIZE ΓòÉΓòÉΓòÉ

W_SIZE(window)

Returns the height and width of the specified window.

Window is the window handle as returned by W_OPEN.

W_SIZE is analogous the the SCRSIZE() function.


ΓòÉΓòÉΓòÉ 4.20. W_UNFIELD ΓòÉΓòÉΓòÉ

W_UNFIELD(window,field_name)

Removes an input field from a window. Always returns 1.

Window is the window handle as returned by W_OPEN.

Field_name must have been defined previously with W_FIELD. The area of the
window occupied by the field will be cleared to blanks with the default window
attribute. It is not necessary to call W_UNFIELD before closing the window with
W_CLOSE.


ΓòÉΓòÉΓòÉ 4.21. W_UNHIDE ΓòÉΓòÉΓòÉ

W_UNHIDE(window)

Reverses the effect of W_HIDE, making a window and all further updates to it
fully visible. Always returns 1.

Window is the window handle as returned by W_OPEN.


ΓòÉΓòÉΓòÉ 5. Specifying Field Names ΓòÉΓòÉΓòÉ

Many people who are just starting to use RXWINDOW have problems with programs
that use W_FIELD and W_READ.  The problems usually stem from errors in
specifying field names passed to these functions.

Field names should normally be specified as literal strings. For example, the
program below has a subtle bug:

      name = 'John'
      w = w_open(4,3,3,50)
      call w_border w
      call w_put w, 2, 3, 'Name:',,15
      call w_field w, name, 2, 9, 30, 112
      call w_read w
      call w_close w
      say 'Name entered =' name
      say 'John =' john

Here, a window is opened that has a single field.  The programmer intended for
this field to be called <NAME>, for this field to be initialized to John, and
for any user input to override this initial value.

What happens instead is that the field is named <JOHN> and no initial value is
set.  Any user input changes the value of a variable called <JOHN>; the value
of the variable <NAME> does not change.  So, the program always displays

      Name entered = John

The problem is with the clause

      call w_field w, name, 2, 9, 30, 112

REXX evaluates <name>, a variable that was previously assigned the value John.
The name of the field is therefore <JOHN>.

What's really needed is:

      call w_field w, "name", 2, 9, 30, 112

REXX evaluates the literal string "name".  The name of the field is therefore
<NAME>, as desired.


ΓòÉΓòÉΓòÉ 6. Usage Notes ΓòÉΓòÉΓòÉ

 o If you have defined overlapping windows, you should work only with the
   topmost window. For example you should not close or move a window if
   overlapping windows are defined on top of it. Otherwise, incorrect data may
   be displayed in the overlapping area.

 o You cannot conveniently mix window-oriented screen interaction with normal
   screen I/O. The REXX SAY instruction, the SCRWRITE() function, and any
   program that writes to the screen with normal system facilities will
   probably either overwrite a window or cause unwanted scrolling. There is no
   way to redirect such output directly to a window. However, the output of
   many commands can be redirected to a file, and portions of this file could
   be displayed using the windowing function package.

 o If you want to save the contents of the screen before displaying a window or
   running a program that needs to use the screen itself, a convenient method
   is to define a window that covers the whole screen (without borders). When
   this window is subsequently closed, the previous contents of the screen will
   be restored. Just remember that each such full-screen window requires 8000+
   bytes of storage.

 o Another method of saving and restoring screens is to use the SCRREAD() and
   SCRPUT() functions. This takes only 4000 bytes of storage per screen.

 o REXX programs that use windowing functions can test whether the RXWINDOW
   package is loaded by using

                RXFUNCQUERY('W_OPEN')