VX·REXX is far more than a set of library functions you attach to REXX and call when you need to use one of its functions. Rather, VX·REXX is more like a graphical glove that wraps itself around REXX and insulates REXX from the command line. Using VX·REXX, all communications between the user and your REXX program are handled by VX·REXX in a graphical fashion. You can see this in Figure 1-1, which shows MESSAGE.EXE, a simple VX·REXX program, running.
As you can see, the standard character input/output screen you normally see when running a REXX program is missing. In its place, you see a graphical user interface with a message to the user and two buttons for the user to click. In fact, because it runs as an OS/2 Presentation Manager application, the option of sending output to the standard command line type output is not available to VX·REXX programs.
This chapter presents a overview of using VX·REXX. Since much of this information is already available in the VX·REXX manual, I'm only going to quickly review the most important features.
When you program in VX·REXX, you are working on what the VX·REXX manual calls a project. A project is a collection of one or more window and code files that form a single program. I find this notation more confusing than helpful. VX·REXX considers a program a project while you are working on it and a program once it's done. I don't see the need for the distinction so I will call everything programs both before and after they are done.
There are two main ways to start VX·REXX. The first is to double-click on its icon in the desktop shell. This loads VX·REXX without a program loaded, as shown in Figure 1-2. When starting a new program, you may also drag a template out of the VX·REXX subdirectory to the folder where you want to save the program. Of course, you may also use the other OS/2 methods, such as double-clicking on a .VXP program file or running the program from an OS/2 command line prompt.
To make VX·REXX instantly available to me, I created a shadow of the editor icon and placed that shadow on the desktop. Now, I can instantly start VX·REXX by double-clicking on that icon. I also placed shadows of all the programs I'm currently working on in a folder on the desktop. If I know I want to work on a particular program, I can open that folder and quickly drag a program icon to the VX·REXX shadow or just double-click on it to start VX·REXX with that program loaded.
Since VX·REXX works with entire programs, rather than individual files, the traditional "Files" menu is replaced with a "Projects" (since VX·REXX calls projects programs) menu. This menu is shown in Figure 1-3. You use this menu to load new programs, save the program you are working on and compile a program into an .EXE program file. VX·REXX does not allow you to load more than one program into memory at once. However, OS/2 does allow you to run multiple versions of VX·REXX, which accomplishes almost the same thing.
There is, however, one drawback to this approach. You can switch to one version of VX·REXX and copy code to the paste buffer and then switch to another version and paste the code. However, this does not work when pasting VX·REXX objects. To paste a VX·REXX object, you must stay in the same session. You can load one program, copy the object to the paste buffer then unload that program and load a second program and paste the object in the second program. As you can imagine, this is more cumbersome than loading two different programs in the same VX·REXX session would be if it were allowed.
To run a program outside of VX·REXX, you must use the "Make EXE File" option from the Projects menu as described below. There will be many times when you will need to run the program you are currently working on in VX·REXX to make sure it is executing properly. You do this using the Run menu, as shown in Figure 1-4. If your program needs command-line parameters or needs to run in a special subdirectory, you can configure this using the "Run" option on the Options menu to configure those options. This is shown in Figure 1-5.
Once you have finished your program and are ready to turn it into an .EXE program, you use the "Make EXE File" option from the Projects menu. This converts all the files associated with the currently loaded program into one .EXE program file. This program file can be executed on any OS/2 machine that has the VX·REXX run time libraries installed.
In addition to your .EXE file, anyone wanting to run your program will have to have a copy of the VROBJ.DLL file that comes with VX·REXX installed in a subdirectory that is in their path. Additionally, if you use database functions, users may also require a copy of the VXQE.DLL file that also comes with VX·REXX. According to the VX·REXX on-line documentation, "...you are hereby granted a non-exclusive, royalty-free right to reproduce and distribute the VROBJ.DLL and VXQE.DLL files located in the VX·REXX directory provided that (a) they are 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." So you can include copies of these two files with any software you write using VX·REXX.
VX·REXX provides context-sensitive help. Just press F1 on any menu or object and a help screen will automatically pop up on the current topic. VX·REXX also comes with three electronic books you can access for additional help, VX·REXX Reference, VX·REXX Programmer's Guide and VXQE Library. The VX·REXX Programmer's Guide on-line documentation contains the chapters from the Getting Started and Programmer's Guide portion of the printed manual. The VX·REXX Reference on-line documentation contains the chapters from the Reference and Appendices portion of the printed manual. The VXQE Library on-line documentation describes using the Q+E database functions with VX·REXX. These can be accessed by clicking on their icon in the VX·REXX folder.
You will see more about using VX·REXX by seeing how to create a simple program. The program we are going to create is called PauseIt and it can be found in the \EXAMPLES\PAUSEIT subdirectory on the disk that comes with this book. As a general rule, programs will be saved to the disk that comes with this book in a subdirectory branching off the \EXAMPLES subdirectory that matches their name. Thus, Todo-1 is stored in the \EXAMPLES\TODO-1 subdirectory. When the subdirectory and program names do not match, I will indicate where the program can be found.
PauseIt will display a message in a Descriptive Text object and pause until the user clicks on a PushButton object. Once the user clicks on the button, control will be passed to the calling program.
We begin by clicking on the Descriptive Text tool icon (top row of the Tools, middle icon) and drawing the box on the screen. Exact size and placement are not critical at this time since all the elements can be moved around and sized at will anytime during the process. Next, we click on the PushButton object icon (second row, left icon) and drawing a PushButton object on the screen. Figure 1-6 shows how the program currently looks.
Notice the dots on the screen in the work area. These are used to align the various elements as you are working. They are not part of the final program. The program currently fills only about one third of the screen. The final program will be the same size as the work area that contains the dots. You can resize the work area using the standard OS/2 resizing tools and the resulting program will be the same size.
Also notice in Figure 1-6 that the PushButton object at the bottom of the work area has eight black squares around it. These are the resizing handles that let you alter the size of the PushButton object. They work just like standard OS/2 resizing tools. Move the mouse cursor over one of these squares and it turns into an arrow to indicate the directions you can drag that square to resize the object. The size squares let you go sideways, the top and bottom squares let you go up and down and the corner squares let you move diagonally. Click and hold the right mouse cursor inside the object and you can move it to a new location.
We are ready to add the text to the Descriptive Text. We move the cursor over the Descriptive Text and press the right mouse button to bring up the VX·REXX pop-up menu. This is shown in Figure 1-7. We do not have to select the Descriptive Text first. In fact, if you look closely at Figure 1-7 you can see that the PushButton object is still selected since you can see the resizing squares.
The VX·REXX pop-up menu always belongs to the object that the mouse cursor was pointing to and not the selected object. You can see in Figure 1-7 that VX·REXX displays the type of object (Descriptive Text in this case) and its name (DT_1) on the line below the menu names. This is a quick way to tell which object the VX·REXX pop-up menu will modify. In this case, we want to alter the properties of the Descriptive Text so we click on "Properties" to bring up the Property Notebook shown in Figure 1-8.
To alter the text, we click on the "Text" tab to bring up the text page of the Property Notebook, as shown in Figure 1-9. Here we enter the text in the Caption block. If you press Return, the text is immediately applied to the Descriptive Text without waiting until you close the Property Notebook. Once you do close the Property Notebook, the program looks like what you see in Figure 1-10.
Aligning the text at the top is a useful approach when you have a lot of text to display. When you only have a single line to display, centering is a more attractive approach. By opening the Property Notebook again and selecting the Style page, we can alter the vertical and horizontal justification of the text. In this case I selected centering for both. Figure 1-11 shows this.
Next, we need to add text to the PushButton object so we bring up the VX·REXX pop-up menu, open its Property Notebook and enter the text under the Text tab. This is shown in Figure 1-12. Now, we need to add the code to cause the program to terminate when the user clicks on the PushButton object. To do that, we bring up the VX·REXX pop-up menu, select Events and then Click. That brings up a REXX subroutine containing the following lines:
/*:VRX */
PB_1_Click:
return
The first line is a comment that the VX·REXX editor uses to track the subroutines. The second line first identifies the object (PB_1 or the first PushButton object added to the program) and then the event, Click. The final return is added automatically. You should not change these.
When the user clicks on this button, we want the program to terminate. There is a system generated Quit subroutine for this purpose so all we have to add is a "CALL Quit" command. Figure 1-13 shows this. We double click on the OS/2 close button at the top left of the window to close and return to the program window.
At this point, I should make a note on capitalization. VX·REXX shows REXX commands in all lowercase as you can see with the Return command. I prefer to have REXX commands in all uppercase but in the VX·REXX programs I write I don't change any commands automatically added by VX·REXX. The McGraw-Hill standard for books is to show commands capitalized so the commands stand out in the book rather than being seen as part of the text. For the text of this book, I will follow the McGraw-Hill convention.
As a last step, we need to align these two objects relative to each other. To do that, you use the pointer icon (top row of the Tools, left icon) and click and hold with the left mouse button at the top left corner of the area containing the objects and drag the cursor so all the objects to align are selected. You then release the left mouse button and click with the right mouse button inside this area to bring up the VX·REXX pop-up menu. From here, you select the Align option and select the type of alignment you want. Here you want to center them vertically, the fourth option from the top. Figure 1-14 shows this. You might also note in Figure 1-14 that both objects have resizing squares, indicating they are both selected.
Figure 1-15 shows the final program as it appears in VX·REXX. By selecting Make EXE File from the Project menu, we are ready to create our stand-along program. Figure 1-16 shows the final program running under OS/2. Notice that the dots and all the VX·REXX items have been removed.
The total time to create this program was about twenty minutes. To write even this simple program in REXX would have taken much longer. Since the program was totally devoted to the user interface, we only had to add one line of REXX code, the "CALL Quit" line we added to the click event of the single PushButton object.
Normally, you think of programming as a programmer sitting at a keyboard and typing computer code. That works with VX·REXX and it's how I write much of my code but there is an easier way, especially if you have trouble remembering all the properties, methods and so on that VX·REXX offers. That easier way is drag-and-drop programming. With drag-and-drop programming, you drag the object you are writing code about to the editor and drop it into your code. At this point, VX·REXX displays a menu of the available things to do and you pick from the menu.
Before we can illustrate this, we need a sample program to work with. Keep in mind that our purpose here is to illustrate the editor and drag-and-drop programming, not the programming concepts themselves. You will understand these as you work through the book but they may be confusing now. Figure 1-17 shows ShowEdit, a sample program that will simply be used to illustrate the editor. You will see four objects on the screen. In order from top to bottom, they are:
Since clicking on PB_1 is the event that is to take the text that is EF_1 and put it into DT_1, we need to click on PB_1 with the right mouse button to bring up a list of possible actions, shown in Figure 1-18. Since we want to define a program to an event, we click on Event to bring up a list of events, shown in Figure 1-19. Since we want the program to do something when the user clicks on PB_1, we click on Click to program the click event. This brings up the VX·REXX editor ready to accept code for the Click event, as shown in Figure 1-20.
The top line you see is a REXX comment that the editor adds to identify the beginning of a section. The second line is the name of the routine. It begins with the name of the object, "PB_1". That is followed by an underscore and the name of the event. If you were to rename the object using its Property Notebook, this name would automatically be changed. The last line is the "return" that REXX uses to mark the end of a subroutine.
At this point, you could begin typing in REXX and VX·REXX code. In fact that is what I normally do. However, for what we want to accomplish, drag-and-drop programming is easier. Before you can use drag-and-drop programming, you must be able to see both the object of interest and the editor. This may require you resizing one or both windows and moving them around.
The first thing we want this code to do is read the contents of EF_1 so we click on EF_1 with the right mouse button and hold that button down while dragging it into the editor. While the mouse cursor remains in the VX·REXX window, EF_1 will move around. Once the mouse cursor moves outside the VX·REXX window, two things will happen. First, EF_1 will pop back to its original location and a line will connect EF_1 with the mouse cursor. Move this line into the editor to initiate drag-and-drop programming.
Once you release the mouse button, a Select An Action box pops up listing all the actions you can perform on that object. For this program, we need to get a value from EF_1 so scroll down to the Get Property section and click on Value. Figure 1-21 shows this. The appropriate code is automatically inserted in the editor, as Figure 1-22 shows.
Once the program has the value from EF_1, we want the value erased from EF_1, so draw another line from EF_1 to the editor to bring up the Select An Action box. This time select Value from Set Property to put another value into EF_1. This brings up the dialog box shown in Figure 1-23 to enter the value. We want a blank value inserted so just click on OK.
Notice in the code that the value from EF_1 is stored in the variable named Value. We want to insert this value into DT_1 so draw a line from DT_1 to the editor. This time, select Caption under Set Property to change the caption of DT_1. Again, this brings up a dialog box. Since the text is stored in a variable, uncheck the Quoted String box and type the variable name (Value) in the field and click on OK. The finished code is shown in Figure 1-24.
Except for programming the Quit button, PB_2, this application is finished. For this, we enter "CALL Quit" in its Click event. Thus, we wrote an entire application pointing with the mouse for all but one quick line of code. Figure 1-25 shows the program running.
However, many of your programs are going to require extensive REXX coding. When that happens, VX·REXX has a feature to help you write this code. For example, let's take the string that gets taken from EF_1 and only use the right twenty five characters. You might recall that the REXX Left function does this but even if you remember that you might not remember its syntax. To get help writing this code, move the cursor to the point where you want the code inserted and select "Insert code..." from the Edit menu. This brings up the EntryField box shown in Figure 1-26.
From this EntryField box, you select the function you wish REXX to perform. The list is surprisingly complete. In this case, we want "Get the leftmost characters from a string." This requires additional information, which VX·REXX requests in the dialog box shown in Figure 1-27. Once this information is completed, the error-free code is inserted into your program at the cursor position. VX·REXX uses the name "newstring" for the variable, but I edited that to restore the string to the Value variable.
While VX·REXX can not write all your REXX code for you, it does an excellent job of remembering syntax and of writing the fairly simple code.
This chapter has provided a review of how to use the various aspects of the VX·REXX program and has shows how to create a simple program using VX·REXX.
© 2002 by Ronny Richardson, All Rights Reserved