OS/2 Shareware BBS: 30 fixes_v/30-fixes_v.zip/vx101b.zip/README.INF

OS/2 Help File | 1993-11-26 | 78KB | 2,424 lines

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


ΓòÉΓòÉΓòÉ 1.1. Package contents ΓòÉΓòÉΓòÉ

We are pleased to forward the enclosed WATCOM VXΓêÖREXX for OS/2 (version 2.0 or
higher). The package contains the components detailed in the following
subsections. We recommend that you take time now to identify each of the
components described.


ΓòÉΓòÉΓòÉ 1.1.1. Documentation ΓòÉΓòÉΓòÉ

o Read Me First (this document)

  The Read Me First contains the system requirements, installation
  instructions, notes on the sample programs included with VX-REXX, release
  information, a new feature summary, and corrections for the printed version
  of the manual.

o WATCOM VXΓêÖREXX for OS/2 Programmer's Guide and Reference

After reading this Read Me First, you should proceed to the WATCOM VXΓêÖREXX
Programmer's Guide and Reference. It describes all of the components of the
VXΓêÖREXX development system and includes a brief tutorial that introduces the
steps in creating a VXΓêÖREXX program.

The Read Me First and the WATCOM VXΓêÖREXX Programmer's Guide and Reference are
also supplied as online books. We strongly recommend that you use the online
books because, in addition to being very convenient, the online books contain
the most up to date information. The features new in version 1.01 are only
documented in the online books.


ΓòÉΓòÉΓòÉ 1.1.2. Diskettes ΓòÉΓòÉΓòÉ

o The package contains two 3.5" diskettes (1.44M).

In addition to the WATCOM VXΓêÖREXX development system, sample programs are
included which demonstrate some of the features of VXΓêÖREXX. These programs are
added to the WATCOM VXΓêÖREXX folder when the software is installed. The sample
programs are described later in this document.


ΓòÉΓòÉΓòÉ 1.2. Send in Your Registration Card ΓòÉΓòÉΓòÉ

You should fill out and mail your registration card as soon as possible to
ensure you are informed of future upgrades and other special offers to
registered users. You must write the product registration number on this card
in the appropriate box. Your registration number is printed on the label of the
diskette. Your registration number will be required when you contact WATCOM
Technical Support.

Note:  Registered users of version 1.01 will be eligible for a free upgrade to
version 2.00 when it becomes available. Version 2.00 will include four
additional objects: Container, Notebook, Slider, and ValueSet.


ΓòÉΓòÉΓòÉ 1.3. System requirements ΓòÉΓòÉΓòÉ

The minimum recommended configuration for WATCOM VXΓêÖREXX is a 20 megahertz 386
personal computer with 8 megabytes of memory. About 5 megabytes of hard disk
space are required to install the software.

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 required is IBM number
XR06055. You can obtain it from the IBM OS/2 BBS, from CompuServe, or directly
from IBM. Contact your IBM representative for more information.

The OS/2 REXX interpreter and the REXX information must also be installed prior
to installing VXΓêÖREXX. If you do not have OS/2 REXX installed, you can add it
now by using the OS/2 Selective Install utility as described in the next
section. (If REXX is installed on your system your \OS2\DLL directory will
contain four REXX files: REXX.DLL, REXXAPI.DLL, REXXUTIL.DLL, and REXXINIT.DLL.
Also your Information folder should contain a REXX Information icon.)

 In addition to using the OS/2 REXX interpreter, VXΓêÖREXX is configured to make
use of the OS/2 Enhanced Editor. Although it is not required, you may wish to
install the Enhanced Editor to make sure that you have access to all of
VXΓêÖREXX's features. Instructions for installing the Enhanced Editor are
included in the next section.


ΓòÉΓòÉΓòÉ 1.3.1. Installing OS/2 system components ΓòÉΓòÉΓòÉ

If you do not have the OS/2 REXX interpreter installed on your system, or you
wish to install the REXX online information or the OS/2 Enhanced Editor, you
must install them using the Selective Install utility before installing
VXΓêÖREXX. You will need the OS/2 installation diskettes to complete the
following procedure.

 1. Open the OS/2 System folder.

 2. Open the System Setup folder.

 3. Open the Selective Install program.

 4. Click on OK in the System Configuration window.

 5. If you need to install the OS/2 REXX interpreter, click on the REXX
    checkbox.

 6. If you wish to install the REXX online information,  click on the
    Documentation checkbox. Then click on the corresponding More button to open
    the Documentation window. Make sure REXX Information is checked, then click
    on OK. If other check boxes are checked, you can uncheck them by clicking
    on their respective check boxes.

 7. If you wish to install the OS/2 Enhanced Editor, click on the Tools and
    Games check box. Then click on the corresponding More button to open the
    Tools and Games window. Make sure that the Enhanced Editor check box is
    checked, then click on OK. If other check boxes are checked, you can
    uncheck them by clicking on their respective check boxes.

 8. Click on Install to start the installation. You will be instructed by the
    Selective Install program after this point.


ΓòÉΓòÉΓòÉ 2. Installation ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 2.1. Installation procedure for WATCOM VXΓêÖREXX ΓòÉΓòÉΓòÉ

The software installation procedure creates a working copy of the WATCOM
VXΓêÖREXX software on your hard disk. There is a setup program on the first
diskette that makes the installation easy and straightforward. The installation
program will create a directory on the hard disk and copy and decompress the
software from the diskettes to the destination disk. Depending on the speed of
your computer, the installation procedure can take up to 6 minutes.


ΓòÉΓòÉΓòÉ 2.2. Running the installation program ΓòÉΓòÉΓòÉ

The first VXΓêÖREXX diskette contains a program called SETUP.EXE which installs
the software.

By default, the software will be installed from the A diskette drive into the
directory \VXREXX on the hard disk with the OS/2 system installed, but you can
change these values. Note that the rest of this document assumes that the
VXΓêÖREXX directory is C:\VXREXX. If you choose another drive or directory, then
substitute your chosen install location for C:\VXREXX in the instructions that
follow.

The software takes up approximately 5 megabytes of disk space. The installation
program will ensure that there is enough free disk space before starting the
actual installation. If there is insufficient free space, you will have to
delete some files from your disk and restart the installation.

If you already have a version of VX-REXX installed on your machine you must
ensure that it is not in use before installing the new version. You must ensure
that you are running neither VX-REXX nor a VX-REXX program or macro.

If you are upgrading VX-REXX we strongly recommend that you install the new
version of VX-REXX in the same directory as the previous version. The
installation will upgrade all the VX-REXX files but will leave the Projects
directory and any projects it contains intact.

Note:  Only one version of VX-REXX can be running at one time. This includes
either VX-REXX itself or any VX-REXX program or macro. However, all VX-REXX
programs and macros created with earlier versions of VX-REXX will run with the
current version without change. It is not necessary to regenerate either EXE or
macro files.

To install VX-REXX:

 1. Open the OS/2 System folder.

 2. Open the Command Prompts folder.

 3. Open an OS/2 Window.

 4. Insert the first WATCOM VXΓêÖREXX diskette in a diskette drive (e.g. the A
    drive).

 5. From the OS/2 command line, type: a:\setup.

You will be asked for the drive and directory in which you want to install
VXΓêÖREXX. You can change the default values to any valid drive and directory.
The directory will be created when the software is installed. You will also be
prompted for the location of the install diskettes. The default value will be
the diskette from which you started the install. Normally you should just
accept the default.

After you have completed these dialogs, the setup program will decompress the
software and copy it to the hard disk. Part way through the installation, you
will be asked to insert disk two. Remove the first diskette from the drive, and
insert the second VXΓêÖREXX diskette. Select OK on the prompt dialog to continue
the installation. When the files have been copied, you will be asked if you
want your CONFIG.SYS updated. If you select this option, your CONFIG.SYS file
will be copied to CONFIG.BAK and then it will be updated so that the PATH,
LIBPATH, HELP and BOOKSHELF variables include the VXΓêÖREXX directory. It will
also create a VXREXX variable set to the VXΓêÖREXX directory. Note that you must
shutdown and restart OS/2 for changes to your CONFIG.SYS file to take effect.

