OS/2 Shareware BBS: 18 REXX/18-REXX.zip/vprupd.zip/update.inf

OS/2 Help File | 1993-10-11 | 14KB | 337 lines

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

VisPro/REXX Version 1.1 (8/93)

by HockWare Inc.

This online book is a summary of the changes in VisPro/REXX for Version 1.1,
from Version 1.0.

For Support details double click here.


ΓòÉΓòÉΓòÉ 1.1. Support ΓòÉΓòÉΓòÉ

For technical support questions call the following numbers:

o Technical support FAX line: [phone]
o Technical support line: [phone]
o Compuserve ID: 71333,3226
o Technical support can also be obtained through COMPUSERVE in the HockWare
  forum (section 8) within the OS/2 Vendors Forum (OS2AVEN)

Note:  The HockWare sales line is [phone]


ΓòÉΓòÉΓòÉ 2. Who should receive this update ΓòÉΓòÉΓòÉ

This product update was has been issued to all of registered VisPro/REXX 1.0
users.  In contains a number of important enhancements (listed below).


ΓòÉΓòÉΓòÉ 3. How to apply the update ΓòÉΓòÉΓòÉ

You must have VisPro/REXX installed in your machine before applying the changes
in this update.

If you have already installed VisPro/REXX, you can easily apply the changes
within this disk by using the UPDATE command, included in this disk.

The UPDATE command will copy the files that need to be modified on your hard
drive.  After the files are copied, you can start using VisPro/REXX right away.


ΓòÉΓòÉΓòÉ 4. What does this update contain? ΓòÉΓòÉΓòÉ

The enhancements in this update are:

o Easy Multithreading
o Stdio Support
o Easier Starting of Commands


ΓòÉΓòÉΓòÉ 4.1. Easy Multithreading ΓòÉΓòÉΓòÉ

All REXX statements are executed in a thread which is different from the user
interface thread.  As a result of this, the user interface will remain
responsive even if the application is still processing an event. You don't need
to modify your programs to get this enhancement, all you need to do is to
rebuild.


ΓòÉΓòÉΓòÉ 4.2. Stdio Support ΓòÉΓòÉΓòÉ

If your REXX statements write something to the standard output or try to read
from the standard input, this will now be handled by the display of a STDIO
(Standard Input Output) Window.  If you wish to see how this works, just place
a statement which produces standard output, such as 'DIR' on an event.

When your program is reading from the standard input, it will wait until input
has been entered by the user on the STDIO Window.


ΓòÉΓòÉΓòÉ 4.3. Easier Starting Of Commands ΓòÉΓòÉΓòÉ

Invoking other programs within VisPro/REXX is a snap.  Just place the program
invocation you wish to use, just like you would in a command line within
quotations.  For instance, invoking the system editor could be done as follows:

     'E C:\CONFIG.SYS'

     or

     'START E C:\CONFIG.SYS'

Both invocations above are similar.  However, the first invocation starts the
system editor and does not continue processing any further REXX statements
until the editor has completed.  The second invocation starts the system editor
and immediately proceeds with the rest of the REXX statements in the current
event.

You may also want to try using the REXX 'ADDRESS' command, which would produce
similar results.


ΓòÉΓòÉΓòÉ 5. New information not covered in the book ΓòÉΓòÉΓòÉ

 1. Multithreading of REXX Code
 2. STDIO window


ΓòÉΓòÉΓòÉ 5.1. Multithreading of REXX Code ΓòÉΓòÉΓòÉ

All REXX code is now invoked in a thread which is different from the user
interface thread.  This allows the user interface to be responsive at all
times, even if some prior event is still being handled in REXX.

If an event is going to take a long time, it is recommended that the user is
given some indication that the program has not completed handling the event.
An easy way of doing this is by changing the mouse pointer to the hourglass and
then changing it back to normal when the processing is done.  Another way of
doing this is to disable the action buttons within the dialog, and to reenable
them when the operation taking a long time has completed.


