═══ Project window ═══ ═══ 1. Project window ═══ The Project window is where you manipulate source files and other project parts, and launch tools that work on particular files or an entire project. Typically, you interact with the project window by: o Entering a wildcard pattern or type name in the parts filter entry field, to filter the project parts that are displayed at any one time. o Selecting one or more files, then selecting an item from the popup menu of one of the files. o Selecting an item from the popup menu of the window background. o Selecting an item from one of the pulldown menus of the window. (Some of the entries under the Project and Selected pulldown menus are the same as entries on the popup menus.) o Double-clicking on a project part that is listed in the window. o Clicking on icons in the toolbar of the window. These icons represent frequently accessed features that are also available through menus or other controls. Menu-Bar Choices o Project o Selected o Monitor o View o Options o Help Controls o Near the top of the window is the project toolbar. A choice under the View menu lets you hide the toolbar. o The Project parts container is where you manipulate the files and other parts that make up the project. Within this container, you can: - Double-click on a project part to run its default action. - Select a project part and then select from its popup menu (which is displayed by pressing mouse button 2). - Press mouse button 2 in the blank area away from the project parts, and select from the popup menu for the container itself. - Drag and drop between the project window and Workplace Shell objects. Only certain drag and drop operations are allowed. For example, you can drop a project part on the shredder or drop a file object or project object onto the project window. Selections under the View pulldown menu let you open different views of this container: - Icon view - Details view - Tree view o The Monitor is where the results of some actions are displayed. A choice under the Monitor menu lets you hide the Monitor container. o Near the bottom of the window is the Monitor toolbar. A choice under the View menu lets you hide the toolbar. o An information line provides an explanation of some parts of the window as the mouse moves over them. A choice under the View menu lets you hide the information line. ═══ 1.1. Project parts container ═══ This region of the project window displays a collection of the files and other projects that are parts of the current project. Related information o This container is part of the project window. o You filter the contents of this container with the parts filter field on the project toolbar. Press the Enter key within this field when changing the filter. o You view different representations of the contents of this container with the Icon, Details, and Tree choices under the View pulldown menu. o After selecting one or more project parts in this container, you operate on those parts by selecting from the Selected pulldown menu or from the popup menu of one of the parts. o After creating or deleting files, you display the updated contents of the container by selecting the Refresh now choice under the View pulldown menu. o You select directories whose contents are displayed in this container using the Location page of the project settings notebook. ═══ 1.2. Monitor window ═══ This region of the project window displays the output from any monitored actions that you run. When an error message, such as a syntax error from a compiler, indicates the source file and a location within the file, you can double-click on the message in the monitor to edit the applicable source file. Related information o The monitor is part of the project window. o You determine if an action is monitored or not on the General page of the action's settings notebook. o You control the monitor through the Monitor pulldown menu, the Monitor toolbar in the project window, and the Monitor page in the project settings notebook. ═══ 1.3. Project menu ═══ Use the entries under this menu to perform operations that affect the whole project, not just a particular subset of project parts. This menu consists of a list of all the actions that are project-scoped, based on their Action applies to setting. These are actions that the product defines, such as Build, or actions that you define yourself. The entries under the Project menu are also available from the background popup menu within the Project window, and the System menu. ═══ 1.4. Selected menu ═══ Use the entries under this menu to perform an action on the project parts that are selected in the project window. If no project parts are selected, or if no actions apply to all of the selected parts, this menu has no items. The items vary depending on the actions that apply to the selected project parts. ═══ 1.5. Monitor menu ═══ Use the entries under this menu to control the operation of the monitor, which is a portion of the project window where output from actions is sometimes displayed. You can also control the monitor with the toolbar in the project window. Project settings related to the monitor are on the Monitor page in the project settings notebook. Menu Summary o Stop o Repeat o History o Edit errors o Save o Erase o Show ═══ 1.5.1. Stop ═══ Cancels the currently running monitored action. It is equivalent to pressing Ctrl+C in a fullscreen or windowed session. Some processes take a while to respond to this stop request and others do not accept stop requests. Related information o This selection acts on the monitor. ═══ 1.5.2. Repeat ═══ Executes the most recently executed monitored action again. It cannot be used to repeat actions that run in a fullscreen or windowed session. Related information o This selection acts on the monitor. ═══ 1.5.3. History ═══ Displays a dialog that lists previously executed monitored actions. For any of these actions, you can view the output again or run it again. Related information o This selection acts on the monitor. ═══ 1.5.4. Edit errors ═══ When an error message is selected in the monitor, this selection edits the applicable source file at the location of the error. It is the same as double-clicking on the line with the error message. If no error message is selected, this selection edits the source file for the first error message produced by the action. Related information o This selection acts on the monitor. o The highlighted message must follow the format of the error template for the action. The file name and error location must be indicated by substitution variables. ═══ 1.5.5. Save ═══ Saves the contents of the monitor window to a file, in case you want to review an error log or other output from a monitored action. Related information o This selection acts on the monitor. ═══ 1.5.6. Erase ═══ Erases the contents of the monitor window. You can view the results of previously executed actions by selecting History. Related information o This selection acts on the monitor. ═══ 1.5.7. Show ═══ Toggles whether the monitor is shown or hidden at the bottom of the project window. Related information o This selection acts on the monitor. o On the Monitor page of the project settings notebook, you can choose to have the monitor displayed or hidden automatically when actions are started or completed, so that more space is available for the list of project parts when you do not need to look at the monitor. ═══ 1.6. View Menu ═══ Use the entries under this menu to customize the way information is presented in the project window. Menu Summary o Icon o Details o Tree o Settings o Tools setup o Information line o Toolbars o Refresh now ═══ 1.6.1. Settings ═══ Use the entries under this cascading menu to take fast paths to commonly referenced pages in the Project Settings notebook, where you can change various properties of the project. Menu Summary o Target o Location o Monitor o Inheritance o View o Sort ═══ 1.6.2. Refresh now ═══ Displays all the information in the window again. Use this selection if project parts are created or deleted while a project view is open. ═══ 1.7. Options menu ═══ Use the entries under this menu to change the options (the runtime parameters used by the tool) for some actions. In the settings notebook for each action (available in the Tools setup window), you can choose whether or not the action is listed under the Options menu, depending on how frequently you need to change its options. ═══ 1.8. Project toolbar ═══ Use the toolbar at the top of the Project window to quickly perform a common WorkFrame operation; most of these operations can also be selected from menus. The toolbar comes already configured with a set of commonly performed operations: Build smarts Displays the Build smarts window where you can set build features for your projects. This feature is optional and might not be present in all products that incorporate the WorkFrame component. Tools setup Displays the Tools setup window that contains the actions, environment variables, and types associated with the project. How Do I? Displays the online How Do I? help for WorkFrame. It contains instructions for how to accomplish common WorkFrame tasks. In the middle of the toolbar is the parts filter, where you select which project parts are displayed in all the open views of the project. The right-hand side of the project toolbar also contains buttons for launching frequently-used, project-scoped actions like Build, Debug, and Run. To remove an action from the toolbar, or add a particular action, change the Use in project Toolbar setting in the Menus tab of the action's settings in the Tools setup window. Related information o Toolbars choice of View pulldown menu o Monitor toolbar ═══ 1.9. Parts filter ═══ Enter the file mask or type name that determines which project parts to list in the project window. You can only enter one file mask or type name. You can also select one of the available types from the dropdown list box. You must press the Enter key to refresh the contents of the view using the new filter. Related information o If you need to use more than one file mask and the dropdown choices are not suitable, you can set up a new file type using the Types view in the Tools setup window. ═══ 1.10. Monitor toolbar ═══ Use the toolbar at the bottom of the Project window to quickly perform an operation on the monitor window (a part of the project window that is sometimes displayed and sometimes hidden). These operations can also be selected from the Monitor pulldown menu. The buttons on this toolbar operate on the entire monitor window and its contents (Show, Erase, Save to file), or on individual actions whose output has been displayed in the monitor window (Stop, Repeat, History, Errors). You cannot change the contents of this toolbar. Toolbar choices Stop Repeat History Errors Save Erase Show Related information o Toolbars choice of View pulldown menu o Project toolbar ═══ 1.10.1. Stop ═══ Cancels the currently running monitored action. It is equivalent to pressing Ctrl+C in a fullscreen or windowed session. Some processes take a while to respond to this stop request and others do not accept stop requests. ═══ 1.10.2. Repeat ═══ Repeats the most recently performed monitored action. ═══ 1.10.3. History ═══ Displays a dialog that lists previously executed actions. You can execute an action again or view its results again. ═══ 1.10.4. Errors ═══ When an error message is highlighted in the monitor, this selection edits the applicable source file at the location of the error. It is the same as double-clicking on the line with the error message. If no error message is selected, this selection edits the source file for the first error message produced by the action. Related information o This selection acts on the monitor. o The highlighted message must follow the format of the error template for the action. The file name and error location must be indicated by substitution variables. ═══ 1.10.5. Save ═══ Save Saves the current contents of the monitor window to a file. ═══ 1.10.6. Erase ═══ Erases the contents of the monitor window. You can view the results of previously executed actions by selecting History. ═══ 1.10.7. Show ═══ Shows or hides the monitor window. ═══ 1.11. Open ═══ You can open various views of the project: o Icon view o Details view o Tree view o Tools setup view ═══ 1.12. Icon view ═══ The Icon view lists the project parts as icons. Related information o This view is part of the project window. o Details view o Tree view ═══ 1.13. Details view ═══ The Details view lists the project parts and multicolumn information, such as location and file size, about each. Related information o This view is part of the project window. o Icon view o Tree view ═══ 1.14. Tree view ═══ The Tree view lists the project parts as a tree structure, with files grouped according to project access method and then according to the directories where they are located. Related information o This view is part of the project window. o Icon view o Details view ═══ Help menu ═══ The choices under this menu give you help about aspects of WorkFrame or of the entire product. Menu choices o Help index displays the index of the WorkFrame online help. o General help displays the overall help panel for the current window. o Using help displays instructions for the help facility. o How Do I? displays online help for WorkFrame tasks. o Depending on the product, there may be a set of product-specific cascading menu items. o Product information displays a window that identifies the product. ═══ Default action help ═══ This menu item represents an action that can be executed on the project (from the Project menu) or on the selected parts (from the Selected menu). An action is a description of a tool that can be used to manipulate a project's parts or build its target. Related information o You can work with actions in the Tools setup window. ═══ Help Menu Items for Online Documentation ═══ The central portion of the Help pulldown menu is dedicated to all the online documentation for the product. Depending on which product you are using, the menu might or might not have these selections. Making a selection from any of these cascading menus launches the documentation associated with the menu item. You can find the same documentation in the Information folder found in the product's Desktop folder. The cascading menus are organized as follows: At A Glance  Provides general information on using Visual Age C++, such as what is new in this release, the overall tutorial, a description of all the sample programs, and answers to frequently asked questions. Using Visual Age C++  Provides direct access to the individual sections of the User's Guide. For example, if you are using the Browser, you would look in the Browsing section for more information. How Do I... Selections  Provides access to the How Do I... information for each component of Visual Age C++. Use How Do I... information to find out how to perform common tasks within Visual Age C++. C/C++  Provides access to the information that is specific to programming in C and C++. Class Libraries  Provides access to the Visual Age C++ Open Class Library documentation. Visual Programming  Provides access to the information that is specific to creating your programs visually. OS/2, PM, and Graphics  Provides access to the documentation for the key aspects of OS/2, Presentation Manager, and graphics programming. IPF, REXX, and Editing  Provides access to the IPF, REXX and Editor references. SOM and Workplace Shell  Provides access to the information specific to SOM and the WorkPlace Shell. Multimedia  Provides access to the information that is specific to creating multimedia applications. ═══ 2. Project settings notebook ═══ Use the Project Settings notebook to change various properties of the project. Pages o Target defines the names of the target file and make file. o Location defines the source and working directories. o Monitor controls the appearance of the display area that shows the results of running actions. o Inheritance defines one or more projects from which to inherit certain properties. o View (Page 1 of 3) controls the appearance of the icon view of the project window. o View (Page 2 of 3) controls the appearance of the tree view of the project window. o View (Page 3 of 3) controls the appearance of the details view of the project window. o Sort controls the order in which project parts are displayed. o And OS/2-standard Menu, File, Window, and General pages. Related information o These settings affect the appearance of the project window. ═══ 2.1. Target page ═══ Use this page to define the file that is ultimately produced by building the project, and the name of the make file that generates the target file. If the target is an executable file, you can also enter options to be passed to it at run time as if they were typed on the command line. Controls Name Enter the name, including the extension, of the target file that will be produced by building the project. Run options These controls only apply when the target file is an executable program. Enter any runtime parameters that you want to pass to the target program as if they were entered on the command line. Makefile Enter the name of the make file to use when building the project. When you use MakeMake to generate a make file for the project, it will save the make file with this name. Undo Restores the page to the same settings as when you opened the dialog. Default Restores the page to its default values. Help Displays this help panel. Related information o This page is part of the project settings notebook. ═══ 2.2. Location page ═══ Use this page to specify which directories contain the files that are part of this project. Controls Directories for project files Enter the names of one or more directories that contain the files that are part of the project. If a directory does not exist, a WorkFrame prompt will let you decide whether or not to create it. Find Displays a Find dialog to select directories nteractively. Working directory After selecting the directories for project files, select one of them as the Working directory. This is the directory where any output files are created. When actions are executed, this directory is their current directory. Undo Restores the page to the same settings as when you opened the dialog. Default Restores the page to its default values. Help Displays this help panel. Related information o This page is part of the project settings notebook. ═══ 2.3. Monitor page ═══ Use this page to customize the display of the monitor window. Controls Show on action start Makes the monitor window visible, if it is not already visible, when a monitored action is executed. Auto erase Clears the monitor window each time a monitored action is executed. Auto scroll Scrolls the monitor window as new output is produced, so that you always see the latest output. Beep on completion Signals you when a monitored action is completed, in case you are doing something else at the time. A high-pitched tone indicates the action was successful (with a return code of zero). A low-pitched tone indicates the action was unsuccessful (with a nonzero return code). Hide on successful completion Hides the monitor window when a monitored action is completed successfully, on the assumption that there are no error messages to check. Refresh view(s) on completion Displays the up-to-date list of project parts in all open project views after a monitored action is completed, in case the action created or deleted any files. If frequent refreshing slows down your work, you can deselect this check box and refresh the views directly from the project window selecting Refresh now under the View pulldown menu. Undo Restores the page to the same settings as when you opened the dialog. Default Restores the page to its default values. Help Displays this help panel. Related information o This page is part of the project settings notebook. ═══ 2.4. Inheritance page ═══ Use this page to select one or more projects whose Tools setup is to be inherited by the current project. You do the selection through a Find dialog. Typically, you might use inheritance to: o Inherit a complete set of actions, types, and environment variable settings from a pre-configured project that comes as part of the product. o Add or override a small set of actions, types, or environment variable settings, if you want to apply these changes to multiple projects. Creating a minimal project and inheriting from it may be more convenient than changing the settings in each new project. Settings from projects that are lower in the list take precedence over settings from higher projects, if there is a conflict such as a duplicate action name. Controls When the Inherit from list box is not empty, you can select a project and use the buttons to remove it from the list, or move it up or down. Inherit from Displays the list of projects, in reverse priority sequence, from which this project inherits actions, environment-variable settings, and types. Promote Moves the selected project up one position in the list, which lowers its precedence. It is only selectable when there is more than one project in the inheritance list. Demote Moves the selected project down one position in the list, which raises its precedence. It is only selectable when there is more than one project in the inheritance list. Add Displays a Find dialog where you can select another project from which to inherit Tools setup objects. Remove Removes the selected project from the inheritance list. Undo Restores the page to the same settings as when you opened the dialog. Default Restores the page to its default values. Help Displays this help panel. Related information o This page is part of the project settings notebook. o You work with the actions, environment variables, and types in the Tools setup window. ═══ 2.5. View page (1 of 3) ═══ Use this page to customize the display of the icon view for the main project window. Controls (Page 1 - Icon view) Format Selects different arrangements for the project parts in the icon view: o Select Flowed if you want the icons arranged in columns across the screen. o Select Non-flowed if you want the icons arranged in a column from the top to the bottom of the screen. o Select Non-grid if you want the icons displayed without columns. Icon display Selects the visibility of icons for project parts in the icon view. Font Selects the font for icon labels in the icon view. You can use the Change font pushbutton to interactively select a different font. Undo Restores the page to the same settings as when you opened the dialog. Default Restores the page to its default values. Help Displays this help panel. Related information o This page is part of the project settings notebook. o View page (2 of 3) o View page (3 of 3) ═══ 2.6. View page (2 of 3) ═══ Use this pages to customize the display of the tree view for the main project window. Controls (Page 2 - Tree view) Format Selects whether or not to connect the parts in the tree view with lines. Icon display Selects the visibility of icons for project parts in the tree view. Font Selects the font for icon labels in the tree view. You can use the Change font pushbutton to interactively select a different font. Undo Restores the page to the same settings as when you opened the dialog. Default Restores the page to its default values. Help Displays this help panel. Related information o This page is part of the project settings notebook. o View page (1 of 3) o View page (3 of 3) ═══ 2.7. View page (3 of 3) ═══ Use this page to customize the display of the details view for the main project window. Controls (Page 3 - Details view) Details to display Selects which details about each project part are displayed in the details view. Font Selects the font for icon labels in the details view. You can use the Change font pushbutton to interactively select a different font. Undo Restores the page to the same settings as when you opened the dialog. Default Restores the page to its default values. Help Displays this help panel. Related information o This page is part of the project settings notebook. o View page (1 of 3) o View page (2 of 3) ═══ 2.8. Sort page ═══ Use this page to select the order in which project parts are listed in each view of the project parts container. Controls Sort by attribute Determines which attributes are listed under the Sort cascading menu of the System menu and the project parts container popup menu. You can sort the project parts by selecting from these menus. Default sort attribute Determines which attribute is to be the default under the Sort cascading menus. Select an attribute from the dropdown list box. If the Always maintain sort order check box is selected, changing this setting also sorts the project parts again. Descending sort order Select this box to sort with largest, latest, or alphabetically greatest items listed first. Always maintain sort order Select this box if you always want to see the projects parts in sorted order. Deselect it if the sorting is not worth the extra performance overhead. Undo Restores the page to the same settings as when you opened the dialog. Default Restores the page to its default values. Help Displays this help panel. Related information o This page is part of the project settings notebook. o You can sort the project parts at any time using the Sort cascading menu under the project's popup or System menu. ═══ Select ═══ Use the choices under this cascading menu to select or deselect all the project parts in the project container at once. ═══ Sort ═══ To sort the parts in a project, select Sort from the project's popup or System menu. You can select the attribute to be used for sorting from the Sort cascading menu. Related information o Select which attributes are listed under the Sort cascading menu, and whether WorkFrame automatically keeps the project parts in sorted order, on the Sort page of the project's settings notebook. ═══ 3. Tools setup window ═══ The Tools setup window is where you define what tools are associated with the project, the settings of environment variables to be in effect when those tools are executed, and symbolic names for the different file types (or groups of file types) that these tools accept as input or produce as output. You can customize what objects are displayed in this window by selecting or deselecting the menu choices under the View pulldown menu. Menu-Bar Choices o Actions o Variables o Types o View o Help Controls o The object container can display these different views: - Actions view. - Variables view. - Types view. o The Tools setup toolbar gives fast access to some of the operations that are available from the popup and pulldown menus. o An information line provides an explanation of some parts of the window as the mouse moves over them. A choice under the View menu lets you hide the information line. ═══ 3.1. Actions view ═══ Information about how to execute a particular tool is contained within an object called an action. Each action defines what types of files the tool accepts as input and produces as output, what options to set when executing the tool, and other related items of information. Depending on what types of files the action applies to, it may appear on the popup menus for objects in the Project window and/or in the background popup menu of the Project window. Actions are grouped according to their Class field, in categories such as Edit and Compile. In the container, you can: o Click on the plus-sign icons next to the class names to expand or contract parts of the tree view. Or double-click on the class names themselves. o Select an actions from the list, and select items from its popup menu to create, delete, change, or do other things to the action. Moving and copying an action both start with an action in the current project and put it in a different project. The Where defined menu choice shows which project has the original definition of this action, if the definition is inherited from another project. o Double-click on an action to change its options. If the action has both project-scoped options and file-scoped options, the project-scoped options are displayed by double-clicking. o Drag and drop an action on the shredder to delete it. Or, drag and drop it on the Tools setup window of another project to move or copy it (depending on whether you hold down the Ctrl key while dragging). Actions that are inherited can only be deleted in the defining project. o Select some common operations from the toolbar as a fastpath. Related information o This view is part of the Tools setup window. o You can switch between the different view with the View pulldown menu o Actions pulldown menu ═══ 3.2. Environment variables view ═══ The Environment variables view lists environment variables and their settings that are in effect while an action is being executed. These settings override those specified in the CONFIG.SYS file. All the listed environment variables are set while running any action. In the view, you can: o Add a new environment variable or override the setting of an existing one, by selecting Add from the toolbar or from the Variables pulldown menu. o Select one or more environment variables from the list, and select an operation from their popup menu. Moving and copying an environment variable both start with a variable in the current project and put it in a different project. The Where defined menu choice shows which project has the original definition of this variable, if the definition is inherited from another project. o Double-click on a variable to change its value. o Drag and drop a variable on the shredder to delete it. Or, drag and drop it on the Tools setup window of another project to move or copy it (depending on whether you hold down the Ctrl key while dragging). Variables that are inherited can only be deleted in the defining project. o Select some common operations from the toolbar as a fastpath. Related information o This view is part of the Tools setup window. o You can switch between the different containers with the View pulldown menu o Variables pulldown menu ═══ 3.3. Types view ═══ The Types view lists symbolic names that are assigned to file types and groups of file types. You can use these names in the places where you can specify file masks, such as *.C. In fields where you can enter multiple names or masks, you can mix these type names with file masks. In the view, you can: o Select one or more types from the list, and select an operation from their popup menu. Moving and copying a type both start with a type in the current project and put it in a different project. The Where defined menu choice shows which project has the original definition of this type, if the definition is inherited from another project. When adding a type, probably the most common form you will use is the FileMask, which is one or more file masks using wildcard characters such as * and ?. To enter a Logical AND or other logical expression, all of the components of the expression must be other type names or file masks. o Double-click on a type to change its value. o Drag and drop a type on the shredder to delete it. Or, drag and drop it on the Tools setup window of another project to move or copy it. (depending on whether you hold down the Ctrl key while dragging). Types that are inherited can only be deleted in the defining project. o Select some common operations from the toolbar as a fastpath. Related information o Background information about types and type classes o This view is part of the Tools setup window. o You can switch between the different containers with the View pulldown menu o Types menu ═══ 3.4. Actions menu ═══ Use the entries under this menu to perform an operation on the selected action, or on the default action for a class if a class is selected. Menu Summary o Project options o File options o Add o Change o Copy o Move o Delete o Expand all o Collapse all o Where defined ═══ 3.4.1. Project options ═══ The choices under this cascading menu allow you to change, copy, or delete the options from a selected project-scoped action. These options are passed to the action as if typed on the command line. If this menu item is not available, either select a project-scoped action or change the action settings and make sure the action applies to projects. Menu Choices Change Allows you to change the options that are used by the action when it is executed as a project-scoped action. Some actions supply a customized options dialog; others use a common change dialog in which you enter the options as a string. Copy Copies the project-scoped options from this action to another action. When you copy the options of an inherited action, the options from the defining project are copied. Delete Removes any changes you have made to the project-scoped options for this inherited action. The options return to their inherited values. If you have not changed the options from their default values or if the action is not inherited, this choice is not available. ═══ 3.4.2. File options ═══ The choices under this cascading menu allow you to change, copy, or delete the options from a selected file-scoped action. These options are passed to the action as if typed on the command line. If this menu item is not available, either select a file-scoped action or change the action settings and make sure the action applies to files. Menu Choices Change Allows you to change the options that are used by the action when it is executed as a file-scoped action. Some actions supply a customized options dialog; others use a common change dialog in which you enter the options as a string. Copy Copies the file-scoped options from this action to another action. When you copy the options of an inherited action, the options from the defining project are copied. Delete Removes any changes you have made to the file-scoped options for this inherited action. The options return to their default values. If you have not changed the options from their default values or if the action is not inherited, this choice is not available. ═══ 3.4.3. Add ═══ Displays a settings notebook where you can define the settings of a new action. If a class name is selected in the window, the settings notebook only has a few values filled in. If an action is selected in the window, the notebook dialog has the same values as the selected action. Change the name and/or class, and any other settings that you want to customize. This is a convenient way to make multiple, slightly customized copies of an action within the same project. If the action is inherited, you can create a local copy (which can be changed) by selecting Add and leaving the name and class the same. Related information o This same notebook is also used to change an action. o Background information about actions ═══ 3.4.4. Change ═══ Displays a settings notebook where you can change the settings of a selected action. If this menu item is not available: o Make sure you have selected an action (not a class name). o Use the Where defined menu choice to check if the action is defined in this project, or inherited from a base project. If the action is inherited, you can change it within the base project, or by selecting Add and making a local copy of the action that overrides the inheriteda action. Related information o This same notebook is also used to add an action o When modifying inherited objects in a base project, there are precautions that you should take. o Background information about actions ═══ 3.4.5. Copy ═══ Copies the selected action or all actions in the selected class to a project. You can enter a different name for the action, which is required when copying an action within the same project. You can also use a Find dialog to locate the project to which to copy the action. If you want to copy an action from some other project to this one, open the other project and perform the copy operation from there. ═══ 3.4.6. Move ═══ Moves the selected action to a project. You can enter a different name for the action, allowing you to rename an action by moving it within the same project. You can also use a Find dialog locate the project to which to move the action. If you want to move an action from some other project to this one, open the other project and perform the move operation from there. If this menu item is not available: o Make sure you have selected an action (not a class name). o Use the Where defined menu choice to check if the action is defined in this project, or inherited from a base project. If the action is inherited, you can move or copy it from the base project. Related information o When modifying inherited objects in a base project, there are precautions that you should take. ═══ 3.4.7. Delete ═══ Deletes the selected action or all actions in the selected class from a project. If this menu item is not available: o Make sure you have selected an action (not a class name). o Use the Where defined menu choice to check if the action is defined in this project, or inherited from a base project. If the action is inherited, you can delete it within the base project. If you delete an action but it is still available in the project, you might have deleted a local copy of an inherited action, and must use the above procedure or remove the inheritance relationship if you want to delete it permanently. Related information o When modifying inherited objects in a base project, there are precautions that you should take. ═══ 3.4.8. Expand all ═══ Expands all levels of the tree view, showing all the action classes and all the associated actions. ═══ 3.4.9. Collapse all ═══ Collapses all levels of the tree view. ═══ 3.4.10. Expand ═══ Expands one level of the tree view, showing the list of actions that are grouped under the selected class. Within each class, actions are listed in the order of their priority, with the highest-priority action on top. This item is only available after selecting a class, not an action. ═══ 3.4.11. Collapse ═══ Collapses one level of the tree view, hiding the list of actions that are grouped under the selected class. This item is only available after selecting a class, not an action. ═══ 3.4.12. Where defined ═══ Displays the project where the selected action, type, or environment variable is defined. You can then go directly to that project's Tools setup, where you can modify an object that is inherited by your project. These objects can be inherited from other projects, that is, defined in one project and used in another. The defining project might be one that you or someone in your organization has set up, or it might be one provided as part of a product. Related information o When modifying inherited objects in a base project, there are precautions that you should take. ═══ 3.5. Variables menu ═══ Use the entries under this menu to perform an operation on the selected environment variable. Menu Summary o Add o Change o Copy o Move o Delete o Where defined ═══ 3.5.1. Add ═══ Displays a dialog where you can define the settings for a new environment variable. Related information o Background information about environment variables ═══ 3.5.2. Change ═══ Displays a dialog where you can change the value of a selected variable. If this menu item is not available: o Use the Where defined menu choice to check if the variable is defined in this project, or inherited from a base project. If the variable is inherited, you can change it within the base project. Related information o Background information about environment variables o When modifying inherited objects in a base project, there are precautions that you should take. ═══ 3.5.3. Copy ═══ Copies the selected variable to a project. You can enter a different name for the variable, which is required when copying a variable within the same project. You can also use a Find dialog to locate the project to which to copy the variable. If you want to copy a variable from some other project to this one, open the other project and perform the copy operation from there. ═══ 3.5.4. Move ═══ Moves the selected variable to a project. You can enter a different name for the variable, allowing you to rename a variable by moving it within the same project. You can also use a Find dialog to locate the project to which to move the variable. If you want to move a variable from some other project to this one, open the other project and perform the move operation from there. Related information o When modifying inherited objects in a base project, there are precautions that you should take. ═══ 3.5.5. Delete ═══ Deletes the definition of the selected variable from a project. If this menu item is not available: o Use the Where defined menu choice to check if the variable is defined in this project, or inherited from a base project. If the variable is inherited, you can delete it within the base project. If you delete a variable but it is still available in the project, you might have deleted a local copy of an inherited variable, and must use the above procedure or remove the inheritance relationship if you want to delete it permanently. Related information o When modifying inherited objects in a base project, there are precautions that you should take. ═══ 3.6. Types menu ═══ Use the entries under this menu to perform an operation on the selected type. Menu Summary o Add o Change o Copy o Move o Delete o Where defined o Register class Related information o Background information about types and type classes ═══ 3.6.1. Add ═══ Displays a dialog where you can define the filters for a new type. You can use types in many of the same places that you can enter file masks, to save having to remember complicated file masks and enter them over and over. Related information o Types view o Background information about types and type classes ═══ 3.6.2. Change ═══ Displays a dialog where you can change the settings of a selected type. If this menu item is not available: o Use the Where defined menu choice to check if the object is defined in this project, or inherited from a base project. If the object is inherited, you can only change it within the base project. Related information o When modifying inherited objects in a base project, there are precautions that you should take. o Types view o Background information about types and type classes ═══ 3.6.3. Copy ═══ Copies the selected type to a project. You can enter a different name for the type, which is required when copying a type within the same project. You can also use a Find dialog to locate the project to which to copy the type. If you want to copy a type from some other project to this one, open the other project and perform the copy operation from there. ═══ 3.6.4. Move ═══ Moves the selected type to a project. You can enter a different name for the type, allowing you to rename a type by moving it within the same project. You can also use a Find dialog to locate the project to which to move the type. If you want to move a type from some other project to this one, open the other project and perform the move operation from there. If this menu item is not available: o Use the Where defined menu choice to check if the object is defined in this project, or inherited from a base project. If the object is inherited, you can only move it within the base project. Related information o When modifying inherited objects in a base project, there are precautions that you should take. ═══ 3.6.5. Delete ═══ Deletes the definition of the selected type from a project. If this menu item is not available: o Use the Where defined menu choice to check if the object is defined in this project, or inherited from a base project. If the object is inherited, you can only delete it within the base project. Related information o When modifying inherited objects in a base project, there are precautions that you should take. ═══ 3.6.6. Register class ═══ Displays a dialog where you can define a new type class that will be available on the dialogs related to types. ═══ 3.7. View menu ═══ Use this menu to change the presentation of information in the Tools setup window. Menu choices o Actions o Variables o Types o Mini-icons o Information line o Toolbar ═══ 3.7.1. Actions ═══ Displays in the window the actions that are available to the project. These actions are displayed on popup and pulldown menus in the Project window. Related information o Actions view. ═══ 3.7.2. Variables ═══ Displays in the window the environment-variable settings that are defined for the project. These settings are in effect while any project action is being executed, overriding any previous value. The settings have no effect on applications or commands that are executed outside the project. Related information o Variables view. ═══ 3.7.3. Types ═══ Displays in the window the types that are defined for the project. Related information o Types view. ═══ 3.7.4. Mini-icons ═══ Toggles whether the action view represents the actions using large or small icons. ═══ 3.7.5. Information line ═══ Toggles whether the information line at the bottom of the window is displayed or hidden. You might not need the information line if you use the View pulldown menu to change the tool bar to a textual representation or turn on the hover help for the tool bar. ═══ 3.7.6. Toolbars ═══ Changes the appearance of any tool bars in this window. Menu choices Show Selects whether any toolbars are displayed in the window. Deselect it if you use the menus or accelerator keys exclusively. Hover help Selects whether or not brief explanations of each toolbar icon are displayed next to the icon as the mouse moves over the toolbar. Deselect it if you are familiar with the toolbar icons, if the explanations in the information line are sufficient, or if the performance overhead of this help slows down your work. Style Selects whether the tool bar should label its icons with graphics, text, or both: Graphic and text Displays both a graphic icon and text label for each toolbar item. Graphic only Displays a graphic icon for each toolbar item. Text only Displays a text label for each toolbar item. ═══ 3.8. Tools setup toolbar ═══ This tool bar contains the following buttons, which provide fastpaths to functions that are also available from the popup and pulldown menus: Add Displays the Add window for the current view. For example, for the Actions view, the Add action window is displayed. Change Opens the settings for the selected object. This button is not available when an inherited object is selected. You can only change Tools setup objects in the project where they are defined. Delete Deletes the selected Tools setup object. This button is not available when an inherited object is selected. You can only delete Tools setup objects from the project where they are defined. File-scoped options Displays the file-scoped options dialog of the selected action. Use this dialog to set options for the file-scoped action. Options are the parameters that are passed to the tool when the action is invoked. This button is not available in the Variables view and Types view, or if the selected action does not have the applicable scope. Project-scoped options Displays the project-scoped options dialog of the selected action. Use this dialog to set options for the project-scoped action. Options are the parameters that are passed to the tool when the action is invoked. This button is not available in the Variables view and the Types view, or if the selected action does not have the applicable scope. Actions view Switches to Actions view. Variables view Switches to Variables view. Types view Switches to Types view. How Do I? Shows the WorkFrame How Do I? help, which explains how to do common tasks using WorkFrame. ═══ Background information about types and type classes ═══ Like actions, types are named and grouped into classes. A type's class provides the method in which a project part is determined to be a member of the type. WorkFrame provides several predefined type classes, including "File Mask": File Mask This type class provides simple OS/2-style pattern matching on the file name of a project part. You specify filter patterns using wild cards. Regular Expression This type class is similar to "File Mask", but allows filter patterns to be specified using the full power of regular expressions. Unlike file masks, a regular expression cannot be used interchangeably with types when you use the project's Parts filter, or when specifying the Source and Target types of an action. You must define and use a Regular Expression type instead. There are several different syntaxes for regular expressions. The one supported here is the Extended Regular Expressions (ERE) format. The syntax is described in a table, where a, b, and c are regular expressions, and n and m are integers. PAM The filter for this type class is the name of a Project Access Method. Only parts returned by the specified PAM are members of the type. For example, a version control tool might provide a PAM type called "Checked out" that identifies project parts that are already in use. A PAM that provides access to parts on a database might support its own types like "Locked" and "Unlocked". Typically, only a very specific list of types can be created from a PAM class type. The basic OS/2 PAM does not support any types. Logical AND The filter for this class is a list of other types or file masks. Parts that are members of all the listed types are also members of this type. Logical OR The filter for this class is a list of other types or file masks. Parts that are members of any one of the listed types are also members of this type. NOT IN File Mask This is the inverse of the File Mask type class. The filter for this class is a list of file masks. Parts that do not match any of the listed masks are members of this type. NOT IN Regular Expression This is the inverse of the Regular Expression type class. The filter for this class is a list of regular expressions. Parts that do not match any of the listed regular expressions are members of this type. NOT IN Logical AND This type class is the inverse of the Logical-AND type class. The filter for this class is a list of other types or file masks. Parts that do not match any of the listed types are members of this type. NOT IN Logical OR This type class is the inverse of the Logical-OR type class. The filter for this class is a list of other types or file masks. Parts that do not match any of the listed types are members of this type. MakeMake Note Only the "File Mask", "Logical OR", and "NOT IN Logical OR" classes are recognized by MakeMake in the source and target types of actions invoked during a project build. Related information o Registering classes ═══ Regular expression syntax ═══ This table shows the notation you can use for specifying regular expressions in type filters. │ a │Denotes an exact match. ─────────────────────────┼────────────────────────────────────────────────── . │Matches any single character. This is the same as │the ? wild card used in OS/2 file masks. To │denote a literal dot character, precede the dot │with a backslash, as in \.. ─────────────────────────┼────────────────────────────────────────────────── ^a │Matches if a occurs at the beginning of the name. ─────────────────────────┼────────────────────────────────────────────────── a$ │Matches if a occurs at the end of the name. For │example, ^a$ matches only a. ─────────────────────────┼────────────────────────────────────────────────── a|b │Matches either a or b. ─────────────────────────┼────────────────────────────────────────────────── [] │Matches any of the characters in the list. For │example, [abc] would match the names a, b, and c. │To match a dash (-) character, it must be placed │first or last in the list (for example, [-abc].c). │To match a caret (^) character, it must be placed │somewhere other than in the first position. To │match a close or open bracket character ([ or ]), │it must be placed first in the list, or second │after a caret. ─────────────────────────┼────────────────────────────────────────────────── [] │Matches any character in the range. For example, │[a-c] would match the names a, b, and c. You could │also write [ab-c] as an equivalent expression. ─────────────────────────┼────────────────────────────────────────────────── [^] │Matches any character other than those specified │in the list or range. For example, [^a-c] will │match any file not named a, b, or c. ─────────────────────────┼────────────────────────────────────────────────── a{n} │Matches a repeated exactly n times. For example, │a{3} will match only the name aaa. ─────────────────────────┼────────────────────────────────────────────────── a{n,m} │Matches a repeated between n and m times, │inclusively. For example, a{2,3} will match only │the file names aa and aaa. If m is ommitted, then │it assumes the value of infinity. ─────────────────────────┼────────────────────────────────────────────────── a? │Matches zero or one occurrences of a. This is │shorthand for a{0,1}. ─────────────────────────┼────────────────────────────────────────────────── a+ │Matches one or more repetitions of a. This is │shorthand for a{1,}. For example, a+b\.c will │match the file name ab.c, but not b.c. ─────────────────────────┼────────────────────────────────────────────────── a* │Matches zero or more repetitions of a. For example │ba* will match the names b, ba, and baaaaaaaaa. to │be considered a comment and lost. The regular │expression .* is equivalent to the OS/2 * │wildcard. │ Notes Because OS/2 files are case-insensitive, WorkFrame ignores case when matching regular expressions. Regular expressions can be grouped using parentheses. To match any literal regular expression character, precede it with a backslash (\). ═══ Copy/Move dialog ═══ Use this dialog to copy or move an object from this project to another project. Controls New name When moving or copying a single object, you can enter a new name. The new name is optional if the destination project does not have an object with the same name. Target project Enter the physical file name of the destination project. This name is on the first File page in the project's settings notebook. Find You can use a Find dialog to browse the directory tree and locate the project file of the destination project. Move or Copy Performs the move or copy operation. Cancel Exits without performing the operation or saving data. ═══ Add/Change environment variable dialog ═══ ═══ Add/Change environment variable dialog ═══ Use this dialog to add or change an environment variable within the project. Controls Name Enter the name of the environment variable that you want to add or change. You can also select a name from the dropdown list box. String Enter or change the value for the environment variable. Remember that this value is only in effect while actions are being executed, not permanently. Add or Change Performs the add or change operation. Undo Restores the page to the same settings as when you opened the dialog. Cancel Exits without performing the operation or saving data. ═══ Add/Change type dialog ═══ ═══ Add/Change type dialog ═══ Use this dialog to add or change a type within the project. Controls Class Enter the class to which the type belongs. Some common type classes are FileMask, Regular Expression, and Logical OR or Logical AND of two or more other types. You can also select a class from the dropdown list box. Name Enter the name of the type to add or change. You can rename an existing type by changing the name and leaving the value the same. Filter Enter one or more values that identify the project parts that this type identifies. The kinds of values depend on the type class: enter file masks for the FileMask class, regular expressions for the Regular Expression class, and so on. Add or Change Performs the add or change operation. Undo Restores the page to the same settings as when you opened the dialog. Cancel Exits without performing the operation or saving data. Related information o Background information about types and type classes o Type requirements for MakeMake ═══ Register new type class dialog ═══ Use this dialog to register a new type class for the project. You only need to do so if you are a product developer and are integrating your product with WorkFrame using the WorkFrame Integration Kit, which will be available through the IBM support channel for this product. You can also delete an existing type class. Type classes are added to the WorkFrame environment through a registration process. Registering new type classes is a specialized task that usually only tool providers need to do. You register, change, and delete type classes by selecting Register class from the Types container pop-up menu. When you register a new type class, you must provide the name of a DLL and an entrypoint that WorkFrame can call to query type membership. WorkFrame calls the type DLL entrypoint passing it a list of parts and the type filter. The entrypoint should then return a boolean value, true indicating that all the parts are valid members of the type, and false indicating that at least one of the parts is not. Controls Existing classes You can select an existing class name from this list to fill in the Class, Module name, and Entrypoint fields with values appropriate to the class. Class Enter the name of the type class to add or delete. You can also select a class from the dropdown list box. Module name Enter the name of the DLL (without the .DLL extension) that contains the function that determines if a given project part is a member of the type. Entry point Enter the name of the entrypoint for the function that determines if a given project part is a member of the type. WorkFrame calls the DLL entrypoint passing it a list of parts and the type filter. The entrypoint should return a boolean value, true indicating that all the parts are valid members of the type, and false indicating that at least one of the parts is not. Add Adds the new type class to the project. Delete Deletes the existing type class from the project. Undo Restores the page to the same settings as when you opened the dialog. Cancel Exits without performing the operation or saving data. Related information o Background information about types and type classes o Type requirements for MakeMake ═══ Precautions for inherited objects ═══ Because inherited objects can be used in multiple projects, make sure that changing, moving, or deleting them in the base project will not cause problems in other projects that might inherit them. If other developers inherit from the same base project, you might need to coordinate changes to the base project with them. ═══ 4. Action settings notebook ═══ Use the Action notebook to customize an action or to get information about an action. This notebook is displayed when you create or change an action. Pages o General o Types o Support o Menus Controls OK (in notebook frame) Closes the dialog and saves all the settings. Close the dialog with this pushbutton rather than with the System menu to preserve any changes you have made. Undo or Reset (in notebook frame) Restores all pages to the same settings as when you opened the dialog. Default (in notebook frame) Restores all pages to their default values. Cancel (in notebook frame) Exits without performing the operation or saving data. Closing this dialog using the System menu has the same effect: changes are not saved. Help (in notebook frame) Displays help for the overall dialog. The Help button on each page displays help for that page. ═══ 4.1. Action notebook - General page ═══ Use this page to specify the basic information about an action: Controls Class The class of an action identifies the general category of an action, and determines how the action is grouped in pop-up menus. There are a number of predefined action classes, such as Edit and Build. You can select one of the predefined names from the drop-down list box, or type in a new class name. Note: If you are adding or changing a Run class action, specify an asterisk (*) on the Program field so that the file to execute is determined by the Run action's options. For example, a project-scoped Run-action options string should contain the %o %r substitution variables to run the project's target. A file-scoped Run action should contain the %f substitution variable to run the selected file. Name An action's name identifies it and sets it apart from the rest of the actions in the same class. The name is also used to list the action in project pop-up menus. Program This field contains the name of the program or command file to run when the action is invoked, including any extension, such as .EXE. By default, actions can execute OS/2, DOS, and WIN-OS2 programs, as well as .CMD or .BAT command files. You do not need to configure any special settings to define actions for DOS and WIN-OS/2 programs or .BAT files. Cross-platform or cooperative development products can extend this capability to execute programs on remote or foreign file systems. Session Select one of these radio buttons to specify where the output from the action should be sent: Default Allows the operating system to decide where to send the output. Monitor Send the output to the project's monitor window where you can click on error messages to bring up the editor on the source file. You can also save the output or print it. This option is only valid for actions that write their output to standard out. Actions that run in the monitor window are called monitored actions. Because the monitor does not support user input, actions that prompt for input should be run in a Window or Full screen session instead. Window Output is sent to a text window. Full screen Output is sent to a full-screen window. Action applies to Actions may be file-scoped or project-scoped: File-scoped File-scoped actions apply to specific project parts, and can only be invoked from those parts. To run a file-scoped action, you must select one or more project parts and then invoke the action on the selected parts. Only file-scoped actions can be included in a make file. The types listed in the action's Source types list determine the project parts the action applies to; the action is listed on the popup menu for parts that have the applicable types. Project-scoped Project-scoped actions apply to a project as a whole, rather than to any particular set of project parts. These actions can be passed project information, such as the name of the project make file or target. Examples of project-scoped actions are Build and Run. Project-scoped actions are invoked from the project's pop-up menu. To bring up the project's pop-up menu, point to any background area in the project container and press mouse button 2. Project-scoped actions cannot be included in a make file. Access method This field is only relevant for a project-scoped action, and is filled in by the person who creates an action. It identifies the project access method (PAM) that executes the program that defines the action. If this field is empty, or if the project contains only OS/2 files, fill in IWFBPAM as the default choice. Undo (on notebook page) Restores the page to the same settings as when you opened the dialog. The Undo pushbutton on the notebook frame undoes the changes for all notebook pages. Default (on notebook page) Restores the page to its default values. The Default button on the notebook frame restores the default values for all notebook pages. Help (on notebook page) Displays help for the notebook page. The Help button on the notebook frame displays help for the overall notebook. ═══ 4.2. Action notebook - Types page ═══ Use the Types page to specify the source and target types that apply to an action. Because the source and target types only apply to file-scoped actions, this page is only available when you have indicated that the action applies to files on the General page. Controls Source types A list of file masks and named types that can apply to an action. This field is only required if the action is file-scoped. For example, an Edit action might have source types like the following: o SourceFiles o *.mak o *.rc o TextFiles Target types A list of file masks and named types that are produced by an invocation of the action. This field is only required if the action is file-scoped and could potentially be included in a make file. For example, an Edit action would not have any target types listed, but an action that created or updated files as part of a Build action would need to list the applicable types. Available types This is the comprehensive list of types that are available to the project. To add a type to the Source types and Target types lists, select one or more available types then click on the <filename for information about the command-line options. o MakeMake limitations o Selecting actions for Build and Make ═══ 5.1. File ═══ Use this pulldown menu to perform open, save, and exit operations for the MakeMake program. Menu choices o Open project o Save makefile o Save and close o Exit ═══ 5.1.1. Open project ═══ Selects a project for which to generate a make file, then reads the list of applicable actions and files from the project. ═══ 5.1.2. Save makefile ═══ Saves the generated make file back into the project, overwriting any earlier version of the same file. If you do not save the make file before exiting from MakeMake, the updated make file information is lost. ═══ 5.1.3. Save and close ═══ Provides a fast way to perform these two final operations when you are finished using MakeMake: o Save make file o Exit ═══ 5.1.4. Exit ═══ Exits from the MakeMake program. Make sure to save the new or updated make file before selecting Exit. ═══ 5.2. Options ═══ Use this pulldown menu to customize the display areas, generated make rules, and prompts for the MakeMake program. Menu choices o Swipe selection o Select new files o Always show make file o Depend on make file o Exit without verification ═══ 5.2.1. Swipe selection ═══ Toggles whether the items listed in the list boxes can be selected and deselected individually, or if a range of items can be selected by selecting one item and dragging the mouse. When Swipe Selection is selected, use Ctrl+Mouse Button 1 to select or deselect multiple ranges of items. ═══ 5.2.2. Select new files ═══ Toggles whether files are automatically selected as they are added to the Source files list box. ═══ 5.2.3. Always show make file ═══ Toggles whether the make file and dependency file are automatically displayed after being generated, so that you can edit them before saving them. If this item is not selected, you can display the Results window by selecting the Change pushbutton. ═══ 5.2.4. Depend on make file ═══ Toggles whether to add the make file as a dependency to each make rule, so that everything will be built again after the make file is changed. ═══ 5.2.5. Exit without verification ═══ Toggles whether to display a confirmation prompt when you try to exit from the MakeMake utility. ═══ 5.3. MakeMake - Results ═══ Use this window to view and alter the make file once it has been created and before it has been saved. If you chose to create a separate dependencies file, a second page appears behind the make file page. You can edit the dependencies file in the same manner as you edit the make file. To edit the make file: 1. Scroll to the area you want to change. (By selecting one of the targets in the Targets list, you can automatically scroll to the statements describing how to build that target.) Note: If you insert or delete lines, selecting a target may no longer take you to the correct line in the make file. 2. The Make file list box acts as a simple text editor. To edit the make file, move the cursor to the area you want to change and start typing. Remember, any editing changes you make will not be reflected if the MakeMake tool is used to replace the make file later. 3. Close this window after you have finished making the changes. Since the MakeMake utility creates an ASCII file, you can also modify the file with an editor. Warning: Any changes you make (within the MakeMake Results window or an editor) will not be restored the next time you use the MakeMake utility to replace the make file. If you decide to undo all the changes you made to the make file after the MakeMake Results window was opened, select the Reset push button. Controls Targets produced Shows the names of all the targets in the make file. Select a target to display the part of the make file that defines it. Make and dependency file notebook Shows the contents of the make file, and the dependency file if one was created, in a notebook dialog. You can edit the contents of these files by changing the text in the notebook. Reset Removes any changes you have made to the generated files. ═══ Select all ═══ Selects all the items in the list box. ═══ Deselect all ═══ Deselects all the items in the list box. ═══ Actions Support DLL (IWFOPT.DLL) Entrypoints ═══ The default actions support DLL (IWFOPT.DLL) supplied with WorkFrame contains support entrypoints for many common actions. The entrypoint defines the options dialog to be used and how the action is used within a make file. The following list describes the purpose of the entrypoints not specifically related to the IBM Developer's Toolkit: COMPILE Use for compilers that do not supply their own actions support DLL. DEBUG Use for debuggers. DEFAULT Use for actions that do not fit into any other category of entrypoint. EDIT Use for editors. LIB Use for a library utility. LINK Use with the LINK386 linker. This is an older OS/2 linker that you may still be using with existing projects. MAKE Use with make utilities such as NMAKE. RUN Use when you simply need to run the selected file or files. The following entrypoints are used with the IBM Developer's Toolkit tools: IMPLIB Use for the Import Library utility. IPF_COMPILE Use for the Information Presentation Facility compiler. MESSAGE_BIND Use with the message binding utility. MESSAGE_COMPILE Use with the message compiler. MSGBIND_PLUS Use with the special message binding utility. RESOURCE_BIND Use when binding resources to an executable file or dynamic link library. RESOURCE_COMPILE Use with the resource compiler. ═══ Default Link Options ═══ The default link options interface is provided by WorkFrame to let programmers set options for the LINK386.EXE linker through a graphical user interface. The help for each option describes its equivalent command line version. This interface is intended to be used only for the LINK386 linker. Other linkers should use the DEFAULT entrypoint. Related information o Entrypoints in IWFOPT.DLL ═══ Generation Options (Pages 1 and 2) ═══ Use these pages to control the format and content of the executable file produced by the linker. For more information, select one of the following items: o Page 1: o Include Debug Information (/CO[DEVIEW]) o Optimize Intrasegment Far Calls (/F[ARCALLTRANSLATION] or /NOF[ARCALLTRANSLATION]) o Sort Segments (/DO[SSEG]) o Sort Segments But Do Not Add 16-byte NULL Region (/NON[ULLSDOSSEG]) o Application Type (/PM[TYPE]:parameter) o Pack The Code Segments (and Size) (/P[ACKCODE][:number] or /NOP[ACKCODE]) o Page 2: o Pack the Data Segments (and Size) (/PACKD[ATA][:number]) o Maximum Number of Segments (/SE[GMENTS]:number) o Stack Size (/ST[ACK]:number) o Module Load Address (/BAS[E]:number) o Segment Alignment (/A[LIGNMENT]:number). o Compress repeated data (/E[XEPACK]). ═══ Compress repeated data ═══ Select this option to compress repeated data in the file. The OS/2 Applications Loader will automatically decompress the data when the program is run. The corresponding command line option is /E[XEPACK]. ═══ Include Debug Information ═══ If you are going to debug your application, select this option to copy the debug information from the objects into the module. The corresponding command line option is /CO[DEVIEW]. ═══ Optimize Intrasegment Far Calls ═══ Select this option to optimize far calls by converting them to near calls if possible. Do not use this option if data in the program could appear to the linker as far calls. The corresponding command line option is /F[ARCALLTRANSLATION]. /NOF[ARCALLTRANSLATION] does not optimize the far calls and is the default. ═══ Sort Segments ═══ Select this option to force segments to be ordered as follows (first to last): 1. All code segments 2. Far data segments 3. Near data (DGROUP) segments, in the following order: a. Any segments of class BEGDATA (this class name is reserved) b. Any segments not of class BEGDATA, BSS, or STACK c. Segments of class BSS d. Segments of class STACK This option also initializes two special variables: _edata is initialized to DGROUP :BSS and _end is initialized to DGROUP : STACK. These variables have special meanings for some compilers so you should avoid using them in your programs. Assembly-language programs can refer to _edata and _end but not modify them. If the _TEXT segment is defined, 16 NULL bytes are added to the beginning of it. The corresponding command line option is /DO[SSEG]. ═══ Sort Segments But Do Not Add 16-byte NULL Region ═══ Select this option to write the segments to the module in the order detailed in the Sort Segments help. Unlike Sort Segments, it does not add 16 NULL bytes to the beginning of the code segment. Note: Do not select this option if the program is being linked with libraries that require the NULL bytes region. The corresponding command line option is /NON[ULLSDOSSEG]. ═══ Pack The Code Segments (and Size) ═══ Select Pack the code segment to concatenate the code segments when building the module. If the Pack the code segment check box is selected, you can use the Size entry field to specify the maximum size of each of the concatenated code segments in the module. The size must be in one of the following formats: o Hexadecimal (prefixed by 0x as in 0x2D7) o Octal (prefixed by zero as in 027) o Decimal (cannot start with zero as in 27). For 16-bit code, the size can be from zero to 65500 and the default value is 65500. For 32-bit code, the size can be from zero to 4294967295 and the default value is 4294967295. The corresponding command line options are: /PACKC[ODE] (the default) If the Pack the code segment is selected. /NOP[ACKCODE] causes the linker to not pack the code. /PACKC[ODE]:number If a number is entered in the Size field. ═══ Pack the Data Segments (and Size) ═══ Select Pack neighboring logical data to concatenate the data segments together when building the module. If the Pack neighboring logical data check box is selected, you can use the Size entry field to specify the maximum size of each of the concatenated data segments in the module. The size must be in one of the following formats: o Hexadecimal (prefixed by 0x as in 0x2D7) o Octal (prefixed by zero as in 027) o Decimal (cannot start with zero as in 27). For 16-bit code, the size can be from zero to 65536 and the default value is 65536. For 32-bit code, the size can be from zero to 4294967295 and the default value is 4294967295. The corresponding command line options are: /PACKD[ATA] (the default) If the Pack neighboring logical data is selected. /PACKD[ATA]:number If a number is entered in the Size field. ═══ Maximum Number of Segments ═══ Specify the maximum number of segments that is to be allowed in the module. The number must be in the range from zero to 3072 (for the LINK.EXE linker) or zero to 16375 (for the LINK386.EXE linker). You can use any of the following formats: o Hexadecimal (prefixed by 0x as in 0x2D7) o Octal (prefixed by zero as in 027) o Decimal (cannot start with zero as in 27). The default value for the LINK.EXE linker is 128. There is no default value for the LINK386.EXE linker. The corresponding command line option is /SE[GMENTS]:number. ═══ Stack Size ═══ Specify the size of the stack to be used by the module. The size must be in the range from zero to 65535 (for 16-bit code) or zero to 4294967295 (for 32-bit code). You can use any of the following formats: o Hexadecimal (prefixed by 0x as in 0x2D7) o Octal (prefixed by zero as in 027) o Decimal (cannot start with zero as in 27). The default value is found within the object modules. The corresponding command line option is /ST[ACK]:number. ═══ Module Load Address ═══ Use this option to specify the address that the module will be loaded at if the address space is not being used by other code. You can use this option for both executable files and dynamic link libraries. You can use any of the following formats: o Hexadecimal (prefixed by 0x as in 0x2D7) o Octal (prefixed by zero as in 027) o Decimal (cannot start with zero as in 27). The corresponding command line option is /BAS[E]:number. ═══ Segment Alignment ═══ Specify the segment alignment factor (in bytes) in the executable file. The default value is 512 for 16-bit code and 4096 for 32-bit code. The corresponding command line option is /A[LIGNMENT]:number. ═══ Application Type ═══ Select one of these radio buttons to specify the type of program to be built by the linker. Select None if you do not want the linker to set the type of program. The program itself will determine what kind of program it is. Select the PM radio button to specify to the linker that the file to be built is a Presentation Manager program and is to be run in a window. The corresponding command line option is /PM[TYPE]:PM. Select Window to specify to the linker that the program can run in a window but is not a Presentation Manager program. The corresponding command line option is /PM[TYPE]:VIO. Select Full screen to specify to the linker that the program can only run in full screen mode. The corresponding command line option is /PM[TYPE]:NOVIO. ═══ Processing Options ═══ The options that appear on this window specify to the linker how to build the executable file. They are: o Display the Logo (/NOL[OGO]) o Search the Extended Dictionary (/NOE[XTDICTIONARY]) o Display Link-time Information (/INF[ORMATION]) o Run Linker in Batch Mode (/BA[TCH]) o Respect Case in Symbol Names (/NOI[GNORECASE]) o Copy Source Line Numbers to Map File (/LI[NENUMBERS]) o Generate Warnings for Fixups (/W[ARNFIXUP]) o Ignore Default Libraries (and Particular Libraries to Ignore) (/NOD[EFAULTLIBRARYSEARCH][:libname]) o Map File (and Maximum Number Of Entries) (/M[AP][:parameter]). ═══ Display the Logo ═══ Choose whether or not to display the name, version, and copyright information of the linker. The corresponding command line option is (/NOL[OGO]). ═══ Search the Extended Dictionary ═══ Select this option to ignore the extended library information (if it exists) found in the library. The corresponding command line option is /NOE[XTDICTIONARY]. ═══ Display Link-time Information ═══ Select this option to display messages as it creates the executable file. The corresponding command line option is /INF[ORMATION]. ═══ Run Linker in Batch Mode ═══ This option causes warning or error messages when a library cannot be found instead of prompting the user for a new path to the library. The corresponding command line option is /BA[TCH]. ═══ Respect Case in Symbol Names ═══ Select this option to respect the case of external definitions when trying to resolve external references. The corresponding command line option is /NOI[GNORECASE]. ═══ Generate Warnings for Fixups ═══ This option causes a message to be produced for each fixup found or generated in the module. The corresponding command line option is /W[ARNFIXUP]. ═══ Ignore Default Libraries (and Particular Libraries to Ignore) ═══ Select Ignore default library search to specify that the linker should not search the default libraries named within the object modules. If only certain default libraries should be ignored, you can enter their names in the Particular libraries to ignore field if the Ignore default library search check box is selected. Note: If you are specifying more than one library, enter one per line. The corresponding command line options are: /NOD[EFAULTLIBRARYSEARCH] To ignore all the default libraries named in the object modules. /NOD[EFAULTLIBRARYSEARCH]:libname For each particular library to be ignored. ═══ Map File (and Maximum Number Of Entries) ═══ Use the None, Regular, and Full radio buttons to specify the content of the map file: None Do not create a map file. Regular Show offsets of all the external symbols that appear in the module. Full Include information about how the references are resolved as well as showing the offsets of all external symbols. Select Full only if you are using the LINK386.EXE linker. If you selected Regular and are using the LINK.EXE linker, you can use the Maximum number of entries field to specify the number of external symbols that the linker should be able to handle. If the linker produces a message indicating the map symbol limit is too high, reduce the limit until the message stops appearing. The number must be in the range 1 to 32767 in one of the following formats: o Hexadecimal (prefixed by 0x as in 0x2D7) o Octal (prefixed by zero as in 027) o Decimal (cannot start with zero as in 27). The default value is 2048. The corresponding command line options are: /M[AP] If Regular is selected and a maximum number of entries is not specified. /M[AP]:number If Regular is selected and a maximum number of entries is specified. /M[AP]:FULL If Full is selected. ═══ Copy Source Line Numbers to Map File ═══ Select this option to include line number information in the map file generated. The corresponding command line option is /LI[NENUMBERS]. ═══ Map File Name ═══ Enter the name of the map file to be produced. If one is not specified, no map file will be produced unless either Regular or Full was selected. If no extension is specified, the linker assumes the extension is MAP. ═══ File Name Options ═══ This page lets you specify the names of the following files: Generated Executable File Name The name of the module file. Libraries To Use The names or paths of any libraries to be used for resolving external references. You can also specify paths to be searched for the required libraries. Definition File Name The name of the definition file used to build the module. ═══ Generated Executable File Name ═══ Enter the name of the module file to be produced. If a name is not specified, the linker uses the file name of the first object passed to it and adds an extension of either EXE or DLL as appropriate. If a name is specified without an extension, the linker assumes the extension is either EXE or DLL. ═══ Libraries to Use ═══ Enter the names of the libraries, one per line, to be searched when the linker tries to resolve the external references found in the objects it is linking. If no extension is specified in a library name, the linker assumes the extension is LIB. The linker searches these libraries before those specified in the objects themselves. You can also specify paths to be searched for the required libraries. Any paths you specify will be searched before those in the LIB environment variable. ═══ Definition File Name ═══ Enter the name of the definition file used to build the module. If no extension is specified, the linker assumes the extension is DEF. ═══ WorkFrame Default Options Dialog ═══ Use this dialog to define the command-line parameters to be passed to a tool when it is executed. For certain actions that produce error messages, you can also define error templates so that WorkFrame can recognize error messages and determine what file to edit to fix the error. Depending on the scope setting for the action, you may be able to specify options for the file-scoped form of the action, the project-scoped form, or both. The different variations in the controls of this dialog come from the different entrypoints in the IWFOPT actions support DLL, which you specify in the action settings notebook. Actions that use support DLLs other than the WorkFrame default might provide different dialogs to set action options. Controls Parameters Fill in a string that represents the command-line parameters to pass to the tool. You can represent variable items, such as file names, using substitution variables. Error template(not always present) Fill in a string that represents the format of an error message. You will be able to launch an editor from the monitor window by double-clicking on the error message. You can represent the information needed to locate the error using a set of substitution variables (different than the ones in the Parameters field). Send errors to editor(not always present) This check box only applies to Edit actions. Select it if the editor supports Dynamic Data Exchange (DDE), so that requests to edit a particular file or location can be transmitted to a running editor session. Prompt Select this check box if you want to enter the options string interactively, when the action is executed. Options entered in response to the prompt override the options specified in the Parameters field. Undo (on notebook page) Restores the page to the same settings as when you opened the dialog. The Undo pushbutton on the notebook frame undoes the changes for all notebook pages. Default (on notebook page) Restores the page to its default values. The Default button on the notebook frame restores the default values for all notebook pages. Help (on notebook page) Displays help for the notebook page. The Help button on the notebook frame displays help for the overall notebook. OK (in notebook frame) Closes the dialog and saves all the settings. Close the dialog with this pushbutton rather than with the System menu to preserve any changes you have made. Undo or Reset (in notebook frame) Restores all pages to the same settings as when you opened the dialog. Default (in notebook frame) Restores all pages to their default values. Cancel (in notebook frame) Exits without performing the operation or saving data. Closing this dialog using the System menu has the same effect: changes are not saved. Help (in notebook frame) Displays help for the overall dialog. The Help button on each page displays help for that page. Related information o Entrypoints in IWFOPT.DLL o Substitution variables for option strings o Substitution variables for error templates ═══ Substitution variables for option strings ═══ Typically, you will use substitution variables in the options string to refer to variable items, such as file names. The substitution variables you can use are: │ %a %z │Is replaced by the names of all the selected files, │separated by a space. If the space between the 'a' and the │'%' is replaced by a string, the names are separated by that │string. For example, if the selected files are d:\cat.obj, │d:\dog.obj and d:\bird.obj the substitution variable %a+%z │produces the string │ d:\cat.obj+d:\dog.obj+d:\bird.obj │The only substitution variables allowed within the %a %z │substitution variables are %% and %d. ──────────┼──────────────────────────────────────────────────────────── %d │Is replaced with the project's working directory. ──────────┼──────────────────────────────────────────────────────────── %e │Is replaced by the extension (including the period) of the │first selected file. ──────────┼──────────────────────────────────────────────────────────── %f │Is replaced with the fully qualified name of the first │selected file. Specifying %f is the same as specifying │%q%n%e. ──────────┼──────────────────────────────────────────────────────────── %m │Is replaced by the make file name specified for the project │in its Settings notebook. ──────────┼──────────────────────────────────────────────────────────── %n │Is replaced by the file name (without an extension and path) │of the first selected file. ──────────┼──────────────────────────────────────────────────────────── %o │Is replaced by the target file name specified for the │project in its Settings notebook. ──────────┼──────────────────────────────────────────────────────────── %p │Is replaced by the fully qualified project file name. ──────────┼──────────────────────────────────────────────────────────── %q │Is replaced by the path of the first selected file. ──────────┼──────────────────────────────────────────────────────────── %r │Is replaced by the run options set for the project target │file in the project's Settings notebook. ──────────┼──────────────────────────────────────────────────────────── %t │Is replaced by the fully qualified file name (without an │extension) of the project's target. ──────────┼──────────────────────────────────────────────────────────── %TOPIC% │Is replaced by the contents of the Help Topic field in the │action's Settings notebook. This field specified the help │topic to be displayed when the user requests help on the │action. ──────────┼──────────────────────────────────────────────────────────── %% │Is replaced by the % symbol. │ Related information o Substitution variables for error templates ═══ Substitution variables for error templates ═══ The substitution variables in the table below are used to specify error message format in error templates. WorkFrame uses error templates to parse error messages in a monitor window when you double-click on an error message to invoke the editor. │ %f │Is replaced by the name of the file name where the error │occurred. If the error message does not emit a │fully-qualified file name, the editor may not be able load │the file if it is not located in the project's Working │directory. ──────────┼──────────────────────────────────────────────────────────── %i │The line in the source file at which the error occurred. ──────────┼──────────────────────────────────────────────────────────── %c │The column in the source file at which the error occurred. ──────────┼──────────────────────────────────────────────────────────── %t │The text of the error message. │ Related information o Substitution variables for option strings ═══ Lib tool options ═══ Use the options on this page to specify the options for the command line Library Manager (LIB.EXE). Controls Display the logo Is equivalent to not using the /NO[LOGO] option. Respect case of names Is equivalent to using the /NOI[GNORECASE] option. Create the extended dictionary Is equivalent to not using the /NOE[XTDICTIONARY] option. Set page size Is equivalent to the /P[AGESIZE] option. Set listing level Is equivalent to the /L[ISTLEVEL] option. List file name Is equivalent to specifying the name of the listing file on the command line. Library file name Is equivalent to specifying the name of the library file on the command line. The %o substitution variable represents the target file name specified on the Target page of the project's Settings notebook. OK (in notebook frame) Closes the dialog and saves all the settings. Close the dialog with this pushbutton rather than with the System menu to preserve any changes you have made. Undo or Reset (in notebook frame) Restores all pages to the same settings as when you opened the dialog. Default (in notebook frame) Restores all pages to their default values. Cancel (in notebook frame) Exits without performing the operation or saving data. Closing this dialog using the System menu has the same effect: changes are not saved. Help (in notebook frame) Displays help for the overall dialog. The Help button on each page displays help for that page. ═══ Build Options ═══ ═══ 6. Build Options ═══ Use this notebook to set the options used by a Build action. You can customize the build for speed, efficiency, convenience, and single-user or team development. Pages o Actions o Make o Project o Display Controls OK (in notebook frame) Closes the dialog and saves all the settings. Close the dialog with this pushbutton rather than with the System menu to preserve any changes you have made. Undo or Reset (in notebook frame) Restores all pages to the same settings as when you opened the dialog. Default (in notebook frame) Restores all pages to their default values. Cancel (in notebook frame) Exits without performing the operation or saving data. Closing this dialog using the System menu has the same effect: changes are not saved. Help (in notebook frame) Displays help for the overall dialog. The Help button on each page displays help for that page. Related information o You can also run this utility from the command line. Enter IWFBUILD /? for information about the command-line options. o Background information about the Build utility ═══ 6.1. Actions ═══ The settings on this page determine which of the actions in the project are processed by the build action. You can do partial builds by omitting some actions. The choices here override the similar choices you can make in the MakeMake utility. The actions that are listed on this page are those that are file-scoped and have at least one source type and at least one target type specified. These types are used by MakeMake to determine the order in which the actions are to be executed. Controls MakeMake Runs the MakeMake utility to produce a new make file separately from this dialog. Reset Restores the page to the same settings as when you opened the dialog. Default Restores the page to its default values. Help Displays this help panel. Related information o Selecting actions for Build and Make ═══ 6.2. Make ═══ The settings on this page determine how the Build action generates and runs make files. Controls Generate a make file Select this check box if you want WorkFrame to automatically determine file dependencies and produce a new make file each time this Build action is executed. Deselect this check box if you have your own make file that you want the Build action to use. Replace make files not generated by MakeMake This check box is a safety feature to prevent WorkFrame from accidentally overwriting a customized make file. Select it if you want WorkFrame to overwrite the existing make file, regardless of any modifications you have made to it. Generate a dependency file Select this check box if you want the dependency information to be stored in a separate file, rather than as part of the make file. Dependency file extension If the build is to generate a separate dependency file, enter the extension (usually .DEP) here. Make file generator Allows you to replace the program that generates a make file, if you want the generated make files to be compatible with some other make utility. The generator program must transform intermediate (.$MM extension) files to finished make files. If you need information about writing a make file generation script, you must get the WorkFrame Integration Kit, which will be available through the IBM support channel for this product. Make command If you want the build process to use a Make command other than the WorkFrame-supplied default, enter the command here. Reset Restores the page to the same settings as when you opened the dialog. Default Restores the page to its default values. Help Displays this help panel. ═══ 6.3. Project ═══ The settings on this page determine how to process projects that are nested inside one another, and allow you to speed up builds of projects for which you are the only developer or builder. Controls Use build settings from parent project Leave this check box selected unless this project is nested within another, and you want to build it with different settings than its parent project. When this check box is selected, the parent's Build settings override any settings for this project. Pass build settings to subprojects Select this check box to allow any nested projects to assume this project's Build settings. If you do not select this check box, and the subprojects are set to use the Build settings from their parent, they will assume the Build settings from this project's parent instead, if one exists. If this project is at the root of a project hierarchy, its subprojects must define Build settings of their own or their builds will fail. Build any subprojects first Deselect this check box to perform a partial build. The current project will be built, but any projects nested inside it will not. For example, you might want to build an executable without rebuilding a DLL upon which it depends. Lock the project as it is built Leave this check box selected unless you are the only person who will be building the project. It speeds up the build process by omitting checks that prevent multiple simultaneous builds of the same project. Ensure the project target is not in use Select this check box to have the build utility check if the target can be accessed before starting the build. If the target is in use, the build will not start. Reset Restores the page to the same settings as when you opened the dialog. Default Restores the page to its default values. Help Displays this help panel. ═══ 6.4. Display ═══ The settings on this page determine what kinds of interactive prompts to display during a build. Controls Prompt if errors are detected during build Select this check box if you will be watching the build in person, and might want to react to any errors that occur. Deselect it if you will leave the build running unattended, or if you want the build to run to completion regardless of any errors that occur. Display the MakeMake window during build Select this check box if you want to explicitly create a make file using MakeMake during a build. This check box allows you to customize the makefile generation each time the build is run. Reset Restores the page to the same settings as when you opened the dialog. Default Restores the page to its default values. Help Displays this help panel. ═══ Background information about the Build utility ═══ The WorkFrame Build utility eliminates the need for explicitly generating and maintaining make files. It uses the MakeMake utility to generate a new make file each time a Build is initiated. You can also set Build options to have the Build utility build all targets, even if they are not out of date with respect to their dependent files, or to effectively perform a Make action by only building the out-of-date files. Build Prerequisites The Build utility relies on a well-defined project setup to correctly generate the build rules and dependency information for your project: o The project dependencies must be expressed within the project hierarchy. o Correct Build options, especially the build actions, must be set. o The actions must have the source and target types set up correctly. o The Actions Support DLLs associated with each action involved in the Build must provide a correct list of dependencies to the MakeMake utility. Note: The default WorkFrame actions are already configured correctly for use in your builds. If you use only these actions in your builds, you only need to concern yourself with the first two prerequisites. You start a build action on your project by selecting Build from the project's pop-up menu or toolbar. ═══ Selecting actions for Build and Make ═══ You can select the build actions from the Actions list box in the Build options dialog, or you can run the MakeMake utility and select Build actions there. Where you select the Build actions depends on: o Whether you want to have descendant projects use the same set of Build actions. If you do, you will need to: 1. Select the Build actions from the Actions list box in the Build options dialog. 2. Select the Pass Build settings to child projects on the Projects page in the Build options dialog. 3. In the Build options for the descendant projects, select the Use build settings from parent project in the Project page (this is the default). The Build actions you select in the Actions list box apply to all the source files in the project. If you only want the Build actions to apply to some of the source files in the project, you must select the Build actions and applicable source files from MakeMake. o Whether you want to explicitly select source files to which the Build actions should apply. If you do, you will need to select the Build actions from MakeMake. Descendant projects cannot use the current project's Build actions if they are specified from MakeMake. MakeMake saves the actions from your last successful make file generation in the extended attributes of the generated make file. If you already have a make file generated by MakeMake, you can use the previously saved actions by deselecting any actions selected in the Actions list box. Note: If any actions in the Build options Actions list box are selected, those actions are used for the Build, even if Build actions were previously set from MakeMake. ═══ MakeMake limitations ═══ The MakeMake utility creates make files that build a single target by invoking a series of actions. Since projects are typically organized as a hierarchy of projects, with each project in the hierarchy representing a single target, MakeMake works very well with WorkFrame projects. However, there are some limitations that you should be aware of. Note: These limitations would only concern you if you need to: o Work with projects that use multiple PAMs o Build with actions that use third-party Actions Support DLLs o Use actions that specify user-defined types Here are four important MakeMake limitations: o The source and target types of each action involved in the make must be specified correctly so that MakeMake can infer the order in which the actions are to be executed. o The types specified in each action's settings for Source types and Target types must be of the type classes "FileMask", "Logical OR", and "NOT in Logical OR" or MakeMake will ignore the type. All the predefined types are of the allowed classes, "FileMask", "Logical OR", and "NOT in Logical OR". The other type classes can be used to specify the source types of actions that are not used in builds (such as Edit), and for the project Parts filter. o MakeMake only works with project parts that are accessed by the basic PAM (IWFBPAM) and other PAMs derived from it. o MakeMake calls application programming interfaces (APIs) in the Actions Support DLLs of every action involved in the make to determine the list of project parts or files the source is dependent on. The accuracy of the dependencies and targets list is dependent upon the Actions Support DLL for each action, not the MakeMake utility. If MakeMake fails to generate the correct list of dependencies or targets for a user-written or third-party action, contact the supplier of the Actions Support DLL. ═══ 7. Project migration tool - Main window ═══ Use this tool to create projects for the current version of WorkFrame, based on existing projects for earlier WorkFrame versions. After the migration process is completed, you can start working with the new projects using the latest version of WorkFrame, and the original projects remain unchanged so that you can archive them. Controls Migrate V1.X projects Selects the migration process that applies to WorkFrame Version 1.X projects. When this check box is selected, you must enter the name of the directory where the project is stored. V1.X project directory Displays the full path name of the directory where WorkFrame Version 1.X projects are located. You can use the Change directory pushbutton to locate the directory. Then use the Find projects pushbutton to locate and select the projects. Change directory Displays a Find dialog where you can locate a directory that contains WorkFrame Version 1.X projects. Then use the Find projects pushbutton to locate and select the projects. Migrate V2.X projects Selects the migration process that applies to WorkFrame Version 2.X projects. When this check box is selected, you must select one or more drives to search for projects to be migrated. Select drives Select one or more drives to search for WorkFrame Version 2.X projects to migrate. Then use the Find projects pushbutton to locate and select the projects. Find projects Automatically searches for projects to migrate, in the directory or on the drives that you selected. After the search is finished, another dialog is displayed where you can select which V2.X or V1.X projects to migrate. Stop search Interrupts the search for projects to migrate, then proceeds to the next migration phase where you select the individual projects. As the search for V2.X projects can take a long time, you might want to stop the search once it has located all the projects that you want to migrate. Cancel Closes the window without performing any operation or saving any data. Related information o What is migrated from Version 1.X projects o What is migrated from Version 2.X projects o V1.X migration window o V2.X migration window ═══ 7.1. Select V2.X Projects to Migrate ═══ Use this window to migrate Version 2.X projects. Select one or more projects, decide whether the default actions are sufficient or if you need to migrate a customized actions profile, then press the Migrate pushbutton. If not all the information for a Version 2.X project is available, you might see error messages in an Action Log window. The migration process will continue despite these messages, and migrate as much of the project as possible. Controls Projects Lists the projects on which you can perform the migration process. Select any existing projects for which you want to create equivalent WorkFrame Version 3.0 projects. This process creates a new project, and does not change the original project. After selecting some projects, you can use the Migrate pushbutton to start the migration process. If there are projects that you want to migrate but are not listed, you can use the More projects pushbutton to select them one at a time. Only projects Generates new projects without including the actions or action profiles that were defined in the existing projects. The new projects will use the same set of default actions as other newly created projects. Select this check box if you have not integrated your own tools into the projects that are being migrated, and will be using the default tools and menus under WorkFrame Version 3.0. Projects and actions Generates new projects that include the actions or action profiles that were defined in the existing projects. Select this check box if you have integrated your own tools into the projects and do not want to have to do this work again in the migrated project. Migrate V2.X action options When you migrate the actions for a project along with the project itself, this check box selects if the action options are migrated too. Otherwise, the migrated actions use the WorkFrame defaults for command-line option strings, error templates, compiler options, and so on. Migrate Starts the migration process. The migration tool creates a folder on your desktop called WorkFrame V3.0 Migration which contains two folders called WorkFrame V3.0 Projects and WorkFrame V3.0 Action Projects. If you chose not to migrate the actions from your old projects, the latter folder is empty. The WorkFrame V3.0 Projects folder contains the migrated projects. Stop Interrupts the migration process. You can stop the process if something goes wrong or you change your mind before it is finished. More projects Allows you to select more projects for the migration process, one at a time through a Find dialog. Cancel Exits from the window without performing the migration process. Related information o What is migrated from Version 2.X projects ═══ 7.2. Select V1.X Projects to Migrate ═══ Use this window to migrate Version 1.X projects. Select one or more projects from the list and then select the Migrate pushbutton. Controls Projects Lists all the WorkFrame Version 1 projects that are in the directory you selected from the previous window. Migrate Begins the migration process. The migration tool creates a folder on your desktop called WorkFrame V3.0 Migration in which a folder called WorkFrame V3.0 Projects is created. WorkFrame V3.0 Projects folder contains your migrated projects. Projects migrated from Version 1.X inherit their actions from the default project for the product. Stop migration Interrupts the migration process before it is completed. Cancel Exits from the window without performing the migration process. Related information o What is migrated from Version 1.X projects ═══ What is migrated from Version 2.X projects ═══ Here is a list of the Version 2.X project information that is migrated by the project migration tool. Information migrated from projects: o Target name o Run parameters o Run prompt o Run monitored o Make file name o Source directories o Working directory o File name filter - The migration utility creates a new type called "Migrated file masks" and adds it to the project's Parts filter entry field. o Auto-scroll monitor o PAMs are migrated as follows: - DDE3BPAM to IWFBPAM - EVFP370 to IWFP370 - EVFPADM to IWFPADM - EVFP400 to IWFP400 - All others to IWFBPAM. The following information is migrated from action profiles into WorkFrame Version 3.0 projects: o Action scope (If an action is project-scoped, its controlling PAM defaults to IWFBPAM.) o Action source and target types o Action run mode o Options DLLs are mapped to new Actions Support DLLs as follows: - DDE3DEF2 to IWFOPT - DDE4ICC2 to CPPICC30 - DDE4ICL2 to CPPICL30 - All others are migrated as is. o Environment variables o Types (All types are migrated to types of class FileMask.) The following information is not migrated: o Since there is no concept of a composite project in WorkFrame Version 3.0, composite projects are not migrated. However, any base projects in a composite project can be migrated. The names of the migrated base projects include the name of their composite project in parentheses. ═══ What is migrated from Version 1.X projects ═══ The project migration tool migrates the following information from Version 1.X projects: o Target name o Make file name o Source directories o Working directory o File name filter Actions are not migrated. ═══ 8. Project Smarts ═══ Project Smarts is a powerful tool to help you get started quickly writing your applications. It is a catalog of template applications you can use as a base with which to write your own applications. products that incorporate the WorkFrame component. is defined as an IPFCPREP macro in IWFCSH.PRE. This feature is optional and might not be present in all products that incorporate the WorkFrame component. The Project Smarts catalog lists the available applications in the Available projects list box. As you select an application name, the Description field is updated with a short description of the application. To create a project, select it and then select the Create push button. You will be prompted for a folder in which to create the project, a directory in which to copy the source files (if it does not exist, it will be created for you), and the name you want to give the created project. You may also be prompted for customization information. A Progress Console appears showing the progress of the install. After the project has been created, it will contain skeleton source files for your application. All the actions necessary to build the applications are configured. ═══ 8.1. Progress Console ═══ The Project Smarts Console shows the progress of the project creation. It has three areas: o The Progress Indicator shows how much work has progressed since the creation was started. o The Status Area shows the current status message. o The Message log shows more detail, and a history of the current status. ═══ 8.2. Location ═══ The Location window prompts you for the folder in which to create the project, the directory in which to copy the source files, and the name to give the new project. It has three fields: Project Enter the name you want to give the new project in this entry field. Directory Enter the fully-qualified path name of the directory where you want the source files to be copied. This directory will be the new project's working directory. Folder This field contains a tree view of all the folders on your Desktop. Select the folder where you want your new project created. ═══ 8.3. Variable Settings ═══ Use the Variable Settings window to customize the generated project by setting values for certain substitution variables, such as the source-file prolog text, current date, and your name. As you select each variable name in the Variable list box, the Variable Description and Variable Setting fields are updated to show a short description of the variable and its default value. Verify the defaults and set values of your own. To change the default values, edit the Value field. The values that you set are used when the application is installed. They are also saved for the next time you install the same Project Smarts application. ═══ 8.4. Project Smarts Settings - Catalog Page ═══ Use the Catalog page of the Project Smarts Settings notebook to change the settings of a Project Smarts application, or add another application to the catalog. To change an application, select it and then select the Settings... push button. To add an application, select the Create another... push button. The Catalog entry window appears where you can change or define the settings for a Project Smarts application. For more details on how to add your own Project Smarts application to the Project Smarts catalog, or how to create a catalog of your own, please refer to the "Project Smarts" chapter of the WorkFrame user's guide. ═══ 8.4.1. Catalog Entry ═══ Unless you are providing your own Project Smarts application, the Catalog Entry window will not be of much interest to you. For more information about this window, and how to provide your own Project Smarts application or catalog, see the "Project Smarts" chapter of the WorkFrame user's guide, called Developing Applications with WorkFrame. The Catalog Entry window contains fields that define a Project Smarts application: Project Enter the project's title. The application is listed under this title in the catalog. It is also the default title for the created project. Description Enter a description of the application. This description also appears in the catalog. Source Enter the location of the base source files for the application. The location can be a directory or an existing WorkFrame project. The install script copies the source from this location. Script Enter the name of the Project Smarts REXX install script that creates the Project Smarts application. You can enter a fully qualified path name or a command file found on the PATH. You can specify your own customized script, or use the default script, IWFSMART.CMD. Parameters List any parameters that your install script may require. Project Smarts will pass these parameters to your script when it invokes it during the installation. Three substitution variables are also available to be passed as parameters to your script: %project% The name of the project, as specified in the Project field of the Catalog Entry window when the Project Smarts application was added to the catalog. The install script can use this name as the default name of the project it creates. %location% The directory where the base source files are located, as specified in the Source field of the Catalog Entry window. Your install script can use this information to copy the files from the source directory, or do some other file processing. %description% The description of the application, as specified in the Description field of the Catalog Entry window. %catalog% The fully-qualified path name of the Project Smarts catalog. The path name of the catalog is a required parameter for the IwfSaveVariables and IwfRestoreVariables utilities because the variable settings are stored with the Project Smarts catalog. If you use the default installation script (IWFSMART.CMD), enter the required parameters %project% %location% in the Parameters entry field. Select the OK push button to make your changes active. ═══ 8.5. Project Smarts Settings - Display Page ═══ Use the Display page of the Project Smarts Settings notebook to configure which dialogs to display during the creation of a Project Smarts application. You can select the following check boxes: Display the installation console Select this option to always display the Project Smarts Progress Console whenever you create a project from Project Smarts. If you do not select this option, the Progress Console will not appear during the installation. Display the variable settings dialog Select this option to always display the Project Smarts Variable Settings window whenever you create a project from Project Smarts. If you do not select this option, you won't be able to customize the created project at installation time. Instead, Project Smarts uses the default variable settings, or the settings specified the last time the application was installed. ═══ Find directories ═══ Use this window to select one or more directories. There are two versions of this window, one for selecting one directory (with only Drives and Directories controls), and an extended version for selecting multiple directories that includes extra pushbuttons. 1. Select a drive from the Drives dropdown list box. 2. Select a directory from the Directories list box. Double-click on a directory to see any subdirectories it contains. 3. In the extended version of the window: o Select the Add pushbutton to add the selected directory to the list of Selected directories. o Repeat this process as often as necessary until you have selected all the directories you want. o You can also remove a selected directory from the Selected directories list box with the Remove pushbutton. To confirm your selection, select the OK button. To cancel the selection, select the Cancel button. ═══ Find and Open Windows ═══ Use the Find and Open windows to locate and select an object such as a file or a project. To locate and select an object: 1. Select the arrow to the right of the Drive list to display all the drives on your system. 2. Select a drive from the Drive list. 3. Select a directory from the Directory list. Note: By default, WorkFrame projects are located under the operating system's Desktop directory. If a project is nested inside a base project, then the associated project file is located in one of the source directories of the base project. 4. Select a file name from the File list or type in a file name and select the OK push button. Note: This list shows only the physical file name of projects. To determine the physical file name for a project, check the File page in its settings notebook. If you are using the FAT (File Allocation Table) file system, the file name is usually the first eight letters of the objects title. If the first eight letters are common to another object in the directory, the file name ends in a number. For example, the projects Test Project 1 and Test Project 2 could appear as TEST_PRO TEST_PR1 For a detailed explanation of each field, select from the list below: o Open filename o Type of file o Drive o Files o Directory o OK o Cancel ═══ Open Filename ═══ Type the name of the file you want to open in the Open filename field. ═══ Type of File ═══ Select the arrow to the right of the Type of file field to display the available file types. The contents of the field and its combination box depend on what task you are performing. ═══ Drive ═══ The Drive list displays the drives on your system. Select the drive that contains the file you are looking for. ═══ Files ═══ The File list displays all the files in the directory you selected from the Directory list that match the Type of file indicated. Select the file you want from this list. ═══ OK ═══ Select this pushbutton when you have selected the file. ═══ Cancel ═══ Select this pushbutton to close the window without selecting a file. ═══ Directory ═══ The Directory list displays the directories on the selected drive. Select a directory to display the list of files from that directory in the File list box. ═══ Confirm Deletion ═══ Use this window to verify you want to delete all the items shown from the project. Select the OK or Yes pushbutton to delete all the items, or the Cancel or No pushbutton if you do not want to delete all the items. ═══ Message Help ═══ Explanation: A loop has been detected in the definitions of the source masks and target masks of the actions. The message box shows the actions and masks that caused the loop. Because of the loop, the order in which the actions need to be processed is unclear. Therefore, the make file generated by MakeMake may not be valid with respect to these actions. For example, suppose you have a project where: 1. The compiler creates object files (*.OBJ) from source code (*.CPP). 2. The IMPLIB utility is used to create an import library (*.LIB) from a definition file (*.DEF). 3. The linker is used to create a dynamic link library (*.DLL) using the object files from the first step and the import library from the second step. You would then expect a make file with the steps shown below: *.CPP ──── *.OBJ ────┐  *.DLL  *.DEF ──── *.LIB ────┘ However, the IMPLIB utility can also build import libraries from DLLs. Therefore, the definition of the source masks within the action settings for the IMPLIB utility could have *.DLL as a valid source mask. In this case, MakeMake would internally build the following flow diagram as it tries to determine the order in which the actions should be invoked in order to make the project: *.CPP ──── *.OBJ ────┐  ┌──── *.DLL   *.DEF ──── *.LIB ────┘ Unlike the previous diagram, there is no clear end to the order of actions. MakeMake has detected this and issued a message. Recovery: There are two methods of dealing with this situation. The first method (strongly recommended) is to remove the loop by deleting one of the source masks or target masks listed in the loop above. In the above scenario, you could go to the action settings where the IMPLIB action is defined and delete the *.DLL entry from the source masks' list. Although removing a valid mask may seem unwise, you need to clarify the order of actions for MakeMake (If you prefer, you could duplicate the action that needs to be changed and then alter the name and masks of the duplicate. This way, you will have both generic and customized forms of the action. Then you can use the customized form only when required.) The second method is to continue with the processing and correct the two types of errors that may occur within the make file. Check for and correct these errors manually in the Change window. The first type of error is that the order in which the actions are processed is not valid, a situation that may result in incomplete file lists. For each action listed in the message, verify that it is dependent on all the required source files with the source mask also indicated in the message. The other type of error is that the .ALL dependency statement may be incomplete. Because of the loop, makemake may be unable to determine which files are final products. In the above example, the import library is as valid a final output as the dynamic link library is. Complete the .ALL statement manually. ═══ Message Help ═══ Explanation: When MakeMake is creating a make file, it first creates a list of potential source files for each action. This list is based on the source types and masks listed for the action. The list is passed to the support dynamic link library (DLL) that is used to set options for the action. If none of the files is selected by the actions support DLL, then MakeMake reports that no files have been selected for that action. This may occur if the set of source masks listed in the action's settings does not match the list of types maintained internally by the DLL. For example, an options DLL for the Link action might require that files with the extension OBJ (object files) be passed to it. However, if object files are not one of the types of files listed as source in the action's settings, no files can be selected. Recovery: Check the action's settings and ensure that the source types listed for the action are valid source types (type class "File Mask" or "Logical-OR") and that they apply to the action and to the files that exist in the project. ═══ Message Help ═══ Explanation: The MakeMake utility tried to use the project's parts access method (PAM) to list the project files, but the PAM could not provide the information. Recovery: Verify that the PAM is defined correctly for the project. If it is not defined correctly, close the MakeMake utility then reopen it. Try to recreate the make file. If the error persists, contact your IBM Service representative. If the project access method you are using was not supplied by IBM, contact the PAM supplier. ═══ Message Help ═══ Explanation: One or more of the selected actions is independent of the other actions. Each of the selected actions must be dependent on another selected action. The dependency between actions is defined by the source and target masks defined in the actions' settings. For example, if the following three actions are selected: o Compile (compiles source code into object code) o Link (links object files to build an executable file) o IPFCompile (compiles help files into help library files used by the executable file) and they have defined source and target masks as shown in the following table: ┌───────────────┬───────────────┬───────────────┐ │Action │Source mask │Target mask │ ├───────────────┼───────────────┼───────────────┤ │Compile │*.c │*.obj │ ├───────────────┼───────────────┼───────────────┤ │Link │*.obj │*.exe │ ├───────────────┼───────────────┼───────────────┤ │IPFCompile │*.ipf │*.hlp │ └───────────────┴───────────────┴───────────────┘ Based on the above information, two project targets could be built: o An executable file: ┌──┐ ┌────┐ ┌────┐ │.C├──icc───┤.OBJ├────link────┤.EXE│ └──┘ └────┘ └────┘ o Or a help file: ┌──┐ ┌────┐ ┌────┐ │.C├──icc───┤.OBJ├────link────┤.EXE│ └──┘ └────┘ └────┘ However, because you can have only one target for every project, the MakeMake utility cannot create the make file. Recovery: Review the list of selected actions and ensure that those actions that are required to make the project target are selected. Also, ensure that no action is selected which is not required to make the project target. If you need to build another target that is related to the project target (for example, the help library in the example above), create another project for that target, and then nest it into the first project by dragging it into the project's parts container. You can then create a separate make file for the Help Project. By doing this, you have established a dependency relationship between the .EXE project and the .HLP project. You can then use the Build utility to build both projects in sequence (the Help Project first, then the .EXE project). ═══ Message Help ═══ Explanation: There are no source files for the action indicated in the message. Every selected action needs to have one or more files corresponding to the Source masks specified in the action's settings. These files can either be part of the project's source files or be produced by another selected action. The MakeMake utility has determined that there are no project source files matching the action's source masks and that no other selected action will produce files with the required source masks. Recovery: If the action indicated in the message is not required to make the project, deselect it in the Actions list. Otherwise, determine if no source files can be found for one or more of the following reasons: o Do more files need to selected in the Files list? If so, select more files. o Is the action that is supposed to create the source files selected? If not, select the action. o If the action that is supposed to create the source files is selected, are its options set so that it will create the missing source files? (For example, a compiler's options could be set so that only the preprocessor is run.) If not, set the options. ═══ Message Help ═══ Explanation: The MakeMake utility has discovered that running the indicated action with its options will generate a file that does not correspond to any of the action's target types. Recovery: Add the correct type or mask to the action's Target types field in the action's settings. ═══ Message Help ═══ Explanation: This message tells you that the MakeMake utility has stopped creating the make file, as you requested. ═══ Message Help ═══ Explanation: The MakeMake utility requires that each selected action result in the creation of at least one file. However, the indicated action will not create any files. Recovery: Ensure that the action's options and the files selected for it would actually create files with the target mask indicated. An option may have been set that prevents the action from doing so. For example, an option could be set that causes the action to simply list the command line syntax without producing any files. ═══ Message Help ═══ Explanation: An options string with incorrect substitution variables was returned to the MakeMake utility. Recovery: Ensure that the invocations string supplied by the action's support DLL in the message returns an invocation string with valid WorkFrame substitution variables. ═══ Message Help ═══ Explanation: A make file cannot be produced unless the project has an action available to it. The action must also operate on the project's parts. ═══ Message Help ═══ Explanation: The MakeMake utility has created the make file successfully but cannot fully display it in the Results window because the file is too large. As much of the make file as possible is displayed, but you cannot edit the file within the MakeMake utility. Save the make file and use a text editor to view the whole file and make any changes. ═══ Message Help ═══ Explanation: You selected a control that removes some or all of the changes you have made to the make file. Recovery: Select Yes if you want to discard your changes. Otherwise, select No. ═══ Message Help ═══ Explanation: You are about to close the MakeMake utility without saving the make file. Recovery: Select Yes if you want to exit without saving the make file. To save the make file, select No, then select Save make file from the File pulldown menu, and exit. ═══ Message Help ═══ Explanation: Another make file with the same name already exists. Recovery: Select Yes if you want to overwrite the existing make file. Otherwise, select No. ═══ Message Help ═══ Explanation: You are being asked to verify that you want to stop the creation of the make file. Recovery: Select Yes to stop the creation of the make file. Select No to continue processing. ═══ Message Help ═══ Explanation: One of the files selected in the Files list is both a target for one of the selected actions and a dependency on another selected file. For example, suppose you selected an action Compile which can operate on the files with extensions .C and .H. If you also selected the files TEST.C and TEST.H (which is included by TEST.C), you would get this message. Recovery: Modify your selections in the Actions and Files list boxes so that no file is both a target for one of the selected actions and a dependency on another selected file. Because your choices are saved between invocations of the MakeMake utility, you do not have to reselect the changes you made in this session in future sessions. ═══ Message Help ═══ Explanation: WorkFrame could not load the project files because it could not access the working directory. The working directory may be incorrect or inaccessible. Recovery: Ensure that the working directory is correct and that you have access, then retry the operation. ═══ Message Help ═══ Explanation: The parameter you specified is not valid. Recovery: Ensure that the parameters you specified are correct. To obtain a list of allowed parameters, type: iwfmmake /? >filename on the command line, or refer to the User's Guide. ═══ Message Help ═══ Explanation: Changes have been made to the make file since it was last generated by MakeMake for this project. Recovery: Select Yes if you want to continue. If MakeMake is completed successfully, the old make file will be replaced. Select No if you want to stop MakeMake. ═══ Message Help ═══ Explanation: Not enough memory is available for MakeMake to operate. Recovery: Stop any large processes that are running and ensure that your swap path is large enough. Retry the operation. ═══ Message Help ═══ Explanation: You cancelled the loading of the project. Recovery: No action is required. ═══ Message Help ═══ Explanation: The system could not handle an exception that was thrown. Recovery: Shut down your system and restart it. Restart the program. If the problem persists, contact your IBM Service Representative. ═══ Message Help ═══ Explanation: For project portability, MakeMake requires a Rexx Script file for every project, but it could not find a Rexx Script for this project. The Rexx Script file name is specified in the build options dialog. Recovery: Ensure that the Rexx Script file name is specified in the directory contained in your PATH statement. The default Rexx Script file is IWFMMGEN.CMD, which is supplied with the WorkFrame. ═══ Message Help ═══ Explanation: The indicated file name is not allowed for the file system in use, or the working directory of the project is on a read-only drive. Recovery: Ensure that the file name is in an allowed format, and that the working directory can be written to. ═══ Message Help ═══ Explanation: MakeMake requires a working directory for the project, but you have not specified one. The working directory is specified in the project's Settings pages. Recovery: Specify a working directory for the project, then retry the operation. ═══ 9. Terms used in this document ═══ action A description of a tool or function that can be used to manipulate a project's parts, or build a project's target. action class A grouping of actions that perform a similar function. actions support DLL A dynamic link library that provides such support for an action as determining dependencies and targets if the action is to participate in a build, providing a user interface for setting options, and integration with the monitor and editor. base project A project from which another project inherits its tools setup. Distinguished from parent project. build An action that invokes the WorkFrame Build tool. The Build tool manages the project's make file, as well as build dependencies between projects in a project hierarchy. build actions A series of actions that are invoked to build a project's target. These actions are set in the Build options window, or in MakeMake, WorkFrame's make file creation utility. default action Each action class has a default action. It is defined as the first action listed for the class. working directory The directory where files that are copied or dragged into the project are stored. Actions are also executed in this directory, so this directory is where many output files are placed. default editor The editor that is first in the list of editors in the Tools setup window. This editor is invoked when you double-click on an error message in the monitor, or when another tool requests an Edit action to be invoked. environment variable In a WorkFrame project, an environment variable is an operating system variable, like PATH and DPATH, and any other environment variables that are defined using the OS/2 SET command, such as TMP. file-scoped action Distinguished from a project-scoped action in that it is invoked on files. Only file-scoped actions can participate in a project build. filter In WorkFrame, the value of a type. The filter of a type can be expressed as a file mask, regular expression, a logical-OR, a logical-AND, or logical-NOT of a list of types, or a filter determined by a PAM. inheritance In WorkFrame, refers to the mechanism in which the tools setup of a project is shared by another project. make An action in which a project's target is built from a make file by a make utility. MakeMake WorkFrame's make file generation utility. Monitor A window that displays output from monitored actions. The Monitor window is attached to the project container. monitored action An action that has been set to run in the monitor window, and outputs to standard out. Actions may also run in full-screen and windowed sessions. nested project A project that appears inside another project. Nesting expresses a dependency of the parent project on the child project's target. This dependency is managed by WorkFrame's Build utility. parent project A project that contains other projects. Distinguished from child project. project The central WorkFrame model of the complete set of data and actions required to build a single target, such as a dynamic link library (DLL) or other executable. A project consists of a set of project parts and a Tools setup.. Project Access Method (PAM) A dynamic link library that contains a set of methods through which a simple abstraction of a file system or repository is provided to WorkFrame. PAMs enable a WorkFrame project to contain any kind of object that a PAM can support, for example a version of a file in a source control library, or another file system like MVS or AIX. project hierarchy A project tree that represents dependencies between projects. The WorkFrame project paradigm requires that one project should be created for every target. Dependencies between projects and their targets should be expressed in a project hierarchy. That is, if a project's build depends on the target of another project, the dependent project should contain the project it depends on. The dependent project is then said to nest the other project. This enables the Build tool to perform Builds in a depth-first search manner from anywhere in the project hierarchy. project-scoped action An action that applies to a project as a whole, or to a project's specially designated parts. Specially designated project parts are the project's make file and target. An example of a project-scoped action is Debug, which is invoked on the project's target. Project Smarts A project catalog that contains templates for common types of applications. Project Smarts application A skeletal application that consists of template source code and a configured project revolving around an application theme. It serves as a starting point for similar applications. source directory A directory where a project's parts are physically stored. A project may have many source directories. source type A source type appears in an action's list of source types. An action's list of source types specifies the kind of parts or files to which the action applies. target A project's target is the file that is produced as a result of a project build. target type A target type appears in an action's list of target types. Target types only apply to actions that participate in a project build, such as Compile and Link. The Build tool and MakeMake utility use the source and target types of build actions to determine the order in which the actions should be run to produce the project's target. template An object that you can use as a model to create other objects. When you drag a template, you create a copy of the original object. The new object has the same settings and contents as the original template object. Tools setup A view of a project where you can see and manipulate the actions, types, and environment variables available to the project. From this view, you can add, delete, and change actions, types, and variables. You can also set the options for any action in this view. type In WorkFrame, describes a group of project files of parts in terms of an expression, such as file masks, regular expressions, or a list of other types, logical-OR'd. type class In WorkFrame, represents the method by which an object is determined to be a member of a type. "File mask" is an example of a type class. Membership to a "File mask" type is determined by matching the file mask filter to the object's name. Other examples of type classes are "Regular expression", and "PAM Name", where the named Project Access Method determines membership to a type. ═══ IDD_IWFOPT_UTIL_ERRLBOX ═══ Help for IDD_IWFOPT_UTIL_ERRLBOX, RES ID 212. No help text is available at this time. ═══ Prompt dialog ═══ Enter a command-line options string to be passed to the action. This string can contain substitution variables. If the action is file-scoped, the files that are selected when the action is executed are displayed in the Source files to use for this invocation list box. You can select which files are passed as command-line options by entering substitution variables in the options string and selecting one or more files in the list box. For example, if the options string uses the %f substitution variable, you can select one file name. If the options string uses the %a %z substitution variable, you can select multiple file names. ═══ 10. Organizing projects ═══ Organizing your projects well is key to using the WorkFrame environment effectively. The organization of your projects determines the way in which they are built, and the way in which make files are generated for your applications. Most of your applications will most likely consist of a hierarchy of projects, rather than a single project, unless they are very simple. It is important that your project hierarchy reflects the project targets and dependencies between components for builds to be performed correctly. Follow these guidelines for a well-defined project hierarchy: 1. Create a separate project for each target or build path in your application. A target is defined as a single part or file that the project will build, such as an executable file, dynamic link library, or help file. A build path is a sequential processing of actions, with no conditional or alternative routes, that produces a single target file. Intermediate files may also be produced during the processing of a build. If your application consists of a two DLLs, a LIB, an EXE, and a HLP file, for example, you should create a separate project for each DLL, the EXE, the LIB, and the HELP file. If LIBs are also produced from the DLLs, the DLL and the LIB can be part of the same project. The LIB would be the designated target of the project, and the DLL is considered an intermediate file. In this example, you would create five projects in all. Five projects in a sample application 2. After you have created the projects, determine the dependencies that exist between them. For example, the DLLs may depend on the LIB, and the EXE depends on the DLLs. Also determine the project that is at the root of the dependency hierarchy, that is, the project that has no dependents. In this example, it is the EXE. 3. Nest the projects to reflect the dependency tree. That is, if a project EXE depends on another project DLL, place project DLL into project EXE. Project DLL is then said to be nested within project EXE. A project is nested in another project when its physical file is located in one of the source directories of the nesting project. You can move a project into another project by dragging it or by selecting Move from its pop-up menu. Note: a. When you move a project into another project, you are actually moving the nested project's physical file into the nesting project's working directory. So if you move a project into another project using the Move pop-up menu item, you will need to specify one of the parent project's source directories as the target in the Move dialog. b. When you move a project, you don't need to move its parts as well because the project does not actually contain its parts, but only a reference to their location. In a situation where two or more projects (say First DLL/LIB and Second DLL/LIB) depend on the same project LIB, nest one of the two depending projects within the other (say, nest Second DLL/LIB within First DLL/LIB), and then nest the mutual dependency project LIB within project Second DLL/LIB. Projects First DLL/LIB and Second DLL/LIB depend on project LIB The root project in the dependency tree will directly or indirectly contain all the other projects in the application. Example Consider the example application that consists of an EXE, two DLLs, a LIB, and a HLP file. The two DLLs depend on the LIB, the EXE depends on the DLLs and the HLP file. The LIB and HLP files do not depend on any other targets. The project hierarchy would look like the one in the following figure. Project hierarchy of a sample application The EXE project is the root project that contains all the other projects. First DLL/LIB and Second DLL/LIB both depend on the LIB, so one nests the other before nesting the LIB project. The two DLLs also produce a LIB file each, so the specified target of each DLL project is a LIB file, because it is the final file produced by a build. You should nest projects this way because the WorkFrame Build utility infers the build sequence from the project hierarchy. When you use the Build utility to build a project, you have the option of having it build descendant projects first. Following this scheme ensures that a project's descendants contain the current project's dependencies. 4. All the files used by the projects in your application can be stored in one or more directories. For example, all the source files to build the DLLs and LIBs could be stored in one directory, all the source files for the EXE in another, and all the HLP files in a third or fourth directory. Nesting Note If you store the files for each project in a different directory, the target of a nested project is not automatically considered a part of the nesting project. You must include the directory that contains the required target in the source directories list of the nesting project. As a better alternative, you could define an environment variable in the nesting project so that the required target is available. For example, the EXE project could define the LIB environment variable in its Tools setup to contain the working directory path of the LIB project whose target it depends on. For example, if the First DLL/LIB project's files are stored in a different directory from the EXE project, say in D:\MYAPP\LIB1, the EXE project must define the LIB environment variable to contain that directory so that the Link action is able to find the required library file: LIB=D:\MYAPP\DLL1;%LIB% Tip Your project's directory structure does not have to mimic your project organization. A project can contain source files that are stored in multiple directories. For example, two projects that build two different targets from the same source files can share one or more source directories, but have separate working directories. If your project has any header files that are stored in directories other than the project's working directory, you should define the INCLUDE environment variable to reference the header files. Add the INCLUDE variable to the project's Tools setup so that it is set in any WorkFrame-generated make files. Project Geometry To put things into perspective for you, this section discusses three different, but simultaneous structures that a project can maintain: two conceptual, and one physical. Inheritance An inheritance graph of all the projects in your system would connect lines between the projects that inherit their Tools setup from each other. If you can think of a project's actions, types, and environment variables as its "behavior", you can say that the projects in an inheritance graph borrow their behavior from one another. Nesting A nesting graph of all the projects in your system would be in the form of a tree, and would connect lines between projects and their subprojects. The organization of a project expresses the interdependency relationships that exist between itself and its descendants. This kind of project structure is very important for setting up project builds using the WorkFrame Build utility. The Build utility allows its options to be passed to a project's descendants, or borrowed from a parent project. Although this resembles an inheritance relationship, it is distinct from it. Build settings can only be passed down to nested projects, or assumed from a containing project. The projects participating in an inheritance relationship with the current project are not involved. Directories The source directories of a project determine a project's parts. The source directories of a project can mimic its nesting structure, or serve a different organizational purpose, such as grouping files by type. For example, private and public header files could be stored in separate directories from the rest of the source.