VXΓêÖREXX will not function properly unless you update your CONFIG.SYS. You must
update your CONFIG.SYS yourself if you do not let the install program do it.
Adding the VXΓêÖREXX directory to the PATH allows you to start VXΓêÖREXX from an
OS/2 command line. The LIBPATH must be updated to run the executable and macro
files generated by VXΓêÖREXX. The HELP and BOOKSHELF variables must be updated to
access the VXΓêÖREXX context sensitive help.

When the installation is complete, you will be asked if you want to view the
Read Me First information. The information displayed is the information from
this Read Me First booklet, plus any information added after this booklet was
printed. (Any extra information will be in a chapter entitled Latest Updates).

You will then be returned to the OS/2 command line. Type exit to close the OS/2
window.

A WATCOM VXΓêÖREXX icon will be displayed on your desktop. Open the folder to
view the VXΓêÖREXX components.


ΓòÉΓòÉΓòÉ 2.3. WATCOM VXΓêÖREXX folder contents ΓòÉΓòÉΓòÉ

After WATCOM VXΓêÖREXX has been successfully installed on a hard disk, the
VXΓêÖREXX folder will contain several icons. This section describes each of the
icons.

Note that the WATCOM VXΓêÖREXX folder on your desktop only contains objects that
reference files in the VXΓêÖREXX directory. Deleting or moving this folder does
not delete or move the VXΓêÖREXX directory. If you accidentally delete the WATCOM
VXΓêÖREXX folder, you can rebuild it with the BUILDVRX command which is described
later.


ΓòÉΓòÉΓòÉ 2.3.1. VXΓêÖREXX ΓòÉΓòÉΓòÉ

You can use the VXΓêÖREXX icon to open the VXΓêÖREXX development environment,
although usually you will open VXΓêÖREXX by opening a VXΓêÖREXX Project object. See
the section on  the Projects folder for more information.


ΓòÉΓòÉΓòÉ 2.3.2. Read Me First ΓòÉΓòÉΓòÉ

Read Me First is an online version of this Read Me First booklet, with four
additional sections: Tips, Restrictions, Fixes in version 1.01, and Latest
updates. The Latest updates section will contain any information released too
late to be put in this document.


ΓòÉΓòÉΓòÉ 2.3.3. Programmer's Guide ΓòÉΓòÉΓòÉ

Programmer's Guide is an online copy of the Programmer's Guide section of the
WATCOM VXΓêÖREXX for OS/2 Programmer's Guide and Reference. You can read this
documentation to learn how to use VXΓêÖREXX and create VXΓêÖREXX applications. You
can also use the chapter A simple program as an online tutorial, actually
building the program in the VXΓêÖREXX development environment as you read through
the chapter.

You should work through the tutorial before trying to create your own project.
It shows you how to examine the code and how to run a VXΓêÖREXX program. If you
need more information, the techniques outlined in the tutorial are expanded in
the first four chapters of the Programmer's Guide.

The online Programmer's Guide contains new information for version 1.01. The
chapter A simple program has been updated to use drag and drop programming.
The chapter Using objects includes a section on using the new SpinButton
control.


ΓòÉΓòÉΓòÉ 2.3.4. Reference ΓòÉΓòÉΓòÉ

Reference is an online copy of the Reference section of the WATCOM VXΓêÖREXX for
OS/2 Programmer's Guide and Reference. Use this documentation to get detailed
information on any component  of the VXΓêÖREXX development system.

The online Reference contains new information for version 1.01. It includes the
new SpinButton control, as well as up to date information for all of the new
version 1.01 features.


ΓòÉΓòÉΓòÉ 2.3.5. REXX Information ΓòÉΓòÉΓòÉ

REXX Information points to the online REXX language documentation which is
contained in the OS/2 Information folder. You can browse this information to
learn about the REXX language and the OS/2 REXX interpreter.


ΓòÉΓòÉΓòÉ 2.3.6. Samples ΓòÉΓòÉΓòÉ

This folder contains icons for the VXΓêÖREXX sample programs: Button, Calc,
HintHelp, MindGame, Movies, MMW, SampleDB, Scan, Threads, and WinCtrl. These
icons are shadows of directories in the VXΓêÖREXX directory.

Each of the samples is a folder which contain the source files for the project,
as well as an icon to run the program, and a folder called BIN. This folder
contains the executable and macro versions (if any) of the program.

To run these sample programs, the LIBPATH and HELP environment variables must
include the VXΓêÖREXX directory.

The sample programs are described in the next chapter.


ΓòÉΓòÉΓòÉ 2.3.7. Projects ΓòÉΓòÉΓòÉ

The Projects folder contains the VXΓêÖREXX Project template. You use this
template to create new VXΓêÖREXX projects. Simply drag the template to the folder
in which you want to store the new project files. Open the VXΓêÖREXX Project
folder that is created, and open the  Project.VRP file to start VXΓêÖREXX with
the new project.

The Projects folder is a shadow of the directory of the same name in the
VXΓêÖREXX directory. You can use this folder to safely store your projects as
they will remain intact even if the WATCOM VXΓêÖREXX folder is accidentally
deleted.


ΓòÉΓòÉΓòÉ 2.3.8. Macros ΓòÉΓòÉΓòÉ

The Macros folder contains sample VX-REXX design-time macros, and information
on developing you own macros. VX-REXX design-time macros allow you to customize
the design environment by adding new commands to the VX-REXX pop-up menu.

Four sample macros are provided: SetTabs (set the tab order), SetProps (another
way to set properties), Resize (force objects to the same size), and ObjList
(list all objects on a window). The source for these macros is included so you
can modify and adapt them to suit your own needs.

Information on the sample macros and the installation instructions is included
in the Profile.VRM file located in the Macros folder. Details on writing your
own macros are contained in the Macros.TXT file also located in the Macros
folder.

The Macros folder is a shadow of the directory of the same name in the VXΓêÖREXX
directory. You can use this folder to safely store your macros as they will
remain intact even if the WATCOM VXΓêÖREXX folder is accidentally deleted.


ΓòÉΓòÉΓòÉ 2.3.9. Color Palette ΓòÉΓòÉΓòÉ

The VXΓêÖREXX installation program creates a color palette Workplace Shell object
in the VXΓêÖREXX folder. You can use the palette to drag and drop colors onto
VXΓêÖREXX objects as an alternative to setting colors using a property notebook.


ΓòÉΓòÉΓòÉ 2.3.10. Font Palette ΓòÉΓòÉΓòÉ

The VXΓêÖREXX installation program creates a font palette Workplace Shell object
in the VXΓêÖREXX folder. You can use the palette to drag and drop fonts onto
VXΓêÖREXX objects as an alternative to setting fonts using a property notebook.


ΓòÉΓòÉΓòÉ 2.4. WATCOM VXΓêÖREXX directory contents ΓòÉΓòÉΓòÉ

In addition to the files and directories comprising the VX-REXX design
environment, the VXΓêÖREXX directory contains the following files.


ΓòÉΓòÉΓòÉ 2.4.1. BUILDVRX.CMD ΓòÉΓòÉΓòÉ

This REXX script rebuilds the Workplace Shell objects for VXΓêÖREXX. If you
accidentally delete your WATCOM VXΓêÖREXX folder, or if your desktop becomes
corrupted, you can run this command file from an OS/2 Window.


ΓòÉΓòÉΓòÉ 2.4.2. BPATCH.EXE ΓòÉΓòÉΓòÉ

The WATCOM Patch Utility can be used to apply patches or bug fixes to VXΓêÖREXX.
As problems are reported and fixed, registered users of VXΓêÖREXX will be
notified of patches that they can apply to resolve these problems.


ΓòÉΓòÉΓòÉ 2.5. Run time library ΓòÉΓòÉΓòÉ

The executable (EXE) and macro files built with VXΓêÖREXX require the run time
library VROBJ.DLL to run. The OS/2 LIBPATH variable must include the directory
that contains VROBJ.DLL. The LIBPATH variable is defined in the OS/2 CONFIG.SYS
file. Note that you must reboot OS/2 before any changes to the LIBPATH will
take effect.