ΓòÉΓòÉΓòÉ 5.2. STDIO Window ΓòÉΓòÉΓòÉ

If an application needs to write to the standard output or read from the
standard input, it will use the STDIO window to accomplish this.  Within this
window, a user will be able to see the output and be able to type input data.

The STDIO window is provided as a way of transitioning existing REXX programs
to VisPro/REXX.  Once an application has been finished, you should have
modified your REXX statements so they don't use this facility, and instead use
standard Presentation Manager controls to show the information graphically.
This is not a requirement, of course, as you may choose to use the STDIO window
as part of your completed application.

When something is written to the standard output, the STDIO Window will
automatically appear and will display output information.  Once this window has
been made visible, it will remain visible while the program is running.

If your program is going to do a read from the standard input, you need to make
certain that the STDIO window is already displayed.  An easy way of doing this
is to output a blank line to standard output.

Once the STDIO window is displayed, it may be minimized or hidden (depending on
the user's OS/2 settings), but it may not be closed.  This is done in order to
prevent the user from closing the STDIO window when the application requires
standard input.

The STDIO window will automatically close when the application ends.

Note:  If you want to prevent standard output and standard error output from
being placed on the STDIO window when invoking OS/2 commands you can simply
redirect this output to a file or to the NUL file, as follows:

            'copy c:\config.sys d:\config.bak 1>NUL 2>NUL'

After the preceding statement is executed the value in the RC variable will
contain 0 if the statement executed correctly.

Note:  For more information on redirection, refer to OS/2 documentation.


ΓòÉΓòÉΓòÉ 6. Additional information not covered in the book ΓòÉΓòÉΓòÉ

 1. Using the toolbar
 2. Return codes in a when closed event
 3. Working out the screen resolution
 4. Changing the pointer
 5. Global Variables
 6. SubProcs
 7. Secondary Forms
 8. The TOPIC variable
 9. Get Item Count call
10. Add items at an index
11. Starting other applications


ΓòÉΓòÉΓòÉ 6.1. Using the toolbar ΓòÉΓòÉΓòÉ

Another handy way of using the toolbar is to drag the object right off the tool
bar.  This allows you to drag an object onto the canvas without changing the
toolbar selection.


ΓòÉΓòÉΓòÉ 6.2. When closed event information ΓòÉΓòÉΓòÉ

When handling a "When closed" event for a form, a return of 1 will cause the
window not to be closed.


ΓòÉΓòÉΓòÉ 6.3. Screen Size ΓòÉΓòÉΓòÉ

To get the size of the screen, you can use the VpWindow call with the
'GETSCREENSIZE' argument.  The following example shows how to get the screen
size and set the current window according to this size:

   xy=VpWindow(window,'GETSCREENSIZE')
   PARSE VAR xy x y
   CALL VpWindow window,'SETPOS', 0, 0, x, y


ΓòÉΓòÉΓòÉ 6.4. Changing the pointer ΓòÉΓòÉΓòÉ

Changing the pointer value can be done with the VpWindow call with the
'SETPOINTER' argument.  The third parameter is the value of the pointer
picture.  The following example shows how to change the mouse pointer to the
hourglass:

   /* valid index 1 - 22 */
   value = VpLoadPicture('SYSICON',3)
   CALL VpWindow window,'SETPOINTER',value

Here is how to set it back to the normal pointer:

   /* valid index 1 - 22 */
   value = VpLoadPicture('SYSICON',1)
   CALL VpWindow window,'SETPOINTER',value

You should set the pointer to the hourglass whenever you have some time
intensive operations to perform.  This will give the user an indication of the
fact that the program is not expecting input from the user at the time.


ΓòÉΓòÉΓòÉ 6.5. Global Variables ΓòÉΓòÉΓòÉ

Global variable values are scoped to the form in which they are defined. This
means that if a variable is defined on a secondary form it will not be
available on the primary form.  Further, if the same variable is defined on the
primary and secondary forms, these variables are treated as if they where
different.


ΓòÉΓòÉΓòÉ 6.6. Subroutines ΓòÉΓòÉΓòÉ

o When adding subroutines to a SubProcs folder, make certain that the file does
  not have an extension.
o All subroutines within the SubProcs folder will be included as part of the
  resulting .EXE file when doing a build.


ΓòÉΓòÉΓòÉ 6.7. Secondary Forms ΓòÉΓòÉΓòÉ

As mentioned in page 98, secondary forms are created by using the VpOpenForm
call.  The VpOpenForm call normally looks as follows:

   value=VpOpenForm(window, 257, 'topic name')

Where:

 1. Window - is the window handle of the form which will be the parent of the
    newly created window
 2. 257 - is a generated unique identifier for the secondary window to be
    created.  Do not change this generated value
 3. 'topic name' - is a customizable argument which is passed to the secondary
    form.  Within the secondary form, this argument value can be obtained by
    using the TOPIC variable.  See the next item for more information on the
    TOPIC variable.


ΓòÉΓòÉΓòÉ 6.8. TOPIC Variable ΓòÉΓòÉΓòÉ

The TOPIC variable is a special variable which contains parameter information
passed in when the form is created.  This variable doesn't need to be declared
in the global variables page, but rather it is always available within a form.
In the case of the primary form, TOPIC contains command line arguments passed
in when the program is invoked. For more information on this variable refer to
the Online help or the User's Guide.


ΓòÉΓòÉΓòÉ 6.9. Get Item Count call ΓòÉΓòÉΓòÉ

To query the number of items in a ListBox, combo box, or container control you
can use the VpGetItemCount function.  This REXX statement for this function is
as follows:

   value = VpGetItemCount( window, ITEMID)

After executing this function, value will contain the number of items in the
list or container.


ΓòÉΓòÉΓòÉ 6.10. Add item at index ΓòÉΓòÉΓòÉ

To add an item to a listbox or combo box at a specific index use the VpAddItem
call as follows:

   CALL VpAddItem window, ITEMID, index, value

Where index is a number specifying the index where the item will be inserted,
and value is the value to be added.


ΓòÉΓòÉΓòÉ 6.11. Starting other applications ΓòÉΓòÉΓòÉ

To start another application, you can use standard REXX conventions and include
the application invocation within quotations, or use the START command within
quotations.  If you require more control over these mechanisms, you can use the
VpStart function.  VpStart has the following syntax:

   applicationid=VpStart(window, arg2,arg3,arg4....)

Where:

o Arg2 - "APP"   - Start an application

  Note:  The form starting the VpStart will get a CLOSE NOTIFY form event when
  the application ends. In this event the FROMTOPIC variable will contain the
  applicationid followed by the return code from the application.
o Arg2 - "SESSION" - Start an application in a separate session
o Arg3 - Fully qualified program path
o Arg4 - Parameter string (optional)
o Arg5 - Title (optional)
o Arg6 - Option string (optional)

   - -I   Inherit environment from main OS/2 process.  This means that the
     program would have the environment given in the CONFIG.SYS file.  This
     option is only valid if using the "SESSION" option. This is required for
     stdin/stdout to function properly
   - -FS  Start in full screen
   - -DOS  Start a DOS session
   - -MAX  Start maximized
   - -MIN  Start minimized
   - -HIDE Start hidden
   - -B   Start in background
   - -C   Start as child process

o Arg7, Arg8, Arg9, Arg10

  Initial position and size of the application (optional)

  Arg7 is the x coordinate, Arg8 is the y coordinate

  Arg9 is the xsize, and Arg10 is the ysize.

  If these arguments are not provided, OS/2 will define the placement and size
  of the application.
o Arg11, and all arguments provided afterwards (optional)

  Environment strings passed to the application.

The following is an example of using the VpStart command:

   applicationid=VpStart(window,"APP", 'c:\os2\e.exe','temp.txt')