OS/2 Shareware BBS: 18 REXX/18-REXX.zip/vxcliser.zip/README.INF

OS/2 Help File | 1988-01-08 | 114KB | 3,729 lines

ΓòÉΓòÉΓòÉ 1. Using online information ΓòÉΓòÉΓòÉ

The most up-to-date information on VX-REXX is available online in the VXΓêÖREXX
Programmer's Guide and and the VXΓêÖREXX Reference. The Errata section of this
document lists the differences between the online documentation and the printed
manual.

In addition to online books, full context sensitive help is available within
the VX-REXX development environment. Simply activate the VX-REXX window by
clicking on it, and press the F1 key. A help window will appear, with general
information about the VX-REXX development environment. You can also access help
for VX-REXX from its Help menu. For more specific help  on any of VX-REXX's
menu choices use the cursor keys to choose a menu item, or hold down mouse
button 1 on the menu item, and press F1.

The context help is linked to the full text of the VXΓêÖREXX Programmer's Guide
and VXΓêÖREXX Reference. To access help on an object, for example, click on the
object in the tool palette and press F1. A help window will open with a short
description of the object. Within the description the object name will appear
with special highlighting. Double click on this field to see the complete
reference entry for that object.


ΓòÉΓòÉΓòÉ 2. Workplace Shell Integration ΓòÉΓòÉΓòÉ

 Workplace Shell (WPS) Integration

 o Create new projects by dragging and dropping
 o Edit VX-REXX objects using WPS techniques
 o Drag and drop programming
 o Assigning icons to your progrmas
 o Providing help for your programs
 o Multi-threaded programs
 o Shutdown and Window List messages
 o Presentation Manager windows


ΓòÉΓòÉΓòÉ <hidden> Create new projects by dragging and dropping a project template ΓòÉΓòÉΓòÉ

The Projects folder in the Watcom VX-REXX folder contains a VX-REXX Project
template. Drag and drop this template to create a new project folder. Open the
folder and double click on the Project.VRP icon to edit the project. You can
also open projects by dropping the project (VRP) file on the VX-REXX icon
contained in the Watcom VX-REXX folder.

For information on developing VX-REXX projects, see Creating and running
projects in the Programmer's Guide.


ΓòÉΓòÉΓòÉ <hidden> Edit VX-REXX objects using Workplace Shell techniques ΓòÉΓòÉΓòÉ

 o Use mouse button 1 to select and resize objects. Both marquee and swipe
   selection are supported.

 o Use mouse button 2 to move objects and to open their pop-up menus.

 o Directly edit text objects by clicking mouse button 1 while pressing the Alt
   key.

 o Directly modify objects using their property notebooks. You can open a
   property notebook either by using an object's pop-up menu or by double
   clicking on the object.

 o Drag and drop fonts and colors from the Workplace Shell font and color
   palettes. You can drag fonts and colors from these palettes onto VX-REXX
   objects to set their font and color properties.

   Note that to set the foreground color on an object, press and hold the Ctrl
   key while dragging and dropping the color,  otherwise the background color
   will be set.

   For more information, please see Adding objects to a window and Changing
   object properties in the Programmer's Guide.


ΓòÉΓòÉΓòÉ <hidden> Write code using drag and drop programming ΓòÉΓòÉΓòÉ

Using the VX-REXX drag and drop programming feature entire programs can be
written without typing a line of code. For example, to create code to get the
value of an entry field you simply drag the entry field and drop it on the
editor where the code is to be inserted. Then you select the Value property
from a list, click OK, and the code is inserted, complete with the name of the
entry field.

You can also insert code directly using the Insert code item in the section
editor's Edit menu, and you can configure VX-REXX to copy the generated code to
the OS/2 clipboard so you can use this feature with external editors.

The A simple program chapter of the Programmer's Guide shows how to use the
drag and drop programming feature.


ΓòÉΓòÉΓòÉ <hidden> Assign icons to your programs ΓòÉΓòÉΓòÉ

Icons can be assigned to VX-REXX executables (EXE) programs using the General
page of the program's Settings notebook. You can also set the icon by placing
an icon (ICO) file with the same name as the program in the same directory as
the program.

Once assigned, a program's icon is used within the Workplace Shell to represent
the program. It is also used when the program is running as the title bar icon,
and as the icon used to represent a minimized window.


ΓòÉΓòÉΓòÉ <hidden> Provide context sensitive help and status information ΓòÉΓòÉΓòÉ

VX-REXX objects include properties that you can use to provide help and status
information (hints) to your users. The help, either a simple text window or an
OS/2 Information Presentation Facility help panel, is automatically displayed
when your user presses F1. Hints are automatically displayed in the status area
whenever an object has the focus or the pointer is moved over an object.

For more information, please see Adding help to a program in the Programmer's
Guide.


ΓòÉΓòÉΓòÉ <hidden> Create programs with multiple threads ΓòÉΓòÉΓòÉ

Every VX-REXX program contains multiple threads. This means your program will
not freeze the system while it performs long calculations. You can also create
and control threads within your own program so you can optimize your use of the
computer.

For more information, please see the StartThread method in the Reference.


ΓòÉΓòÉΓòÉ <hidden> Respond to Window List and shutdown messages ΓòÉΓòÉΓòÉ

Your users can halt your programs using the OS/2 Window List or by shutting
down OS/2 -- even when your program is performing long calculations. You can
provide code to ensure your application shuts down gracefully when interrupted,
so for example, you can give your users a chance to save or discard their data
when OS/2 is shut down.

For more information, please see the Halt routine in the Reference.


ΓòÉΓòÉΓòÉ <hidden> List, control, and send keys to PM windows ΓòÉΓòÉΓòÉ

You can write programs that list and control windows on the OS/2 desktop. You
can get and set their caption, position and size, and z-order, as well as
enable, disable, minimize, maximize, and restore them. For more information,
please see the Working with other programs chapter in the Reference.


ΓòÉΓòÉΓòÉ 3. Commonly Asked Questions ΓòÉΓòÉΓòÉ

 General

 o Known limits and problems
 o What are the __TMP directories?
 o Recovering from system crashes
 o Running programs from VX-REXX
 o Modal vs. modeless windows
 o Common mistakes
 o Tab order
 o Using OS/2 file types
 o Making VX-REXX programs that do not require Presentation Manager
 o Installation problems

 Objects

 o The VX-REXX console
 o Using the ComboBox and DropDownComboBox objects
 o Using the GroupBox object
 o Object naming
 o Overlapping objects

 REXX questions

 o Common REXX coding errors
 o Opening and closing files
 o Reading and writing files
 o Returning multiple values

 Compatibility issues

 o Issues with the SOMObjects Toolkit
 o Issues with OS/2 2.0, Microsoft LAN Manager
 o Issues with Quercus System's Personal REXX


ΓòÉΓòÉΓòÉ <hidden> Known limits and problems ΓòÉΓòÉΓòÉ

 Presentation Manager restrictions:

 o ListBox, ComboBox and DropDownComboBox objects can only hold a certain
   amount of data.  The exact number of lines depends on the length of the
   lines, but is commonly between 1500 and 2000 lines.
 o Placing several hundred objects on a Window can exhaust the Presentation
   Manager memory area, and you will not be able to create any more objects
   unless you delete some first.  There is usually no valid reason for having
   so many objects and you should consider splitting your window into two or
   more windows.

 Video driver problems:

 o Early versions of the Compaq QVision video driver caused problems with
   VX-REXX and other applications.  Contact Compaq for an updated driver if
   problems occur.
 o Problems with VX-REXX have been reported on machines running OS/2 2.11 and
   ATI video cards based on the MACH-32 chip.  These problems are under
   investigation.

 Property notebook updating:

 o Open property notebooks are not updated while open to show the results of
   drag and drop fonts and colors. To refresh the values on a page, turn to
   another page, then turn back to the first page. Closing and reopening a
   notebook also refreshes the values.

 Loading files saved as text:

 o Not all syntax errors in text-format (VRT) window files are reported. In
   these cases the file will load successfully, but the window will not appear.
   If this happens, fix the syntax errors in the text file and reload it.

 Debugger restrictions:

 o Because of the way the debugger handles breakpoints, it is impossible to
   break a program on the first instruction in a file.

 o The current version of the interactive debugger supports only the main
   thread of a program. Use the standard REXX trace instruction with the
   VX-REXX console to debug multithreaded projects.


ΓòÉΓòÉΓòÉ <hidden> The __TMP directories ΓòÉΓòÉΓòÉ

 VX-REXX creates temporary directories where it saves all files in an open
 project. The directory names have the form __TMP<n> where <n> is a number
 between one and nine. VX-REXX creates these temporary directories under the
 following directories, in the order listed:

  1. The directory specified in the TMP environment variable, if it is defined.
  2. The root of the current drive.
  3. The root of the drive containing VX-REXX.

 Usually, VX-REXX removes its temporary directory when you shut it down.
 However, if your system crashes while you are editing a project, the temporary
 directory will be left behind. You can recover the most recent changes to the
 project using the files in the temporary directory -- see Recovering from
 system crashes. If you do not want to recover the most recent changes, you are
 free to delete the temporary directories.


ΓòÉΓòÉΓòÉ <hidden> Recovering from system crashes ΓòÉΓòÉΓòÉ

 If your OS/2 system crashes or locks up while you are editing a VX-REXX
 project, it may be possible for you to recover the project. The program
 RECOVER.EXE has been provided to help in this task.

 Temporary directories

 VX-REXX creates temporary directories where it saves all files in an open
 project. The directory names have the form __TMP<n> where <n> is a number
 between one and nine. Attempts are made to create temporary directories under
 the following directories, in the order listed:

  1. The directory specified in the TMP environment variable, if it is defined.
  2. The root of the current drive.
  3. The root of the drive containing VX-REXX.

 A temporary directory contains the macro version of a project. There are files
 with extensions of VRM and VRW which correspond to project files of the same
 name but with extensions of VRX and VRY, respectively.

 A temporary directory also contains files with an extension of CMD. These
 files contain individual sections of a project. All sections can be found in
 the CMD files. However, the section names and the project files from which the
 sections were taken are not saved in the temporary directory.

 The RECOVER utility rebuilds a project from the VRM and VRW files in a
 temporary directory. It does not consider the CMD files. This utility may be
 able to recover changes to a project which have been lost due to a system
 crash.

 Using RECOVER

 This program lists temporary directories from which VX-REXX projects can be
 recovered. The search for these directories is carried out in the locations
 stated above. Note that the roots of all drives will be searched for temporary
 directories. If a project needs to be recovered from a network drive or a
 floppy disk, ensure that the appropriate disk is accessible before running
 RECOVER. Also, make sure that you do not delete directories that are currently
 in use by a VX-REXX session. If you are unsure which directories are being
 used, simply close all VX-REXX sessions before recovering or deleting a
 directory.  P.To determine which temporary directory contains a particular
 project, select a directory from the directory listing. The window and code
 files contained in the directory will be listed. Select a file and then press
 the View File button in order to view the file. Browse through the directory
 listing and view files until the project to recover has been found.

 Note that more than one temporary directory may contain a given project. In
 this case, use the dates of the directories to determine which version of the
 project needs to be recovered.

 When the directory containing the project to recover has been found, press the
 RECOVER button. First the name and path of the project file will be requested
 followed by prompts for new names of the code and window files. Pressing
 Cancel during any of these prompts will cancel the recovery from the selected
 directory. It is strongly recommended that new directories be created in which
 to place the recovered projects as there is no guarantee that the recovered
 project will work properly. Recovering the project on top of an old copy of
 the project can be risky.

 After the names of all files in a project have been specified, the project
 will be recovered and the temporary directory containing the project may be
 deleted. Usually, this directory is deleted to prevent the accumulation of
 temporary directories. However, it may be retained if its CMD files need to be
 examined or recovered, since this utility does not recover these files.

 In addition, there is a Delete button which allows you to delete VX-REXX
 temporary directories without recovering the projects they contain. You may
 wish to do this if all available temporary directory names are already in use,
 which prevents VX-REXX from running. You may also do this if the project in a
 directory has already been recovered, and so the contents of the directory are
 no longer needed.


ΓòÉΓòÉΓòÉ <hidden> Making VX-REXX programs that do not require Presentation Manager ΓòÉΓòÉΓòÉ

 You may use VX-REXX to create applications that run in OS/2 full-screen or
 windowed sessions providing the following restrictions are met:

  1. The VX-REXX project has no window files.
  2. The project does not use VRGet, VRSet, VRMethod, VRFileDialog,
     VRFontDialog, VRMessage, VRMessageStem, VRPrompt, VRWindow, or any other
     function that can only be run in a Presentation Manager session.
  3. The executable is marked as a non-PM executable.

 To mark an executable as a non-PM executable, use the exehdr program, which is
 part of the OS/2 Toolkit and also included with VX-REXX.  For example, to mark
 test.exe as an executable for use in OS/2 windowed or full-screen sessions,
 use:

  exehdr /pmtype:windowcompat test.exe


ΓòÉΓòÉΓòÉ <hidden> Using the ComboBox and DropDownComboBox objects ΓòÉΓòÉΓòÉ

 ComboBox and DropDownComboBox behaviour with respect to the Click event
 changed in version 2.0 of VX-REXX.  Here are the important points to remember:

 o The Click event occurs when a new item in the list is selected, not for each
   mouse click.

 o When responding to a Click event, use the Selected property or
   SelectedString property to determine which item in the list was selected.
   The Value property is not necessarily accurate at that point in time.

 o When responding to a Change event, use the Value property to determine the
   new value.

 In addition, note that the Height of a DropDownComboBox object is the height
 of the visible area plus the height of the drop-down list.  If the height is
 too small, the drop-down list will not be accessible by the user.


ΓòÉΓòÉΓòÉ <hidden> Using the GroupBox object ΓòÉΓòÉΓòÉ

 In VX-REXX, the GroupBox object contains the objects that are placed inside
 it.  Objects in a group box cannot be moved outside the group box except by
 cutting and pasting them.


