═══ 1. Welcome ═══ Welcome to the demonstration version of VX-REXX. Click the Forward button to continue. ═══ 2. Introduction to VX-REXX ═══ The VX-REXX visual development environment for OS/2 REXX is an easy to use, powerful and fully integrated environment for creating applications that exploits the graphical user interface capabilities of OS/2 2.x and Presentation Manager. The product combines a project management facility, visual designer, and an interactive source-level debugger to deliver a very approachable and highly productive visual development environment. Design applications visually Create rich graphical applications quickly and easily using the visual design environment. With the visual designer, you can graphically create Presentation Manager objects, quickly customize their properties, and easily attach REXX routines to the objects. Intergrated development environment Build, test, and debug your applications without leaving the development environment. Then package your applications as an EXE file or PM macro for royalty-free redistribution. The power of the integrated development environment can also be used with your existing REXX applications. Powerful open environment Enjoy the simplicity of event-driven programming together with global editing capabilities essential for professional project management. The Watcom visual development environment is open and extensible through IBM's object oriented System Object Model (SOM) technology. You can access all standard REXX APIs including DB2/2 because the VX-REXX is based on the OS/2 2.x system REXX. Highlights o Easy to use visual development environment o Create and modify objects dynamically at both edit and run time o Powerful project management facility o Advanced interactive source-level debugger o Package your applications as EXE files or PM macros o Access standard REXX APIs including DB2/2 o Create REXX code visually using drag and drop programming o System Object Model (SOM) based object manager o Support for multi-threaded applications o Include OS/2 style help and hints in your applications o Supports SAA CUA '91 objects o Autosizing and alignment of objects o Integrated console window support for existing REXX programs o Royalty-free run time library o Multiple modeless window support o Create PM macros for applications supporting REXX as a macro language ═══ 3. Watcom VX-REXX Client/Server Edition ═══ The VX-REXX Client/Server Edition includes the powerful features of VX-REXX plus database objects that simplify GUI client/server application development on OS/2. This demonstration version includes all of the Client/Server Edition features. o Simplify Database Development The database connection and query objects make GUI client/server application development simple and approachable. With these objects you can quickly build windows to display and update data from a wide range of database systems. Just point and click on a connection object and enter parameters to connect to the database. With a query object you can visually design and test a SQL query. You can then automatically populate a window with objects that display data from the query and provide search and update capabilities. The package also includes a database administrator which lets you easily create new databases, define tables and set the column types and relationships. o Support from DB2 and More VX-REXX Client/Server Edition makes it easy to connect to a wide range of databases. You can create OS/2 client applications which connect to DB2/2 or DB2/6000. VX-REXX Client/Server Edition can also use IBM's DRDA support on OS/2 to access DB2 for MVS, DB2/400 for AS/400, and DB2/VSE and VM (SQL/DS) for VM and VSE. Also supported are Watcom SQL and ODBC enabled databases. o Visualize Your Data Create more than a dozen types of charts with the chart object. Customize your charts from 150 display options including chart type, 3D view and titles. Charts can be bound directly to SQL queries making it easy to create rich visual client/server applications. You can even build interactive charts since the charting object supports run-time events. Click the Forward button to continue. ═══ 4. How to use this tutorial ═══ This tutorial shows you how to create applications with VX-REXX. The first two parts show you how to use the tools and the system to create applications. The third part of the manual is an alphabetical reference for all components of the VX-REXX software. At any point in the tutorial, you can click the Back button to review a previous page. You can also press Forward to skip ahead. To see an outline of the whole tutorial, press the Contents button. ═══ 5. Samples included with the demonstration version ═══ A number of sample programs come with the demonstration version of VX-REXX. They are located in the Samples folder, in your Watcom VX-REXX folder. All samples come ready to run with full source code. Here is a list of the sample programs: Bounce A globe bounces around a window, driven by a timer. Button A simple first application with push buttons. Calculator A four function calculator. CUA 91 Skeleton The CUA 91 sample demonstrates several VX-REXX features and programming techniques relevant to developing CUA'91 compliant applications. It also demonstrates how to use subroutines contained in OBJECT.VRS to simplify the process. DDE Explorer A program that lets you converse with DDE servers. DragDrop A simple example of adding drag-drop to your programs. Employee Database A database sample that uses the REXX API to IBM DB2/2 or Watcom SQL. File browser A program that lists various information about files in a container. Hint and Help A demonstration of the run time help facility in VX-REXX. Hocus focus This program displays the PM window handle of the window that currently has the input focus. Mind Game A pattern guessing game. MMW An example of modal and modeless windows. Movies A multimedia sample that plays OS/2 movies (AVI files). Notebook A simple program that uses the notebook object. Popup A demonstration of using pop-up menus. Printing Sends a file to printer. RGB Display colors using a value set object and some sliders. Scan An EPM macro that scans through the current file looking for REXX labels. Threads A sample of a multithreaded program. Window Controller This program lists the top level frame windows on the desktop and lets you minimize, maximize, restore, and shake them. There are a number of samples that use the database objects available in the Client/Server Edition of VX-REXX. They are located in the Database Samples folder which is in your Watcom VX-REXX folder: Sample Database Generator This program creates a sample database used in the other database sample programs. This program can create DB2/2 or Watcom SQL databases. Getting Started This is a simple project that uses bound objects to display database values. Master/Detail This program illustrates a sample master-detail form. This is a window with two queries, one for the master table and one for the detail table. Order Entry Application This program is an order entry system for a fictitious company. It stores information about customers, products, and orders in a sample database. It is a more complex example that shows how to use a number of queries on many windows. There are a number of samples that use the chart object available in the Client/Server Edition of VX-REXX. They are located in the Chart Samples folder which is in your Watcom VX-REXX folder: Chart titles This sample program shows how to change title options. Click This sample shows you how to respond to events on chart objects. Data This program demonstrates changing chart data values, row names, and column names. Drill Down This program shows how to use the Click event to drill down into a chart. Database Charting 1 Database Charting 2 These programs shows the use of bound charts that display data directly from a database. Group Options This program shows how to set the slice cut for a section in a pie chart. Mouse This sample shows you how to respond to right mouse clicks on chart objects. Print Use this sample to see how you can print charts. Row and Column This sample shows the way to add rows and columns to a chart at run time. Simple Click This program shows how to find out what part of the chart a user clicked on. ═══ 6. About the demonstration version of the software ═══ The demonstration version of VX-REXX differs from the full version in a number of ways: o You cannot save projects, make standalone executables, or make macro files using the demonstration version. o The IBM Help Compiler (IPFC) is included in the Client/Server Edition, but not in this demonstration version. o The EXEHDR utility is included in the Client/Server Edition, but not in this demonstration version. ═══ 7. System requirements ═══ The minimum recommended configuration for Watcom VX-REXX is a 20 megahertz 386 personal computer with 8 megabytes of memory. About 6 megabytes of hard disk space are required to install the base software; another 7 megabytes are required if you install the Client/Server Objects (database and charting). 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. ═══ 8. How to contact Watcom ═══ ═══ 8.1. In North America (and all other locations not listed below) ═══ Watcom International Corporation. 415 Phillip Street, Waterloo, Ontario, CANADA, N2L 3X2 Technical Support hot-line: (519) 886-3700 fax: (519) 747-4547 BBS: (519) 884-2100 Internet: tech@watcom.on.ca Compuserve: type GO WATCOM General Inquiries tel: (519)886-3700 fax: (519)747-4971 Sales, upgrades, other product orders, and reseller inquiries/orders: 1-800-265-4555 (toll free in North America) ═══ 8.2. In Europe ═══ Watcom Europe Limited. PO Box 64, LIVINGSTON, West Lothian, EH54 7AE, UNITED KINGDOM Technical Support United Kingdom tel: 0506 460112 fax: 0506 460115 Other Locations tel: (44) 506 460112 fax: (44) 506 460115 BBS: (519) 884-2103 Internet: tech@watcom.on.ca Compuserve: type GO WATCOM General Inquiries United Kingdom tel: 0506 460112 fax: 0506 460115 Other Locations tel: (44) 506 460112 fax: (44) 506 460115 Sales, Upgrades, other product orders, and reseller inquiries/orders: United Kingdom Toll Free tel: 0800 44 44 55 fax: 0800 55 54 55 Germany Toll Free tel: 0130 81 88 62 fax: 0130 81 88 63 France Toll Free tel: 05 90 81 35 fax: 05 90 81 36 All Other Locations tel: (44) 506 460112 fax: (44) 506 460115 ═══ 8.3. In Japan ═══ Lifeboat, Inc. 3-6 Kanda -- Nishikicho, Chiyoda-ku, Tokyo, Japan, 101 Japan tel: (03) 3293-4711 fax: (03) 3293-4710 ═══ 9. A simple program ═══ This chapter provides a brief introduction to the VX-REXX development environment through a tutorial. We will learn how to start and stop VX-REXX and create, and run a simple application. In addition, the drag and drop programming feature of VX-REXX will be used to reduce the time and effort needed for writing code. The same steps used in this tutorial can be used to develop all VX-REXX applications. Subsequent chapters provide more details about each step. In this tutorial, you will create an application which consists of an entry field, push button, and list box. When run, text typed in the entry field will be added to the list box using the push button. ═══ 9.1. Starting VX-REXX ═══ You can start VX-REXX by double clicking on the VX-REXX icon in the Watcom VX-REXX folder on your desktop. After it starts, you will see a window similar to Figure 1. Figure 1 The initial VX-REXX screen. The VX-REXX interface consists of a menu bar, a tool palette, and a project window containing a grid of dots. The menu bar contains the commands that are used to create and run applications. The tool palette contains the objects which can be placed in the project window to create the user interface for an application. Note: The demonstration version of VX-REXX automatically opens the tutorial book when it starts up. ═══ 9.2. Creating an application ═══ There are three basic steps to building a VX-REXX application: 1. Creating the user interface by adding objects to the project window. 2. Customizing each object's properties. 3. Attaching code to each object. We will go through these steps in the following sections to create a simple application. ═══ 9.3. Creating the user interface ═══ Creating the user interface is the first step in building an application. The interface to this application has three objects: an entry field, a push button, and a list box. We will start by adding the entry field to the window: 1. Click on the Tools menu and then choose EntryField. 2. Position the mouse pointer near the top left corner of the project window. The cursor will change to a cross while it is positioned on the project window. 3. Hold down mouse button 1 and drag the mouse down and to the right until the entry field is approximately the size of the one shown in Figure 2. Figure 2 The entry field added to the window. 4. Release the mouse button. Add the push button to the window using a similar procedure: 1. Click on the Tools menu and then choose PushButton. 2. Position the cursor below the bottom left corner of the entry field. 3. Hold down mouse button 1 and drag the mouse down and to the right until the push button is approximately the size of the one shown in Figure 3. Figure 3 The push button added to the window. 4. Release the mouse button. Repeat the above steps using the ListBox item from the Tools menu to make your window similar in appearance to Figure 4. Figure 4 The entry field, push button and list box on the window. Finally, to improve the appearance of the window, center the three objects on the window as follows: 1. Position the cursor on the entry field. 2. Press and hold down mouse button 1. Sizing handles will appear along the border of the entry field. Move the cursor over the push button and then over the list box. Now all three objects will have sizing handles along their borders. The screen should look similar to Figure 5. Figure 5 The entry field, push button and list box are selected. 3. Release mouse button 1. 4. Position the cursor on the entry field once again and press mouse button 2 to invoke the VX-REXX pop-up menu. 5. Select the Align menu item using mouse button 1. A second menu will appear. From this menu, click on the menu item used for centering objects as shown in Figure 6. Figure 6 The menu item used to centre objects. The push button and the list box will now be centered underneath the entry field. 6. Position the cursor over the right border of the window. The cursor shape should change to a sizing arrow. 7. Hold down mouse button 1 and move the cursor left or right to adjust the width of the window until the objects are centered. 8. Click on the window background to deselect the objects. The screen should appear as in Figure 7. Figure 7 The objects centred on the window. All the objects we need have been created. Now their properties must be customized. ═══ 9.4. Customizing object properties ═══ Each VX-REXX object has properties such as color and size which can be customized. An object is given default property values when it is first created. Often, these properties need to be changed. The entry field has a font property which determines the font used to display text. The height of the entry field should be set according to the size of the font being used. This step can be done automatically using the entry field's Autosize property. If this property is set to 1, the height of the entry field will be adjusted automatically based on the font being used. Initially, the Autosize property is set to 0. Change it to 1 as follows: 1. Click mouse button 2 anywhere over the entry field. A pop-up menu will be displayed. 2. Choose the Open... menu and then choose the Properties menu item. A property notebook will be displayed. 3. Click on the Size index tab. The Size page will be displayed as in Figure 8. Figure 8 The size page of the property notebook. 4. Click on the check box marked Autosize. 5. Close the entry field's property notebook by double clicking on the title bar icon in the upper left corner. The text which appears on a push button is called the caption and is determined by the push button's Caption property. To set the caption of the push button to Add Item: 1. Click mouse button 2 anywhere over the push button, choose the Open... menu and then choose Properties to open the push button's property notebook. 2. Click on the Text index tab. The Text page will be displayed as in Figure 9. Figure 9 The text page of the property notebook. 3. Click on the Caption entry field and type: Add Item 4. Close the property notebook. The text Add Item will appear on the push button. Lines in a list box are displayed one below another, beginning at the top. The last line in the list box may not appear completely, depending on the height of the list box. The height must be adjusted if this characteristic is undesirable. To have the height adjusted automatically, set the AdjustHeight property of the list box as follows: 1. Open the property notebook for the list box using the same method as before. 2. Turn to the Size page by clicking on the Size index tab. 3. Click on the AdjustHeight check box. By default, items in a list box will be sorted in ascending order. For our application, we want items to be listed in the order they are added to the list box. The list box's Sort property must be changed: 1. With the list box property notebook open, turn to the List page by clicking on the List index tab. 2. Click on the scroll arrows in the Sort drop down combobox. 3. Choose none from the drop down list. 4. Close the property notebook by double clicking on its title bar icon. Finally, set the text that will appear on the window title bar: 1. Open the property notebook for the window. Note that the cursor must be positioned on the window but not over any object in the window when pressing mouse button 2. 2. Index tabs for all pages in the notebook cannot be seen at once. The tab scroll arrows at the top and bottom right corners of the notebook, as shown in Figure 10, must be used to view all the index tabs. Press mouse button 1 on the bottom right tab scroll arrow until the Text index tab appears. Figure 10 The window's property notebook. 3. Open the Text page of the notebook by clicking on the Text index tab. 4. Click on the Caption entry field and type: Sample 5. Close the property notebook. The first two steps in developing the sample application are complete: creating the objects and customizing their properties. ═══ 9.5. A preliminary run ═══ Although the sample program is not finished you can run it to see what it will look like when complete. To run it, click on the Run menu and choose Run project. This will hide VX-REXX and run the application, which should appear similar to Figure 11: Figure 11 A test run of the sample program. Notice that the background of the window no longer contains a grid of dots. Type text into the entry field to see how it will appear. Use the Tab key to move between the objects. Click on the push button. Nothing happens because no code has been attached to the push button. Attaching code to the objects in the window is the next step in developing our sample application. Exit the application and return to VX-REXX by clicking on the title bar icon and choosing Close. ═══ 9.6. Attaching code to objects ═══ In this application pressing the push button will add the text in the entry field to the list box. We will use the drag and drop programming feature of VX-REXX to help us write the code which will perform this task. First we must obtain the text in the entry field. To attach this code to the push button: 1. Open the push button's property notebook and turn to the Event page by clicking on the Event tab. Code can be attached to the push button for any events which appear on this page. 2. Select Click and then click on Open to invoke an editor we can use to write our code. The editor will contain a skeleton for an event routine, as shown in Figure 12. Figure 12 Event routine skeleton The first line in the editor is a comment, the second is the name of the routine, and the last line contains a REXX return instruction which needs to be executed at the end of the routine. The REXX code we place in this routine will be executed when the push button is pressed. 3. At this point, we could write code manually but there is a much easier method. Press and hold down mouse button 2 over the entry field. Now move the mouse over the editor. The editor window and the application window may need to be moved apart before this step can be done. A line joining the mouse to the entry field will appear as in Figure 13: Figure 13 Getting the text in the entry field. 4. Release mouse button 2. A dialog box will appear which lists descriptions of all the entry field methods which can be invoked and all the entry field properties which can be set or retrieved. 5. Click on the Value item under the Get property heading. We need to get the Value property because it contains the text in the entry field. Now click on OK. The following instruction is placed at the insertion point in the editor: value = VRGet( "EF_1", "Value" ) This instruction will assign the variable value with the text in the entry field. The automatic code generation feature of VX-REXX we have used is called drag and drop programming. Using this feature, you can create REXX applications without having to memorize the syntax of VX-REXX functions and methods. The next step is to add the text to the list box: 1. Press and hold down mouse button 2 over the list box and then move the pointer over the editor window. A line joining the cursor to the list box will appear. 2. Release mouse button 2. A dialog box will appear listing all the list box methods that can be invoked and all the list box properties which can be set or retrieved. Click on the Add a string item under the Methods heading and then press the OK button. 3. Another dialog box, as shown in Figure 14, will appear. Figure 14 The Add a String dialog box. 4. Click on the string field and type the following: value 5. Click on the Quoted String check box. Now it should not be checked. 6. Press the OK button. The REXX code to add the text to the list box will be placed underneath the previous instruction, as shown in Figure 15. Figure 15 The event routine for the push button. After getting the text, we should clear the entry field to allow new text to be entered: 1. Press and hold down mouse button 2 over the entry field and then move the mouse over the editor window. 2. Release mouse button 2. A dialog box will appear. 3. Click on the Value item under the Set property heading and then press the OK button. 4. Click on OK from the second dialog box. The editor window should now appear as in Figure 16. Figure 16 The unfinished push button event routine. The push button will have the focus when this routine is executed. We should set the focus to the entry field so that new text can be entered immediately: 1. Press and hold down mouse button 2 over the entry field and then move the mouse over the editor window. 2. Release mouse button 2. 3. Click on the Set focus to object item underneath the Methods heading and then press the OK button. A line of code will be inserted below the previous lines in the editor window. 4. Close the editor window by double clicking on its title bar icon. The push button event routine is now complete and is shown in Figure 17. We can perform a test run to see if it works correctly. Figure 17 The complete push button event routine. ═══ 9.7. A test run ═══ To run the application, click on the Run menu and choose Run project. The application window will look the same as it did during the first run. We have not changed its appearance. However, try clicking on the push button after typing text into the entry field. Now the text is added to the list box. Also, the entry field is cleared and is given the focus again. The push button click routine we created appears to be working as it should. Try adding more text to the list box. Also, try pressing the push button when there is no text in the entry field. It seems as though no action is performed. However, if more text is added to the list box, you can see that a blank line is inserted when the entry field is empty and the push button is pressed, as shown in Figure 18. Figure 18 Adding text to the list box. This behavior is undesirable and needs to be prevented with the addition of more code. Also, to make the application easier to use, we should allow text to be added to the list box with the use of the Enter key. ═══ 9.8. Improving the application ═══ A push button can be enabled or disabled. When enabled, a push button responds to events such as a click event. The push button in our application has always been enabled. When a push button is disabled it does not respond to any events and also appears grayed. In particular, a disabled push button cannot receive the focus and will not respond when pressed. We will use this property of push buttons to prevent blank lines from being added to the list box: 1. Press mouse button 2 anywhere over the entry field to activate the VX-REXX pop-up menu. 2. Click on events and then click on change. The editor window will appear with the skeleton of a routine, as shown in Figure 19. Figure 19 The entry field change routine. This routine will be executed whenever the contents of the entry field change. We need to determine if the entry field has become empty and if this is the case, we will disable the push button to prevent it from adding any text to the list box. 3. Press and hold down mouse button 2 over the entry field, move the mouse over the editor window and then release the mouse button. As before, a dialog box will appear. 4. Click on the Value item underneath the Get property heading and then press OK. The code to get the contents of the entry field will be generated. 5. Add the following line of code at the insertion point: if value = "" then do Press the Enter key and then the Tab key at the end of this line. 6. At this point, we have determined that the entry field is empty so we must disable the push button. Press and hold down mouse button 2 over the push button, move the mouse over the editor window and then release the mouse button. A dialog box listing all methods and properties of a push button will appear. 7. Click on the Enabled item under the Set property heading and then press OK. A second dialog box will appear, as shown in Figure 20. Figure 20 The enabled property dialog box. Click on the Enabled check box so that it is not checked. Press OK. The instruction to disable the push button is placed at the insertion point in the editor window. 8. Now we need to add the code that will enable the push button when the entry field is not empty. Add the following lines at the insertion point: end else do Press the Enter key and then the Tab key at the end of the second line. The editor window should appear as in Figure 21. Figure 21 The incomplete entry field change routine. Press and hold down mouse button 2 over the push button, move the mouse over the editor window and then release the mouse button. From the dialog box click on the Enabled item under the Set property heading and then press OK. Press OK again on the second dialog box which appears. The code to enable the push button is inserted into the editor window. 9. One last line needs to be added to the routine: end The complete routine is shown in Figure 22. Figure 22 The complete entry field change routine. Now we must make the push button disabled when the application is first run: 1. Open the push button's property notebook and turn to the Style page. Click on the Enabled check box so that it is not checked. 2. Also on this page is the Default check box. Click on this check box so that it becomes checked. Now, when the Enter key is pressed the push button click routine will be executed, as though the push button had been pressed. This behavior will allow text to be added to the list box by pressing the Enter key. We can easily make another improvement to the application by using the Hints feature of VX-REXX: 1. Turn to the Hint page of the push button's property notebook. Type the following in the Hint entry field: Add the text to the list box. 2. Open the entry field's property notebook, turn to the Hint page and type the following: Enter text. 3. Open the window's property notebook, turn to the Hint page and click on the ShowHints check box. Select the Bottom item from the Status Area drop down combobox. A status bar will appear at the bottom of the window, as shown in Figure 23. Figure 23 The status bar for showing hints. The status bar may overlap with the bottom of the list box. If this is the case then the list box can be raised or its height can be decreased. The previous steps add hints to the application. When the mouse is moved over the push button, its hint text will be displayed in the status bar. Similarly, when the mouse is positioned over the entry field, its hint text will be displayed. We can now try out the improvements we have made. ═══ 9.9. Running the application ═══ Run the application as before by clicking on the Run menu and choosing Run project. Move the mouse over the entry field and then the push button to see their hints. The application window is shown in Figure 24. Figure 24 Running the finished application. Try typing in text and adding it to the list box with the use of the Enter key as well as the push button. Notice that the push button becomes disabled whenever the entry field is empty. Although this is a simple application, it would take considerably more effort and expertise to create it with other languages and development tools. However, with VX-REXX features such as drag and drop programming, we have created it easily with little knowledge of OS/2 or the REXX language. ═══ 9.10. Stopping VX-REXX ═══ To exit VX-REXX and return to the OS/2 desktop, click on the VX-REXX title bar icon and choose Close or double click on the title bar icon. In this tutorial, the following techniques have been learned: 1. Adding objects to a window. 2. Modifying an object's properties. 3. Using the VX-REXX drag and drop programming feature to add code. 4. Testing a project. These are the basics. The following chapters expand on these basics to show how to create and maintain complex as well as simple applications.