═══ 1. Special Notices ═══ References in this help to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM licensed program in this help is not intended to state or imply that only IBM's licensed program may be used. Any functionally equivalent product, program, or service that does not infringe any of IBM's intellectual property rights may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, except those expressly designated by IBM, is the user's responsibility. IBM may have patents or pending patent applications covering subject matter in this help. The furnishing of this help does not give you any license to these patents. The following terms, denoted by an asterisk (*) in this help, are trademarks of the IBM Corporation in the United States and/or other countries: IBM OS/2 Operating System/2 Presentation Manager WorkFrame/2. The following terms used in this publication are trademarks of Microsoft Corporation. They are denoted by a double asterisk (**) when they appear in the text. Microsoft Windows. This help contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. ═══ 2. Start Here ═══ Welcome to the IBM* WorkFrame/2* tutorial. In this tutorial, you will learn what the WorkFrame/2 product is and how to use it. The tutorial is divided into several sections: About this Tutorial Tells you how to use the tutorial. Overview Looks at the main, underlying concepts behind the product. Learning to Use the WorkFrame/2 Product Takes you step-by-step through the development of a sample application. Select the Forward push button to continue. ═══ 3. About this Tutorial ═══ The first section of the tutorial gives an tour of the product. After the overview, you will learn how to use the WorkFrame/2 product through a series of step-by-step lessons that take you through the development of a sample project. This part of the tutorial is interactive and you will be using the WorkFrame/2 product itself with the sample CLC project as you follow the steps. Though you can use the Table of Contents to go to various parts of the tutorial in any order you wish, first-time users should go through it sequentially by clicking on the Forward push button when finished with the current panel. Doing the lessons in the tutorial takes approximately one hour. The tutorial does not describe every control within the WorkFrame/2 product. Once you have finished the tutorial, you can learn more by using the online help. ═══ 4. Overview ═══ The WorkFrame/2 product offers a unique application development environment that you can easily tailor to your own personal needs. It takes full advantage of the OS/2* Workplace Shell* interface to create a customizable and user-friendly graphical interface that simplifies the process of organizing and building software projects. The Workplace Shell enhances your general productivity through its object-action association techniques. With the WorkFrame/2 product, you enhance your programming productivity by using similar object-action techniques specifically customized for software development. One of the major tasks any programmer faces is the problem of organizing all the code for a software project. Using containers designed specifically for code, the WorkFrame/2 product lets you organize your files in a clear and meaningful manner. See Projects and Composite Projects for more information. Once you have organized code, you will not only need to edit, compile, and debug it, but you will likely want to use special tools such as icon editors and performance profilers too. Ideally, you will want these actions easily accessible and easily done. Using the WorkFrame/2's object-action approach, the actions you need are available right on the object's pop-up menu. For example, if the icon represents a C++ file, you compile it just by selecting the compiler you want from its pop-up menu. See Performing Actions for a full explanation. In summary, with the WorkFrame/2 product, you can: o Group source code into containers to give you a visual perspective of how your software projects are organized. o Organize the actions used to build software applications in a way that is more geared toward the development process than the Workplace Shell association techniques are. o Set options for actions quickly and easily using graphical user interfaces. o Integrate the tools you like to use. If you have a favorite editor, your own bitmap viewer, or other tools, you can integrate them along with WorkFrame/2-enabled tools provided by vendors. o Capture output from actions in a Presentation Manager* (PM) window (see WorkFrame/2 Monitor Window). o Create make files and manage object code libraries. And because the WorkFrame/2 product uses many of the OS/2 Desktop features, you will find it to be a natural extension of the Workplace Shell that is ideal for developing software. ═══ 4.1. WorkFrame/2 Folder ═══ Once the WorkFrame/2 has been installed, you will see the WorkFrame/2 icon on the Desktop. Clicking on the WorkFrame/2 icon causes the WorkFrame/2 folder to open as shown in the following figure. The WorkFrame/2 Folder The icons in this folder represent various components of the WorkFrame/2 product: Setup Is the Setup program. Use it when you want to reinstall the WorkFrame/2 program, add users to a LAN-based WorkFrame/2 installation, or migrate files from previous versions to this version. Tools Contains development tools such as utilities for creating make files and managing libraries of object modules. Information Contains online information that will help you use the product. Samples Contains the sample code supplied with the WorkFrame/2 product. Actions Profiles Contains the profiles defining actions (such as compiling and linking) used in the software development process. Action Log Lets you view and save a record of your activities. ═══ 4.2. Information Folder ═══ Online information is available in context-sensitive help and online books. With context-sensitive help, you press the F1 key or select the Help push button to get context-sensitive help for the selected user interface control. To access an online book, open the Information folder in the WorkFrame/2 folder and select what you want to view. The Information folder contains tutorials and an online book: IBM WorkFrame/2 Tutorial Teaches you the WorkFrame/2 basic concepts with a step-by-step example of building a software application. IBM Library Manager Tutorial Teaches you how to manage libraries of object modules using the IBM Library Manager utility. LIB Utility Reference Describes the command line interface of the IBM Library Manager. ═══ 4.3. Templates Folder ═══ Some of the most important components are not in the WorkFrame/2 folder but in the OS/2 Templates folder. When you open up this folder, you see three new templates: o WorkFrame/2 Project o WorkFrame/2 Composite Project o Actions Profile o Action Log. From these, you can create projects, composite projects, and profiles in the same way you create other OS/2 objects. ═══ 4.4. Projects ═══ The development of software applications can usually be divided into different components. For example, the components of a software application could consist of an executable file, a dynamic link library, and an online book. There might also be components that are not part of the final product but a component of the development process, such as a class library. With the WorkFrame/2 product, these different components are referred to as projects. A project visually appears as a container holding the source code for one of these components (see Figure A Composite Project (CLC) and Two Projects (DLL and LIB)). Projects also contain information used to build the component such as tool options and a make file. ═══ 4.5. Composite Projects ═══ Composite projects are containers holding projects or other composite projects. Use composite projects to organize the projects associated with the software application. In the example mentioned previously, there were projects for the following components: o Executable file o Dynamic link library o Class library o Online book. When open, the composite project for the example would appear as below. A Composite Project (CLC) and Two Projects (DLL and LIB) ═══ 4.6. Actions Profiles ═══ The WorkFrame/2 product uses the term action in the same sense that the OS/2 Workplace Shell does: an action is a command performed on an object. In the WorkFrame/2 environment, objects include files, projects, and composite projects. You can control which actions appear on the pop-up menus of these objects and set options for each action. The set of actions associated with one or more projects is known as an actions profile. Each actions profile is represented by an icon. You can see the actions in the actions profile by opening up its Settings note book. Actions can be configured using an interface like that shown here. Changing an Action in an Actions Profile The actions profile defines a number of things, including: o The class you want the action to belong to. Actions belonging to the same class are grouped together (see Performing an Action). o The command used to perform each action in the actions profile. In Figure Changing an Action in an Actions Profile, the action with the name Link is accomplished by starting the program link386.exe. o The file mask on which the action can be performed. Most actions are performed on only certain types of files. For example, an action that starts a C compiler would not be useful on executable (.EXE) files. Therefore, to specify that the action only appears on the menus of C source files, you would specify the *.C mask. o The name of the dynamic link library (DLL) containing the interface for setting the action's options. o Environment variable settings (not shown). For example, you might want to append the PATH environment variable with another path whenever the action profile is used. You can also set your own environment variables. Whatever you specify overrides the current environment settings when the action is started. When the action is completed, the environment reverts to the state it had before the action was started. Language products, such as compilers, that are enabled for the WorkFrame/2 product typically supply an actions profile and options DLL that you can add to the ones included with the WorkFrame/2 product. Actions are not limited to those used directly to build the software application. Any tools, such as those for editing icons or counting lines of source code, can be integrated as an action through an actions profile. ═══ 4.7. Actions and Projects ═══ Each project has an associated actions profile. You specify the actions profile in one of the settings note book pages for the project. Another page (see Figure Actions Page in a Project's Settings Note Book) lets you specify options for each action. Actions Page in a Project's Settings Note Book The Options... push button on this page lets you specify the options to be used when the selected action is invoked. If the program used to perform the action is enabled for the WorkFrame/2 product, you can use a customized graphical user interface like the one in Figure Options Interface for the OS/2 Linker to select the options. If no customized interface is available, use the one provided by the default options DLL included with the WorkFrame/2 product. Options Interface for the OS/2 Linker Because the options are saved with the project, each project has its own, unique set of options for each action. ═══ 4.8. Performing Actions ═══ Setting up projects and actions is only the organizational aspect of software development. Most of the development process is a cycle of creating the source code, building it into an executable form, and then modifying it until you get the product you want. How do you perform these actions using the WorkFrame/2 product? When you want to perform an action on an object in the Workplace Shell (such as editing a file), you just point to the icon and select an action from its menu. In the same way, with the WorkFrame/2 object-oriented approach, you first select the icons you want to perform an action upon, and then you select an action from a pop-up menu. Because the options for the action are set in advance and stored with the project, you can ignore them unless you want to change them. The actions you can perform are not limited to those provided by the WorkFrame/2 product. You can define new actions in the actions profile and these actions will automatically appear on pop-up menus such as the one shown here. Performing an Action You can choose to display the output of an action in a text window, a full-screen window, or a WorkFrame/2 monitor window (see below). WorkFrame/2 Monitor Window If an error message in the window contains the name of the file in which the error occurred, you can click on the message to start an editing session for that file. If the error message also contains the location of the error within the file, a WorkFrame/2-enabled editor (such as the OS/2 Enhanced Editor) will automatically scroll to the error's location and highlight it. These capabilities make the development process smoother and more efficient. ═══ 5. Learning to Use the WorkFrame/2 Product ═══ Whether you have used a previous version of the WorkFrame/2 product or not, the more familiar you are with the OS/2 Workplace Shell basics, the more productive you will be with the WorkFrame/2 Version 2.1 product. View the OS/2 Start Here tutorial to learn about the Workplace Shell if you have not already done so. Because the WorkFrame/2 interface offers a number of features that are ideal for mouse users, this tutorial describes the steps as performed with a mouse. If you prefer, you can also perform these steps using your keyboard. Shortcut keys are indicated on menus, and underlined in windows. For example, an action can be selected by typing the shortcut key that is underlined in the menu, instead of selecting that action with the mouse. If you want more information while using the tutorial, consult the WorkFrame/2's online help by placing the selection focus on the control and pressing F1 or the Help push button. ═══ 5.1. Lesson 1: A Sample Application ═══ The sample application you will build is called the Command Line Calculator. To build it, you need the IBM C/C++ Tools compiler and the make utility (NMAKE.EXE) that comes with IBM Developer's Toolkit product. If the Developer's Toolkit was installed before the WorkFrame/2 product was installed, the action starting NMAKE.EXE already exists in the default actions profile. If the Developer's Toolkit was installed after the WorkFrame/2 product was installed, you need to: 1. Open the IBM WorkFrame/2 V2.1 folder. 2. Open the Actions Profiles folder. 3. Open the Default Actions Profile and the IBM Toolkit Profile. 4. In the IBM Toolkit Profile, select the action with class MAKE and name NMake. Hold down mouse button 2, press the Ctrl key, and drag the action to the Actions list in the Default Actions Profile. A copy of the action will appear in the default actions profile. 5. Close both actions profiles and the Actions Profiles folder. Note: Be sure to check the READ.ME file for any information about the tutorial before you do it. ═══ 5.2. Lesson 2: Organizing the Project ═══ The Command Line Calculator has been divided into four components: o A class library file containing class definitions. o The executable file which starts and ends the program. o The dynamic link library containing the calculator's functions. o Online documentation that can be viewed using the OS/2* view command. Visually, this application will appear as a composite project containing four project icons. Note: Because of the simplicity of the sample application, the number of source files per project is small. In a practical application, the number of source files would be greater and the benefits of organizing them through projects would be more evident. ═══ 5.3. Lesson 3: Creating a Composite Project ═══ You create WorkFrame/2 objects in the same way as you would create other OS/2 Workplace Shell objects. 1. Open the OS/2 Templates folder. 2. Find the template for the WorkFrame/2 Composite Project and drag it to the Desktop. When you drop the the template on the Desktop, it changes into an actual composite project. 3. Open the Settings note book for the composite project now on the Desktop. (Like other OS/2 objects, you can open the Settings note book by clicking once with mouse button 2 to display the pop-up menu and then selecting OpenSettings.) 4. Go to the General page and change the Title to "Command Line Calculator". 5. Go to the Background page. 6. Select Color as the Background and then select the Change color... push button to open the color palette. 7. Select a new color from the color palette and then close the palette. 8. Close the Settings note book. 9. Open the composite project by double-clicking on it with mouse button 1. You should now see a folder on your screen with the title "Command Line Calculator". It will have the background color you selected. Colors and fonts of WorkFrame/2 projects can be changed using the standard techniques that come with the OS/2 WorkPlace Shell. ═══ 5.4. Lesson 4: Creating a Project ═══ Now that you have created the composite project, you need to create the projects that comprise the Command Line Calculator. In this lesson, you will create the project for the dynamic link library of the Command Line Calculator. This DLL contains the functions available to the calculator. 1. Find the WorkFrame/2 Project template (also in the Templates folder) and drag it into the Command Line Calculator folder. When it reaches the latter folder, the template changes into an actual project. 2. Close the Templates folder. 3. Double-click on the Project icon you just created to open its Settings note book. 4. Go to the General page of the project's Settings note book and change the Title to "Functions". ═══ 5.5. Lesson 5: Adding Code ═══ In these steps, you will specify where the source code resides for the Functions project. The code has already been supplied with the WorkFrame/2 product so you do not have to write it. 1. Go to the Source page (of the Functions - Settings note book). 2. In the Source directories list box and type drive:\wfv2_directory\PRJ\CLC\DLL drive:\wfv2_directory\PRJ\CLC\HEADERS Note: Replace drive:\wfv2_directory with the drive and directory where the WorkFrame/2 product is installed on your computer. Because the sample code was installed with the WorkFrame/2 product, these directories already exist. If they did not already exist, the WorkFrame/2 product could create them for you. 3. In the File masks list, enter the following extensions one per line: *.CPP *.H *.DEF *.MAK *.DLL By specifying file masks, you can control what types of files are displayed within the project. 4. Open the pop-up menu of the Functions project icon and select OpenIcon view. You will see the files contained in the directories you specified. ═══ 5.6. Lesson 6: Completing the Project Settings ═══ 1. Turn to the Target note book page. Ensure that drive:\wfv2_directory\PRJ\CLC\DLL is selected as the Working directory. (Remember, drive:\wfv2_directory is the directory where the WorkFrame/2 product is installed on your computer.) When you drag a file to a base project, the file is placed in this directory. New files created by actions are also placed in the target directory. 2. In the Make file name field, type CALCFUNC.MAK. You may have to delete or type over the default entry. CALCFUNC.MAK is the name of the make file to be used to create the target file. You will create this file later in this tutorial. 3. Go to the second Target page. In the Target program file name field, type CALCFUNC.DLL. The target file name defines the object to be built by the project (such as an executable module or DLL.) 4. Go to the Profile page. 5. Open the Actions Profiles folder (located in the IBM WorkFrame/2 folder) and drag the CLC Actions Profile to the Actions Profile field in the top left part of the Profile page. The field now indicates the path to the command line calculator's actions profile and its Title is now shown as CLC Actions Profile. Note: If you move the Actions Profile folder after you have specified a project's actions profile, you may get messages saying the actions profile cannot be found. Should this happen, open the actions profile and close it again. You have now specfied what files make up the project. When you selected the profile, you selected what set of actions can be used to build the project's target program. ═══ 5.7. Lesson 7A: About Actions Profiles ═══ The Overview at the beginning of the tutorial gave a brief introduction to actions and actions profiles. In the following sections, you will examine, in more detail, how the action that starts the compiler has been set up. Unlike other parts of the tutorial, the following steps do not require you to add or change anything; they simply show you how actions are set up. ═══ 5.8. Lesson 7B: How Actions Appear In Menus ═══ In the WorkFrame/2 environment, you can define a wide variety of attributes for an action. The most important ones are described here. (See the online help for information about those attributes which are not described here.) Some attributes control how actions appear on menus. ╔══════════════════════════════════════════════════╗ ║ Project ║ ╠══════════════════════════════════════════════════╣ ║ ┌──────────────── Classes of actions ║ ║ ├────│────┤ ║ ║ │...  │ ║ ║ ├─────────┼────────┐ ║ ║ │COMPILE │ Default│ ║ ║ │EDIT │ IBM C++│ ║ ║ ┌├─────────┤ ABC C++│ ║ ║ ││... ├────────┘ ║ ║ │├─────────┤  ║ ║ │ │ │ ║ ║ └───┘ └────────── Names of actions ║ ║ FILE.CPP ║ ╚══════════════════════════════════════════════════╝ The above diagram shows the pop-up menu of a file. The pop-up menus of projects and composite projects are similar except that the classes are pointed to by an Actions  item. How does an action (like one for invoking a C compiler) appear on the menu of a file? First, the action must be part of the actions profile associated with the project. Each action within the profile has a list of file masks and file types that indicate what files are valid source for the action. For example, an action that compiles C files (*.C) into object (*.OBJ) files should appear on the pop-up menu for C files. The same action would be inappropriate for object files. Then the actions are grouped into classes. (An action's class is defined when you are adding the action to the actions profile.) For example, if you have actions for compiling with different compilers, you could group them under the class COMPILE. When the menu is first opened, only the classes of actions are shown. To display the actions belonging to the class, click on the arrow ('') button to the right of the class. Actions that act on the project rather than specific files can appear on the project's pop-up menu. Again, you can control this feature through the actions profile. ═══ 5.9. Lesson 7C: Setting Up an Action ═══ 1. Open the CLC Actions Profile. The Actions page shows you a list of the actions defined in the profile as well as controls for adding, changing and deleting actions. The order of the actions in this list controls the order the actions appear in pop-up menus. If you wanted an action to be at the top of its menu, you would move it above the other actions in its class. 2. Select the action which has its class as COMPILE and its name as CLC C++. 3. Select the Change... push button to open up the note book containing the actions's settings. This note book is used when you are adding an action as well as changing one. The General page of the Change note book contains controls that let you specify the class, name, and what menus the action appears on. It also specifies the command that invokes the action's executable file and how it will be run. For the COMPILE::CLC C++ action, its executable file is ICC.EXE and this program will be run in a Monitor window. ═══ 5.10. Lesson 7D: Setting Up an Action (Continued) ═══ 1. Go to the Options page. This page specifies the dynamic link library (DLL) containing the interfaces to the action. For WorkFrame/2-enabled actions, the vendor of the action will have supplied a customized DLL. Since the DLL may contain interfaces for a variety of actions, the class of entry point is also specified on this page. (By default, the WorkFrame/2 product tries to match the class of entry point with the class of action you specified.) Typically vendors will have already provided an actions profile specifiying these parameters or will have provided specific instructions to help you set up the actions they provide. The COMPILE::CLC C++ action uses DDE4ICC2.DLL file supplied with the IBM C/C++ Tools product and the selected entry point class is COMPILE. The WorkFrame/2* product provides several classes (including a DEFAULT class) in its default DLL (DDE3DEF2.DLL). You can use this DLL when you want to add actions that have not been specifically enabled for the WorkFrame/2 product. Before you run an action, you may need to set or change environment variables. The Environments page of the actions profile lets you specify the environment required when an action in the actions profile is invoked. The Types page in the note book lets you specify the types of files the action can act upon and the types of files that can be produced. The Help page lets you provide help for the action. When you have finished examining the Change window, select the Cancel push button to close it. When you have finished browsing the CLC Actions Profile, close it and go to the next panel. ═══ 5.11. Lesson 8A: Setting the Compiler Options ═══ Often, a group of projects will use a common set of actions. However, the options for those actions are usually specific to each project. Therefore, you set options from within each project's Settings note book. 1. Go to the first Actions page of the Functions - Settings note book. This page lists the actions that operate on files. Actions are referred to by first indicating the action's class and then the name of the action itself. The two items are separted by a pair of colons. For example, COMPILE::IBM C++ is an action with the name IBM C++ and its class is COMPILE. 2. Select the COMPILE::CLC C++ action in the Actions list box. Then select the Options push button to open the IBM C/C++ Tools Compiler Options note book. Each note book tab corresponds to a category of processing options. 3. Go to the Other page and deselect Yes as the option for Preload compiler components. Ensure that Perform compile only, no link is selected. This field indicates that you want the linker invoked as a separate step of the build process. 4. Go to the Object page and select the DLL choice as the Build type. 5. Select the OK push button to close the IBM C/C++ Tools Compiler Options note book. ═══ 5.12. Lesson 8B: Setting the Linker Options ═══ 1. Select the LINK::CLC Link action in the Actions list box. Then select the Options push button to open the IBM C/C++ Tools Linker Options note book. A note book appears with each tab representing a category of linker options. 2. Go to the Generation page. This page allows you to set options that control how the executable file is to be generated. 3. At the bottom of the Generation window are the Application Type options. Ensure that the Window radio button is selected. This instructs the linker to generate a text-windowed application. By default the linker attempts to make a non-Presentation Manager (PM) application text-windowed. By explicitly selecting this option you eliminate a warning message at link time. ═══ 5.13. Lesson 8C: Setting Linker Options (Continued) ═══ 1. Go to the File names page. 2. Enter the following: Libraries to use ..\LIB\CALC_CLS.LIB Definition (.DEF) file name CALCFUNC.DEF The %o text in the Generated target file name field is a substitution variable. Substitution variables are used by the WorkFrame/2 product to represent objects like actual file names, projects, or options. %o represents the target program of the project (specified on the Target page of the Functions settings note book). Details about other substitution variables can be found in the online help. 3. Select the OK push button to close the IBM C/C++ Tools Linker Options note book. 4. Close the project's Settings note book. ═══ 5.14. Lesson 9: Copying the Rest of the Projects ═══ The other sample projects have already been created for you. In this section you will copy them into the Command Line Calculator composite project. 1. Open the Samples folder (located in the IBM WorkFrame/2 folder) and then open the composite project entitled CLC. As you can see, this composite project contains four projects: EXE, LIB, INFO, and DLL. (The DLL project is a duplicate of the Functions project you just created.) 2. Select Copy... from the pop-up menu of the EXE project. 3. Once the Copy window opens, specify the New name field to "Executable". 4. Select Command Line Calculator as the target folder and then select the Copy push button to complete the copying. 5. Do the above steps once again to copy the projects for the calculator's class library (LIB) and online reference (INFO). Specify the new names as "Class Library" and "Reference". 6. Close the CLC and Samples folders. You have now created and copied all the projects needed for the command line calculator. In this tutorial, none of the projects in the Command Line Calculator is itself a composite project. However, composite projects can also contain other composite projects. ═══ 5.15. Lesson 10: Prioritizing the Projects ═══ The composite project contains settings controlling how the order that the projects within it are made. If the projects are independent of each other, then the order they are made in does not matter. However, if one project is depends on another, then the order does matter. In the Command Line Calculator, both the Executable and Functions projects use files created by the Class Library project. Therefore, the class library needs to be made before them. After it is made, the other projects can be made in any order. 1. Open the Settings note book for the Command Line Calculator composite project. 2. Go to the Sequence page. 3. All the projects in Command Line Calculator composite project appear in the Available projects list box. Select the Class Library project and then select the Add >> push button to move it to the Project sequence list. 4. Select the rest of the projects in the Projects list box. You can do this by placing the mouse pointer on the first item, holding mouse button 1 down, dragging the pointer across the other items, and releasing mouse button 1 once the pointer is over the last item. 5. Drag the selected projects from the Available projects list box to the Project sequence list box. End the drag at a point below the Class Library item in the list box. Note: If you decide later to reorder the projects in the Project sequence list box, you can just select projects and drag them to a new place in the sequence. ═══ 5.16. Lesson 11: Specifying the Target Project ═══ 1. Go to the Target page. On this page you can select one of the projects to be the target project of the composite project. A target project has the following characteristics: o When files are copied or moved into the composite project, the file is physically placed in the working directory specified in the target project's settings. o When OpenTarget program is selected from the composite project's pop-up menu, the WorkFrame/2 product tries to run the target program of the target project. (The target program is the file built by the project.) 2. Select Executable as the target project. This project is the executable file used to start the command line calculator. The Functions project is the dynamic link library defining the calculator's functions. 3. Close the Command Line Calculator's Settings note book. ═══ 5.17. Lesson 12: Creating a Make File ═══ Creating make files can be one of the more time-consuming tasks of product development. Fortunately, the WorkFrame/2 product comes with a utility for automating the creation of make files that can be used with NMAKE program that comes with the IBM Developer's Toolkit product. In this lesson, you will use the MakeMake utility to create a make file for the Functions project. 1. Open the WorkFrame/2 Tools folder and locate the MakeMake icon. 2. Drag the Functions project icon to the MakeMake icon to open the MakeMake utility. Once the MakeMake's product information window appears, select its OK push button to continue. 3. Select the COMPILE::CLC C++ and LINK::CLC Link actions. As you select actions, source files for those actions automatically appear in the Files list box. In this case, only one source file, CALCFUNC.CPP, is listed. Ensure that it is shown as selected. 4. Select the Start push button to create the make file. 5. When the make file has been created, the MakeMake Results window appears. This window shows you the make file (CALCFUNC.MAK) and its dependency file (CALCFUNC.DEP) if one was created. You could modify these files using the MakeMake Results window or any text editor. In this case, you do not have to change it, so just close the MakeMake Results window. 6. Select the Save make file item from the File pull-down of the MakeMake window. 7. Close the MakeMake utility. The name of the make file, CALCFUNC.MAK, is the one you specified in the project's settings. ═══ 5.18. Lesson 13: Building the Project ═══ Now that you have set up the projects, specified actions and their options, and built a make file, you are now ready to build the first version of the project. To build the project, you need to run the MAKE::NMake action on the make file of each project starting with the Class Library. You already specified the order in which the projects should be built on the Sequence page of the composite project. And because the MAKE::NMake action is included in the default actions profile, it appears on the pop-up menu of the Command Line Calculator composite project. Selecting the MAKE::NMake action from the Command Line Calculator's pop-up menu, starts the MAKE::NMake action for each project. 1. Open the system menu for Command Line Calculator composite project. 2. Find the Actions entry in the menu and select ActionsMAKENMake. 3. When the Action window opens, deselect Multiple, concurrent monitors to make the processing sequential. (You can set the default monitor behaviour on the Monitor page of each project.) Then select Start to start the make actions. 4. When the Monitor window appears, select Automatic scrolling. In the Monitor window, you will see the MAKE::NMake action started for each project. Each invocation is followed by output from the tools and then by a line showing two return codes. The rc=0 return code indicates that none of the tools started by the NMAKE utility returned any errors. 5. When the make actions are finished, close the Monitor and Command Line Calculator - MAKE::NMake windows. ═══ 5.19. Lesson 14: Running the Command Line Calculator ═══ Now that all the files for the command line calculator have been built, you are almost ready to run the program. Because you cannot reset the LIBPATH environment variable (which the operating system uses to locate dynamic link libraries) without rebooting the computer, you need to copy the Functions DLL to a directory already pointed to by the LIBPATH variable before doing the following steps. Therefore, copy the CALCFUNC.DLL file from the drive:\wfv2_directory\PRJ\CLC\DLL subdirectory to the drive:\wfv2_directory\DLL subdirectory. (drive:\wfv2_directory refers to the directory where the WorkFrame/2 product is installed on your computer.) 1. Go to Command Line Calculator's system menu. Select OpenTarget program to run the calculator. Because Window was specified as the Application Type in the linker options, a text window opens in which the calculator starts. The text window should look something like this: ╔═══════════════════════════════════════════════════════════════════╗ ║ ║ ║ [E:\IBMWF\PRJ\CLC]calc ║ ║ ║ ║ The Command Line Calculator is starting... ║ ║ ║ ║ Command Summary: ║ ║ add Adds x to result. Syntax: "add x". ║ ║ div Divides result by x. Syntax: "div x". ║ ║ end Ends CLC. Syntax: "end". ║ ║ help Lists this help. Syntax: "help". ║ ║ inv Inverts result. Syntax: "inv". ║ ║ mult Multiplies result by x. Syntax: "mult x". ║ ║ rcl Copies value of register x into result. Syntax: "rcl x". ║ ║ regs Show contents of registers. Syntax: "regs". ║ ║ sqrt Sets result to its square root. Syntax "sqrt". ║ ║ stats Finds average and standard deviation of a set of values. ║ ║ Syntax: "stats". ║ ║ sto Copies result into register x. Syntax: "sto x". ║ ║ sub Subtracts x from result. Syntax: "sub x". ║ ║ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ║ ║ ║ ║ Ready for calculations. ║ ║ [ 0] :>_ ║ ║ ║ ╚═══════════════════════════════════════════════════════════════════╝ 2. After the initial euphoria of getting the calculator to build and run, you now notice there is no function for squaring a result. In the next lessons, you will add this function. 3. Enter end at the Command Line Calculator's prompt to close the calculator. Both the calculator and its text window will close. ═══ 5.20. Lesson 15: Adding a Function ═══ In this lesson, you will add a new function to the Command Line Calculator. The new function squares the contents within the display area. The functions are defined in the CALCFUNC.CPP file in the calculator's dynamic link library. 1. Locate the file CALCFUNC.CPP in the Functions project. Open its pop-up menu and select the EDITEPM action of the CALCFUNC.CPP file. 2. Go to line 45 and remove the "// " in front of the line // int Square(void) to change it to int Square(void) You may have noticed that this prototype does not end with a semicolon. The error caused by this problem will be used to demonstrate how the WorkFrame/2 product integrates with the Enhanced Editor. 3. Go to line 66 and remove the "// " token at the front of the line // CLC.AddFunction( "square", ... 4. Go line 176 and change the "/*" token to the "//" token. 5. Go line 183 and change the "*/" token to the "//" token. Again, you may have noticed an error that will be corrected later in this tutorial. 6. Select the Save and quit item from the editor's File pull-down menu to save the file and close the editor. ═══ 5.21. Lesson 16: Compiling A File ═══ The MAKE::NMake action was started from the project's pop-up menu. To demonstrate how an action is invoked against a specific file, the following steps show you how to compile CALCFUNC.CPP. 1. Select COMPILECLC C++ from the pop-up menu of the icon representing the CALCFUNC.CPP file. 2. After the monitor window opens, you will see the output from the compiler in it. Since there are errors, you will have to correct them. Place the mouse pointer on the text of the first error message containing the file name and location of the error. (In this case, the message is drive:\wfv2_directory\PRJ\CLC\DLL\CALCFUNC.CPP(46:1) : error EDC3263: Syntax error - expected ";" or "{" and found "int". The syntax of the message indicates the error is at row 46 and column 1 in the file CALCFUNC.CPP.) Start the editor by double-clicking on the error message. 3. When the editing session has started, note how the editor's cursor is positioned where the first error occurred. In the steps above, you compiled just one file. If you had changed several C++ files, you could have compiled them in a similar manner by first selecting the files to be compiled and then selecting the compile action. See objects selecting multiple in the operating system's Master Help Index for more information about invoking an action for several objects. ═══ 5.22. Lesson 17: Fixing the Errors ═══ In this lesson, you will correct the errors introduced to the CALCFUNC.CPP file when the new function was added. The steps illustrate the ease with which you can locate errors and get detailed information about them. To get help on key words using Ctrl+H key sequence, you need to have the IBM Developer's Toolkit product installed. You do not need to be running the WorkFrame/2 product to use this feature. 1. In the last panel, the editor's cursor moved automatically to the beginning of the int Sqrt(void); line. 2. Select Describe error... from the editor's Compiler pull down to open the Describe Error window. Note that you could use the Compiler pull down to move between the two errors by selecting Next error or Previous error. The WorkFrame/2 product also offers an alternative method which will be used shortly. 3. Click on Details to see help for the error message that is selected in the Describe errors window. 4. Press Esc to close the help window. 5. Click on Cancel (in the Describe Errors window) to return to the editor session. 6. Put the cursor on the int statement and press Ctrl+H. Help for the int key word appears. 7. Close the help window. 8. Add a semicolon (';') to the end of the line above to fix the syntax error. The correct line should look like this: int Square(void); 9. Click on the last error in the monitor window. The editor's cursor now moves to the beginning of the line Rsult *= Result; Correct the second error by changing "Rsult" to "Result". Note: The other errors were caused by the missing semicolon and, therefore, no other fixes need to be made. 10. Select Save and quit from the editor's File pull down to save the file and exit from the editor. 11. Close the Monitor window. ═══ 5.23. Lesson 18: Making the Project Again ═══ Now that the errors have been fixed the functions DLL needs to be built again. This time the file compiles correctly. 1. Select ActionsMAKENMake from the pop-up menu of the of the Functions project to run the make process again. 2. When the process is complete, close the Monitor window. Note that you have started actions from three different WorkFrame/2 objects in this tutorial: o The Command Line Calculator composite project o The CALCFUNC.CPP file o The Functions project. ═══ 5.24. Lesson 19: Running the Calculator Again ═══ Now that the dynamic link library containing the new square function has been recreated successfully, you can test it. Because you created a new dynamic link library for the calculator's functions, you need to copy it again from drive:\wfv2_directory\PRJ\CLC\DLL directory to the drive:\wfv2_directory\DLL directory before doing the following steps. (As before, drive:\wfv2_directory refers to the directory where the WorkFrame/2 product is installed on your computer.) 1. Run the CLC Sample Project again by opening the Command Line Calculator's system menu and selecting OpenTarget program. 2. This time you see that the "square" function has been added. ╔═══════════════════════════════════════════════════════════════════╗ ║ ║ ║ [E:\IBMWF\PRJ\CLC]calc ║ ║ ║ ║ The Command Line Calculator is starting... ║ ║ ║ ║ Command Summary: ║ ║ add Adds x to result. Syntax: "add x". ║ ║ div Divides result by x. Syntax: "div x". ║ ║ end Ends CLC. Syntax: "end". ║ ║ help Lists this help. Syntax: "help". ║ ║ inv Inverts result. Syntax: "inv". ║ ║ mult Multiplies result by x. Syntax: "mult x". ║ ║ rcl Copies value of register x into result. Syntax: "rcl x". ║ ║ regs Show contents of registers. Syntax: "regs". ║ ║ sqrt Sets result to its square root. Syntax "sqrt". ║ ║ square Squares result. Syntax: "square". ║ ║ stats Finds average and standard deviation of a set of values. ║ ║ Syntax: "stats". ║ ║ sto Copies result into register x. Syntax: "sto x". ║ ║ sub Subtracts x from result. Syntax: "sub x". ║ ║ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ║ ║ ║ ║ Ready for calculations. ║ ║ [ 0] :>_ ║ ╚═══════════════════════════════════════════════════════════════════╝ 3. At the cursor, enter "add 2.3" and then "square" to test the calculator. ║ ║ ║ Ready for calculations. ║ ║ [ 0] :>add 2.3 ║ ║ [ 2.3] :>square ║ ║ [ 5.29] :>_ ║ ╚═══════════════════════════════════════════════════════════════════╝ 4. Enter "end" to close the calculator. ═══ 5.25. Lesson 20: Deleting the Project ═══ In this lesson you delete the Command Line Calculator composite project. 1. Drag the Command Line Calculator icon to the Shredder icon. 2. Ensure that the Delete folder contents check box is selected. 3. Confirm the deletion by selecting Yes when the warning message appears. Though you deleted the folder (and its contents), the CLC directory and all of its files still exist. If you also wanted to delete the project's files and directories, you could do so using the operating system's Drives program. Warning: Because the code used in the Functions project is also used by the DLL project of the CLC sample project, do NOT delete any of the directories or source code files. ═══ 5.26. Summary ═══ This tutorial has guided you through all the major steps of the development process. You should now be able to effectively use the IBM C/C++ Tools compiler within the WorkFrame/2 environment. The WorkFrame/2 product itself offers some other tools and features that could be of interest to you. Use the online help and documentation to familiarize yourself with its other features and increase your productivity. A copy of the original CALCFUNC.CPP file can be found in the DLL subdirectory with the name CALCFUNC.BAK. You may wish to delete CALCFUNC.CPP and then copy CALCFUNC.BAK to CALCFUNC.CPP so that other users will be able to use this tutorial. ═══ ═══ Trademark of the IBM Corporation.