ΓòÉΓòÉΓòÉ <hidden> The VX-REXX console ΓòÉΓòÉΓòÉ

 VX-REXX provides a simple console window that is used to display messages that
 would normally be displayed in an OS/2 window or OS/2 full-screen session.
 Output from the REXX SAY statement (usually called the standard output stream)
 is printed on the console.  User input for the REXX PULL statement (usually
 called the standard input stream) occurs from the console.  Here are a few
 tips to using the console:

 o To shut off the console or log it to a file, use the VRRedirectStdIO
   function.

 o The console can be show, hidden, moved or resized under program controls.
   See the Using objects chapter in the Programmer's Guide and the Console
   object in the Reference.

 o The console may not always work when running a VX-REXX program as a macro
   within another application because that application may be intercepting the
   standard input and output streams.  Refer to that application's
   documentation.


ΓòÉΓòÉΓòÉ <hidden> Running programs from VX-REXX ΓòÉΓòÉΓòÉ

 General

 Programs are run from within a VX-REXX project by using the facilities
 provided by the OS/2 command interpreter, CMD.EXE, and the ADDRESS statement.

 To run a program FOO.EXE and suspend the VX-REXX project until the program has
 finished, use this syntax:

  address cmd 'foo'

 You may use the usual redirection operators, as in:

  address cmd 'dir >out.lst'

 To run a program FOO.EXE without waiting for it to finish, use the OS/2 START
 command:

  address cmd 'start foo'
 To get help for the START command, type help start from and OS/2 window.

 VIO support

 Certain types of OS/2 programs require direct access to the OS/2 console.
 This direct access is provided by a system facility called "VIO support".
 Presentation Manager programs such as VX-REXX cannot directly run programs
 requiring VIO support. If you run such a program, you will get the following
 error:

  SYS0436: An invalid VIO handle was found

 The OS/2 PSTAT command, for example, requires VIO support.  To run such a
 program from VX-REXX, you must use the START command to run the program in its
 own OS/2 window:

  address cmd 'start /win pstat <con >con 2>&1'

 Redirecting the standard input, output and error streams

 By default, VX-REXX redirects the standard input, output and error streams to
 its own console window.  If you start a program or an OS/2 command, its output
 is sent to the console and its input is taken from the console.

 For example, the following instruction sends a directory listing to the
 console:

  address cmd 'dir'

 When you run non-PM programs, the output is sent to the console unless you
 explicitly redirect it to a file using the > operator:

  address cmd 'dir >out.lst'

 Use the < operator to redirect input.  Use the 2> operator to redirect
 standard error.  Standard error and standard output may be merged by using the
 syntax 2>&1.

 To redirect to the console instead of a file, use con as the filename:

  address cmd 'start /win pstat <con >con 2>con'


ΓòÉΓòÉΓòÉ <hidden> Modal vs. modeless windows ΓòÉΓòÉΓòÉ

 A modal window disables its parent window, but a modeless window does not.
 Modal windows must be dimissed before processing can continue in the parent
 window.

 Modal windows are most often created as the primary window in another window
 file, and that window file is called whenever the modal window is to be
 displayed, passing the value of VRWindow as the first parameter.  A modal
 window may also be created as a secondary window, however, and should be
 loaded using the wait option of VRLoadSecondary.

 Modal and modeless windows always stay on top of their parent window. If you
 want a modeless window to act like the main window of your application, you
 must load it using VRLoad instead of VRLoadSecondary, passing a null string as
 the parent window.

 For more discussion on modal and modeless windows, see the Creating custom
 dialogs, Secondary windows, and Multiple file projects chapters in the
 Programmer's Guide.


ΓòÉΓòÉΓòÉ <hidden> Common mistakes ΓòÉΓòÉΓòÉ

 Referencing a window before it is loaded

 The primary window in a window file is automatically loaded by VX-REXX, but
 any secondary windows must be explicitly loaded by calling VRLoadSecondary.
 If a window is not loaded and you try to set or get any of its properties, a
 syntax error will occur.

 You can use the VRIsValidObject function to determine if a window or other
 object is available.


ΓòÉΓòÉΓòÉ <hidden> Object naming ΓòÉΓòÉΓòÉ

 Two new forms of object naming, parent-child naming and context-sensitive
 naming, simplify the building of complex projects.

 o Parent-child naming
 o Context-sensitive naming


ΓòÉΓòÉΓòÉ <hidden> Tab order ΓòÉΓòÉΓòÉ

 When creating new objects, those objects are placed at the end of the tab
 order.  Objects pasted into a window, however, are not placed at the end of
 the tab order. They keep their current tab index and the tab indices of other
 objects on the window are adjusted accordingly.

 You should create and edit your windows without regard to the tab order, then
 set the tab order in the final version. To set the tab order, you can either
 set the TabIndex property on objects in a window, or you can use the tab
 editor which is described elsewhere in this document.


ΓòÉΓòÉΓòÉ <hidden> Issues with the SOMObjects Toolkit ΓòÉΓòÉΓòÉ

The initial release of SOM version 2 was not compatible with certain SOM-based
applications, including VX-REXX. IBM has released a corrective service disk for
SOM-2. Ask your IBM service representative for the SOM-2 CSD 2.02 or higher.


ΓòÉΓòÉΓòÉ <hidden> Issues with OS/2 2.0, Microsoft LAN Manager ΓòÉΓòÉΓòÉ

 IBM OS/2 2.0 Service Pak required

 IBM OS/2 version 2.0 with the OS/2 Service Pak or higher must be installed
 prior to installing VX-REXX. If you are running OS/2 2.0 without the OS/2
 Service Pak, you must obtain it from IBM and install it to make sure that all
 features of VX-REXX work correctly. The Service Pak can be number XR06055 or
 XR06100. You can obtain the Service Pak from the IBM OS/2 BBS, from
 CompuServe, or directly from IBM. Contact your IBM representative for more
 information.

 IBM OS/2 2.1 and Microsoft Lan Server

 The released version of OS/2 2.1 does not support Microsoft Lan Server public
 applications properly. Public applications will work under OS/2 2.1 if an IBM
 patch for OS/2 2.1 is applied. Contact IBM support and ask for the fix for
 APAR PJ08829.

 Note that the VROBJ.DLL file must be in the same directory as the VX-REXX
 executable (EXE) file that uses it, or in some directory listed in your
 LIBPATH. Your LIBPATH is set in the CONFIG.SYS file in the root of your OS/2
 volume.


ΓòÉΓòÉΓòÉ <hidden> Issues with Quercus System's Personal REXX ΓòÉΓòÉΓòÉ

 Syntax errors with Quercus System's Personal REXX

 When running under Quercus System's Personal REXX version 3.0a syntax errors
 are either reported only within the VX-REXX console or both within the VX-REXX
 console and the standard VX-REXX error dialog.

 Multithreading problems with Quercus System's Personal REXX

 When running under Personal REXX version 3.0a multithreading problems can
 occur. Users are encouraged to contact Quercus Systems.

 Contacting Quercus Systems

 For more information on Personal REXX, please contact Quercus Systems at the
 following address:

      Quercus Systems
      P.O. Box 2157
      Saratoga, CA 95070
      USA
      [phone]
      [phone] (FAX)


ΓòÉΓòÉΓòÉ <hidden> Overlapping objects ΓòÉΓòÉΓòÉ

 Overlapping objects may not be displayed correctly unless the ClipSiblings
 property is set for every object that intersects another object.  See the
 section on moving objects to the front and back in Adding objects to a window
 for more details.


ΓòÉΓòÉΓòÉ <hidden> Common REXX coding errors ΓòÉΓòÉΓòÉ

 Blank space where it does not belong

 In REXX expressions, blank space is interpreted as an implicit concatenation
 operator (the terms are concatenated with a blank in between). As a result,
 REXX will interpret many mistyped statements as an expression involving the
 blank concatenation operator.

 For example, inserting a blank after a function name in a function call
 changes the meaning of the expression:

  textUpper = translate ( text )

 to:

  textUpper = "TRANSLATE" || " " || text

 Blank space also plays a special role in the parse instruction. Compare the
 following:

  parse arg a b c
  parse arg a, b, c

 The first line parses the first argument passed to the routine into three
 parts, the second line sets the three variables to the value of the first
 three arguments passed to the routine.

 Function calls versus the CALL statement

 When you call a routine that returns a result, you must enclose the parameters
 in parentheses:

  text = VRGet( "EF_1", "Value" )

 If you are calling a routine that does not return a value, you should use the
 call instruction:

  call VRSet "EF_1", "BackColor", "Blue"

 Note that there is no comma between the name of the routine and the first
 parameter.

 Ignoring return values of functions

 When using a function as a procedure, you must not ignore the return value. If
 the return value is not handled it will be passed to the default host
 environment as a command. This will normally result in a failure trace
 message. Either assign the returned value to a variable or use the call
 instruction to call the function as a procedure.

 Line continuation

 In REXX, the comma is the line continuation character. It is required when
 extending one clause over several lines. For example,

  call foo a, b, c

 can also be written as

  call foo a, ,
           b, ,
           c

 It is easy to forget the second comma if you are breaking a line in the middle
 of a parameter list.

 Omitted arguments

 REXX allows arguments to be omitted. Be careful not to omit arguments by
 accident.

 The following calls foo with four arguments (the first one is omitted).

  call foo, a, b, c

 Undefined variables

 It is not a syntax error to use undefined variables in REXX. Undefined
 variables are defined to have their own name translated to uppercase as their
 value. As a result it is often difficult to find programming errors that are a
 result of using undefined variables.

    o Add a "SIGNAL ON NOVALUE" statement to the main section of your programs.
      This will cause the system to issue a syntax error if you use an
      undefined variable.

    o Be careful to include the period when referring to stems. The variables A
      and A. are unrelated.

    o Misspelled commands will often be interpreted as undefined variables. The
      line

            sy 'hello'

      (which should be "say 'hello'") will be interpreted as

            "SY" || " " || 'hello'

      Thus the string "SY hello" will be sent to OS/2 for execution, resulting
      in a command failure error.

 Using expressions in the tail of a compound symbol

 The tail of a compound symbol can only be a simple variable, as in:

  ok = A.I

 Literals are not allowed. For example, the following is interpreted as a
 concatenation between A. and "name"

  bad = A."name"

 Expressions are not allowed. The following is interpreted as "bad = (A.I) -
 1".

  bad = A.I-1

 A way around this is to assign the literal or expression to a simple variable
 and use that to form the compound variable. For example:

  J = I - 1
  ok = A.J


ΓòÉΓòÉΓòÉ <hidden> Opening and closing files ΓòÉΓòÉΓòÉ

 Explicit open and close commands are not required to read and write files
 using REXX, but you must be aware that once you access a file it is left open
 unless you explicitly close it. You cannot delete files that are open and you
 may be unable to open new files if all available file handles have been used.

 To avoid such problems, be sure your REXX program closes any files it opens as
 soon as it is done with them. For example, the following code opens a file
 called baker, writes to it, and closes it:

  call stream "baker", "c", "open write"
  call lineout "baker", "Skip to the loo"
  call stream "baker", "c", "close"

 For more information about the stream instruction, see the online REXX
 Information.


ΓòÉΓòÉΓòÉ <hidden> Reading and writing files ΓòÉΓòÉΓòÉ

 Data is read from a file using the LINEIN and CHARIN functions.

 Data is written to a file using the LINEOUT and CHAROUT functions.

 These functions can also be used to read and write from serial ports, however
 there also exist REXX function libraries geared specifically towards this
 task.


ΓòÉΓòÉΓòÉ <hidden> Returning multiple values ΓòÉΓòÉΓòÉ

 Multiple values can be returned from a function by concatenating them into a
 single string, returning the string, then using parse to break the return
 string into separate values.

 Another way to return multiple values is to use the PutVar and GetVar methods.


ΓòÉΓòÉΓòÉ <hidden> Using OS/2 file types ΓòÉΓòÉΓòÉ

 OS/2 files have the concept of a file type which may be associated with every
 file. The file type is a text string which describes the contents of the file.
 Not all files have a file type (ie. the file type is the null string). The
 following file types are predefined by OS/2:

 Assembler Code
 Binary Data
 Bitmap
 C Code
 DOS Command File
 Dynamic Link Library
 Executable
 FORTRAN Code
 Icon
 Library
 Metafile
 Object Code
 OS/2 Command File
 Pascal Code
 Plain Text
 Resource File

 You can get a list of all file types defined on your computer by using the
 VRListFileTypes function. To set the file type for a file, use the
 VRSetFileType function. The VRGetFileType function returns the file type for a
 given file.

 You can pass file types to the VRFileDialog function to display files that
 have a certain file type.


ΓòÉΓòÉΓòÉ <hidden> Installation problems ΓòÉΓòÉΓòÉ

 The installer says "Fatal Error: Target Directory is Read-Only"

 The installer may display this message if you are installing over an existing
 copy of VX-REXX and there are read-only files in the VXREXX directory tree.

 The solution is to remove the read-only protection from all files in the
 directory tree, then try installing again. To remove the read-only protection,
 follow these steps:

     1. Open an OS/2 command window.

     2. Change to the VXREXX directory. Type

                    cd \vxrexx

     3. Reset the read-only file attribute. Type

                    ATTRIB -R * /S


ΓòÉΓòÉΓòÉ 4. Errata ΓòÉΓòÉΓòÉ

 Errata:

 August 1994 printing

 Manual Omissions
 Corrections and Additions


ΓòÉΓòÉΓòÉ <hidden> Omissions from the printed manual ΓòÉΓòÉΓòÉ

 The following functions and methods are described only in the online version
 of the Reference:

 (none)


ΓòÉΓòÉΓòÉ <hidden> Corrections and additions ΓòÉΓòÉΓòÉ

 The following table lists corrections and additions to the August 1994
 printing of WATCOM VX-REXX Programmer's Guide and Reference. The number in the
 left column is the page number, and the right column describes the necessary
 change.

 86                  In the "Renaming an object" section, the second label in
                     both event routines should be PB_Start_ClickEnd:.

 125                 A new section called "Selecting records" has been added.
                     See the online version of the Programmer's Guide.

 133                 Before the "Programming with the DragDrop event" section,
                     an additional note was added regarding the Source
                     attribute and dragging within a single container. See the
                     online version of the Programmer's Guide.

 139                 The last paragraph on the page should start "To set the
                     types of all items at once..."

 196                 The first code sample in the "Returning multiple values"
                     section should be as follows:

                                          call Window2
                                          call VRMethod "Application", "GetVar", "parm."
                                          say "Window2 returned" parm.1 "and" parm.2