ΓòÉΓòÉΓòÉ 2.5.1. Additional redistribution rights ΓòÉΓòÉΓòÉ

Subject to the terms and conditions of the WATCOM Software License Agreement,
in addition to any Redistribution Rights granted therein, you are hereby
granted a non-exclusive, royalty-free right to reproduce and distribute the
file VROBJ.DLL located in the VXΓêÖREXX directory provided that (a) it is
distributed as part of and only with your software product; (b) you not
suppress, alter or remove proprietary rights notices contained therein; and (c)
you indemnify, hold harmless and defend WATCOM and its suppliers from and
against any claims or lawsuits, including attorney's fees, that arise or result
from the use or distribution of your software product.


ΓòÉΓòÉΓòÉ 3. Sample programs ΓòÉΓòÉΓòÉ

Each of the following sections describes one of the sample programs included
with VXΓêÖREXX. The files for these programs are located in the Samples
directory, which is in the VXΓêÖREXX directory. The WATCOM VXΓêÖREXX folder
contains a shadow of the Samples directory.


ΓòÉΓòÉΓòÉ 3.1. Button ΓòÉΓòÉΓòÉ

The Button program displays four push buttons with the  caption "Push Me!".
When you run this program and click on any of the buttons, the button's color
and caption changes to Red. When it is clicked again, the color and caption
changes to Yellow. If you continue to click on a button, it will alternate
between red and yellow.

The program is similar to the one developed in the tutorial chapter A Simple
Program in the Programmer's Guide. It demonstrates the two VXΓêÖREXX functions
that you use to access object properties at run time.

To run the program, double click on the Button icon. To edit the project,
double click on the Button.VRP icon.


ΓòÉΓòÉΓòÉ 3.2. Calc ΓòÉΓòÉΓòÉ

Calc is a simple calculator program. It does addition, subtraction,
multiplication, division, and percentages. The buttons CE and C clear the
current entry and the current calculation, respectively. Memory buttons are
provided to save (M+ and M-), recall (MR) and clear (MC) calculations.

The program illustrates using general routines for code that is used by many
objects and shows how to pass arguments to a REXX routine.

The calculator sample also demonstrates the use of the KeyPress event and
KeyString property. Instead of using the mouse to click on the calculator
buttons you can just type the calculator operations on the keyboard. The C
button is accessed using the letter C on the keyboard, the CE button through
the letter E on the keyboard, and the memory functions by pressing F5-F8 on the
keyboard for M+, M-, MR, and MC  respectively.

To run this program, double click on the Calculator icon in the Calc folder. To
edit the project, double click on the Calc.VRP icon.


ΓòÉΓòÉΓòÉ 3.3. HintHelp ΓòÉΓòÉΓòÉ

The HintHelp sample program demonstrates the use of hints and context sensitive
help in VXΓêÖREXX projects. When the program is running, move the pointer over
each of the objects in the window to view the hints for each. The hints appear
in the status area in the bottom of the window. Press the F1 key to open a help
window.

To run this program, double click on the Hint and Help icon in the HintHelp
folder. To edit the project, double click on the HintHelp.VRP icon.


ΓòÉΓòÉΓòÉ 3.4. MindGame ΓòÉΓòÉΓòÉ

MindGame is a game in which you must guess the colors of four buttons in ten
guesses or less. When it is run, the buttons for the first guess are located
above the horizontal bar at the bottom left hand corner of the window. To
begin, choose a color from the color palette at the top right hand corner of
the window. The currently selected color is shown in the large colored button
to the right the color palette. When you have chosen a color, click on the
button to which you want to assign the color. When you have chosen colors for
all four  buttons, click on Guess. An X is displayed for each button for which
the color is correct. An O indicates that a correct color is chosen but it is
not assigned to the correct button. You continue guessing until you guess
correctly or complete ten tries. The New item in the Game menu starts a new
game. The Peek item lets you see the correct solution. The About item in the
Help menu shows copyright information.

This program shows how to add a dialog to a program (the About dialog) and how
to use VXΓêÖREXX predefined functions (VRMessage). It also illustrates using
general routines for code that is used by many objects and shows how to pass
arguments to a REXX routine. It shows some of the features of the REXX language
such as program control statements (do and if) and how to use REXX stem
variables as arrays to simplify programming. MindGame also demonstrates the use
of menus.

To run this program, double click on the Mind Game icon in the MindGame folder.
To edit the project, double click on the MindGame.VRP icon.


ΓòÉΓòÉΓòÉ 3.5. MMW ΓòÉΓòÉΓòÉ

The MMW sample program demonstrates the difference between modal and modeless
windows. It allows you to open both modeless and modal windows, and explains at
each step how you should proceed.

To run this program, double click on the MMW icon in the MMW folder. To edit
the project, double click on the MMW.VRP icon.


ΓòÉΓòÉΓòÉ 3.6. Movies ΓòÉΓòÉΓòÉ

The Movies sample program demonstrates the use of VXΓêÖREXX with the multimedia
extensions to OS/2. You will require the IBM Multimedia Presentation Manager/2
software to run this sample. This software is included in OS/2 2.1 but is
installed separately.

This sample allows you to play movies, either in the main thread, or as part of
a separate thread, allowing you to continue working in  the current thread.

To run this program, double click on the Multimedia icon in the Movies folder.
To edit the project, double click on the Movies.VRP icon.


ΓòÉΓòÉΓòÉ 3.7. Scan ΓòÉΓòÉΓòÉ

In this sample, VXΓêÖREXX is used to create a REXX macro that can be run with the
OS/2 Enhanced Editor (EPM). When run from EPM, the Scan macro searches the
current file for all REXX labels (with format labelname:) and displays the
labels in a list box. If you double click on a label in the list box, that
label becomes the current line in the editor.

The sample program was created with VXΓêÖREXX. The macro was created using Make
macro from the VXΓêÖREXX Project menu.

To start the macro, open the EPM with Scan object in the Scan folder.
Alternatively, you can run the macro from within EPM by doing the following:

 1. Press Ctrl+I or choose Command dialog from the Command menu.

 2. Type the following in the entry field:

   rx c:\vxrexx\samples\scan\bin\scan

The Scan folder also includes a Profile.ERX file that will add a menu to EPM
which can be used to run the macro. To use the profile:

 1. Open EPM.

 2. Select Command dialog from the Command menu.

 3. Enter Profile on and select OK in the Command dialog.

 4. Select Save options from the Options menu.

 5. Close EPM.

Now when you double click on the EPM with Scan icon and select a label, EPM
should include a Labels menu. Selecting Find from this menu will run the sample
macro.

To edit the project, double click on the Scan.VRP icon.


ΓòÉΓòÉΓòÉ 3.8. SampleDB ΓòÉΓòÉΓòÉ

The SampleDB application demonstrates the use of VXΓêÖREXX with either Database 2
OS/2 (DB2/2) or Extended Services for OS/2 Database Manager. SampleDB accesses
the Database Manager sample database using the Database Manager REXX API
(Application Programming Interface). You are provided with a simple interface
to view the records in this sample database. Click on the Search button to
display the first record, and then click on Next to view each subsequent
record.

Clicking on Clear closes the database. You can quit the program at any time by
clicking on the Exit button.

For more information about this sample program, and about using VXΓêÖREXX with
the Database Manager, refer to the chapter entitled Database Manager with
VXΓêÖREXX in the Programmer's Guide.

Running this sample program requires that you have either Database 2 OS/2 or
the older Extended Services for OS/2. These are a separate products, and are
not included with either VXΓêÖREXX or the OS/2 system. If you do have either of
these database packages, make sure that you have installed the sample database
provided with the Database Manager.

To run this program, double click on the Sample Database icon in the SampleDB
folder. To edit the project, double click on the SampleDB.VRP icon.


ΓòÉΓòÉΓòÉ 3.9. Threads ΓòÉΓòÉΓòÉ

The Threads sample program demonstrates VXΓêÖREXX's ability to create
multithreaded applications. This feature allows you to write applications which
perform lengthy operations in the background. For example, an application could
allow the user to continue to work in the main window while saving files in the
background. The main window would be one thread, and the part of the program
saving the files would be another thread.