ΓòÉΓòÉΓòÉ 5. New since version 2.1 ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 5.1. New in version 2.1b ΓòÉΓòÉΓòÉ

 What's new in version 2.1b:

 Design environment:

 General

 Runtime environment:

 Objects
 Functions


ΓòÉΓòÉΓòÉ <hidden> General ΓòÉΓòÉΓòÉ

 o Autosave prompt

   The autosave prompt now returns the focus to whatever window had the focus
   before the prompt appeared. Also, the autosave prompt does not appear if the
   VX-REXX design environment is minimized.

 o Property notebook help

   Previously, if you pressed the F1 key to get help while in a window object's
   property notebook, the VX-REXX design environment would sometimes shut down.
   This problem has been fixed.

 o OOREXX beta

   VX-REXX has been modified to work with the IBM OOREXX beta software.

 o Section editor

   The stability of the section editor while saving large sections has been
   improved.


ΓòÉΓòÉΓòÉ <hidden> Objects ΓòÉΓòÉΓòÉ

 o Screen object

   The GetFocusWindow and GetActiveWindow methods for this object now accept
   the optional parameter Object. This parameter causes these methods to return
   a VX-REXX object handle instead of a Presentation Manager window handle.
   Also, the FindWindow method no longer causes an access violation if you pass
   it an invalid second parameter.

 o SpinButton object

   You can now clear the SpinButton list by calling the SetStringList method
   and specify a list of zero length, or the empty string.

 o ComboBox and DropDownComboBox objects

   Previously, if the focus changed from an object with a Verify event to a
   ComboBox or a DropDownComboBox object, the Verify event routine would not be
   run. Now this event is called correctly.

 o Application object

   The PutClipboard method used to return 0 even if information was put into
   the clipboard successfully. Now 1 is returned in this case.

 o Container object

   The behavior of the container object was changed so that when the user does
   a drag and drop operation within a container, the record being dragged is
   not automatically moved if the drag is a copy or a link operation. The
   record is still moved automatically if the user is performing a drag and
   drop move operation.

   Direct editing in a container now works correctly when the container is in
   split view. Previously, tabbing over the splitbar did not work when in
   direct edit mode.

   The SetFieldAttr method now accepts Name as one of the attributes that can
   be set for the record.

 o PictureBox object

   Previously, changing the Pointer property on a window would not affect the
   pointer when it was moved over a PictureBox object. Now the pointer remains
   set when moved over a PictureBox object.

 o MoveRecord event

   The VRInfo function previously would return the empty string if passed the
   parameter SourceRecord in the MoveRecord event. Now this attribute is set
   correctly.

 o Font property

   Previously, setting the font property of an object would not always set the
   font to use the correct code page, resulting in some characters being
   displayed incorrectly.


ΓòÉΓòÉΓòÉ <hidden> Functions ΓòÉΓòÉΓòÉ

 o VRIsDir and VRDir functions

   Previously, the VRIsDir function would sometimes cause a problem in the
   VRDir function on LAN Server remote drives. This problem has been fixed.
   Also, the VRIsDir function would return 1 if passed any parameter that ended
   with a backslash character, even if the specified directory did not exist.
   Now 1 is only returned if the specified parameter is a real directory.

 o VRInfo( "Source" )

   Previously, calling VRInfo( "Source" ) from the ContextMenu event of a
   container in details view would not return the correct handle. Now the
   correct handle is returned.


ΓòÉΓòÉΓòÉ 5.2. New in version 2.1a ΓòÉΓòÉΓòÉ

 What's new in version 2.1a:

 Design environment:

 General

 Runtime environment:

 Containers
 Functions
 Objects


ΓòÉΓòÉΓòÉ <hidden> General ΓòÉΓòÉΓòÉ

 o VX-REXX now works with OS/2 3.0.

 o Previously, shared sections would be saved in expanded form as part of your
   project if it was saved after generating an executable file, or running your
   project from the design environment. Now shared sections are only saved in
   your generated executable, or while your project is running. They are not
   expanded within your project's code files.

 o Drag and drop coding has been fixed for the PostEvent method, the
   SetFieldAttr method, and the SetRecordAttr method.

 o The VX-REXX design environment now works with Personal REXX installed.

 o The VX-REXX design environment no longer treats object names in a case
   sensitive manner, so you cannot have two objects named PB_1 and pb_1.


ΓòÉΓòÉΓòÉ <hidden> Containers ΓòÉΓòÉΓòÉ

 o BackColor property

   Previously, if the BackColor of a container object was set to the value
   <default>, it would appear the same color as the parent window in the design
   environment, but changed color at run time.

 o DragDiscard event

   On some systems, the DragDiscard event would not be generated when a record
   was dragged from a container onto the shredder. This problem has been fixed.

 o Painting property

   Adding record to a container while painting is turned off no longer causes
   the records to appear at inappropriate locations when the Painting property
   is turned back on.

 o SetRecordAttr method

    - You can now use the SetRecordAttr method to make a record invisible even
      if the container's Painting or Visible properties are turned off.

    - The SetRecordAttr method no longer leaves holes in the record list when a
      record's visible property is changed.

    - You can now use the SetRecordAttr method to set a record's Icon and
      Caption attributes in the same method call.

 o Dragging records

   Dragging a record with no icon and no dragging icon that was only partially
   visible when the drag started no longer leaves a visible trail along the
   path of the drag.

 o DragDrop event

    - When dropping multiple objects, the VRInfo value returned when passed the
      parameters Top, Left, and Bottom now returns correct values for all
      records, not just the first record.
    - When dropping multiple records, the VRInfo value returned when passed the
      parameter TargetObject now returns the correct value, even when the
      records are dropped near the edge of the container.

 o GetFieldList method

   This method now returns 1 when successful.

 o FindRecord method

   This method no longer causes your program to fail when executed after an
   invisible record has been deleted.

 o AddRecord and AddRecordList methods

   These method no longer fail when the same record handle is passed as the
   parent and position parameters.

 o ForeColor property

   The container ForeColor property now accepts values such as Blue and
   SystemWindowText as well as accepting RGB values.

 o OpenEdit method

   Previously, using the OpenEdit method for a field that was right of the
   split bar would cause the editing field to appear in the left half of the
   container rather than the right half. This problem has been fixed.


ΓòÉΓòÉΓòÉ <hidden> Functions ΓòÉΓòÉΓòÉ

 o VRInfo function

   The VRInfo function would sometimes return an incorrect value when passed
   the parameter SourceIndex or TargetIndex if the source or target was a
   ValueSet object. Now the correct index is returned.


ΓòÉΓòÉΓòÉ <hidden> Objects ΓòÉΓòÉΓòÉ

 o Menu object, MenuItem object, and MenuBar object

   These objects no longer have Query and QueryColumns properties.

 o ImageRadioButton object

   This object no longer has the BoundSetValue property.

 o MultilineEntryField object

   MultilineEntryFields can now have their Value property set to a string that
   is longer than their TextLimit property. The string is truncated to a length
   equal to the TextLimit.

 o Notebook object

   If an entry in the InitialPageList property of the notebook contains tab
   text but no window name, the entry is ignored.


ΓòÉΓòÉΓòÉ 6. Previous versions ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 6.1. New in version 2.1 ΓòÉΓòÉΓòÉ

 What's new in version 2.1:

 Design environment

 General
 Code sharing
 Object renaming
 New options
 Menu editor
 Section editor
 Code generation macros
 Property notebook
 Secondary windows

 Runtime environment

 General
 Parent-child naming
 Context-sensitive naming
 Drag-drop support
 Functions
 Methods
 Properties and events
 Objects
 Window manipulation

 Sample programs

 Bounce
 CUA 91


ΓòÉΓòÉΓòÉ <hidden> Property notebook changes ΓòÉΓòÉΓòÉ

 o The property notebook now uses a 10 point "Helv" font.

 o Context-sensitive help is available for any property or event by pressing
   F1.

 o New property notebooks open to the last page that was turned to in an
   already open property notebook.  This makes it easier to change the same
   property on different objects.


ΓòÉΓòÉΓòÉ <hidden> Secondary window changes ΓòÉΓòÉΓòÉ

 The following changes have been made to the way secondary windows are created
 by the design environment:

 o Previously, modal secondary windows had to kept in a separate file. This
   restriction has now been removed. You can open a modal secondary window from
   the same file by using the new "W" parameter to the VRLoadSecondary
   function. If you do this, VRLoadSecondary will not return until the user has
   closed the window.

 o The code to make secondary windows visible has been moved from the
   VRLoadSecondary function to the Create event for the secondary windows
   themselves.

   This means that if you copy the new VRLoadSecondary function into an old
   project created with VX-REXX version 2.0 or earlier, you will also have to
   make a Create event for the secondary window and add code to make the window
   visible.


ΓòÉΓòÉΓòÉ <hidden> Parent-child object naming ΓòÉΓòÉΓòÉ

 Version 2.0 introduced parent-child object naming, where if you had two
 objects with the same name (on two different secondary windows, for example)
 you could distinguish between them by including the name of the parent object,
 as in:

  call VRSet 'SW_1.PB_1', 'Caption', 'First'
  call VRSet 'SW_2.PB_1', 'Caption', 'Second'

 If an object was contained inside a group box, you could extend the notation:

  call VRSet 'SW_1.GB_2.PB_1', 'Caption', 'In the box'

 This notational convenience has been extended so that you do not have to
 specify every parent object. If MyButton is a push button inside the group box
 MyGroup located on the window MyWindow, the following notations all work:

  call VRSet 'MyWindow.MyGroup.MyButton', 'Caption', 'A'
  call VRSet 'MyWindow.MyButton', 'Caption', 'B'
  call VRSet 'MyGroup.MyButton', 'Caption', 'C'
  call VRSet 'MyButton', 'Caption', 'D'

 (If there are two group boxes called MyGroup on different windows, only the
 first two forms uniquely identify the object.)

 The internal handle of an object, obtained using:

  handle = VRGet( 'MyWindow', 'Self' )

 or inside an event routine using:

  object = VRInfo( 'Object' )

 can be substituted for a symbolic name at any point:

  handle = VRGet( 'MyWindow', 'Self' )
  call VRSet handle || '.PB_2', 'Caption', 'foo'


ΓòÉΓòÉΓòÉ <hidden> Context-sensitive object naming ΓòÉΓòÉΓòÉ

 If an object name is passed to VRGet, VRSet or VRMethod, the Window where the
 last event was generated is searched first. In other words, if inside the
 Click event for PB_1 you say:

  call VRSet 'PB_1', 'Caption', 'Foo'

 the new behaviour is equivalent to:

  window = VRInfo( "Window" )
  if( VRIsValidObject( window || '.PB_1' ) )then
      call VRSet window || '.PB_1', 'Caption', foo
  else
      call VRSet 'PB_1', 'Caption', foo

 The name of the Window on which the object is located is implicitly added to
 the front of the object name.

 This behaviour only applies to programs generated using VX-REXX 2.1. You can
 explicitly turn it off using:

  call VROptions 'NoImplicitNames'

 or turn it on using:

  call VROptions 'ImplicitNames'

 Unless explicitly changed, programs created with earlier versions of VX-REXX
 do not exhibit the new behaviour.


ΓòÉΓòÉΓòÉ <hidden> Code sharing ΓòÉΓòÉΓòÉ

  Shared routines (sections) can be added to a file using the Section List
 window and the Add menu item. You will be prompted for the name of a file. The
 contents of the file will be appended to the current code or window file when
 the project is compiled into an executable or a macro.

 You may edit a shared section by double clicking on the entry in the section
 list.

 If a relative path name is given, the file will be searched for in the
 following order:  relative to the project directory, then relative to the
 directories in the VXINCLUDE environment variable, then relative to the
 directory in the VXREXX environment variable.


ΓòÉΓòÉΓòÉ <hidden> General ΓòÉΓòÉΓòÉ

 o Objects can be dragged from the tool palette and dropped onto a window.

 o The design environment prompts you for a window name when creating new
   primary or secondary windows.

 o The menus the Window, Section and File lists are now accessible as popup
   menus as well.

 o The system menu for primary and secondary windows is now active in design
   mode. This means that you can close a window in the design environment by
   double clicking on its system menu.

 o The menu editor has been moved to the Open menu item on the pop-up menu for
   the Window object.

 o A Tab Editor can be used to set the tab order of objects on a window.  It is
   accessed by selecting the Tab editor... item from the Open... menu on the
   Window object's pop-up menu.

 o A new Close window menu item has been added to the Window pop-up menu. You
   may use this for closing a Window with no system menu.

 o When a secondary window is created, new Init and Fini routines for that
   window are created.  The Create and Close events automatically call the Init
   and Fini routines.

 o The UserData property is now encoded when a file is saved as a text file.

 o Sections can be renamed.

 o Hints are now displayed at design time.