This sample allows you to create threads by clicking on the Spawn New Thread
button. A new window is opened into which you can enter text. Clicking on the
Send to parent button then sends the text to the main window, where it is
displayed in a list box.

You can also stop the new threads that you create by selecting a thread number,
then clicking on the Halt Selected Thread button.

To run this program, double click on the Threads icon in the Threads folder. To
edit the project, double click on the Threads.VRP icon.


ΓòÉΓòÉΓòÉ 3.10. WinCtrl ΓòÉΓòÉΓòÉ

The WinCtrl demo illustrates the use of the ListWindows method and PM window
handles. The program lists all of the top level frame windows that are
currently visible on the desktop. After selecting windows in the program's list
box, you can then minimize, restore, or shake them.


ΓòÉΓòÉΓòÉ 4. Release information ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 4.1. Online information ΓòÉΓòÉΓòÉ

The most up-to-date information on VXΓêÖREXX is available online. Both this Read
Me First and the Programmer's Guide and Reference are available online. The
most recent information is in the Latest Updates section of the online Read Me
First. The online Programmer's Guide and Reference contains all of the changes
noted in this document.

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.

In addition, the context help is linked to the full text of the Programmer's
Guide and 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.

Similarly, the reference entry for any event, function, method, object,
predefined routine or property can be quickly obtained by using the help index.
Open a VXΓêÖREXX help window by clicking on a VXΓêÖREXX window and pressing F1.
Open the help index by clicking on the Index button within the help window.
Select the appropriate topic from the beginning of the index list, for example
A list of functions. This will bring you to a list of items, each of which has
special highlighting. Double click on the item of interest to see its reference
entry.


ΓòÉΓòÉΓòÉ 4.2. Workplace Shell integration ΓòÉΓòÉΓòÉ

VXΓêÖREXX has been integrated into the Workplace Shell to allow you to take full
advantage of the OS/2 environment. The following highlights some of the
features related to the Workplace Shell.

o 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.

  See Creating and running projects in the Programmer's Guide.

o Edit VXΓêÖREXX objects using Workplace Shell techniques

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

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

   - 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.

   - 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.

     See Adding objects to a window and Changing object properties in the
     Programmer's Guide.

o 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.

  See the next section, New features in version 1.01.

o 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.

o 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.

  See Adding help to a program in the Programmer's Guide.

o 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.

  See StartThread method in the online Reference.

o 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.

  See Halt section in the online Reference.

o 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.

  See ListWindows method and HWnd property in the Reference.


ΓòÉΓòÉΓòÉ 5. New features in version 1.01B ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 5.1. New design environment features ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 5.1.1. Version checking on projects ΓòÉΓòÉΓòÉ

If you try to load a project that was created with a later version of VX-REXX,
you now get a warning, asking if you want to try to load the project anyway. If
the project does not contain any new objects, you may be able to edit the
project.


ΓòÉΓòÉΓòÉ 5.2. New run time features ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 5.2.1. Improved support for controlling other applications ΓòÉΓòÉΓòÉ

o Getting your process ID

    pid = VRMethod( "Application", "GetProcessID" )

  You can now get your application's process identifier using the new
  GetProcessID method. You can use this in conjunction with the ListWindows
  method to determine which windows are part of your application.

o Finding the active window

    pmWindowHandle = VRMethod( "Screen", "GetActiveWindow" )

  The Screen object has a new method, GetActiveWindow, which returns the
  Presentation Manager (PM) window handle of the currently active window.

  Use this method when writing application macros in VX-REXX to get the PM
  window handle of the application window. You can then set the new FrameOwner
  property of the VX-REXX window to be the application window to make sure that
  the VX-REXX window is minimized, maximized, and restored along with the
  application window.

o Finding the focus window

    pmWindowHandle = VRMethod( "Screen", "GetFocusWindow" )

  The new GetFocusWindow method of the Screen object returns the PM window
  handle of the window that currently has the focus.

o Improved ListWindows method

    ok = VRMethod( "Screen", "ListWindows", "windows.", ["ALL"] )

  The ListWindows method now optionally lists all top level windows, not just
  the frame windows. As a result, you can now write programs that can walk the
  entire PM window tree. a top level window is one whose parent is the OS/2
  desktop window.

o Improved SendKeyString method

  If you omit the destination object parameter to the SendKeyString method, the
  keys are sent to the object that currently has the focus. This means you can
  send keys to windows in other applications without figuring out which window
  to sent them to.

o Setting the focus to any PM window

  You can now use the SetFocus method on any PM window handle returned by
  ListWindows.

o Referring to the desktop and root object windows

  You can now refer to the desktop window itself using the special PM window
  handle "?HWND1". Similarly, to refer to the root object window, use the
  predefined PM window handle "?HWND2".


ΓòÉΓòÉΓòÉ 5.2.2. Improved control over windows ΓòÉΓòÉΓòÉ

o Minimized / maximized state

  You can now tell whether one of your VX-REXX application's windows has been
  minimized or maximized. Windows now have a WindowState property which
  reflects the current window state. You can also set this property to
  minimize, maximize, or restore a window. The following are valid values for
  the property:

   Minimized      The window is maximized.

   Maximized      The window is minimized.

   Normal         The window is neither maximized or minimized.

o Setting the PM owner for a window

  Now when you write VX-REXX macros for other applications, the macro's windows
  can be minimized, maximized, or restored along with the application's
  windows. To do this, you set the new FrameOwner property of a VX-REXX window
  to the PM window handle of the application window.

  Use this method when writing application macros to set the owner of your
  macro's window to be the application's window. Use the GetActiveWindow method
  in the Init section of your macro to get the PM window handle of the
  application window. Then set the macro window's FrameOwner property to the
  handle of the application window.

  The window assigned to the FrameOwner property must be in the same process as
  the VX-REXX macro.


ΓòÉΓòÉΓòÉ 5.2.3. Improved combo boxes and drop down combo boxes ΓòÉΓòÉΓòÉ

Combo boxes (and drop down combo boxes) are combinations of entry fields and
list boxes. Previously, combo boxes had a subset of the properties of entry
fields and list boxes. Now, they have most of the combined properties. The
following combo box properties are new to version 1.01B: HorizScroll, Selected,
SelectedString, SelectedStart, SelectedEnd, SelectedText, and TextLimit.

Note that the Value property reflects the contents of the entry field portion
of a combo box. The Selected and SelectedText indicate the selected item in the
list box portion. If you are responding to a Click event, you should use the
Selected and SelectedText properties to find out what the user clicked on (the
Value property may not hold the new value when the Click event is processed).
Similarly, when responding to a Change event, examine the Value property
because the Selected and SelectedText properties may not have been updated yet.


ΓòÉΓòÉΓòÉ 5.2.4. Improved version checking for generated executables ΓòÉΓòÉΓòÉ

If you try to run an EXE file generated by a newer version of VX-REXX, it will
display a dialog which tells you the version it requires. You are given the
option of trying to run it anyway, or quitting.


ΓòÉΓòÉΓòÉ 5.2.5. Getting printer information ΓòÉΓòÉΓòÉ

ok = VRMethod( "Application", "ListPrinters", "printer."

You can now get the list of installed printers on your system by using the new
ListPrinters method of the Application object. The method returns the queue
name, the physical name, and the driver name for each printer.

The method fills the compound variable printer. with the list of all printer
objects available on the system. After returning, printer.0 contains the number
of printers in the list. printer.1 holds information about the first printer,
printer.2 holds information about the second printer, and so on. If there are
no printers installed, printer.0 will be zero.

The method returns 1 if successful, 0 if there was some error.

The format of the strings returned is:

queueName;physicalName;driverName

The following example displays a list of printers:

ok = VRMethod( "Application", "ListPrinters", "printer." )
if ok = 1 then do
    do i = 1 to printer.0
        say printer.i
    end
end


ΓòÉΓòÉΓòÉ 5.2.6. Improved multiline entry fields ΓòÉΓòÉΓòÉ

The multiline entry field (MLE) object has the following new features:

o Ignore tabs

  Setting the new IgnoreTab property to 0 prevents tab characters from being
  added to the text. Instead, the focus moves to the next object in the tab
  order.

o Undo

  You can now undo the last change made to a MLE using the Undo method. If you
  do not want to allow the user to undo changes, set the DisableUndo property
  to 1.


ΓòÉΓòÉΓòÉ 5.2.7. New tab handling in entry fields ΓòÉΓòÉΓòÉ

Entry fields have a limit on the number of characters they can hold. If the
(new) AutoTab property is set to 1, then the focus automatically changes to the
next object in the tab order when the maximum number of characters have been
typed in the entry field.


ΓòÉΓòÉΓòÉ 5.2.8. Controlling word wrap in descriptive text ΓòÉΓòÉΓòÉ

If you set the new WordBreak property of descriptive text objects, the text
will not wrap automatically.


ΓòÉΓòÉΓòÉ 5.3. Other new or improved properties, events, and methods ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 5.3.1. Drop down combo box ΓòÉΓòÉΓòÉ

Typing the first character of an item in the list now selects it. If you type
the same character, the next item that starts with that character is selected.


ΓòÉΓòÉΓòÉ 5.3.2. VRMessageStem function ΓòÉΓòÉΓòÉ

The VRMessageStem function has been made faster.


ΓòÉΓòÉΓòÉ 6. New features in version 1.01 ΓòÉΓòÉΓòÉ

For more information on the following features refer to the online
documentation.


ΓòÉΓòÉΓòÉ 6.1. Improved Development Environment ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 6.1.1. 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.


ΓòÉΓòÉΓòÉ 6.1.2. 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.


ΓòÉΓòÉΓòÉ 6.1.3. 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.


ΓòÉΓòÉΓòÉ 6.1.4. 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.


ΓòÉΓòÉΓòÉ 6.1.5. 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.


ΓòÉΓòÉΓòÉ 6.1.6. 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.


ΓòÉΓòÉΓòÉ 6.1.7. 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.


ΓòÉΓòÉΓòÉ 6.1.8. 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.


ΓòÉΓòÉΓòÉ 6.2. New run time features ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 6.2.1. 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 in the online Programmer's Guide and SpinButton object in
the online Reference for more information.


ΓòÉΓòÉΓòÉ 6.2.2. 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 online
  Reference documentation  for a full description of this new feature.


ΓòÉΓòÉΓòÉ 6.2.3. 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 online Reference for complete information.


ΓòÉΓòÉΓòÉ 6.2.4. 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.


ΓòÉΓòÉΓòÉ 6.2.5. Improved control over STDIO redirection ΓòÉΓòÉΓòÉ

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


ΓòÉΓòÉΓòÉ 6.2.6. 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.


ΓòÉΓòÉΓòÉ 6.2.7. 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.


ΓòÉΓòÉΓòÉ 6.2.8. 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.


ΓòÉΓòÉΓòÉ 6.2.9. Support for Personal REXX version 3.0a ΓòÉΓòÉΓòÉ

VXΓêÖREXX now works with Quercus System's Personal REXX version 3.0a.


ΓòÉΓòÉΓòÉ 6.3. Other new or improved properties, events, and methods ΓòÉΓòÉΓòÉ

Refer to the online Reference for complete information on the following.


ΓòÉΓòÉΓòÉ 6.3.1. AddStringList method ΓòÉΓòÉΓòÉ

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


ΓòÉΓòÉΓòÉ 6.3.2. AdjustHeight property ΓòÉΓòÉΓòÉ

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


ΓòÉΓòÉΓòÉ 6.3.3. Change event ΓòÉΓòÉΓòÉ

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


ΓòÉΓòÉΓòÉ 6.3.4. 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).


ΓòÉΓòÉΓòÉ 6.3.5. 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.


ΓòÉΓòÉΓòÉ 6.3.6. Justification property ΓòÉΓòÉΓòÉ

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


ΓòÉΓòÉΓòÉ 6.3.7. 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.


ΓòÉΓòÉΓòÉ 6.3.8. ListChildren method ΓòÉΓòÉΓòÉ

This method lists the children of a given object.


ΓòÉΓòÉΓòÉ 6.3.9. ListClasses method ΓòÉΓòÉΓòÉ

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


ΓòÉΓòÉΓòÉ 6.3.10. Maximize method ΓòÉΓòÉΓòÉ

This new window method causes a window to be maximized.


ΓòÉΓòÉΓòÉ 6.3.11. Minimize method ΓòÉΓòÉΓòÉ

This new window method minimizes a window.


ΓòÉΓòÉΓòÉ 6.3.12. MultiLineEntryField object ΓòÉΓòÉΓòÉ

Multiline entry fields now support the DoubleClick event.


ΓòÉΓòÉΓòÉ 6.3.13. 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.


ΓòÉΓòÉΓòÉ 6.3.14. Pointer property ΓòÉΓòÉΓòÉ

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


ΓòÉΓòÉΓòÉ 6.3.15. 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.


ΓòÉΓòÉΓòÉ 6.3.16. Restore method ΓòÉΓòÉΓòÉ

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


ΓòÉΓòÉΓòÉ 6.3.17. StatusArea ΓòÉΓòÉΓòÉ

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


ΓòÉΓòÉΓòÉ 6.3.18. SupportsMethod method ΓòÉΓòÉΓòÉ

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


ΓòÉΓòÉΓòÉ 6.3.19. SupportsProperty methods ΓòÉΓòÉΓòÉ

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


ΓòÉΓòÉΓòÉ 6.3.20. 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.


ΓòÉΓòÉΓòÉ 6.3.21. 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. For a full description, see the online documentation.


ΓòÉΓòÉΓòÉ 7. Tips ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 7.1. Using VXΓêÖREXX ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 7.1.1. Running VXΓêÖREXX ΓòÉΓòÉΓòÉ

o VXΓêÖREXX can be started from an OS/2 command prompt. The command line syntax
  is:

      vrxedit [project]

  where project is the name of a project (VRP) file.

o Before executing a pull instruction, be sure to execute a say instruction in
  order to open the standard I/O console. If you execute pull when the console
  is not visible your program may appear frozen. Your program has not crashed;
  it is just waiting for input.

  You can force the console to become visible by selecting Show for the VXΓêÖREXX
  console in the OS/2 window list. Alternatively, you can exit your program by
  selecting Close from the program's pop-up menu in the OS/2 window list.


ΓòÉΓòÉΓòÉ 7.1.2. Using the debugger ΓòÉΓòÉΓòÉ

o To stop the debugging session at any time simply close the debugger section
  list window.

o You can enter REXX statements for immediate execution in the Results window.
  For example you can enter say statements to see the value of variables and
  simple expressions.


ΓòÉΓòÉΓòÉ 7.1.3. Interrupting a VXΓêÖREXX program ΓòÉΓòÉΓòÉ

You can use the Close command from the OS/2 Window List Window (Ctrl+Esc) to
interrupt a VXΓêÖREXX program.


ΓòÉΓòÉΓòÉ 7.2. Using VXΓêÖREXX objects ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 7.2.1. Using property notebooks ΓòÉΓòÉΓòÉ

The property notebook for a Window has more page tabs than are displayed at the
default size. To see additional page tabs, make the notebook larger or use the
double up and down arrows above and below the page tabs.


ΓòÉΓòÉΓòÉ 7.2.2. Window files versus multiple windows ΓòÉΓòÉΓòÉ

We strongly recommend that you place modal windows in separate window files.
Window files are created and managed using the File list in VXΓêÖREXX. You should
use secondary windows, and the VXΓêÖREXX Window list only for modeless windows.
See the MMW sample program for an example of modal versus modeless windows.


ΓòÉΓòÉΓòÉ 7.2.3. Using DropDownComboBoxes ΓòÉΓòÉΓòÉ

The height set for drop-down combo boxes in the design environment is the
dropped-down height (the height of the entry field is fixed and depends only on
the font). If you set the size too small the drop-down list will not drop down
at run time.


ΓòÉΓòÉΓòÉ 7.2.4. Using GroupBoxes ΓòÉΓòÉΓòÉ

GroupBoxes must contain objects within their borders; you cannot simply place a
GroupBox on top of existing objects. Objects are contained in a GroupBox if
they are created in the GroupBox or if they are pasted into the group box. Use
Cut and Paste to move existing objects into a GroupBox.