ΓòÉΓòÉΓòÉ <hidden> Object renaming ΓòÉΓòÉΓòÉ

 The design environment includes some enhancements to object renaming:

 o Clicking on an object while holding the Alt and Shift keys down can be used
   to change the name of the object.

 o When an object is renamed, the design environment updates references to that
   object in the REXX code. The references that are changed all have the format
   name_suffix, where name is the old name of the object and suffix is any
   string without underscores.  To be changed, name must be a string starting
   with a series of alphabetic characters followed by an underscore and any
   sequence of alphanumeric characters. Only the following references are
   changed in the REXX code:

    - Literal strings
    - Labels
    - call and signal instructions

   For example, if the object PB_1 is renamed to PB_Open, the following code:

      PB_1_Click:
          if( VRGet( "PB_1", "Caption" \= "" ) then signal PB_1_ClickEnd
          call VRSet "PB_1", "Caption", "Clicked"
      PB_1_ClickEnd:
      return

   is updated to:

      PB_Open_Click:
          if( VRGet( "PB_Open", "Caption" \= "" ) then signal PB_Open_ClickEnd
          call VRSet "PB_Open", "Caption", "Clicked"
      PB_Open_ClickEnd:
      return

   But note that if PB_1 had been renamed to Foo, then renaming Foo to another
   name would only rename the sections that belong to Foo, and not any
   references in the REXX code.


ΓòÉΓòÉΓòÉ <hidden> New options ΓòÉΓòÉΓòÉ

 The Options menu has been reorganized:

 o Run options has been moved from the Options menu to the Run menu.

 o The new Autosave item can be used to set timed reminder messages for saving
   your project.  An option is also available to automatically save the project
   before running or debugging it.

 o The new Messages item lets you control the verbosity of the design
   environment.

 o The new Object libraries item lets you automatically load object libraries.
   This item replaces the Add object library and Remove object library items in
   previous versions of VX-REXX.

 o The Editor item now allows you to specify a default header for new sections,
   and to use the VX-REXX section editor instead of an external editor when
   editing files.

 o The new Advanced item controls whether or not executables made with VX-REXX
   are compressed (the default) or simply encoded.


ΓòÉΓòÉΓòÉ <hidden> Menu editor ΓòÉΓòÉΓòÉ

 o The menu editor is now accessed from the Open... item of the pop-up menu or
   by double-clicking on the window menubar.

 o A bug in the menu editor has been fixed allowing the editing of menu items
   with the same caption.

 o A Clear button has been added to the menu editor, which clears the current
   values in preparation for inserting a new menu or menu item.

 o After editing, menus can be viewed at design time. Simply select the menu sa
   you normally would.  You may also double click on a menu or menu item to
   bring up its property notebook.


ΓòÉΓòÉΓòÉ <hidden> Section editor ΓòÉΓòÉΓòÉ

 o Fixed the bug that could cause a crash when selecting large amounts of text.

 o Fonts and colors dragged from the OS/2 font and color palettes are now
   supported.  Fonts and colors may also be changed using the items under the
   Settings menu.

 o Font, color and window size settings can be saved.

 o Menu items and accelerators have been added to run the project and to switch
   to various windows.

 o Case-sensitive search and replace can now be done.

 o Easier access to online help.

 o Characters are no longer missing when exporting selected text to a file.


ΓòÉΓòÉΓòÉ <hidden> Code generation macros ΓòÉΓòÉΓòÉ

 o The "Add records from a directory" container method (FillFromDir) now
   generates correct code.


ΓòÉΓòÉΓòÉ <hidden> General ΓòÉΓòÉΓòÉ

 o The VX-REXX run time libraries are now built with Pentium optimizations.

 o Events can be added dynamically at run time using the DefineEvent method.

 o Picture references are now cached, resulting in better performance,
   especially with container icon references.


ΓòÉΓòÉΓòÉ <hidden> Drag and drop ΓòÉΓòÉΓòÉ

All objects can now act both as drag sources and drag targets, as controlled by
the following events and properties:  AllowDrag, DragDrop, DragIcon, DragStart,
DragTarget, StartDrag.

Drag targets

To act as a drag target, the DragTarget property must be set to a value other
than "None" AND the DragDrop event must be defined. The special value "Parent"
may be used to let the parent object act as the drag target instead of the
object itself. Otherwise, valid drag targets are "Record", "Files=",
"Filetypes=", "Objects", "Formats=". The first three work as described for the
Container's DragTarget property. If "Objects" is specified, VX-REXX objects
from the same application can be dropped onto the application. "Formats="
allows you to specify in detail the exact rendering formats the object will
accept as a drag target.

The DragTarget property can also specify the default operation and the
supported operations. For example, to define an object that allows *.TXT files
to be dropped on it, with a default Copy operation and only allows Link and
Copy:

Files="*.TXT";Default=Copy;Operations=Link,Copy

When an acceptable object is dropped on a VX-REXX object, a DragDrop event is
defined and information is made available about the dropped object. The
following items can be accessed using VRInfo with the DragDrop event:

 SourceObject        The internal name of the VX-REXX object that is the drag
                     source. This will be null if the source object is not an
                     object in your program.

 TargetObject        The internal name of the VX-REXX object that is the drag
                     target.

 SourceRecord        If the source object is a container, this is the record
                     handle of the record being dragged.

 TargetRecord        If the target object is a container, this is the record
                     handle of the record where the drop occurred.

 SourceIndex         If the source object is a listbox, value set or combo box,
                     this is the numeric index (starting at 1) of the item in
                     the object where the drag started, or 0 if the drag did
                     not start on an item.

 TargetIndex         Like SourceIndex, but identifies which item the drop
                     occurred on.

 SourceName, TargetName, ContainerName Strings that identify the file or
                     object.

 SourceFile          The concatenation of ContainerName and SourceName.

 Format              The complete OS/2 rendering format of the object.

 NativeFormat        The native format, a subset of the Format.

 Left, Top, Bottom   Where the object was dropped.

 Operation           The drag operation.

 No actions occur in response to a drop -- the program must analyse the drop
 and decide on an appropriate course of action.

 Drag sources

 To act as a drag source, an object must have the AllowDrag property set. If a
 DragStart event is defined, the program must call the StartDrag method to
 start the actual dragging operation. For all objects except the Container, the
 syntax for StartDrag is as follows:

  call VRMethod object, 'StartDrag', default, dragimage,,
                format, type, cname, sname, tname, index

 The arguments are:

 default             The default operation dragging operation, one of
                     "Default", "Copy", "Link" or "Move". If omitted, "Default"
                     is the default.

 dragimage           The path of the icon or bitmap to use for the dragging
                     operation. If omitted, the value of the DragIcon property
                     is used. If DragIcon is not defined and the object
                     supports a PicturePath property, the latter is used
                     instead.

 format              The OS/2 drag and drop rendering format string. If
                     omitted, the format <DRM_VXREXX_OBJECT,DRF_UNKNOWN> is
                     used.

 type                The OS/2 drag and drop type string. If omitted, the type
                     "VX-REXX Object" is used.

 cname               The "container name", which has nothing to do with the
                     Container object, but is rather the a string which
                     describes the object that "contains" the object being
                     dragged. If omitted, the internal name of the parent
                     object is used.

 sname               The "source name". If omitted, the internal name of the
                     source object is used.

 tname               The "target name". If omitted, the internal name of the
                     source object is used.

 index               The numeric value to use when setting the "SourceIndex"
                     VRInfo parameter when the object is dropped on another
                     VX-REXX object.

 If a DragStart event is NOT defined, the drag action occurs automatically as
 if StartDrag had been called as follows:


ΓòÉΓòÉΓòÉ <hidden> Functions ΓòÉΓòÉΓòÉ

 o VRFlush function

   The VRFlush function is used to remove unwanted events from the event queue,
   based either on the event type or the object that generated them, or both.

 o VRFileDialog function

   The VRFileDialog function now supports multiple file selection.

 o VRFontDialog function

   Use the VRFontDialog function to present a standard font dialog to the user.

   The syntax is:

      newFont = VRFontDialog( [parent], [initialFont], [title] )

    parent              The dialog's parent window. If omitted, the desktop is
                        used instead.

    initialFont         The font that is initially selected in the dialog.

    title               The font dialog title.

   The font strings have the form

      <size>.<facename>[modifier1][modifier2]...

   modifiers are:

    Bold
    Italic
    Underline
    Strikeout

 o VRGetFileType function

   The VRGetFileType function no longer strips off the last character on files
   types that were not set using VRSetFileType.

 o VRInfo function

   The VRInfo function has been extended in several ways:

    - The following new information is available for all events:

       o Left
       o Top
       o AltPressed
       o CtrlPressed
       o ShiftPressed
       o Button1Pressed
       o Button2Pressed
       o FocusObject
       o FocusWindow

    - The name of a stem variable can be passed to VRInfo.

 o VRIsChildOf function

   The new VRIsChildOf function checks if a given object's type is a child of
   some other object type.  You can use this function, for example, to see if
   the parent of a window is a notebook.

 o VRLoadSecondary function

   The VRLoadSecondary function can now load modal windows from the current
   file. To do this, specify the new "W" parameter. VRLoadSecondary will wait
   for the user to close the secondary window before returning.

 o VROptions function

   VROptions has two new options: ImplicitNames and NoImplicitNames, used to
   turn implicit (context-sensitive) naming on or off.

 o VRSetFileType function

   VRSetFileType now accepts the null string as a valid type.


ΓòÉΓòÉΓòÉ <hidden> Methods ΓòÉΓòÉΓòÉ

 o Clear method

   The Clear method has been added to the Console object.

 o CharFromLine method

   The CharFromLine method returns the insertion point that corresponds to the
   start of the given line in an MLE.

 o ColorIndex method

   Use this Screen object method to convert color indices to strings and back.

 o DefineEvent method

   The DefineEvent method has been added to all objects and can be used to add
   a new event to an object that is triggered when a specified Presentation
   Manager message is sent to an object.

 o DisableRefresh method

   The DisableRefresh method disables updating of an MLE while changes are
   being made and also changes the mouse pointer.

 o EnableRefresh method

   The EnableRefresh method enables the updating of an MLE and restores the
   mouse pointer.

 o GetFieldAttr method

   The GetFieldAttr method now accepts the new Width attribute. This returns
   the width of the field in twips. If the width is 0, the container
   automatically resizes the field to accommodate the widest data in that
   field. The default width is 0.

   The Name of the field can also be retrieved using this method.

 o GetFieldData method

   The container GetFieldData method now also accepts the name of a stem
   variable in place of a field handle (or name).  Passing a stem indicates you
   want data on all the fields in the given record. On return, stem.0 is the
   number of fields, stem.1 is the first data value, stem.2 is the second value
   and so on. If a field has a symbolic name, the method also sets the variable
   with the form stem.!fieldName.

 o GetFieldList method

   The new container GetFieldList method returns a list of field handles in a
   REXX stem variable.

 o GetPageNumber method

   The notebook GetPageNumber method now returns the correct value.

 o GetRecordAttr method

   The container GetRecordAttr method supports two new record attributes:

    - UserData, used to store arbitrary application data.
    - Source, used to indicate which records are to be included in a drag or
      pop-up menu operation.

 o LineFromChar method

   The LineFromChar method returns the line number that corresponds to the
   given insertion point in the MLE.

 o ListPrinters method

   The ListPrinters method now also returns the default printer.

 o PostEvent method

   The PostEvent method has been added to all objects. It allows an object to
   "trigger" one if its own events.

 o PostQueue method

   The "object" and "event" values returned by VRInfo can now be set when
   calling the PostQueue method. If "object" is set, the "window" value is also
   implicitly set.

 o Popup method

   When activated using the Popup method, menus now pop up on the currently
   active window, not the window they are defined in.

 o QueryChanged method

   The QueryChanged method returns the MLE changed flag status.

 o QueryFirstChar method

   The QueryFirstChar method returns the insertion point of the first visible
   character of an MLE.

 o QueryFormatLineLength method

   The QueryFormatLineLength method returns the number of bytes in an MLE line
   after formatting has been applied.

 o QueryFormatTextLength method

   The QueryFormatTextLength method returns the length of the specified MLE
   text after formatting is applied.

 o QueryLineCount method

   The QueryLineCount method returns the number of lines in an MLE.

 o QueryLineLength method

   The QueryLineLength method returns the length of an MLE line starting at the
   given insertion point.

 o QuerySel

   The QuerySel method returns the insertion point of the anchor point or
   cursor point in an MLE.

 o QueryTabStop method

   The QueryTabStop method returns the size (in pixels) of the MLE tab stop.

 o Search method

   The Search method searches for text in an MLE.

 o SetChanged method

   The SetChanged method sets the changed status of an MLE.

 o SetFieldAttr method

   The SetFieldAttr method now accepts the new Width attribute. Set the width
   to the field width in twips. If the width is set to 0, the container
   automatically resizes the field to accommodate the widest data in that
   field. The default width is 0.

 o SetFieldData method

   The SetFieldData method now raises a REXX syntax error if passed the name of
   an invalid field attribute. Previously, it would just return 0 without
   causing an syntax error.

 o SetFirstChar method

   The SetFirstChar method sets the first visible character in an MLE.

 o SetRecordAttr method

   The SetRecordAttr method supports the new record attributes, Source and
   UserData.

 o SetSel method

   The SetSel method sets the cursor and anchor points of an MLE.

 o SetTabStop method

   The SetTabStop method sets the length of the tab stop (in pixels) of an MLE.

 o StartDrag method

   The StartDrag method now applies to all objects, but with an extended syntax
   allowing the program to specify in detail how the dragging operation should
   occur.

 o StartThread method

   When starting a window file, code file or external file as a new thread
   using the StartThread method, either of the words "command", "function" or
   "subroutine" may be added before the name of the file. The file will then be
   started as either a command file, a function, or a subroutine. For example,
   to start a window file as a subroutine:

      call VRMethod 'Application', 'StartThread', 'subroutine window2'

   If not specified, the default is "command".

 o UpdateLayout method

   When dynamically adding or removing children from a window or group box
   whose LayoutStyle property is set, the UpdateLayout method can be used to
   force an update of the layout.


ΓòÉΓòÉΓòÉ <hidden> Objects ΓòÉΓòÉΓòÉ

 o Application object

   The Program property is now set to a null string if the program is being run
   from within the design environment.

 o CheckBox. object

   The NoPointerFocus property has been added.

 o ComboBox object

    - You can now store per-string user data for combo boxes list items. See
      the on-line documentation for the GetItemData, SetItemData,
      GetItemDataList, and SetItemDataList methods.
    - System response has been improved when passing large stem arrays to
      AddStringList.

 o Console object

    - The Clear method is now supported on the Console object.

 o Container object

    - New AutoEdit property.
    - Enhanced GetFieldAttr method.
    - Enhanced GetFieldData method.
    - New GetFieldList method.
    - New Guard event.
    - New GuardRecords property.
    - New GuardScroll method.
    - New KeptRecords property that sets an upper limit on the number of
      records in a container.
    - Enhanced SetFieldAttr method.
    - New TreeCount property.
    - Enhanced GetRecordAttr and SetRecordAttr methods.
    - New UserData record attribute.
    - New Width and UserData field attributes.
    - Certain painting problems were fixed.
    - System response has been improved when passing large stem arrays to
      AddRecordList and SetRecordAttr.
    - Previously, the in-use emphasis would be drawn in detail view only if the
      first column was an icon field.  Now the in-use emphasis is drawn on the
      leftmost icon field, even if it isn't the first field.
    - Passing an invalid value to SetFieldData to set a ULONG field now returns
      0.
    - Setting the field data for an icon field to the null string removes the
      icon.
    - Asking for SourceOrSelected returns the empty list if the container
      itself has the source emphasis.
    - Records that were initially created as invisible are now redrawn
      correctly when they are made visible.

 o DropDownComboBox (DDCB) object

    - You can now store per-string user data for DDCB list items. See the
      on-line documentation for the GetItemData, SetItemData, GetItemDataList,
      and SetItemDataList methods.
    - System response has been improved when passing large stem arrays to
      AddStringList.

 o GroupBox object

    - New properties: BorderType and LayoutStyle.
    - New method: UpdateLayout.

 o ImagePushButton and ImageRadioButton objects

    - These objects paint themselves correctly when they are disabled.

    - Both objects now support the ForeColor property and the NoPointerFocus
      property.

    - The ImageRadioButton has a new ToggleMode property.

 o ListBox object

    - System response has been improved when passing large stem arrays to
      AddStringList.

 o MultiLineEntryField object

   The MLE had difficulty retrieving text more than 64K in size. This has been
   fixed.

   The MLE supports these new methods:

    - CharFromLine

    - LineFromChar

    - QueryLineLength

    - SetFirstChar

    - SetTabStop

    - SetChanged

    - QueryFormatLineLength

    - DisableRefresh

    - EnableRefresh

    - QueryChanged

    - QueryFirstChar

    - QueryLineCount

    - QueryTabStop

    - QueryFormatTextLength

    - QuerySel

    - SetSel

    - Search

 o Notebook object

    - In a PageSelected event, the internal name of the old page window is
      available using VRInfo:

            oldPageWindow = VRInfo( "OldPageWindow" )

    - Previously calling VRInfo("OldPage") in a PageSelected event returned the
      internal name of the notebook, not the page number (as advertised). This
      bug has been fixed.

    - Notebooks were behaving like GroupBox objects and "swallowing" objects
      they were laid on top of. This has been fixed.

    - Keyboard navigation between notebook pages is now properly supported.

    - The GetPageNumber method now returns the correct page number.

    - Fixed the bug that prevented PageLoad events from occurring when pages
      were added using InsertBlankPage after calling DeletePage.

 o PushButton object

   The NoPointerFocus property has been added.

 o RadioButton object

   The NoPointerFocus property has been added.

 o Screen object

   The Screen object supports the following new methods and properties:

    - ColorIndex

      Converts a color index to a string and back.

    - FindWindow

      Allows you to find a window handle by name.

    - PixelsToTwips

      Convert pixels into twips.

    - PointerVisible

      Controls the pointer visibility.

    - TwipsToPixels

      Convert twips into pixels.

   The GetActiveWindow and GetFocusWindow methods will now optionally return
   the internal name of the VX-REXX object that is active or has the input
   focus.  Previously, these two methods would only return a Presentation
   Manager window handle.

 o Slider object

   The slider object would sometimes shrink in size. This has been fixed.

 o Window object

   The Window object supports the following new events, methods and properties:

    - Help event

      Occurs when the user presses F1.
    - UpdateLayout method

      Used to force an update of the window layout if LayoutStyle is set.


ΓòÉΓòÉΓòÉ <hidden> Properties and events ΓòÉΓòÉΓòÉ

 o AllowDrag property

   All objects in the tool palette support the AllowDrag property. If on, the
   object can act as a drag source. See the DragStart property.

 o AutoEdit property

   When this property is set to 1, pressing TAB (or BACKTAB) while editing a
   detail view field will automatically move to the next (or previous field).
   If there are no more fields in the record, the next record is opened for
   editing. If there are no more records to edit, the input focus is moved to
   the next object in the tab order.  Read-only fields are skipped.

 o Autosize property

   The Autosize property takes mnemonics into account when calculating the size
   of the object. It does not leave extra space around the radio button and
   check box objects either.

 o AutoTab property

   Entry fields now handle overstrike mode correctly when AutoTab is on.

 o BeginEdit event

   The handle of the field being edited can be had using VRInfo.

 o BorderType property

   The GroupBox object has several new border styles that are set using the
   BorderType property.

 o ClipSiblings property

   A new property on most objects, it controls how objects are painted if they
   overlap. Turn it on to ensure that the objects paint themselves according to
   their SiblingOrder.

 o ContextMenu event

   When a ContextMenu event is generated on a ListBox, ComboBox or
   DropDownComboBox object, VRInfo("Index") can be used to retrieve the index
   of the item that was clicked on. The value will be zero if the click did not
   occur on a list item. The value is also available from the menu Click event
   if a menu invoked using the Popup method inside the ContextMenu event code.

 o DragIcon property

   This is the icon or bitmap to use when dragging the object. It uses the same
   syntax as PicturePath.

 o DragDrop event and DragTarget property

   All objects now support the DragTarget property and the DragDrop event.

 o DragStart event

   All objects support this event. As with the container, if AllowDrag is on
   and DragStart is NOT defined, a default dragging action occurs. Otherwise it
   is up to the program to call the StartDrag method from within the DragStart
   event to start the dragging.

 o EndEdit event

   The handle of the field being edited can be had using VRInfo.

 o ForeColor property

   The ForeColor property has been added to the ImagePushButton,
   ImageRadioButton and PictureBox.  This property is used along with BackColor
   when displaying monochrome bitmaps.

 o Help event

   The Help event occurs when the user presses F1 on a window. See also Adding
   help to a program for more information.

 o LayoutStyle property

   The LayoutStyle property has been added to the GroupBox object.

 o NoPointerFocus property

   The NoPointerFocus property has been added to the PushButton, RadioButton,
   CheckBox, ImagePushButton and ImageRadioButton objects.  If set, the user
   can click on the object but the focus will not move to the object.

 o PointerVisible property

   The PointerVisible property on the Screen object controls whether or not the
   mouse pointer is visible.

 o Program property

   The Program property is now set to a null string when the program is being
   run or debugged from within the design environment.

 o StatusFont property

   Sets the font used in the status area of a window.

 o ToggleMode property

   The new ToggleMode property can be used to make an ImageRadioButton object
   act as a toggle.

 o TreeCount property (containers)

   The new TreeCount property returns the total number of records in a
   container, including child records. It is different from the Count property
   in that the Count property only includes top level records.

 o Verify event

   A new event that can be used to validate data entered in entry fields, MLEs,
   combo boxes, DDCBs and spin buttons.

 o WindowListTitle property

   Sets (or removes) the name of a window in the WindowList.


ΓòÉΓòÉΓòÉ <hidden> Window manipulation ΓòÉΓòÉΓòÉ

The following features aid in the manipulation of Presentation Manager windows
from within a VX-REXX program:

 o The Working with other programs chapter has a section describing how to
   obtain and work with Presentation Manager window handles.
 o The FindWindow method has been added to the Screen object.
 o The following properties can be set using VRSet or retrieved using VRGet:

    - Left
    - Top
    - Width
    - Height
    - Caption
    - Visible
    - Enabled
    - Parent
    - SiblingOrder
    - WindowState

 o The following additional properties can be used with VRGet only:

    - ClassName
    - ProcessID
    - ThreadID
    - ID
    - Parent
    - Sibling
    - FirstChild
    - Owner
    - Self
    - Hwnd
    - Object

 o The following methods can be invoked using VRMethod:

    - SetFocus
    - Maximize
    - Minimize
    - Restore


ΓòÉΓòÉΓòÉ <hidden> Bounce ΓòÉΓòÉΓòÉ

The Bounce sample has been improved by the addition of gravity.


ΓòÉΓòÉΓòÉ <hidden> CUA 91 ΓòÉΓòÉΓòÉ

The CUA91 sample demonstrates several VX-REXX features and programming
techniques relevant to developing CUA'91 compliant applications. It also
demonstrates how to use subroutines contained in OBJECT.VRS to simplify the
process.


ΓòÉΓòÉΓòÉ 6.2. New in version 2.0a ΓòÉΓòÉΓòÉ

 What's new in version 2.0a:

 Design environment

 Miscellaneous Changes

 Runtime environment

 Containers
 Container and Workplace Shell interaction
 Named field support for containers
 Popup Menus
 I/O Console
 Bitmap Support
 Picturebox Object
 DDE Support
 Accelerators
 Font Support
 DBCS Support
 Other Changes

 VX-REXX Features

 Properties, methods, and functions

 Sample programs

 New or improved samples


ΓòÉΓòÉΓòÉ <hidden> Miscellaneous Changes ΓòÉΓòÉΓòÉ

 The following sections list significant changes to the design environment.

 o The design environment's initialization file (VRXEDIT.INI) is now stored in
   the OS2 directory. Previously, it was stored in the VXREXX directory.

 o Drag and drop code generation macros

   The code generation macros are now faster. The macro for VRDestroy was
   missing and has been added. The macro for SetRecordAttr has been corrected.

 o Menu editor

   The menu editor has been sped up. It also asks the user if changes have been
   made to a menu or menu item and the Change button was not clicked.

 o The property notebook for containers has been rearranged.

    - The AutoPosition property has been moved from the "Style" page to the
      "Views" page.
    - The ExtendSelect and MultiSelect properties have been moved from the
      "Style" page to the "List" page.

 o The SetProp macro used to cause unpredictable results if you selected all
   objects.

 o The Help menu now contains items to directly access the VX-REXX Reference,
   VX-REXX Programmer's Guide and REXX Reference online documents.

 o Section editor

   The built-in section editor has been improved in several ways:

    - Previously, the "Insert code" feature would stop working after a certain
      number of times due to a bug in the C run-time library. This has been
      corrected.
    - Double-byte character set (DBCS) support has been added, including a DBCS
      conversion bar. The conversion bar only appears in DBCS versions of OS/2.
    - The font used by the section editor can be changed using a new menu item
      in the Settings menu. When you pick a new font, it is propagated to all
      open section editor windows.
    - In previous versions of the VX-REXX design environment, it was not
      possible to save window files that were greater than 64k bytes long. This
      restriction has been removed.
    - Closing a section editor window from the Task List will only close the
      window, not the complete project.
    - Restoring a section editor window from the Task List will also restore
      the complete project if the project was also minimized.
    - The online reference manuals can be accessed from the Help menu.
    - When text is selected in a section editor window, a new 'Lookup' item
      appears in the popup menu allowing you to lookup the currently selected
      word in the online references. You can also use Ctrl+DoubleClick to
      select a word and automatically look it up.

 o File limits

   Windows with more than 64K of data in them are now saved correctly.

 o Font editing

   The font dialog in the property notebooks now supports the Strikeout,
   Underscore and Outline attributes. The appear in the font name as
   ".Strikeout", ".Underscore" and ".Outline", in any order.

 o Direct editing

   Direct text editing with alt-Click no longer sounds a beep.

 o Bitmaps and icons

   A new Show pictures menu item has been added to the Options menu. If set,
   all PictureBox, ImagePushButton and ImageRadioButton objects will display
   their pictures in the design environment. Previously, they would only do so
   at run-time. If this option is not set, these objects will be hatched if a
   value has been assigned to their PicturePath properties and blank otherwise.


ΓòÉΓòÉΓòÉ <hidden> Containers ΓòÉΓòÉΓòÉ

 o You now have greater control over the drag/drop operation. You can specify
   the default operation type using the DragStart method. You can change the
   set of dragged records when the operation begins by changing the Source
   attributes while in the new StartDrag event.

 o You can now fill a container based on the contents of a directory using the
   new FillFromDir method.

 o You can now refer to detail view fields using a symbolic name. See the
   enhanced AddField method.

 o The appearance of minitature icons has been improved.

 o The amount of screen flicker has been reduced when invoking the
   SetRecordAttr and SetFieldData methods.

 o The source emphasis is now drawn more consistently around records.

 o Setting the Expanded and Collapsed record attributes now expands or
   collapses the record tree.


ΓòÉΓòÉΓòÉ <hidden> Container and Workplace Shell interaction ΓòÉΓòÉΓòÉ

 You can now drag records onto Workplace Shell objects other than the Shredder
 and printer objects. See the new DragFile event and the expanded SetRecordAttr
 method.


ΓòÉΓòÉΓòÉ <hidden> Named field suppport for containers ΓòÉΓòÉΓòÉ

 You can now assign symbolic names to container fields using the AddField
 method. Any method that takes a field handle will now accept a symbolic field
 name.

 For example, the following code sample creates two named fields called
 "NameField" and "PriceField". A record is then added, and its field
 information is set.

  f1 = VRMethod( "CN_1", "AddField", "String", "Name", "NameField" )
  f2 = VRMethod( "CN_1", "AddField", "ULong", "Price", "PriceField" )
  record = VRMethod( "CN_1", "AddRecord",,, "Car wax", "Information" )
  call VRMethod "CN_1", "SetFieldData", record,,
                "NameField", "Car wax",,
                "PriceField", "19.95"

 Notice that the field names "NameField" and "PriceField" are passed to the
 SetFieldData method. You could also invoke the method with the following line
 for the same result:

  call VRMethod "CN_1", "SetFieldData", record,,
                f1, "Car wax",,
                f2, "19.95"


ΓòÉΓòÉΓòÉ <hidden> Popup menus ΓòÉΓòÉΓòÉ

 o The internal name of the object for which a context menu was requested is
   now available in the Click event of popup menu items. In the Click event you
   can retrieve the source object name by using the VRInfo function.

   The Popup sample program shows how you can use VRInfo to get the name of the
   object to which the context menu applies. The Click event for one of the
   popup menu items is shown below:

      MI_BackRed_Click:
          call SetColor "Red"
      return

      SetColor: procedure
          parse arg color

          source = VRInfo( "Source" )
          call VRSet source, "BackColor", color
      return

 o Closing a cascaded portion of a popup menu no longer closes the whole menu.


ΓòÉΓòÉΓòÉ <hidden> I/O console ΓòÉΓòÉΓòÉ

 The I/O console no longer converts carriage return characters to newline
 characters on input, and also makes sure that all input lines are terminated
 with a CR-LF pair. The OS/2 BACKUP command will now work properly with the I/O
 console.

 You can use the name 'Console' to refer to the console's frame window and use
 VRGet, VRSet and VRMethod to manipulate the console as you would any other
 Presentation Manager window.  For example:

  /* Hide the console */

  call VRSet 'Console', 'Visible', 0

  /* Get the width */

  width = VRGet( 'Console', 'Width' )

 See the entry for HWnd for more information on how to manipulate window
 handles.  The Window Controller sample is also a good place to look.


ΓòÉΓòÉΓòÉ <hidden> Bitmap support ΓòÉΓòÉΓòÉ

 When loading a bitmap from a file which contains several bitmaps (a bitmap
 array, each bitmap specific to a particular display resolution and/or number
 of colors), VX-REXX used to pick the bitmap with exactly the same number of
 colors as the current display, or the first bitmap in the file. Now it picks
 the closest bitmap, where "closest" means the bitmap with the greatest number
 of colors less than or equal to the maximum number of displayable colors for
 your system. (Only the standard system color palette is supported, however.)


ΓòÉΓòÉΓòÉ <hidden> PictureBox object ΓòÉΓòÉΓòÉ

 The PictureBox object now correctly draws its border when displaying a
 picture. Pictures are also clipped to the correct area if ResizePicture is not
 set.


ΓòÉΓòÉΓòÉ <hidden> DDE support ΓòÉΓòÉΓòÉ

 DDE conversations were not being properly terminated in some cases. This has
 been fixed. If the DDE client is in the middle of a conversation with a DDE
 server and the server terminates or hangs abruptly without notifying the
 client, your application can be interrupted cleanly by closing it from the
 Task List.


ΓòÉΓòÉΓòÉ <hidden> Accelerators ΓòÉΓòÉΓòÉ

 Menu accelerators now accept mixed-case alphabetic characters by default.
 Previously, they only accepted the lowercase version of an alphabetic
 character. You can now add the keyword case to the end of the accelerator
 string to force the accelerator to be case-sensitive.


ΓòÉΓòÉΓòÉ <hidden> Font support ΓòÉΓòÉΓòÉ

 All objects that have a Font property now support strikeout, underscore, and
 outline attributes. For example, setting Font to 10.System
 Proportional.Underscore causes the object to underline displayed text. See the
 Font section of the online Reference for more information.


ΓòÉΓòÉΓòÉ <hidden> DBCS support ΓòÉΓòÉΓòÉ

 The following features have been added to support DBCS (double byte character
 set) environments:

 o VX-REXX objects now support DBCS fonts.
 o Window objects can have an options DBCS-SBCS conversion bar at the bottom of
   the window.


ΓòÉΓòÉΓòÉ <hidden> Other changes ΓòÉΓòÉΓòÉ

 o Previously, running executables generated with VX-REXX would sometimes
   report problems if multiple copies of VROBJ.DLL were in the LIBPATH and the
   directory where the executable was located. This problem has been fixed.

 o The size of the stack used by VX-REXX run time library (VROBJ.DLL) can be
   increased by setting the VXREXXSTACK environment variable to desired stack
   size in bytes before running the program. The default stack size for VROBJ
   is 32K. You may need to increase the stack size if you are developing new
   VX-REXX objects that demand a larger stack.

 o In version 2.0, a syntax error would occur if you tried to use VRSet, VRGet
   or VRMethod with a Presentation Manager window handle that was no longer
   valid (if, for example, the window has been destroyed).  In 2.0a this no
   longer occurs.  Instead, the function call is simply ignored and has no
   effect.  (This is only true for window handles, not VX-REXX objects.)


ΓòÉΓòÉΓòÉ <hidden> New or improved properties, methods, and functions ΓòÉΓòÉΓòÉ

 The following sections list new or improved properties, methods, and functions
 for version 2.0a.

 Accelerator property

 Accelerators are now mixed-case by default. Use the new keyword Case to define
 case-sensitive accelerators. See the Accelerator property in the online
 Reference for details.

 Acknowledge event

 The Acknowledge event was inadvertently missing from the documentation,
 although it existed in version 2.0.

 AddField method

 The AddField method takes a new name parameter which lets you assign a
 symbolic name to a field.

 AddRecordList method

 The AddRecordList method now inserts records in the given order when adding to
 the front of the list.

 CenterWindow method

 The relative parameter is now case insensitive.

 DBCSConversionBar property

 Window objects can now optionally include a DBCS-SBCS conversion bar at the
 bottom of the window. See the DBCSConversionBar section in the online
 Reference for details.

 Delay property

 The Delay property of Timer objects now works for values greater than 65,535.

 Destroy event

 Previously the Destroy event was not being generated. This has been fixed. See
 the revised Destroy section in the online Reference for tips on using the
 Destroy event.

 DragFile event

 The DragFile event occurs when records are dropped onto Workplace Shell
 objects other than the printer or the OS/2 Shredder.

 DragStart event

 The DragStart event occurs whenever the user starts dragging container
 records.

 FillFromDir method

 The FillFromDir method fills a container with records based on the contents of
 a directory. The result is a container that acts like a Workplace Shell
 folder. See the FillFromDir method for more information.

 GetClipboard method

 The GetClipboard method no longer causes a syntax error if the clipboard is
 empty or contains something other than text. Instead, an empty string is
 returned.

 GetFieldData method

 The GetFieldData method now raises a REXX syntax error if passed an invalid
 field handle/name.

 GetRecordAttr method

 The GetRecordAttr method now supports a new record attribute called
 "Filename".

 GetRecordList method

    o You can now use the GetRecordList method to list records that have the
      Source attribute set to 1.

    o The method now supports the keyword SourceOrSelected for the emphasis
      parameter. The method will return records with the source emphasis or, if
      there are none, records with the selected emphasis. This keyword is
      useful when writing menu item click events in menus that are used both as
      pull-down and popup menus.

 HelpTag property

 Help file contents can now be accessed by setting the HelpTag property to
 contents or help contents.  HelpTag also supports index (or help index) and
 using (or help using) as well.

 Menu objects

 Menu objects can now be destroyed using VRDestroy.

 MenuItem objects

 Disabled menu items in popup menus are now displayed as dimmed text. Menu
 items can also now be destroyed using VRDestroy.

 Popup method

 The Popup method used to cause an access violation if the pos parameter was
 null. This has been fixed.

 SetFieldData method

 The amount of screen flicker that results from invoking the SetFieldData
 method has been reduced.

 SetRecordAttr method

    o The SetRecordAttr method now supports a new record attribute called
      "Filename".

    o The method now supports the keyword All in place of a record handle.

    o The amount of screen flicker that results from invoking this method has
      been reduced.

    o Setting the Expanded or Collapsed record attributes now expands and
      closes the record tree.

 Source property

 Containers now have a Source property. Setting this property causes the
 container to be drawn with the source emphasis.

 StartDrag method

 The StartDrag method initiates a drag operation.

 VRCreate function

 You can now use the VRCreate function to create objects on windows that were
 created from different REXX files.

 VRFileData function

 The VRFileDate function now sets the seconds part of the file time correctly.

 VRIniDir property

 The new VRIniDir function returns the directory where the OS/2 initialization
 files are stored.

 VRParseFilePath function

 Previously, the VRParseFilePath function would cause a system error if passed
 an empty string. Now it returns an empty string.

 VRSortStem function

 Previously, the VRSortStem function would fail for large arrays. It can now
 handle arrays with millions of items.


ΓòÉΓòÉΓòÉ <hidden> New or improved sample programs ΓòÉΓòÉΓòÉ

 The following sections new sample programs have been updated for version 2.0a:

 File browser        shows how to display a list of files using a container

 These samples are described in the Samples section of this document.


ΓòÉΓòÉΓòÉ 6.3. New in version 2.0 ΓòÉΓòÉΓòÉ

 What's new in version 2.0:

 New Features

 New Objects
 Direct Object Editing
 Design Environment
 Tab Editor
 OS/2 File Type Support
 File Functions
 Object Naming
 Error Detection
 Improved List Boxes
 Improved MLEs
 Improved Windows
 Picture Boxes
 Properties, events, methods
 Improved Documentation

 Q+E interface functions

 VXQE Runtime library
 VXQE Function Prototypes
 Sample Programs
 Known Problems
 Contacting Q+E

 Fixed Bugs

 Design Environment
 Runtime Environment
 Properties, events, methds


ΓòÉΓòÉΓòÉ <hidden> New Objects ΓòÉΓòÉΓòÉ

 o Container

   A container shows a view of a set of records. The view may consist of icons,
   text, or a combination of both.

    - Provides icon, name, text, detail and tree views
    - User definable columns for detail view
    - Supports drag and drop interactions with other containers and with
      Workplace Shell objects
    - Supports sorting and searching records
    - Allows records to be shared between containers

   For more information, see the Using objects chapter in the VXΓêÖREXX
   Programmer's Guide or the Container section in the VXΓêÖREXX Reference.

 o Notebook

   Notebooks present a group of windows to the user using a book metaphor. The
   notebook shows each window as page. Pages have tabs that the user can click
   on to display the page.

   Some features of notebooks include:

    - Full control over the positioning of the binding and the page tabs
    - Supports pages with major, minor, or no tabs
    - Pages can be added or removed dynamically at run time
    - Pages are loaded only as required to improve performance
    - Any VX-REXX window can be shown in a notebook

   For more information, see the Using objects chapter in the VXΓêÖREXX
   Programmer's Guide or the Notebook section in the VXΓêÖREXX Reference.

 o Popup menus

   Any Menu object can now be displayed as a pop-up menu.

   For more information, see the Creating a pop-up menu chapter in the VXΓêÖREXX
   Programmer's Guide and the Popup method section of the VXΓêÖREXX Reference.


 o Conditional cascaded menus

   Any Menu object can now be displayed as a conditional cascaded menu.

   For more information, see the Creating a conditional cascaded menu chapter
   in the PrGuide. and the DefaultItem property section in the VXΓêÖREXX
   Reference.


 o Slider

   Sliders let the user select a value from a range of values. They can also be
   used as a status bar or "thermometer" to indicate progress in a long
   operation.

   For more information, see the Using objects chapter in the VXΓêÖREXX
   Programmer's Guide and the Slider object section in the VXΓêÖREXX Reference.


 o Timer

   You can use timers to respond to the passing of time. Timers wait for some
   configurable interval, then post an event.

   For more information, see the Using objects chapter in the VXΓêÖREXX
   Programmer's Guide and the Timer object section in the VXΓêÖREXX Reference.


 o DDE Client

   With a DDE client object, your programs can communicate with DDE servers
   that are part of other applications running on your computer.

   Some features of the DDE client include:

    - Supports cold, warm, and hot links
    - Allows communication with OS/2 and Windows DDE servers

   For more information, see the Using objects chapter in the VXΓêÖREXX
   Programmer's Guide and the DDEClient section in the VXΓêÖREXX Reference.

 o ValueSet

   Value sets presents the user with a set of choices, one of which is selected
   at all timers. The items in the ValueSet are arranged in a grid. The items
   can display bitmaps, colors, icons, or text.

   For more information, see the Using objects chapter in the VXΓêÖREXX
   Programmer's Guide and the ValueSet section in the VXΓêÖREXX Reference.


ΓòÉΓòÉΓòÉ <hidden> Direct editing of objects at design time ΓòÉΓòÉΓòÉ

 You can now use direct editing techniques to change the Value or Caption
 properties of the following objects at design time:

 o check boxes
 o DDE clients
 o descriptive text
 o entry fields
 o multiline entry fields
 o push buttons
 o radio buttons
 o timers
 o windows

 For example, to change the caption on a push button, follow these steps:

  1. While holding the Alt key, click mouse button 1 on the push button.

  2. Type the new text for the button.

  3. Click mouse button 1 anywhere not on the button.


ΓòÉΓòÉΓòÉ <hidden> Easier to use design environment ΓòÉΓòÉΓòÉ

 o Accelerator keys have been added to many menu items in the design
   environment.

 o All windows in the design environment are positioned so that part of the
   title bar is visible.

 o In property notebooks, you can now change the Font property by typing in the
   entry field. You can still press the Edit button to invoke the font dialog.

 o In the menu editor, double clicking on a menu caption in the list box is
   equivalent to pressing the "Edit event" button.

 o The "OK" button in the menu editor has been renamed "Close".

 o The pop-up menu for objects now uses check marks to show which events have
   routines defined.

 o You can now position windows by clicking mouse button 2 and dragging the
   window, the same as for all other objects.

 o You can now resize windows with Thin or Dialog borders the same way as
   windows with Sizeable borders.

 o VX-REXX now indicates when it is saving or loading a project by displaying
   the appropriate text on the status bar.


ΓòÉΓòÉΓòÉ <hidden> New tab editor ΓòÉΓòÉΓòÉ

 The tab editor is now installed automatically in the design environment's
 pop-up menu. Use the tab editor to visually set the tab order of objects on a
 window.

 Initially the tab editor displays all objects on the window that have the
 TabStop property set to 1. To move an object in the tab order, follow these
 steps:

  1. Move the mouse over the object in the tab editor window.

  2. Press mouse button 2 and drag the object to the desired position in the
     list.

  3. Release mouse button 2

 To set the tab order according to the CUA guidelines, press the Auto button.
 This automatically orders objects from left-to-right and from top-to-bottom in
 the window.

 Press the OK button to accept the changes you made in the tab editor window.
 To throw away the changes, press Cancel or close the window.


ΓòÉΓòÉΓòÉ <hidden> New OS/2 file type support ΓòÉΓòÉΓòÉ

 You can now get, set, and list OS/2 file types using the new VX-REXX functions
 VRGetFileType, VRSetFileType, and VRListFileTypes.


ΓòÉΓòÉΓòÉ <hidden> Improved file functions ΓòÉΓòÉΓòÉ

 The functions related to files and directories have the following
 improvements:

 o They accept HPFS file names for files on HPFS volumes
 o File names which contain more than one period are now supported.
 o LAN Server UNC names are now supported.
 o New file name parsing function: VRParseFilePath.


ΓòÉΓòÉΓòÉ <hidden> Enhanced object naming ability ΓòÉΓòÉΓòÉ

 VX-REXX now allows you to refer to objects using the name of the object's
 parent (and grand parent). To do this, prefix the name of the object with the
 name or internal name of its parent, followed by a period.

 For example, suppose you have a window (name is "Window1", internal name is
 "?VR0001"), with a group box (name is "GB_1", internal name is "?VR0002"),
 which contains a radio button (name is "RB_1", internal name is "?VR0003").
 Any of the following expressions identify the radio button:

  RB_1
  GB_1.RB_1
  Window1.GB_1.RB_1
  ?VR0003
  ?VR0002.RB_1
  ?VR0001.GB_1.RB_1
  ?VR0001.?VR0002.RB1
  ?VR0002.?VR0003
  ?VR0001.?VR0002.?VR0003

 The rules for forming a dotted name are as follows:

 o Dotted names are processed from left to right where the parent is listed to
   the left of its child.

 o Dotted names can start with either a name or an internal name.

 o If a dotted name starts with an internal name, then there must not be any
   internal names following the first (regular) name.

 o After the last internal name (if any), the remaining names must be regular
   names (ie. no internal names).

 o Dotted names cannot start or end with a dot.

 o No spaces are allowed before or after a dot.

 This feature is useful for referencing objects on a window that you load a
 number of times. For example, suppose you have a window with the name SW_1. On
 that window is a push button called PB_1. If you load the window twice (using
 VRLoad or VRLoadSecondary), the push buttons will have the same name. To refer
 to a specific button, prefix the button's name with the internal name of the
 window. The following code loads the SW_1 window twice, then sets the captions
 on the two buttons:

  w1 = VRLoadSecondary( "SW_1" )
  w2 = VRLoadSecondary( "SW_1" )
  call VRSet w1 || "." || "PB_1", "Caption", "Button1"
  call VRSet w2 || "." || "PB_1", "Caption", "Button2"


ΓòÉΓòÉΓòÉ <hidden> Improved error detection at run time ΓòÉΓòÉΓòÉ

 Calling VRSet, VRGet, or VRMethod with an invalid object name now causes a
 syntax error. To test whether an object name is still valid, use the new
 VRIsValidObject function.

 To disable this new error detection, use the new VROptions function.


ΓòÉΓòÉΓòÉ <hidden> Improved list boxes ΓòÉΓòÉΓòÉ

 You can now associate user data with strings in a list box. The AddString
 method now takes user data for a list item as a new optional parameter.
 Similarly, AddStringList now takes an optional stem variable with an array of
 user data for the list items.

 The following new list box methods are also provided to set and retrieve list
 item user data: SetItemData, GetItemData, SetItemDataList, and
 GetItemDataList.

 Note:  These methods are documented in the online Reference only.


ΓòÉΓòÉΓòÉ <hidden> Improved multiple line entry fields ΓòÉΓòÉΓòÉ

 Multiple line entry fields (MLEs) can now hold more than 64k of data. MLEs
 also now support both raster and outline fonts. Previously, only raster fonts
 were supported.


ΓòÉΓòÉΓòÉ <hidden> Improved windows ΓòÉΓòÉΓòÉ

 If a window that is positioned off the screen is made visible, the window is
 automatically centered over its parent window.

 You can now create windows that do not have a title bar by setting the new
 TitleBar property to 0.


ΓòÉΓòÉΓòÉ <hidden> Support for icons in picture objects ΓòÉΓòÉΓòÉ

 You can now name icon resources and files using the PicturePath property. To
 reference an ICO file, set the PicturePath property to the complete file name
 of the ICO file including path. For an icon resource in a DLL, use the
 following syntax:

  $resourceID:DLLName

 where resourceID is the icon resource identifier. DLLName is the name of the
 DLL that contains the resource. You should not include any path information in
 the DLLName.


ΓòÉΓòÉΓòÉ <hidden> New or improved properties, events, methods, and functions ΓòÉΓòÉΓòÉ

 See the online Reference for more information.

 Autosize property

 Objects that have AutoSize set to 1 now resize themselves when they are
 loaded. This new behavior applies to descriptive text, DDE clients, timers,
 push buttons, radio buttons, check boxes, and entry fields.

 GetItemData method

 The GetItemData method retrieves user data for a list box item.

 GetItemDataList method

 The GetItemDataList method retrieves user data for a number of list box items.

 Popup method

 The Popup method displays a Menu object as a pop-up menu.

 SetItemData method

 The SetItemData method associates user data with a list box item.

 SetItemDataList method

 The SetItemDataList method associates user data with a number of list box
 items.

 TitleBar property

 The TitleBar property controls whether or not a window has a title bar.

 VRInfo function

 The VRInfo function now accepts the parameter Window for all events. It
 returns the internal name of the window which contains the object that caused
 the event.

 VRIsValidObject function

 The VRIsValidObject function returns 1 if a given object or PM window handle
 is still valid.

 VRParseFilePath function

 The VRParseFilePath function parses a file name without checking if the file
 exists.

 VRPrintFile function

 The VRPrintFile function prints a file.

 VRPintJobDialog function

 The VRPrintJobDialog function displays a print job dialog for a given printer.

 VRSortStem function

 The VRSortStem function sorts a REXX array.


ΓòÉΓòÉΓòÉ <hidden> Improved documentation ΓòÉΓòÉΓòÉ

 o Added chapter in the Programmer's Guide on writing programs with multiple
   threads.

 o Added chapter on writing custom modal dialogs.

 Bounce              shows how to use a timer

 DDE Explorer        shows how to find and communicate with DDE servers

 DragDrop            shows how to add drag and drop to your programs

 File browser        shows how to display a list of files using a container

 Notebook            shows how to use a notebook

 Popup               shows how to use a pop-up menu

 Printing            shows how to print a file

 Q+E Text            shows how to use VXQE and QELIB (from Q+E Software)

 RGB                 shows how to use sliders and value sets

 Update DB Sample    shows how to use VXQE and QELIB or the DB2/2 SQL interface
                     with DB2/2

 These samples are described in the Samples section of this document.


ΓòÉΓòÉΓòÉ <hidden> VXQE runtime library ΓòÉΓòÉΓòÉ

 The file VXQE.DLL is the VXQE Library for Watcom VX-REXX. This library allows
 VX-REXX applications to access the Q+E Database Library, available from Q+E
 Software. You are allowed to redistribute the library royalty free under the
 restrictions described elsewhere in this document.


ΓòÉΓòÉΓòÉ <hidden> Generating prototypes for VXQE functions ΓòÉΓòÉΓòÉ

 To generate prototypes for VXQE functions, select the Insert Code item from
 the Edit menu in the VX-REXX section editor. The list of items in the dialog
 box which is displayed contains a section called VXQE Library. Descriptions
 for all the VXQE Library functions are listed in this section. Selecting any
 of these function descriptions will produce another dialog box which will
 prompt for parameter values and then automatically insert code for the
 selected function into the section editor. For a complete description of the
 automatic code generation feature, see the VXΓêÖREXX Programmer's Guide.


ΓòÉΓòÉΓòÉ <hidden> Sample programs ΓòÉΓòÉΓòÉ

 There are two sample programs that demonstrate using the VXQE library:

 Q+E Text            The Q+E Text program displays data for selected employees.
                     It uses the VXQE library and the QELIB library (from Q+E
                     Software) to access the EMP.TXT file supplied with QELIB.
                     This sample application is the VX-REXX equivalent of the
                     example provided with QELIB.

 Update DB Sample    The Update DB Sample program uses the VXQE library and the
                     QELIB (from Q+E Software), or the DB2/2 SQL interface to
                     access IBM DB2/2. This sample is similar to the Sample
                     Database sample, except it provides greater functionality,
                     and allows the use of the Q+E interface. This application
                     allows employee records from the STAFF table of the SAMPLE
                     database to be viewed, modified, deleted and created. The
                     sample database, called SAMPLE, supplied with Database
                     Manager must be installed to run this sample. Also, to use
                     the Q+E interface, any steps required to use a QELIB
                     application with Database Manager must be performed. In
                     particular, QLEE.DLL must be bound to the SAMPLE database.
                     See the Q+E Database Library Documentation for complete
                     details.


ΓòÉΓòÉΓòÉ <hidden> Known problems ΓòÉΓòÉΓòÉ

 A time stamp error may be reported by the IBM DB2/2 application. This error
 will probably be the result of an incorrect QLEE.BND file supplied with the
 Q+E Database Library. Contact Q+E Software to obtain a correct QLEE.BND file.


ΓòÉΓòÉΓòÉ <hidden> Contacting Q+E Software ΓòÉΓòÉΓòÉ

 For more information on the Q+E Database Library (QELIB), please contact Q+E
 Software at the following addresses:

  In North America:
      Q+E Software
      5540 Centerview Drive
      Suite 324
      Raleigh, NC 27606
      USA
      [phone] (Sales)
      [phone] (Technical support)

  In Europe:
      Q+E Software Europe
      Marten Messweg 99
      Rotterdam, The Netherlands
      ([phone]


ΓòÉΓòÉΓòÉ <hidden> Design environment ΓòÉΓòÉΓòÉ

 o Previously, if you changed a section from a file that was not the current
   file, the changes would be ignored. This has been fixed.

 o Previously, if you quit the VX-REXX while the design environment was
   minimized, the design windows could be positioned in unpredictable locations
   the next time you ran VX-REXX. This bug has been fixed.

 o Previously, if you renamed an object that had event routines defined, the
   event sections might not have been renamed. The sections are now always
   renamed.

 o Previously, the debugger would not always show the last line of a section in
   a trace or source window.

 o Previously, pressing F1 when a user window was active would show the help
   text defined for the window rather than the VX-REXX help text.


ΓòÉΓòÉΓòÉ <hidden> Run time environment ΓòÉΓòÉΓòÉ

 o Menu items that are added to a menu bar are now displayed correctly.
   Previously, they were not always visible.

 o Previously, picture boxes were not painted properly if they overlapped the
   list area of a drop down combo box. They are now painted correctly.

 o Previously, in programs that were started without any command line
   arguments, the InitArgs.0 REXX variable was set to 1. It is now 0 (zero).


ΓòÉΓòÉΓòÉ <hidden> Properties, methods, events, and functions ΓòÉΓòÉΓòÉ

 Click event

 Setting the Selected property of a list box used to erroneously cause two
 Click events to be generated. Now a single event is generated.

 Enabled property

 Previously, if a window was created with Enabled set to 0, setting Enabled to
 1 later on would have no effect. Now the window is enabled correctly.

 ForeColor property

 The ForeColor property has been removed from ImagePushButton and
 ImageRadioButton objects.

 PicturePath property

 Previously, if a window had a bitmap picture as the background, and the window
 was resized, the background would not always be drawn correctly.

 VRDir function

    o The function now validates its "search" parameter. Previously, the
      debugger may have behaved unpredictably when debugging a call to VRDir
      that passed an invalid search parameter.
    o VRDir no longer raises a syntax error if parameters were omitted.

 VRMessage function

 Fixed VRMessage to take into account the length of the title when setting size
 of dialog. Also made minimum width of dialog be 120 pixels. (Max width is 3/4
 of screen width.) The function is now faster.

 VRParseFileName function

 Previously, the function would not correctly parse names ending in a
 backslash.

 VRRedirectStdio function

 This function now restores the original standard I/O streams when redirection
 is turned off. This fixes the problem of sometimes not being able to close
 streams after turning redirection off.

 File functions

 All file and directory related functions allow file names that contain more
 than one period. In previous versions of VX-REXX, these types of names were
 not allowed.


ΓòÉΓòÉΓòÉ 6.4. New in version 1.01 ΓòÉΓòÉΓòÉ

 What's new in version 1.01:

 Development Environment

 Drag and Drop
 Macros
 Swipe Selection
 Status Line
 Tool Palette
 Event Routine Access
 Code Section Editor
 Default Editor

 New Runtime Features

 SpinButton Object
 Enhanced Keyboard Support
 Other Application Windows
 Clipboard support
 STDIO Redirection
 Source Code Encoding
 Error Handling
 Debugger Menus
 Personal REXX v3.0a Support

 Properties, Events, Methods

 AddStringList Method
 AdjustHeight Property
 Change Event
 ExtendedSelect Property
 HWnd Property
 Justification Property
 LayoutStyle Property
 ListChildren Method
 ListClasses Method
 Maximize Method
 Minimize Method
 MLE Object
 Painting Property
 Pointer Property
 PostQueue Method
 Restore Method
 StatusArea
 SupportsMethod Method
 SupportsProperty Method
 TabGroup Property
 VertJustification Property


ΓòÉΓòÉΓòÉ <hidden> Drag and drop programming ΓòÉΓòÉΓòÉ

 VX-REXX has a new facility to make programming faster and easier. All REXX
 functions, all of VX-REXX's built in functions, as well as all object methods
 and properties can be used without having to write a single line of code. All
 you have to do to start the process is drag an object onto a section editor
 window.

 Suppose you have a window with a list box and a push button. You want to add a
 string to the list every time the push button is clicked.

  1. Open a VX-REXX section editor for the push button's Click event.

  2. Position the insertion cursor in the section editor window at the point
     where you want the code to be inserted.

  3. Drag the list box onto the section editor window.

     When the pointer is over an editor window, VX-REXX draws a line linking
     the object to the window to indicate that it will generate code, instead
     of moving the object. When you release the mouse button, VX-REXX displays
     a list of actions you can perform on the list box.

  4. Select Add a string from the list

     VX-REXX will prompt you for the parameters to the AddString method.

  5. Type the text you want to add to the list in the String entry field.

  6. Click OK.

 VX-REXX will add a line at the insertion point similar to the following:

  position = VRMethod( "LB_1", "AddString", "Pressed" )


 Inserting code without drag and drop

 You can also use this facility directly from the Insert code menu item in the
 section editor's Edit menu.  This allows you to generate code for an object
 without dragging and dropping it, and to generate non-object specific code
 such as calls to standard REXX functions.

 To insert code in a section editor:

  1. Open a section editor.

  2. Position the insertion cursor in the section editor window at the point
     where you want the code to be inserted.

  3. Select Insert code from either the Edit menu or the (new) pop-up menu
     (click on the section editor window with mouse button 2).

     VX-REXX will show a list of objects and tasks for which it can generate
     REXX code.

  4. Pick an action, then fill in the dialog as described above to generate the
     code.


 Inserting code into external editors

 Drag and drop code generation does not work for editors other than the VX-REXX
 section editor. However you can configure VX-REXX so you can insert code into
 the OS/2 clipboard from where it can be pasted into any editor. The macros
 GenCodeO.VRM and GenCodeG.VRM in the Macros folder are used to enable this
 feature. Their use is explained in the Profile.VRM file, also contained in the
 Macro folder.

 It is also possible to directly invoke the insert code dialogs from a
 PM-hosted, REXX-aware editor. The files in the EPMProto directory in the
 Macros folder are provided to show how an insert code command can be added to
 the OS/2 Enhanced Editor (EPM). See the file EPMProto.TXT in the EPMProto
 directory for more information.


ΓòÉΓòÉΓòÉ <hidden> Macros in the development environment ΓòÉΓòÉΓòÉ

 You can now tailor the VX-REXX development environment by creating custom
 commands as VX-REXX macros. This allows you to add new features to VX-REXX!

 You create the macros using VX-REXX, just as you would for any other
 PM-hosted, REXX-aware application. You create a project, then choose Make
 macro from the Project menu. You add the macro to the development environment
 by adding a line to the Profile.VRM file located in the Macros folder. Macro
 commands added to VX-REXX appear as extra menu items in the VX-REXX pop-up
 menu -- either on all objects or only on selected objects.

 The following macros, along with their source projects, are included with
 VX-REXX:

 o Tab editor macro

   The tab editor macro provides a fast and easy way to set the tab order for
   all of the objects on a window.

 o Set properties macro

   The set properties macro can be used instead of property notebooks to view
   or set an object's properties. It makes it easier to edit all of the
   properties of a single object, or to set the same property on a number of
   objects.

 o Resize macro

   The resize macro forces a number of objects to the same size. A typical use
   is to force a number of push buttons to the same size.

 o Object list macro

   This macro lists all objects on a window. You can select objects from the
   list and open their property notebooks. This makes it possible to find
   objects that are behind other objects or beyond the border of the window.

 Details on how to create and install macros are provided in the Profile.VRM
 and the Macros.TXT files in the Macros directory.


ΓòÉΓòÉΓòÉ <hidden> Swipe selection now supported ΓòÉΓòÉΓòÉ

 If you press mouse button 1 while the pointer is not over an object, you get a
 marquee selection with a bounding rectangle. All selection in version 1.00 was
 done this way.

 If you press mouse button 1 while over an object, you start a swipe selection.
 As long as you hold mouse button 1 down, you will select any object the
 pointer passes over.


ΓòÉΓòÉΓòÉ <hidden> New status line ΓòÉΓòÉΓòÉ

 A status bar has been added to VX-REXX to give the name and class of the
 object that is currently under the pointer. You can disable the feature by
 unchecking the Show Hints menu item in the Options menu.


ΓòÉΓòÉΓòÉ <hidden> Resizable tool palette ΓòÉΓòÉΓòÉ

 You can now resize the tool palette. Its size and position is saved along with
 the size and position of the other VX-REXX windows when you save a project.


ΓòÉΓòÉΓòÉ <hidden> Quicker access to event routines ΓòÉΓòÉΓòÉ

 There is a new item in the VX-REXX object popup menu which lists all of the
 events for the object. This is a short cut for opening the object's property
 notebook, selecting the Events page, and clicking on the event.


ΓòÉΓòÉΓòÉ <hidden> New popup menu in code section editor ΓòÉΓòÉΓòÉ

 Clicking on a code section editor with mouse button 2 now displays a popup
 version of the Edit menu. This speeds up access to common commands such as
 cut, copy, and paste.


ΓòÉΓòÉΓòÉ <hidden> Set the default editor to an external editor ΓòÉΓòÉΓòÉ

 You can now configure VX-REXX to use an external editor as the default editor.
 To do this, set the check box in the external editor configuration dialog.


ΓòÉΓòÉΓòÉ <hidden> New SpinButton object ΓòÉΓòÉΓòÉ

 An additional object, the spin button, has been added. A spin button allows a
 user to enter a value or select a value from a list. Only a single value from
 the list is displayed; the user can change the displayed value by clicking on
 up and down buttons.

 You can set the list in a spin button either at design time or run time, and
 you can specify the list as either an enumerated set of values or as a range
 of values with a specified increment.

 See the Using objects section in the online Programmer's Guide and SpinButton
 object in the Reference for more information.


ΓòÉΓòÉΓòÉ <hidden> Enhanced keyboard support ΓòÉΓòÉΓòÉ

 o Accelerators

   VX-REXX menus can now have accelerator or short-cut keys. Accelerator keys
   allow your users to execute menu commands without opening a menu. See the
   online Reference under the Accelerator property or InstallAccelerator method
   for a full description.

 o Mnemonics

   Mnemonics are now supported for all options with captions. Mnemonics allow
   your users to activate objects without using a mouse. See the Caption
   property in the online Reference for more information.

 o Keystroke trapping

   Programs can now trap and modify keystrokes. This allows you to change the
   behavior of objects, for example convert text in an entry field to uppercase
   as it is entered. See the KeyPress event or KeyString property in the
   Reference documentation  for a full description of this new feature.


ΓòÉΓòÉΓòÉ <hidden> Manipulate windows belonging to other applications ΓòÉΓòÉΓòÉ

 Using the new ListWindows method you can list all of the top level windows in
 the system. Then you can use the VRGet, VRSet, and VRMethod functions to
 interact with these windows. The windows appear to the program as VX-REXX
 objects which support a limited number of properties and methods.

 You can also post or send keystrokes to PM windows using the new PostKeyString
 and SendKeyString methods.

 See the ListWindows method, HWnd property, PostKeyString method, and
 SendKeyString method in the Reference for complete information.


ΓòÉΓòÉΓòÉ <hidden> Clipboard support ΓòÉΓòÉΓòÉ

 You can use two new methods on the Application object to read and write text
 from/to the OS/2 clipboard. See the PutClipboard and GetClipboard methods in
 the online documentation for more information.


ΓòÉΓòÉΓòÉ <hidden> Improved control over STDIO redirection ΓòÉΓòÉΓòÉ

 The VRRedirectSTDIO function now lets you enable and disable standard I/O
 redirection and logging under program control.


ΓòÉΓòÉΓòÉ <hidden> Source code encoding in EXE files ΓòÉΓòÉΓòÉ

 VX-REXX now encodes your REXX source code when it makes EXE files. This means
 that you can distribute your programs and keep your source secure.


ΓòÉΓòÉΓòÉ <hidden> Improved error handling in VX-REXX generated macros ΓòÉΓòÉΓòÉ

 When you make macros, VX-REXX now automatically generates code to trap syntax
 errors. The code displays an error message, then exits the macro. If you have
 your own syntax error handler, it will override the automatically generated
 one.


ΓòÉΓòÉΓòÉ <hidden> File menu removed from the debugger ΓòÉΓòÉΓòÉ

 The debugger section list window no longer contains a File menu with a single
 Quit item. It was removed to improve the conformance of VX-REXX to the CUA '91
 object model. Now just close the section list window to quit the debugger and
 return to the design environment.


ΓòÉΓòÉΓòÉ <hidden> Support for Personal REXX version 3.0a ΓòÉΓòÉΓòÉ

 VX-REXX now works with Quercus System's Personal REXX version 3.0a.


ΓòÉΓòÉΓòÉ <hidden> AddStringList method ΓòÉΓòÉΓòÉ

 This method now disables list box repainting while adding strings to the list,
 speeding up the operation.


ΓòÉΓòÉΓòÉ <hidden> AdjustHeight property ΓòÉΓòÉΓòÉ

 This ListBox property forces the list box to adjust its height to an integral
 number of lines.


ΓòÉΓòÉΓòÉ <hidden> Change event ΓòÉΓòÉΓòÉ

 Objects containing an entry field now support a Change event which is
 triggered whenever the contents of the field have changed.


ΓòÉΓòÉΓòÉ <hidden> ExtendedSelect property ΓòÉΓòÉΓòÉ

 List boxes now support two styles of multiple selection, extended (items are
 selected in ranges) and non-extended (items are selected one at a time).


ΓòÉΓòÉΓòÉ <hidden> HWnd property ΓòÉΓòÉΓòÉ

 All visible objects now have an HWnd property which gives the value of the PM
 handle to the outer window of the object.


ΓòÉΓòÉΓòÉ <hidden> Justification property ΓòÉΓòÉΓòÉ

 DescriptiveText and EntryField objects have a new Justification property,
 which can be Left, Right, or Center.


ΓòÉΓòÉΓòÉ <hidden> LayoutStyle property ΓòÉΓòÉΓòÉ

 The layout style controls how a window arranges the objects it contains. You
 can use this property to make windows that automatically resize their
 children.


ΓòÉΓòÉΓòÉ <hidden> ListChildren method ΓòÉΓòÉΓòÉ

 This method lists the children of a given object.


ΓòÉΓòÉΓòÉ <hidden> ListClasses method ΓòÉΓòÉΓòÉ

 Use this method to list the classes of objects in a DLL or in the current
 program.


ΓòÉΓòÉΓòÉ <hidden> Maximize method ΓòÉΓòÉΓòÉ

 This new window method causes a window to be maximized.


ΓòÉΓòÉΓòÉ <hidden> Minimize method ΓòÉΓòÉΓòÉ

 This new window method minimizes a window.


ΓòÉΓòÉΓòÉ <hidden> MultiLineEntryField object ΓòÉΓòÉΓòÉ

 Multiline entry fields now support the DoubleClick event.


ΓòÉΓòÉΓòÉ <hidden> Painting property ΓòÉΓòÉΓòÉ

 This new property has been added to all visible objects and can be used to
 suppress painting of an object or group of objects during an update.


ΓòÉΓòÉΓòÉ <hidden> Pointer property ΓòÉΓòÉΓòÉ

 Use this property to set the pointer to an hourglass or other shape during
 long calculations.


ΓòÉΓòÉΓòÉ <hidden> PostQueue method ΓòÉΓòÉΓòÉ

 This method is the same as the Post method except that it allows you to
 specify which window queue (i.e. which primary window) should receive the
 posted event. This ensures that the event is not simply delivered to the
 currently active window.


ΓòÉΓòÉΓòÉ <hidden> Restore method ΓòÉΓòÉΓòÉ

 This window method restores a minimized or maximized window to its previous
 size and position.


ΓòÉΓòÉΓòÉ <hidden> StatusArea ΓòÉΓòÉΓòÉ

 The status area on windows now has a sporty 3D look.


ΓòÉΓòÉΓòÉ <hidden> SupportsMethod method ΓòÉΓòÉΓòÉ

 This method determines if a given method is available for a specified object
 or type of object.


ΓòÉΓòÉΓòÉ <hidden> SupportsProperty methods ΓòÉΓòÉΓòÉ

 This method determines if a given property is available for a specified object
 or type of object.


ΓòÉΓòÉΓòÉ <hidden> TabGroup property ΓòÉΓòÉΓòÉ

 This property has been added to all objects with the TabStop property. This
 property is used to group objects into tab groups without using group boxes.
 The user can move from object to object within a tab group by using either the
 tab or cursor keys, but can only switch between tab groups by using the tab
 key.


ΓòÉΓòÉΓòÉ <hidden> VertJustification property ΓòÉΓòÉΓòÉ

 DescriptiveText objects have a new VertJustification property, which can be
 Top, Bottom, or Center. You must set this property at design time; it is read
 only at run time.


ΓòÉΓòÉΓòÉ 7. Contacting Watcom ΓòÉΓòÉΓòÉ

 How to Contact Watcom

 In North America (and all other non-European locations)

 Watcom International Corporation. 415 Phillip Street, Waterloo, Ontario,
 CANADA, N2L 3X2

  General Inquiries    Sales                             Technical Support
  tel: [phone]   Upgrades, other product orders,   hot-line: [phone]
  fax: [phone]   and reseller inquiries/orders:    fax:      [phone]
                       1-800-265-4555 (toll free in      BBS:      [phone]
                       North America)                    Internet: [e-mail]
                                                         Compuserve: type GO WATCOM

 Watfax

 Technical support and product information is available 24 hours a day using
 our Watfax system. To reach Watfax, call 1-519-747-2693 from your touch-tone
 fax phone.

 In Europe

 Watcom Europe Limited. PO Box 64, Livingston, West Lothian, EH54 7AE, UNITED
 KINGDOM

  General Inquiries      Sales                             Technical Support
  United Kingdom         Upgrades, other product orders,   United Kingdom
  tel: [phone]       and reseller inquiries/orders:    tel: [phone]
  fax: [phone]                                         fax: [phone]
                         United Kingdom Toll Free
  Other Locations        tel: [phone]                Other Locations
  tel: [phone]   fax: [phone]                tel: [phone]
  fax: [phone]                                     fax: [phone]
                         Germany Toll Free
                         tel: [phone]                BBS: [phone]
                         fax: [phone]                Internet: [e-mail]
                                                           Compuserve: type GO WATCOM
                         France Toll Free
                         tel: [phone]
                         fax: [phone]

                         All Other Locations
                         tel: [phone]
                         fax: [phone]


ΓòÉΓòÉΓòÉ 8. Notices ΓòÉΓòÉΓòÉ

 Topics

 Copyright
 Disclaimer
 Trademarks


ΓòÉΓòÉΓòÉ <hidden> Copyright ΓòÉΓòÉΓòÉ

 Copyright 1993, 1994 by Watcom International Corporation All rights reserved.
 No part of this publication may be reproduced or used in any form or by any
 means -- graphic, electronic, or mechanical, including photocopying,
 recording, taping or information storage and retrieval systems -- without
 written permission of the Watcom International Corporation.


ΓòÉΓòÉΓòÉ <hidden> Disclaimer ΓòÉΓòÉΓòÉ

 Watcom (Watcom International Corporation and all of its subsidiaries)  makes
 no representation or warranty with respect to the adequacy of this
 documentation or the programs which it describes for any particular purpose or
 with respect to its adequacy to produce any particular result. In no event
 shall Watcom, its employees, its contractors or the authors of this
 documentation be liable for special, direct, indirect or consequential
 damages, losses, costs, charges, claims, demands or claim for lost profits,
 fees or expenses of any nature or kind.


ΓòÉΓòÉΓòÉ <hidden> Trademarks ΓòÉΓòÉΓòÉ

 Watcom and VX-REXX are trademarks of Watcom International Corporation.

 IBM, OS/2, Extended Services, Extended Services for OS/2, Database 2, DB2/2,
 Multimedia Presentation Manager/2, and MMPM/2 are trademarks of the IBM
 Corporation.

 Q+E is a trademark of Q+E Software.