ΓòÉΓòÉΓòÉ 7.2.5. Changing tab behavior with multiline entry fields ΓòÉΓòÉΓòÉ

By default, pressing Tab in a multiline entry field (MLE) inserts a tab
character into the MLE, rather than moving the focus to the next object in the
tab order. While the user can always press Ctrl+Tab to move to the next object,
you can use the KeyPress event to do this automatically when the user presses
Tab.

Add a KeyPress event for the MLE as follows:

MLE_1_KeyPress:
    keystring = VRGet( "MLE_1", "KeyString" )
    if keystring = "{Tab}" then do
        ok = VRSet( "MLE_1", "KeyString", "{Ctrl}{Tab}" )
    end
return

For more information about the KeyPress event or the KeyString property, see
the online reference.


ΓòÉΓòÉΓòÉ 7.2.6. Generating timer events ΓòÉΓòÉΓòÉ

You can generate timer events by using the multithreading capability of
VXΓêÖREXX:

 1. Create a separate code-only file with the following code:

        Main:
            call RXFuncAdd "SysLoadFuncs", "REXXUTIL", "SysLoadFuncs"
            call SysLoadFuncs

            do forever
                call SysSleep 1    /* wait 1 second */
                call VRMethod "Application",,
                              "PostQueue", 0, 1, "call TimerEvent"
            end
        return

 2. In the Init section of the main window file, start the timer thread using
    the StartThread method:

        call VRMethod "Application", "StartThread", "File1"

    You should replace File1 with the actual name of the code-only file you
    created in step 1.

 3. From the section list, add a new section called "TimerEvent" to the main
    window file.

When you run your program, the TimerEvent routine will be called every second.

For longer timeouts add a second loop in the timer thread code to count seconds
rather than increase the time spent in the SysSleep function. This will ensure
that your application can be shutdown, as it will not be blocked in SysSleep
for long periods of time.

You can also pass and use internal object names between threads. For example
you could pass the internal name of a descriptive text field to a timer thread
which could then use VRSet to modify the text directly -- without posting an
event. This would ensure that the text was updated even when the window it was
on was not responding to events.


ΓòÉΓòÉΓòÉ 7.3. Launching programs from REXX ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 7.3.1. Running commands that require OS/2 session "VIO" support ΓòÉΓòÉΓòÉ

Since VXΓêÖREXX projects are Presentation Manager programs, you cannot directly
execute OS/2 commands which require "VIO" support. The OS/2 PSTAT command uses
VIO support. If you try to run it from REXX, you will get a "SYS0436: An
invalid VIO handle was found" error.

Use the OS/2 start command to run this program. The following instructions will
run PSTAT in its own OS/2 window.

address cmd "start /win pstat <con >con"

To get help for the OS/2 start command, type help start from an OS/2 command
window. The use of the redirection symbols < and > is explained below.


ΓòÉΓòÉΓòÉ 7.3.2. Redirecting standard input, output and error ΓòÉΓòÉΓòÉ

By default, VXΓêÖREXX redirects the standard input, output, and error streams to
its console window. If you launch a program or execute an OS/2 command, the
output is sent to the console and 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. The following instruction will run PSTAT in its own
window, and the results will be displayed in the window.

address cmd "start /win pstat <con >con"

If the program you are running writes to standard error, you should add 2>con
to redirect standard error, as follows:

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


ΓòÉΓòÉΓòÉ 7.4. Writing REXX programs ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 7.4.1. 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.


ΓòÉΓòÉΓòÉ 7.4.2. Using 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.


ΓòÉΓòÉΓòÉ 7.4.3. 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. 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

Assign the literal or expression to a simple variable and use that to form the
compound variable:

J = I - 1
ok = A.J


ΓòÉΓòÉΓòÉ 8. Restrictions ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 8.1. Installation ΓòÉΓòÉΓòÉ

The installation program requires a minimum of 1M free space on the OS/2 boot
drive to start the install.


ΓòÉΓòÉΓòÉ 8.2. Development environment ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 8.2.1. Missing windows ΓòÉΓòÉΓòÉ

On some occasions a project's window positions may not be saved correctly. It
may appear that one or more of the windows in your project has disappeared, but
they are actually just off the screen. Move the VXΓêÖREXX window around your
screen, as this may cause the windows to reappear. Once you can see any part of
the window click on it and press Atl+F7 to move it, or double click on it and
set the Top and Left properties to 0.

If the windows do not reappear, save the file as text, and manually change the
Top and Left properties of the hidden windows to 0, which will be certain to be
on the screen when you reload the file.


ΓòÉΓòÉΓòÉ 8.2.2. Tab order ΓòÉΓòÉΓòÉ

Objects pasted into a window are not placed at the end of the tab order. They
keep their current tab index; 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.


ΓòÉΓòÉΓòÉ 8.2.3. Updating property notebooks ΓòÉΓòÉΓòÉ

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.


ΓòÉΓòÉΓòÉ 8.2.4. Loading files saved as text ΓòÉΓòÉΓòÉ

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.


ΓòÉΓòÉΓòÉ 8.2.5. HPFS file names ΓòÉΓòÉΓòÉ

File names containing multiple periods (e.g. a.b.c) are not accepted by
VXΓêÖREXX. Avoid these names when saving project and source files.


ΓòÉΓòÉΓòÉ 8.2.6. Debugger ΓòÉΓòÉΓòÉ

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.


ΓòÉΓòÉΓòÉ 8.3. Using VXΓêÖREXX objects ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 8.3.1. Overlapping objects ΓòÉΓòÉΓòÉ

VXΓêÖREXX does not support overlapping objects (nor in general does OS/2).
Overlapping objects will not paint correctly.


ΓòÉΓòÉΓòÉ 8.3.2. Sending key strings to OS/2 and DOS sessions ΓòÉΓòÉΓòÉ

You cannot use PostKeyString or SendKeyString to send key strings to OS/2 and
DOS sessions (windowed or full screen).


ΓòÉΓòÉΓòÉ 8.4. Running VXΓêÖREXX programs ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 8.4.1. Running VXΓêÖREXX macros from an OS/2 window ΓòÉΓòÉΓòÉ

VXΓêÖREXX macros created with the Make macro command cannot be run from an OS/2
command prompt. They must be run from within a Presentation Manager session.
The VRX command can be used to run VXΓêÖREXX macros:

    vrx macro-name

You should use the Make EXE file command in the Project menu to make standalone
programs. Use the Make macro command to make macros to use with other PM
applications such as the Enhanced Editor.


ΓòÉΓòÉΓòÉ 8.4.2. Starting OS/2 commands from multiple threads ΓòÉΓòÉΓòÉ

The OS/2 command host will only run one program at a time. I.e. if you start a
program on one thread, you will be unable to start a program on any other
thread until the first program returns. To run multiple programs at the same
time use the OS/2 start command. Enter help start at an OS/2 command prompt for
more information.


ΓòÉΓòÉΓòÉ 8.4.3. Syntax errors with Quercus System's Personal REXX ΓòÉΓòÉΓòÉ

When running under 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.


ΓòÉΓòÉΓòÉ 9. Fixes in version 1.01B ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 9.1. Objects, properties, events, and methods ΓòÉΓòÉΓòÉ

AddStringList method

The AddStringList method now works properly when invoked from different
threads.

ListProperties method

The ListProperties method now works correctly with the Application and Screen
objects.

ListWindows method

Previously, some PM window handles would not be returned consistently. As a
result, the WINCTRL sample program could not always list all frame windows.

Multiline entry field object

The MLE now returns correct values for the SelectedStart and SelectedEnd
properties. Previously, it was not counting carriage return and line feed
characters correctly.

PutVar method

Previously, using PutVar to store undefined REXX variables caused unpredictable
results. This problem has been fixed.

StartThread method

This method now consistently frees the memory that it allocates.


ΓòÉΓòÉΓòÉ 10. Fixes in version 1.01A ΓòÉΓòÉΓòÉ

Results of the REXX say and trace instructions are now displayed correctly in
the console window. In version 1.01, executing these instructions would produce
unpredictable results under some circumstances.


ΓòÉΓòÉΓòÉ 11. Fixes in version 1.01 ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 11.1. Installation ΓòÉΓòÉΓòÉ

o Improved installation check for free disk space.

o CONVERT.EXE has been removed from the VXΓêÖREXX directory.

o The install setup program is deleted from the root of the OS/2 boot drive.


ΓòÉΓòÉΓòÉ 11.2. Design environment ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 11.2.1. General ΓòÉΓòÉΓòÉ

o Improved error handling if VXΓêÖREXX is unable to load a window.

o VXΓêÖREXX now correctly handles filenames which contain blanks or apostrophes.

o Save as text now works correctly for code only files.

o You can no longer drag objects off of a window or group box at design time.

o REXX syntax errors are now handled more gracefully when running and debugging
  a project.

o Fixed occasional problems in updating the file and window lists.

o Pressing F1 now opens the general help for VXΓêÖREXX when an edit window is
  active.

o Fixed problem in VXΓêÖREXX that generated a REXX error if OS/2 was shutdown or
  a work area was closed while VXΓêÖREXX was running.

o VXΓêÖREXX now confirms the creation of an EXE or macro.

o VXΓêÖREXX now shows the full path of a file in the dialog that warns you about
  overwriting existing files.

o Disabled items have been removed from popup menus.

o Fixed a problem with "ghost menus" appearing on some OS/2 2.1 systems when
  mouse button 2 was pressed.

o Fixed painting of edit handles on multiwindow objects.

o Z-order of windows is now preserved when changing property values.

o Better handling of long tokens in REXX programs.


ΓòÉΓòÉΓòÉ 11.2.2. Property notebooks ΓòÉΓòÉΓòÉ

o Notebooks are now updated automatically while they are open if the object's
  size, position, or tab order is changed. You can also refresh the values on a
  page by flipping to another page, then flipping back.

o Notebook pages no longer flash when they are selected for the first time.

o The act of opening a section editor by selecting an event no longer marks the
  object as being changed.

o Deleted events are no longer shown in bold on the events page.

o The font selection dialog now recognizes italics and bold attributes.
  Previously, they were ignored.

o The font and file dialogs are now centered over the notebook, rather than
  being centered on the screen.

o Pressing F1 when a notebook is active now opens the general help for VXΓêÖREXX.

o The value of the InitialList property can now be deleted without freezing the
  notebook window.

o Changing a property on the "Style" page for a secondary window now marks the
  project as changed. Previously it did not.

o Previously, if more than one property notebook was open, changing the Name
  property in one notebook incorrectly changed the title of the other notebook.

o Notebooks are now displayed as an icon when minimized. Previously, they were
  shown as the lower left corner of the full sized window.

o Previously the tab order could have been changed when setting certain
  properties. This problem has been fixed.

o In version 1.0, if you restored a minimized property notebook by double
  clicking on its icon in the Minimized Window Viewer, OS/2 would crash. This
  problem is fixed.

o Previously, opening more than one property notebook at a time would cause the
  notebooks to flash when they opened. This has been fixed.

o Property notebooks now show the object type in the title bar.

o Property notebooks now appear in the OS/2 window list.

o Deleting a section with a name of the same form as an event section no longer
  causes an error.

o Fixed a problem that left a secondary window disabled when a system menu was
  added or removed from it.


ΓòÉΓòÉΓòÉ 11.2.3. Code section editor ΓòÉΓòÉΓòÉ

o When you open a section, you are placed automatically in insert mode.

o Fixed problem with spurious characters appended to imported text data in the
  section editor.

o Deleting a section now closes the editor window for that section.

o In some rare instances, activating a section editor window could cause the
  project windows to change their Z-order. This has been fixed.


ΓòÉΓòÉΓòÉ 11.2.4. Debugger ΓòÉΓòÉΓòÉ

o The debugger now gracefully terminates if the REXX program contains a syntax
  error.

o The REXX RESULT variable is no longer reset by the debugger.

o Previously, the first character of some lines in the results window was
  inadvertently converted to a blank. This problem has been fixed.

o The "Clear" item in the "Breakpoints" menu is now disabled if no breakpoints
  are set.

o The "Set" item in the "Breakpoints" menu is now enabled all the time.

o REXX errors resulting from statements typed in the Results window are now
  printed in the Results window. Previously, they were displayed in the Errors
  window for the project.

o All debugger windows except Results now appear in the OS/2 window list.


ΓòÉΓòÉΓòÉ 11.3. Objects, properties, events, and methods ΓòÉΓòÉΓòÉ

AddString method

   o This method now returns the position at which the string was inserted.
     Previously, the method returned 0 or 1.

AddStringList method

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

Autosize property

   o A minimum size is now enforced on all objects. This means that if you set
     Autosize on an object with no caption, the object is no longer sized down
     to a height and width of zero.

   o If you drag and drop a font onto an object with autosize enabled, the
     object resizes itself immediately. Previously, you had to turn off
     autosize, then turn it on again after dropping the font for the object to
     resize itself.

ComboBox object

   o Combo boxes now resize correctly when the font is changed.

   o Drag and drop colors and fonts now work correctly.

   o You can now set the Value property at design time.

   o The Value property is now updated as soon as an item in the list is
     clicked. This means that in the Click event, the Value property will be
     the new selection. Previously, it was the old selection.

DeleteList method

   o This method now disables list box repainting while removing strings from
     the list, speeding up the operation.

DescriptiveText object

   o The TabStop property has been removed.

   o The SetFocus method has been removed.

   o Autosize no longer causes the last word in the caption to disappear.

DropDownComboBox object

   o Drop down combo boxes that are in group boxes are now painted correctly.

   o The list area of a drop down combo box is now repainted correctly when you
     move the object.

   o Drop down combo boxes now resize correctly when the font is changed.

   o Drag and drop colors and fonts now work correctly. Previously, they were
     ignored.

   o You can now set the Value property at run time. Previously, this would not
     work consistently.

   o Previously, clicking in the list box portion of the object would generate
     two Click events: one for the click in the list, and one when the entry
     field is changed. Now a Click event is generated, followed by a Change
     event when the entry field changes value.

   o The Value property is now updated as soon as an item in the list is
     clicked. This means that in the Click event, the Value property will be
     the new selection. Previously, it was the old selection.

   o The tracking rectangle for drop-down combo box objects is now only as
     large as the visible portion allowing them to be positioned more easily.

   o Dropped down lists now repaint properly when moved.

EntryField object

   o You can now change the width of entry fields with autosize turned on.
     However, their height is still unchangeable as stated in the
     documentation.

   o The default TextLimit has been raised from 32 to 255.

GroupBox object

   o You can now drag and drop colors from the color palette onto group boxes.

   o The TabStop and TabOrder properties have been removed.

HelpFile property

   o The help file is now closed properly when the program terminates.

HelpText property

   o Help information loaded from files is no longer followed by spurious
     characters.

HintText property

   o The status area is blanked when the pointer is over a window that has no
     hint defined.

MoveWithParent property

   o Previously, if you unchecked the MoveWithParent property, the edit window
     would no longer move with the primary window at design time. This has been
     fixed.

MultiLineEntryField object

   o The Click event now works.
   o The Value property now returns the correct result even if the MLE has not
     been made visible.
   o The MLE no longer strips out carriage returns from its Value property.
   o Setting the Value property before making the MLE visible no longer causes
     an error.

PictureBox object

   o The autosize property now causes resizing only when it is turned on, or a
     new picture is loaded.

   o Now correctly handles the BackColor property.

StartThread method

   o The StartThread method now returns the thread identifier of the newly
     created thread, or -1 if the method was unsuccessful.

   o The maximum number of threads has been increased from 32 to 200.

TextLimit property

   o The TextLimit property has been moved to the Text page of property
     notebooks.

VRChAttr function

   o You can now reset all attributes for a file.

VRDir function

   o The function now works properly with the mask parameter set to "*.*".

   o You can now consistently list the files in the root of an HPFS volume.
     Previously, VRDir would list only the "." directory if the fileSpec was of
     the form "C:\*.*".

VRFileDate function

   o The VRFileDate function now allows you to omit either or both of the
     second and third parameters. The time can be set without changing the
     date, and the date can be set without changing the time.

VRFindFile function

   o VRFindFile now returns 0 if it is passed an invalid path.

VRFini function

   o Calling VRFini from the main thread now halts any other threads that are
     still running.

VRMessage function

   o VRMessage now sets the focus correctly.

VRPrompt function

   o VRPrompt now sets the focus correctly.

VRVersion function

   o The VRVersion function now works properly.


ΓòÉΓòÉΓòÉ 12. Latest updates ΓòÉΓòÉΓòÉ

(This section is currently empty).


ΓòÉΓòÉΓòÉ 13. Errata ΓòÉΓòÉΓòÉ

There have been two printings of the VXΓêÖREXX Programmer's Guide and Reference.
In the first printing (June 1993), no date appears beneath the ISBN number on
page ii. In the second printing (August 1993), the date appears at the bottom
of page ii.


ΓòÉΓòÉΓòÉ 13.1. Corrections to the August 1993 printing ΓòÉΓòÉΓòÉ

The following table lists some corrections and additions to the 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.

214            In the example program, the line that reads

               if( selects.0 = 0 )then do

               should read

               if( items.0 = 0 )then do

342            If A is specified in the output parameter, but a file has no
               attributes set, a hyphen ("-") is returned where the attributes
               would normally go.


ΓòÉΓòÉΓòÉ 13.2. Corrections to the first (June 1993) printing ΓòÉΓòÉΓòÉ

The following table lists some corrections and additions to the 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.

68             The last sentence of the second paragraph of the section
               "Selecting and deselecting list items" should read: "The
               MultiSelect property can be set at design time or at run time."

72             Line three of the example should read  "DataType( value ) \=
               "Num" then do".

98             The last sentence of the first paragraph should read "You can
               change the default main file by changing the file name specified
               for Main file in the Run options dialog accessed from the
               Options menu."

128            The first line of the example should read "if (SQLCA.SQLCODE \=
               0 & SQLCA.SQLCODE \= -1026) then do".

141            There are several methods missing from the list of methods. See
               the online Reference for a full description of these methods.

   CenterWindow   Center a window relative to its parent window or the desktop.

   DeleteString   Remove a single item from a list.

   HaltThread     Stop a thread started with the StartThread method.

   InvokeHelp     Invoke help on an object as if the user has pressed F1.

143            The Summary of predefined routines should include the  Halt
               section. This section is signalled when your program is halted
               while it is running. See the online Reference for more
               information.

145            There are several functions missing from the list of functions.
               See the online Reference for a full description of these
               functions.

   VRCreateStem   Create an object using a REXX compound variable to pass all
                  of the create-time properties.

   VRLoadSecondary Load a window from a file.

   VRVersion      Return version information for a VXΓêÖREXX DLL.

160            In the See Also section, the third property should be "Font",
               not "CaptionFont". As well, the last paragraph should read: "If
               you change the Height or Width properties directly, either at
               design time or at run time, the object will resize itself
               (AutoSize is ignored). The object resizes itself only when
               AutoSize is changed from 0 to 1, or when the font or caption
               changes."

161            The BackColor property can also be an RGB value of the form
               "(red,green,blue)". There are also a number of additional
               predefined color values that correspond to system defaults. See
               the online Reference for a complete description of this
               property.

163            The BorderColor property can also be an RGB value of the form
               "(red,green,blue)". There are also a number of additional
               predefined color values that correspond to system defaults. See
               the online Reference for a complete description of this
               property.

176            In the last sentence of the first paragraph, delete the words
               "Create event routine of the ComboBox, or into the".

186            In the first paragraph of the Notes section, add the words "if
               necessary" to the end of the second last sentence.

193            Delete the last sentence in the first paragraph, "A Click event
               ... is received."

199            The syntax for the FindString method should be:

               position = VRMethod( object, "FindString", target, [
               starting-position ], [ search-type ], [ case ] )

               The printed book has starting-position and search-type reversed.

               The first sentence in the description of the search-type
               argument should be "If specified, this argument must be a string
               value that is one of Exact, Prefix, or Substring."

               The first sentence in the description  of the case argument
               should be "The only possible value for the case argument is the
               string value Case."

204            The ForeColor property can also be an RGB value of the form
               "(red,green,blue)". There are also a number of additional
               predefined color values that correspond to system defaults. See
               the online Reference for a complete description of this
               property.

208            In the example program, the line that reads

               if( selects.0 = 0 )then do

               should read

               if( items.0 = 0 )then do

214            The GetVar method has an optional extra parameter which can be
               used to specify the name of the variable to receive the value.
               Also, compound variables used with GetVar must be REXX arrays.
               For a complete description of this method, see the online
               Reference.

223            The HelpTag property has several predefined values which provide
               access to standard OS/2 help panels. See the online Reference
               for full details.

245            In the last sentence of the second last paragraph of the Notes
               section, delete the words "Create event routine of the ListBox,
               or into the".

269            In the Description section, delete the word "metafiles".

271            In the second last paragraph of the Description section, the
               first sentence should start "a string specifying the id of an
               icon or bitmap resource...".

273            The Post method is not properly described in the printed
               Reference. See the online Reference for full details on this
               method.

279            The PutVar method has an optional extra parameter which can be
               used to specify the name to use for the stored value. Also,
               compound variables used with PutVar must be REXX arrays. For a
               complete description of this method, see the online Reference.

308            The StartThread method is not completely described in the
               printed Reference. See the online Reference for full details on
               this method.

335            If A is specified in the output parameter, but a file has no
               attributes set, a hyphen ("-") is returned where the attributes
               would normally go.

343            The VREvent function is not correctly described in the printed
               Reference. See the online Reference for full details on this
               function.

347            In the description of the newdate argument, the sentence in
               brackets should be "as returned by the REXX Date( "sorted" )
               function".

365            In the example, in the response = VRMessage ( ... ) function
               call, the  parameter "button." should be "buttons.".

369            In the example, in the response = VRMessage ( ... ) function
               call, the  parameter "button." should be "buttons.".

373            In the Arguments section, delete the sentence in the description
               of the filespec argument that starts with "If filespec is
               null...".

               The last sentence in the description of format should read "If
               format is omitted, a default of DPNE is used."


ΓòÉΓòÉΓòÉ 14. Contacting WATCOM ΓòÉΓòÉΓòÉ

Although a significant amount of testing has gone into WATCOM VXΓêÖREXX, errors
in the software may be encountered. You may also discover errors or omissions
in the documentation. If you find any problems or have some good suggestions,
we would like to hear from you.

A form is included in the Read Me First booklet for you to use to report any
problems or suggestions. When reporting a problem, please make a blank copy of
this form, in case you have further problems or suggestions. When you have
filled it in, make a second copy and keep it for your records.


ΓòÉΓòÉΓòÉ 14.1. In North America (and all other non-European locations) ΓòÉΓòÉΓòÉ

WATCOM International Corporation.

415 Phillip Street, Waterloo, Ontario, CANADA, N2L 3X2

Technical Support
hot-line:   [phone]
fax:        [phone]
BBS:        [phone]
Internet:   [e-mail]
Compuserve: type GO WATCOM

General Inquiries
tel: [phone]
fax: [phone]

Sales, upgrades, other product
orders, and reseller inquiries/orders:
1-800-265-4555 (toll free in North America)


ΓòÉΓòÉΓòÉ 14.2. In Europe ΓòÉΓòÉΓòÉ

WATCOM Europe Limited.

PO Box 64, LIVINGSTON, West Lothian, EH54 7AE, UNITED KINGDOM

Technical Support
    United Kingdom
        tel: [phone]
        fax: [phone]

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

    BBS: [phone]
    Internet: [e-mail]
    Compuserve: type GO WATCOM

General Inquiries
    United Kingdom
        tel: [phone]
        fax: [phone]

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

Sales, Upgrades, other product orders, and reseller inquiries/orders:
    United Kingdom Toll Free
        tel: [phone]
        fax: [phone]

    Germany Toll Free
        tel: [phone]
        fax: [phone]

    France Toll Free
        tel: [phone]
        fax: [phone]

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