Index of Topics

- 1 -

10 "<file>" is not a valid bitmap file.
100 Trying to add a Win16 or Win32 RES file "<file>" to an OS/2 executable "<file>".
101 <value> is not a valid resource type.
102 Symbol <value> is not defined.
11 Trying to add a Win16 or OS/2 RES file "<file>" to a Win32 executable "<file>".
12 Trying to add a Win32 or OS/2 RES file "<file>" to a Win16 executable "<file>".
13 Object alignment increase required.  Relink with larger object alignment.
14 EXE contained old resources that could not be removed.
15 Error reading EXE file "<file>":  <reason>.
16 Error reading file "<file>":  Unexpected end of file.
17 Error writing to "<file>":  <reason>.
18 Error reading icon file "<file>":  <reason>.
19 Error reading cursor file "<file>":  <reason>.

- 2 -

20 Error reading bitmap file "<file>":  <reason>.
21 Error reading font file "<file>":  <reason>.
22 Error reading data file "<file>":  <reason>.
23 Error reading RES file "<file>":  <reason>.
24 Error reading temporary file "<file>":  <reason>.
25 Error writing to temporary file "<file>":  <reason>.
26 Unable to open temporary file "<file>":  <reason>.
27 Error reading from file "<file>":  <reason>.
28 Unable to read RES file "<file>":  wrong version.
29 "<file>" is not a valid RES file.

- 3 -

30 Internal compiler error <internal_error_num>.
31 Error writing resources to temporary file "<file>":  <resource>.
32 Error while closing file "<file>" or flushing buffers to it:  <reason>.
33 Error while closing temporary file "<file>" or flushing buffers to it:  <reason>.
35 RCINCLUDE keyword not currently supported.  Use #include.
36 '<src_char>' is not valid at this point.
37 String may not cross newline boundary.
38 Expecting '<expected_str>' but found '<src_char>'
39 Too many arguments:  <extra_name>

- 4 -

40 Filename required on command line.
41 Unknown option '<option>'
42 No options specified after options character.
43 Out of memory
44 No type given for accelerator <source_num>
45 Keyword <accel_type> ignored for type ASCII accelerator <source_num>
46 Duplicate resource:  <resource_name>
47 Internal parser error.
49 Syntax error near "<src_str>"

- 5 -

50 <source_num> is a duplicate string identifier.
51 Raw data item <source_num> is too big.  Max <max_num>
52 Raw data item <source_num> is too small.  Min <max_num>
53 Font name must be a number.
54 Can't #include more than <max_num> levels.
55 Unknown preprocessor directive
56 Invalid #line directive
57 Unknown option '<option>'
58 "<file>" is not a valid EXE file.
59 Unable to produce fastload section.

- 6 -

6 Unable to open file "<file>":  <reason>.
60 Can't find file "<file>".
61 Unknown target OS:  '<os>'
62 <preproc_msg>
63 Keyword "<keyword>" is only valid for Win32.
64 Keyword "<keyword>" not currently being supported.
65 Resource strings not found.
66 Error can't find character translation file "<file>".
67 Error opening character translation file "<file>":  <reason>.
68 Error reading character translation file "<file>":  <reason>.
69 "<file>" is not a valid character translation file.

- 7 -

7 Error renaming temporary file "<file>" to "<file>":  <reason>
70 Unable to read character translation file "<file>":  wrong version.
71 Option '<option>' not valid for a Win32 .RES file.
72 L"..." construct is not valid for Win16.
73 Options '<option>' and '<option>' may not be specified together.
74 Environment variable '<var>' is not set.
76 MENUITEM must have ID value.
77 Id/Type/State/HelpId not allowed for MENU POPUP controls.
78 MENUITEM options are not allowed for MENUEX POPUP controls.
79 Type/State not valid for MENU MENUITEM controls.

- 8 -

8 "<file>" is not a valid icon file.
80 MENUITEM options not valid for MENUEX MENUITEM controls.
81 HELPID not valid for DIALOG.
82 Font Italic setting not allowed for DIALOG.
83 Font Weight setting not allowed for DIALOG.
84 HELPID not valid for DIALOG controls.
85 Data Elements not valid for DIALOG controls.
86 <value> is not a valid resource id.
87 User interrupt detected.
88 Resource type for resource "<resource>" is greater than 32767.
89 Resource ID "<id>" is greater than 32767.

- 9 -

9 "<file>" is not a valid cursor file.
90 Unmatched quotation mark on command line.

- A -

Absolute and Relative Percentages
The Accelerator Editor Menu Bar
The Accelerator Editor Toolbar
Accelerator Editor:  Accelerator Item List
Accelerator Editor:  Action Buttons
Accelerator Editor:  Attributes Area
Accelerator Editor:  Changing Memory Options
Accelerator Editor:  Copy To
Accelerator Editor:  Resource Name Field
Accelerator Editor:  Save As
Accelerator Editor:  Update
Accelerator Functions
Accessing Help
The Actions Menu
Adding a Module File
Adding a New Accelerator Item
Adding a New Menu Item
Adding a New String Item
Adding a Target
Adding a Window
Adding Controls to a Dialog
Adding Resources to a Target
Adding Source Files
Allocate All Memory
Allow Multiple Memory Display Windows
Assigning Colors to Mouse Buttons
Auto Position Memory Info Window
Auto Refresh
Auto-arranging of Graph Views
Automatically Saving Options on Exit

- B -

The Begin Zoom Item
Browser Files
The Browser Menu Bar

- C -

Calculating Memory Size
Changing an Existing Accelerator Item
Changing an Existing Menu Item
Changing an Existing String Item
Changing Colors
Changing the Caption in a Dialog
Changing the Dialog Size
Changing the Font
Changing the Graph Orientation
Changing the Heap Walker Display
Changing the Location of a Dialog
Changing the Monitoring State of the Message
Changing the Name of a Dialog
The Class Inheritance View
Clipboard Messages
Closing a File
Closing a Project
Closing the Image Editor
Collapsing Nodes
Compact and Local Walk
Compacting the Global Heap
Configuring the Browser
Configuring the Editor
Configuring the Heap Walker Session
Configuring the Integrated Development Environment
Configuring Zoom
Configuring Zoom:  Always On Top
Configuring Zoom:  Auto Refresh
Configuring Zoom:  Sticky Magnifier
Controlling Magic Characters
Controls
The Convert Dialog
The Convert Menu
Copying Into an Existing Resource File
Creating a Browser Database File from the Command Line
Creating a Browser Database File within the Browser
Creating a Design Grid
Creating a New Accelerator Table
Creating a New Menu
Creating a New Resource
Creating a New Resource File with the Resource Editor
Creating a New String Table
Creating and Editing Bitmaps
Creating and Editing Cursors
Creating and Editing Icons
Creating New Dialogs

- D -

DDE Messages
DDE Spy
The DDE Spy Event List
The DDE Spy Menu Bar
The DDE Spy Toolbar
DDE Spy:  Action When Log File Exists
DDE Spy:  Automatic Scrolling
DDE Spy:  Clearing the Event List
DDE Spy:  Configuring the Log File
DDE Spy:  Default Log Name
DDE Spy:  Log Name
DDE Spy:  Logging Type
DDE Spy:  Marking the Event List
DDE Spy:  Pause Logging
DDE Spy:  Pausing the Event List Output
DDE Spy:  Saving the Event List to a File
DDE Spy:  Setting the Font
DDE Spy:  Start Logging
DDE Spy:  Stop Logging
DDE Spy:  Working with Log Files
Defining Aliases
Defining Graph View Legends
Deleting a Menu Item
Deleting a Resource
Deleting a String Item
Deleting a Window
Deleting Accelerator Items
Deleting All Accelerator Items
Deleting All Menu Items
Deleting All String Items
Deleting an Accelerator Item
Deleting Menu Items
Deleting String Items
The Detail View
The Dialog Editor Information Bar
The Dialog Editor Menu Bar
The Dialog Editor Toolbar
The Dialog Editor Toolbox
Dialog Editor:  Save
Dialog Editor:  Save As
Dialog Functions
Dialogs
Differences from IBM Resource Compiler
Disabling a Module File
Disabling Aliases
Discarding an Object
Display Heap Information
Display Memory Info Window
Display Resources
Displaying Help for the Message
Displaying Information about the Receiving Window
DOS - 16-bit Targets
DOS - 32-bit Targets

- E -

The Edit Window
Editing an Existing Resource
Editing the Key Value
Editing the Source File
The Editor Toolbar
Enabling a Module File
The Entire Heap
Enumerator Styles
Executing Special Commands
Expanding Nodes

- F -

File Matching Regular Expressions
The File Menu
File Specific Options
File Specific Options :  Language
File Specific Options :  Miscellaneous
File Specific Options :  Source
File Specific Options :  Tabs
File Specific Options :  Tags
The Files the Integrated Development Environment Uses
Find
Find Filters
Find Pattern
Find Selected
Finding a Selector
Free All Memory
Free Items List
The Function Call Tree View

- G -

GDI Local Walk
General Options
General Options :  Features
General Options :  Filenames/Paths
General Options :  Miscellaneous
General Options :  Searching
General Options :  VI Emulation
General Options :  Word Definitions
Getting Help
Getting Started with a Short Tutorial
Global Symbol Queries
Global Views
Goto Definition

- H -

Heap Walker
The Heap Walker Menu Bar
Heap Walker:  Configuring the File Name Paths
Heap Walker:  Configuring Window Behaviour
Heap Walker:  Saving the Current Configuration
Heap Walker:  Setting the Font
The Help Menu
Hiding and Showing the Color Palette
Highlighting the Receiving Window
How the Environment Operates
How the Integrated Development Environment Looks
How to Use the Profiler Effectively

- I -

The IDE Menu Bar
The IDE Status Bar
The IDE Switches
The IDE Toolbar
The Image Editor Color Palette
The Image Editor Menu Bar
The Image Editor Status Line
The Image Editor Toolbar
The Image Editor Toolbox
Including Libraries in a Target
The Information Area
Information Dialog Boxes
Init Messages
Input Messages
Invoking DOS Applications from the IDE under OS/2
Invoking Other Applications from the IDE

- L -

Line Drawing Method for Graph Views
Linux Targets
The List View
Listing All Windows
Loading a Message Configuration
Loading Options
Local Walk
Locating Symbols
LRU Items List

- M -

The Main Screen
Making Source Files
Making Targets
Manipulating the Tree Views
Marking a Source File for Remake
Marking a Target for Remake
MDI Messages
Member Filters for Classes
The Memory Display Window
The Menu Editor Menu Bar
The Menu Editor Toolbar
Menu Editor:  Action Buttons
Menu Editor:  Attributes Area
Menu Editor:  Changing Memory Options
Menu Editor:  Copy To
Menu Editor:  Menu Item List
Menu Editor:  Resource Name Field
Menu Editor:  Save As
Menu Editor:  The Preview Window
Menu Editor:  Update
Menu Functions
Minimizing a Target
Modifying Controls in a Dialog
Monitoring All Windows
Monitoring Data Segment Usage
Mouse Messages

- N -

NC Misc Messages
NC Mouse Messages

- O -

The Open Watcom Accelerator Editor
The Open Watcom Browser
The Open Watcom Dialog Editor
The Open Watcom Editor
The Open Watcom Execution Profiler
Open Watcom Execution Profiler Command Line Format
The Open Watcom Execution Profiler User Interface
The Open Watcom Execution Sampler
The Open Watcom IDE Project Window
The Open Watcom Image Editor
Open Watcom Integrated Development Environment
The Open Watcom Menu Editor
The Open Watcom Resource Compiler
The Open Watcom Resource Editor
The Open Watcom String Editor
Opening a New File
Opening a New Resource File with the Dialog Editor
Opening a Project
Opening an Existing Accelerator Table
Opening an Existing Browser Database File
Opening an Existing File
Opening an Existing Menu
Opening an Existing Resource File with the Dialog Editor
Opening an Existing Resource File with the Resource Editor
Opening an Existing String Table
Opening and Closing Files
Opening Existing Dialogs
Opening the Image Editor
The Options Dialog
Ordering Controls in a Dialog
OS/2 - 16-bit Targets
OS/2 - 32-bit Targets
Other Allocation Functions
Other Messages
Other Run Functions

- P -

Pasting with Zoom
Pause Spying
Performing the Find
The Popup Menu
Predefined Spy Message Classes
Profile Analysis Tools
The Profiler Menu Bar
Profiling a NetWare NLM
Purging Aliases

- Q -

Query Filters
Query Pattern
Quitting DDE Spy
Quitting Heap Walker
Quitting Spy
Quitting the Accelerator Editor
Quitting the Browser
Quitting the Dialog Editor
Quitting the Menu Editor
Quitting the Open Watcom Integrated Development Environment
Quitting the Resource Editor
Quitting the String Editor
Quitting Zoom

- R -

Refresh the Heap
Refreshing the Global Heap
Regular Expression BNF
Regular Expressions
Regular Expressions for Find and Query
Removing a Module File
Removing a Source File
Removing a Target
Removing Discardable Objects
Renaming a Menu
Renaming a Resource
Renaming a Source File
Renaming a Target
Renaming an Accelerator Table
Replacement Strings
Replacing Text
Repositioning an Object
Resetting the Usage Count
Resizing the Zoom Window
Resource Compiler Options
Resource Definition Files
The Resource Editor Menu Bar
The Resource Editor Toolbar
Resource Editor:  Changing Memory Options
Resource Editor:  Save
Resource Editor:  Save As
Review of What Happened
Running a Target

- S -

Sample .RC file
Sampler Command Line Options
Sampler Operating System Considerations
Sampler Options Summary
Samples
Save Main Window Size/Position
Save Memory Window Size/Position
Saving a Message Configuration
Saving a Project
Saving a Resource
Saving a Resource File with the Dialog Editor
Saving a Resource File with the Resource Editor
Saving Accelerator Items
Saving and Loading Message Configurations
Saving Dialogs
Saving Files
Saving Heap Walker Information to a File
Saving Menu Items
Saving Options
Saving String Items
Saving the Configuration
Saving the Log
Saving the Project Under a New Name
Saving to a New Resource File
Saving to an Existing Resource File
Screen/Window Options
Screen/Window Options :  Editing
Screen/Window Options :  Miscellaneous
Searching Text
Selecting a Source Revision Control System
Selecting a Text Editor
Selecting Individual Messages
Selecting Information to Monitor
Selecting Message Classes
Selecting Messages to Monitor
Selecting Root Nodes
Selecting Screen and Inverse Colors
Selecting Your Own Text Editor
The Selector List
Setting Application Parameters
Setting Search and Replace Options
Setting Search Options
Setting Source File Switches
Setting Source Search Paths
Setting Target and Source File Switches
Setting Target Switches
Setting the Callback Filter
Setting the Message Filter
Setting the Offset in the Memory Display Window
Show Status Bar
Show Toolbar
A Simple Executable
Sorting the Lists
Sorting the Local Heap
Source References
Spy
The Spy Menu Bar
The Spy Toolbar
The Spy Window
Spy:  Action When Log File Exists
Spy:  Always On Top
Spy:  Automatic Scrolling
Spy:  Clearing the Message List
Spy:  Configuring the Log File
Spy:  Default Log Name
Spy:  Log Name
Spy:  Logging Type
Spy:  Marking the Message List
Spy:  Pause Logging
Spy:  Saving the Contents of the Message List
Spy:  Setting the Fonts
Spy:  Start Logging
Spy:  Stop Logging
Spy:  Working with Log Files
Spying
Spying on More Windows
Start Spying
Starting and Quitting the Editor
Starting DDE Spy
Starting Heap Walker
Starting Spy
Starting the Accelerator Editor
Starting the Browser
Starting the Dialog Editor
Starting the Menu Editor
Starting the Open Watcom Integrated Development Environment
Starting the Resource Editor
Starting the String Editor
Starting Zoom
Startup Options
Status Bar Contents
Status Bar Contents :  Alignment
Status Bar Contents :  Commands
Status Bar Contents :  Items
The Status Line
Stop Spying
Stopping the Make Function
The String Editor Menu Bar
The String Editor Toolbar
String Editor:  Action Buttons
String Editor:  Changing Memory Options
String Editor:  Copy To
String Editor:  Save As
String Editor:  Update
String Functions
String ID Field
String Text Field
Strings List
Symbol References
System Messages

- T -

Targets and Image Types Supported by the IDE
Testing with Heap Walker
The Title Area
Tracking Conversations
Tracking Links
Tracking Servers
Tracking Strings
Tracking with DDE Spy

- U -

Unknown Messages
Updating the Project
USER Local Walk
User Messages
Using DDE Spy
Using Drag and Drop Palettes
Using Fgrep Capabilities
Using Heap Walker
Using Menus
Using Release and Development Switches
Using Shortcuts to Create a Resource
Using Shortcuts to Create Accelerator Tables
Using Shortcuts to Create menus
Using Shortcuts to Create String Tables
Using Spy
Using the Accelerator Editor
Using the Accelerator Editor Window
Using the Auto Save Feature
Using the Autodepend Switch
Using the Browser
Using the Dialog Editor
Using the Dialog Editor Window
Using the IDE Log Window
Using the Information of the IDE from outside
Using the Menu Editor
Using the Menu Editor Window
Using the Open Watcom Integrated Development Environment
Using the Open Watcom Resource Compiler
Using the Open Watcom Resource Editor
Using the Right Mouse Button
Using the Sampler with DOS
Using the Sampler with DOS/4GW or DOS/4G
Using the Sampler with NetWare 386
Using the Sampler with OS/2
Using the Sampler with the Phar Lap 386|DOS-Extender
Using the Sampler with Win32
Using the Sampler with Windows 3.x
Using the String Editor
Using the String Editor Window
Using Zoom

- V -

Viewing an Object's Memory
Viewing Detail Information
Viewing Included Files
Viewing Information
Viewing Information About a Window
Viewing Memory Management Information
Viewing Message Information
Viewing the Contents of Memory
Viewing the Global Heap Summary
Viewing the Make Command for a Source File
Viewing the Make Command for a Target
Viewing Window Information

- W -

Walking the Global Heap
Walking the Local Heap
Warning and Error Messages
When Less Than One Line is Selected
When More Than One Line is Selected
Win16 Targets
Win16:  Customize the Log File
Win16:  Debugging a Task
Win16:  Dr.  Watcom for Windows 3.1
Win16:  Dr.  Watcom:  Applying Registers
Win16:  Dr.  Watcom:  Changing the Registers
Win16:  Dr.  Watcom:  Clearing the Event List
Win16:  Dr.  Watcom:  Exception Handling
Win16:  Dr.  Watcom:  Marking the Event List
Win16:  Dr.  Watcom:  Naming the Log File
Win16:  Dr.  Watcom:  Other Options
Win16:  Dr.  Watcom:  Saving Event List Information to a File
Win16:  Dr.  Watcom:  Segment Mapping
Win16:  Dr.  Watcom:  Setting the Fonts
Win16:  Dr.  Watcom:  Specifying the Log File Data
Win16:  Dr.  Watcom:  Working with Log Files
Win16:  Erase the Log File
Win16:  Examining the Task Status
Win16:  Log the Current State
Win16:  Performing a Stack Trace
Win16:  Performing Task Control
Win16:  Quitting Dr.  Watcom
Win16:  Resetting the Fault Handled Flag
Win16:  Setting the Alert Feature
Win16:  Showing the DIP status
Win16:  Starting Dr.  Watcom
Win16:  Terminating a Task
Win16:  The Dr.  Watcom Menu Bar
Win16:  Using Dr.  Watcom
Win16:  Using the Clear Alert Function
Win16:  Using the Dr.  Watcom Window
Win32 Targets
Win32:  Add New Process
Win32:  Attaching Processes to Dr.  Watcom
Win32:  Auto Add Processes
Win32:  Command Line
Win32:  Creating A Log File Entry
Win32:  Customizing the Log File
Win32:  Debugging Information Processors
Win32:  Dr.  Watcom for Win32
Win32:  Dr.  Watcom:  Applying Registers
Win32:  Dr.  Watcom:  Changing the Registers
Win32:  Dr.  Watcom:  Choosing the Log Viewer
Win32:  Dr.  Watcom:  Clearing the Event List
Win32:  Dr.  Watcom:  Exception Handling
Win32:  Dr.  Watcom:  Marking the Event List
Win32:  Dr.  Watcom:  Naming the Log File
Win32:  Dr.  Watcom:  Other Options
Win32:  Dr.  Watcom:  Saving Event List Information to a File
Win32:  Dr.  Watcom:  Setting the Fonts
Win32:  Dr.  Watcom:  Specifying the Log File Data
Win32:  Dr.  Watcom:  Viewing Memory
Win32:  Dr.  Watcom:  Working with Log Files
Win32:  Erasing the Log File
Win32:  Examining the Process Status
Win32:  Performing Process Control
Win32:  Process Control
Win32:  Quitting Dr.  Watcom
Win32:  Resuming a Thread
Win32:  Setting the Process Priority
Win32:  Starting Dr.  Watcom
Win32:  Summarizing Process Memory Usage
Win32:  Suspending a Thread
Win32:  Terminating a Process
Win32:  Terminating a Thread
Win32:  The Dr.  Watcom Menu Bar
Win32:  Using Dr.  Watcom
Win32:  Using External Exception Handlers
Win32:  Using the Annotate Log Dialog
Win32:  Using the Debugging Information Processor Status dialog
Win32:  Using the Dr.  Watcom Window
Win32:  Using the Memory Dump Dialog
Win32:  Viewing the Current Log File
Win32:  Viewing the Memory for a Process
Win32:  Viewing the Threads for a Process
Win386 (Watcom Extender) Targets
Window Messages
The Windows Menu
Working with Aliases
Working with Browser Module Files
Working with Individual Objects
Working with Resource Files
Working with Resources
Working with Source Files
Working with Targets
Working with the Global Heap
The Workspace

- Z -

Zoom
The Zoom Menu Bar
Zoom Operations
The Zoom Window
Zoom-In and Backout
Zooming

Open Watcom Integrated Development Environment

How the Environment Operates

How the Integrated Development Environment Looks

The Files the Integrated Development Environment Uses

Using the Open Watcom Integrated Development Environment

• Starting the Open Watcom Integrated Development Environment
• Quitting the Open Watcom Integrated Development Environment
• The IDE Menu Bar
• The IDE Status Bar
• The IDE Toolbar

Starting the Open Watcom Integrated Development Environment

Quitting the Open Watcom Integrated Development Environment

The IDE Menu Bar

File

Open new or existing projects, close and save projects, exit the IDE, and show or hide the toolbar and status bar

Actions

Make all targets, run applications, and invoke other GUI Tools

Targets

Work with targets, including setting switches and creating, removing, and renaming targets

Sources

Work with sources, including setting switches and creating, removing, and renaming sources

Options

Set switches for creating targets and sources

Log

Perform functions relating to the IDE Log window

Window

Refresh the contents of the IDE windows and view the targets currently available on the IDE window

Help

Access on-line help information

The IDE Status Bar

The IDE Toolbar

Create

Create a new project.  This is equivalent to the option New Project in the File menu.

Open

Open an existing project.  This is equivalent to the option Open Project in the File menu.

Save

Save the current project.  This is equivalent to the option Save Project in the File menu.

Edit

Edit the selected source file.  This is equivalent to the option Edit Text in the Sources menu.

Make Source

Make the selected source file.  This is equivalent to the option Make in the Sources menu.

Make Target

Make the current target.  This is equivalent to the option Make in the Targets menu.

Run

Run the current target.  This is equivalent to the option Run in the Targets menu.

Debug

Debug the current target.  This is equivalent to the option Debug in the Targets menu.

Remote Debug

Debug the current target on a remote machine.  This is equivalent to the option Remote Debug in the Targets menu.

Browse

Browse the current target.  This is equivalent to the option Browse in the Targets menu.  Currently, browsing is supported by the Open Watcom C/C++ compilers only (Open Watcom FORTRAN 77 does not support browsing).

Sample

Run and sample the current target.  This is equivalent to the option Sample in the Targets menu.

Profile

Profile the current target.  This is equivalent to the option Profile in the Targets menu.

Make All

Make all targets in the project.  This is equivalent to the option Make All in the Actions menu.

Getting Started with a Short Tutorial

A Simple Executable

(1)

Double-click on the IDE icon in the Open Watcom Tools window.
The Open Watcom IDE Project window appears. 

(2)

Choose New Project from the File menu.
The Enter Project Filename dialog appears.  The default project name is noname.wpj.

(3)

Enter the filename \project\first in the File Name field and click on OK.

Figure 4. Enter the filename in the Enter Project Filename dialog.

This is the name of the project you are creating.  If you enter a directory that doesn't exist (in this case, \project), the IDE reveals a message box asking if you want to create the specified directory.  Click on OK to create the specified directory and project file.

Note:

The IDE looks for existing projects with the new name.  If a project with the specified name already exists, the IDE will prompt you rather than simply overwriting the existing project.

The project name appears in the title bar of the Open Watcom IDE Project window.  Note that the IDE added the extension ".wpj" to the project name.  The New Target dialog appears on the screen where you define a target for the new project.

(4)

Enter the desired target name in the Target Name field (we suggest target1).  Next, select the appropriate Target Environment (we suggest "Win32") and Image Type (we suggest "Character-mode Executable").  Click on OK when completed.

Figure 5. Select target name, target environment and image type

The New Target dialog closes and the IDE creates a target window entitled target1.exe for the new target.   Note that the IDE appends the appropriate extension to the target name for you once you click on OK.  You can now add sources to the target.

(5)

Choose New Source from the Sources menu.
The Add File(s) dialog appears where you specify the sources you want to add to the target.  Source names must be filenames with extensions; pathnames are not required.

For the OS/2 IDE, you can add multiple source files to the target at one time by inserting a space between each filename you enter.  You can also use the file browser to add files by clicking on the Browse...  button.

For all other systems, you can enter the names of the source files (with extensions) in the File Name field or you can use the file browser to select files.  The type of files displayed in file list window can be controlled by modifying the List Files of Type field.  Once you have typed a name in the File Name field or selected a name from the file list, you can add it to the list of source files to be included by clicking the Add button.  All files in the file list can be added by clicking the Add All button.  Individual names can be removed from the "add" list by selecting them and clicking the Remove button.


Figure 6. Select source file names in the Add File(s) dialog

(6)

Enter the following source file names.
     
     source1.c   (or source1.for)
     source2.c   (or source2.for)
     source3.rc

For the OS/2 IDE, enter all the names into the field separating each name by a space.  Click on OK when done.

For all other systems, enter one name at a time into the File Name field, pressing Enter or clicking on Add after each one has been entered.  Click on Close when done.


Figure 7. Enter one or several source files in the Add File(s) dialog.

The IDE adds the new source files to the target window, followed by the characters [n/a].  This indicates that the source files are not available, meaning that the files do not yet exist.  The indicators are:

[n/a]

This code appears if the file does not exist.

[r/o]

This code appears if the file is Read Only.

[sw]

This code appears if the user has set switches for the specified source file.

The Integrated Development Environment organizes the source files in the target window under headers according to the filename extension.  You can expand and collapse the file groups by clicking on the folder icon.

For this tutorial, we only need one source file, so now we will delete the extra files from the target.

(7)

Click on the file source2.c (or source2.for) to select it then choose Remove Source from the Sources menu.
A message box appears asking if you want to remove the selected source.  Click on the Yes button to continue.  The IDE removes the selected source file from the target window.  Now we can remove source3.rc.  To do this we will perform the function of removing all source files with a common extension.

(8)

Click on the (.rc) header on the target window then choose Remove Source from the Sources menu.
A message box appears on the screen asking if you want to remove all of the ".rc" files.  Click on the Yes button to continue.  The message box closes and the IDE removes the source3.rc file from the target window.   Now you can edit the remaining source file.

(9)

Highlight the line source1.c (or source1.for) and choose Edit Text from the Sources menu to edit the selected source file.
The Open Watcom Editor appears.  The name of the selected source file, source1.c (or source1.for), appears in the window.  Here you can enter the source code.

Hint:  You can also invoke the Open Watcom Editor by double-clicking on the source file that you want to edit.

In this case, the Open Watcom Editor appears because the selected source file has a ".c" or ".for" extension.  Performing an edit can open different editors, depending on the extension of the selected source file.

(10)

Enter the following lines of source code.

Important:

For the purpose of this session, we ask you to enter ii instead of i in the "print" line.  This will allow you to see how the Integrated Development Environment reacts to errors.  You will then be able to correct the error.

     
     #include <stdio.h>

     void main()
     {
         int i;
         for (i=0; i<10; i++)
         {
             printf( "Value is %d\n", ii );
         }
         printf("Press Enter...\n");
         getchar();
     }

FORTRAN programmers can enter the following lines of code.

     
           program main
           implicit none
           integer i

           do i = 0, 9
             print *, 'Value is ', ii
           enddo

           print *, 'Press Enter...'
           read *

           end

You can now save your work and close the Editor in one of the following two ways:  close down the entire editor or close down only the source file window.  For this exercise, close only the source file window as follows.

(11)

Choose Close from the File menu to close down the current source file window.
In both cases, if changes have been made to the file and not saved, a message prompts you to save the changes before exiting.   The advantage of closing only the Editor window is that the Editor continues to run.  If you need to access it again, you will not need to wait for it to go through the start-up procedures again.

Important:

You must save the file.  The Open Watcom compilers do not access the source lines in the Editor's buffers.

(12)

Minimize the Editor window.
or

Click on the Open Watcom IDE Project window to bring it to the foreground.

(13)

Choose Refresh from the Window menu.
This action forces the IDE to update the display with the state of all files.  It is not necessary to use this function if you have selected Auto Refresh in the File menu.  If Auto Refresh is disabled then it may be necessary to alert the IDE of the presence of the file on disk. 

(14)

Choose Save Project from the File menu to save your project up to this point.
You are now ready to make and run the target.  Making a target is the act of constructing a target file.  In this case, it involves compiling the source file source1.c (or source1.for) using the appropriate Open Watcom compiler and linking the target executable using the Open Watcom Linker.

(15)

Highlight the line source1.c and choose C Compiler Switches...  from the Source Options item located under the Sources menu to set compile options.
FORTRAN programmers:  Highlight the line source1.for and choose Fortran Compiler Switches...  from the Source Options item located under the Sources menu to set compile options.

The C Compiler Switches dialog appears.  If you are using FORTRAN, the Fortran Compiler Switches dialog appears.

(16)

Click on the ">>" button until the 7.  CodeGen Strategy Switches dialog appears.  Click on the "Multithreaded application [-bm]" checkbox button to select this option.
FORTRAN programmers:  Click on the ">>" button until the 9.  Application Type Switches dialog appears.  Click on the "Multithreaded application [-bm]" checkbox to select this option.

A check-mark appears in the checkbox.

Note:  Selecting this option is for demonstration purposes only, it is not required for this simple application.

Click OK to close the dialog.

(17)

Choose Make from the Targets menu.
The IDE constructs a makefile based on its knowledge of the target and construction rules and then invokes the Open Watcom Make utility to create target1.exe.  The IDE Log window appears at the bottom of the Open Watcom IDE Project window.  Use this window to monitor the procedure.  Since you entered ii instead of i, the MAKE fails.


Figure 8. Use the IDE Log window to monitor the make procedure.

(18)

Highlight the error message in the IDE Log window and choose Help on Message from the Log menu.
Help information regarding the error message appears on the screen.


Figure 9. Help for error messages is available

Close the Help window and edit the source file as follows.

(19)

Highlight the error message in the IDE Log window and choose Edit File from the Log menu.
or

Double-click on the error message in the IDE Log window.
The Open Watcom Editor opens and the cursor appears at the position of the error.  Edit and correct the error and then save the file again.  Minimize the Editor window and bring the IDE window to the foreground.

(20)

Choose Make from the Targets menu again.
This time, the procedure creates the executable file target1.exe.

(21)

Choose Run from the Targets menu.
The IDE executes the program target1.exe.


Figure 10. Run from the Targets menu runs the target.

The program you wrote is a character mode application and its output appears in a separate console window.  You are now ready to debug your target program.  You probably do not need to debug this simple program with the Open Watcom Debugger but go through the steps so that you know what to do for more complex programs.

The IDE has several debugging information options which it uses as defaults when it is started.  The first thing to do is check to make sure that your application compiled with the default debugging information activated.

(22)

Choose Target Options from the Targets menu to activate the Target Options menu.
The option Use Development Switches should appear in grey text with a check mark next to it.  Development Switches automatically include debugging information in the target.  If you were to select Use Release Switches, the IDE would select options useful for a production version of your program.  Selecting this option turns the text grey and places a check mark beside it.  The IDE uses the development switches by default.

Note:

For the purpose of this session, you should make the target with the development switches on.  If this is not the option selected, select it and remake the target before debugging.

(23)

Choose Debug from the Targets menu.
The IDE starts the Open Watcom Debugger.

(24)

Choose Step Over from the Run menu of the Open Watcom Debugger to step through the code.  Choose Go from the Run menu of the Open Watcom Debugger to continue execution to the end of the code.  For more information on using the Open Watcom Debugger, refer to the Open Watcom Debugger User's Guide.  The task has completed running appears when the program has completed execution.

(25)

Choose Exit from the File menu to terminate the debugging session.
The Open Watcom Debugger closes and you return to the Open Watcom IDE Project window.  You can now exit the IDE.

(26)

Choose Exit from the File menu to exit the IDE.
The IDE prompts you to save the current project if you have not saved it since the last change.

Review of What Happened

first.wpj

Describes the screen layout and refers to a file called target1.tgt

target1.tgt

Describes the target executable target1.exe and all switches required to link it.  It also describes source1.c (or source1.for) and the switches required to compile it.

The Open Watcom IDE Project Window

Important:

You can have only one project open at a time in the IDE.  If you attempt to open or create a project while one already exists in the IDE window, a message box appears informing you that the IDE is closing the current project and asks if you want to save any changes made to that project.  Choose Yes, No, or Cancel in this box to continue.

Opening a Project

To create a new project:

(1)

Choose New Project from the File menu.
The Enter Project Filename dialog appears on the screen where you enter the name of the project you are creating.

(2)

Enter the desired name in the File Name field and choose the desired directory.
All projects must have the extension ".wpj".


Figure 11. Use the Enter Project Filename dialog to create a new project.

(3)

Click on OK when completed.
The Enter Project Filename dialog closes and the new project name appears in the title bar of the Open Watcom IDE Project window.  A New Target dialog opens on the screen where you add a target to the new project.  Refer to the section Adding a Target for more information.

To open an existing project:

(1)

Choose Open Project from the File menu.
The Open dialog appears on the screen where you select the project you want to open.


Figure 12. Use the Open dialog to open an existing project.

(2)

Choose the desired project.
All projects have the extension ".wpj".

(3)

Click on OK when the desired project appears in the File Name field.
The Open dialog closes and the name of the selected project appears in the title bar of the Open Watcom IDE Project window.   If targets exist for the selected project, windows representing the targets appear in the main window.

Closing a Project

To close the current project:

(1)

Choose Close Project from the File menu.
The IDE removes all target windows for the current project from the Open Watcom IDE Project window.  The project name disappears from the title bar and the window is empty.

Saving a Project

Updating the Project

To perform a simple save on your project:

(1)

Choose Save Project from the File menu.
The IDE updates the project specified in the title bar.  The status bar along the bottom of the window indicates that the save function is being executed.

Saving the Project Under a New Name

To save the current project using a different name:

(1)

Choose Save Project As from the File menu.
The Save As dialog appears on the screen where you specify the file name by which you want to save the current project.

(2)

Enter the desired project name in the File Name field.
This is the new name by which you want to save the current project.  This can be the name of a new project or an existing project.

Important:

Entering the name of an existing project overwrites the contents of that project with the contents of the current project.

(3)

Choose the desired directory for the project using the Directories list on the Save As dialog.

(4)

Click on OK when completed.
The Save As dialog closes and the new project name appears in the title bar of the Open Watcom IDE Project window.

Working with Targets

• Adding a Target
• Minimizing a Target
• Removing a Target
• Renaming a Target
• Marking a Target for Remake
• Making Targets
• Running a Target

Adding a Target

To add a new target to the current project:

(1)

Choose New Target from the Targets menu.
The New Target dialog appears on the screen where you enter the details of the target you are adding.


Figure 13. Enter the new target details in the New Target dialog.

(2)

Enter the target name in the Target Name field.
Enter the entire pathname to ensure the directory is created where you want.  Depending on the nature of the target, it may or may not be able to share the same directory as other pre-existing targets.  Generally, if the target shares one or more of the same source files as other targets in the project, then it must be placed in its own subdirectory.  The object files that are produced for the target may have different attributes than a pre-existing target's object files (e.g., 16-bit vs 32-bit).  This is why the target should be placed in a separate subdirectory.

(3)

Select the desired Target Environment and Image Type as desired.

(4)

Click on OK when the Target Name, Target Environment and Image Type fields are correct.
If you specify a new directory in the target pathname, a message box appears asking if you want to create the specified directory.  Choose Yes or No to continue.  A window representing the new target appears on the Open Watcom IDE Project window.  The target name appears in the title bar.

The first line in this window describes the target.  It specifies the current mode, the target type.  The current mode is represented by either the letter D or R which appears in parentheses in front of the target type.  The letter D indicates that the target is placed in Development mode.  The letter R indicates that the target is placed in Release mode.  The rest of the window displays the source files for the target.

To add an existing target to a current project:

(1)

Choose New Target from the Targets menu.
The New Target dialog appears on the screen.

(2)

Click on the Browse button.
The Enter Target Filename dialog appears on the screen.  This dialog allows you to browse the directories and files and select the ".tgt" file for the target you want to add.


Figure 15. Choose an existing target from the Pick Target Filename dialog for the current project.

(3)

Click on the desired target to select it.
The selected target appears in the File Name field.

(4)

Click on OK to process the target selection.
The Enter Target Filename dialog closes.

(5)

Click on OK to close the New Target dialog.
A window representing the new target appears on the Open Watcom IDE Project window.  The target name appears in the title bar.

The first line in this window describes the target.  It specifies the current mode and the target type.  The current mode is represented by either the letter D or R which appears in parentheses in front of the target type.  The letter D indicates that the target is placed in development mode.  The letter R indicates that the target is placed in Release mode.  The rest of the window displays the source files for the target.

Minimizing a Target

To minimize a target window:

(1)

Click on the system box in the upper left-hand corner of the target window you want to close.
A menu appears listing the functions you can perform on the selected window.

(2)

Choose Minimize from the menu.
The selected target window closes and an icon appears along the bottom of the screen representing that window.  The name of the target appears on or under the icon.

(3)

Double-click on the icon to open the target window again.

Removing a Target

To remove a target from the current project:

(1)

Click once on the target window you want to remove from the project.
The title bar of the selected target window is highlighted.

(2)

Choose Remove Target from the Targets menu.
A message box appears on the screen asking if you really want to remove the selected target.

(3)

Choose OK to continue.
The message box closes and the selected target window disappears from the Open Watcom IDE Project window.

Renaming a Target

To rename a target:

(1)

Click once on the target window you want to rename.
The title bar of the selected target window is highlighted.

(2)

Choose Rename Target from the Targets menu.
The Rename Target dialog appears.  The Target Name, Target Environment, and Image Type of the selected target appear in the appropriate fields.


Figure 17. Change a target's name using the Rename Target dialog.

(3)

Enter the new target name in the Target Name field.
or

Click on the Browse button and select an existing target name; click on OK when completed.
The selected or entered target name appears in the Target Name field.

(4)

Verify that the Target Environment and Image Type are correct.

(5)

Click on OK on the Rename Target window.
The Rename Target dialog closes.  The title bar of the selected target window now displays the new target name.

Marking a Target for Remake

To mark a target for remake:

(1)

Click once on the target window you want to mark.
The title bar of the selected target window is highlighted.

(2)

Choose Mark Target for Remake from the Targets menu.
A message box appears asking if you want to also mark all of the source files of the selected target.

(3)

Choose Yes or No to continue.
Choosing Yes marks all of the source files for the selected target as well as the target itself.  This means that the next time you do a make, the source files for the selected target will be compiled.  Choosing No marks only the selected target for remake.  In both cases, the message box closes and you return to the Open Watcom IDE Project window.

Making Targets

To make a single target:

(1)

Click once on the target window you want to make to select it.
The title bar of the selected target window is highlighted.

(2)

Choose Make from the Targets menu.
The IDE Log window opens along the bottom of the Open Watcom IDE Project window.  In the log window you can monitor the make procedure.  Execution Complete appears in the IDE Log window when the make is completed on the selected target.  If the make is successful an executable file for the selected target can be found in the directory associated with the target window.


Figure 18. Use the IDE Log window to monitor the make procedure.

To make all targets for the current project:

(1)

Choose Make All from the Actions Menu.
The IDE Log window opens along the bottom of the Open Watcom IDE Project window.  In the log window you can monitor the make procedure.  Execution Complete appears in the IDE Log window when the make is completed on the targets.   If the make is successful an executable file for each target in the project can be found in the directory associated with the target window.

Viewing the Make Command for a Target

To view the make commands for targets:

(1)

Click once on the target window whose makefile commands you want to view.
The title bar of the selected target window is highlighted.

(2)

Choose Target Options from the Targets menu.
A submenu appears on the screen from the Target Options menu.

(3)

Choose Show Make Command from the Target Options submenu.
The Target Command dialog appears on the screen.  This dialog displays the makefile commands for the selected target.


Figure 19. The Target Command dialog displays the makefile commands for the selected target.

(4)

Click on OK to close the dialog.

Running a Target

To run a target:

(1)

Click once on the target window you want to run.
The title bar of the selected target window is highlighted.

(2)

Choose Run from the Targets menu.
The IDE executes the target program.


Figure 20. Run from the Targets menu runs the target.

Other Run Functions

To run other programs in the IDE:

(1)

Choose Run from the Actions menu.
or

Choose Run Batch from the Actions menu.
A Run or Run Batch dialog appears on the screen.  These dialogs are identical.


Figure 21. Use the Run (or Run Batch) dialog to run other programs in the IDE.

(2)

Enter the name of the program you want to run in the Command field.

(3)

Click on OK to run the specified program.
The dialog closes and the specified program runs, either under the host environment or in the IDE Log window.

Setting Application Parameters

Working with Source Files

• Adding Source Files
• Removing Source Files
• Renaming a Source File
• Marking a Source File for Remake
• Making Source Files
• Viewing Included Files

Adding Source Files

xxx.asm

The ".asm" extension invokes the Open Watcom Assembler.

xxx.c

The ".c" extension invokes the Open Watcom C compiler.

xxx.cpp

The ".cpp" extension invokes the Open Watcom C++ compiler.

xxx.for

The ".for" extension invokes the Open Watcom FORTRAN 77 compiler.

xxx.hlp

The ".hlp" extension invokes either the Win16, OS/2, or Win32 compiler.

xxx.rc

The ".rc" extension invokes the Open Watcom resource compiler.

xxx.res

The ".res" extension invokes the Open Watcom Resource Editor.

xxx.sqc

The ".sqc" extension invokes the embedded SQL preprocessor and the Open Watcom C compiler.

xxx.sqp

The ".sqp" extension invokes the embedded SQL preprocessor and the Open Watcom C++ compiler.

To add new source files to the selected target:

(1)

Choose New Source from the Sources menu.
The Add File(s) dialog appears where you specify the name(s) of the source file(s) you are adding.  Source names must be filenames with extensions; pathnames are not required.

For the OS/2 IDE, you can add multiple source files to the target at one time by inserting a space between each filename you enter into the filenames field.

For all other systems, you can enter the names of the source files (with extensions) in the File Name field, one at a time.  Once you have typed a name in the File Name field, you can add it to the list of source files to be included by clicking the Add button.  Individual names can be removed from the "add" list by selecting them and clicking the Remove button.


Figure 22. Add one or several source files to a target using the Add File(s) dialog.

(2)

Enter the source file name(s).
For the OS/2 IDE, enter all the names into the field separating each name by a space.  Click on OK when done.

For all other systems, enter one name at a time into the File Name field, pressing Enter or clicking on Add after each one has been entered.  Click on Close when done.

The Add File(s) dialog closes and the selected source file(s) appear in the selected target window on the Open Watcom IDE Project window.

The source files are grouped by their file extensions and appear in alphabetical order.  You can expand and collapse the list of source files by clicking on the folder icon to the left of the header.

To add existing source files to the selected target using the file browser:

(1)

Choose New Source from the Sources menu.
The Add File(s) dialog appears on the screen.

For the OS/2 IDE, click on the Browse button and the Pick Filename dialog appears on the screen.  This dialog allows you to browse the directories and files and select the source file(s) you want to add to the current target.  Click on the desired source file to select it.  The selected source file(s) appear highlighted in the Pick Filename dialog.  When done browsing files, click on OPEN to add the selected files.  The Pick Filename dialog closes.  When done selecting files, click on OK.

For all other systems, you can use the file browser to select files.  The type of files displayed in file list window can be controlled by modifying the List Files of Type field.  Once you have selected a name from the file list, you can add it to the list of source files to be included by clicking the Add button.  All files in the file list can be added by clicking the Add All button.  Individual names can be removed from the "add" list by selecting them and clicking the Remove button.  When done, click on Close to add the selected files.

The Add File(s) dialog closes and the selected source file(s) appear in the selected target window on the Open Watcom IDE Project window.

The source files are grouped by their file extensions and appear in alphabetical order.  You can expand and collapse the list of source files by clicking on the folder icon to the left of the header.

To add existing source files to the selected target using wild cards:

(1)

Choose New Source from the Sources menu.
The Add File(s) dialog appears on the screen.

For the OS/2 IDE, enter the source file name pattern in the filename(s) field using wild cards.  For example, enter sou*.c to add all source files whose name begins "sou" and have a ".c" extension to the current target.  When done, click on OK to add the selected files.

Hint:  Even when entering wild cards, you can add multiple source file groups by separating each entry with one space (e.g., sou*.c sou*.cpp).

For all other systems, enter the source file name pattern in the File Name field using wild cards.  For example, enter sou*.c to select all source files whose name begins "sou" and have a ".c" extension.  Click on the Add All button to add all the names that match the wild card pattern.  Individual names can be removed from the "add" list by selecting them and clicking the Remove button.  When done, click on Close to add the selected files.

The Add File(s) dialog closes and the selected source file(s) appear in the selected target window on the Open Watcom IDE Project window.

The source files are grouped by their file extensions and appear in alphabetical order.  You can expand and collapse the list of source files by clicking on the folder icon to the left of the header.

Removing a Source File

To remove one source file from a target:

(1)

Click once on the source file you want to remove from the target.
The selected source file appears highlighted in the target window.

(2)

Choose Remove Source from the Sources menu.
A message box appears asking if you are sure you want to remove the selected source file.

(3)

Click on the Yes button.
The message box closes and the IDE removes the selected source file from the target window.

To remove a group of source files from a target:

(1)

Click once on the header to the right of the folder icon of the source files group you want to remove from the target.
The selected header appears highlighted in the target window.


Figure 23. Click on the header to remove all source files with a common file extension.

(2)

Choose Remove Source from the Sources menu.
A message window appears asking if you want to remove all source files with the selected file extension.

(3)

Choose OK to continue.
The message box closes and the IDE removes the selected group of source files from the target.

Renaming a Source File

To rename a source file:

(1)

Click once on the source file you want to rename.
The selected source file appears highlighted in the target window.

(2)

Choose Rename Source from the Sources menu.
The Rename File dialog appears where you enter the new name of the selected source file.


Figure 24. Use the Rename File dialog to rename the selected source file.

(3)

Enter the new source file name in the field.
or

Click on the Browse button and select an existing source file name; click on OK when completed.
The selected or entered source file name appears in the Rename File dialog.

(4)

Click on OK on the Rename File dialog.
The Rename File dialog closes.  The target window displays the updated source file.

Marking a Source File for Remake

To mark a source file or a group of source files for remake:

(1)

Click once on the source file you want to mark.
or

Click once on the header of the group of source files you want to mark.
The selection is highlighted in the target window.

(2)

Choose Mark Source for Remake from the Sources menu.
If you selected a group of source files to mark, a message box appears asking if you want to also mark all of the source files of the specified extension.

(3)

Choose Yes to continue.
The message box disappears and the IDE marks all of the source files in the selected group to be recompiled.

Making Source Files

To make source files:

(1)

Click once on the source file you want to make.
or

Click once on the header of the group of source files you want to make.
The selected source files are highlighted in the target window.

(2)

Choose Make from the Sources menu.
The IDE Log window opens along the bottom of the Open Watcom IDE Project window.  In the log window you can monitor the make procedure.  Execution Complete appears in the IDE Log window when the make is completed on the selected source files.

To make all targets for the current project:

(1)

Choose Make All from the Actions Menu.
The IDE Log window opens along the bottom of the Open Watcom IDE Project window.  In the log window you can monitor the make procedure.  Execution Complete appears in the IDE Log window when the make is completed on the targets.   If the make is successful an executable file for each target in the project can be found in the directory associated with the target window.

Viewing the Make Command for a Source File

To view the make commands for source files:

(1)

Click once on the source file whose makefile commands you want to view.
or

Click once on the header of the group of source files whose makefile commands you want to view.
The selected source file or group header is highlighted.

(2)

Choose Source Options from the Sources menu.
A submenu appears on the screen from the Source Options menu.

(3)

Choose Show Make Command from the Source Options submenu.
The Source Command dialog appears on the screen.  This dialog displays the makefile commands for the selected source file or source file header.


Figure 25. The IDE Source Command dialog displays the makefile commands for the selected source file(s).

(4)

Click on OK to close the dialog.

Viewing Included Files

To view the list of included files:

(1)

Click on the source file whose list of included files you want to view.
The selected source file is highlighted in the target window.

(2)

Choose Included Files from the Sources menu.
The Files Included dialog appears on the screen.  This dialog lists all source files on which the selected source files depends.

To edit a source file from the File Included dialog:

(1)

Click once on the source file in the included files list that you want to edit.
The selected source file is highlighted in the File Included dialog.

(2)

Click on OK.
or

Double-click on the selected source file.
The Files Included dialog closes and the IDE invokes the appropriate editor for the selected included file.  The editor appears and you can edit the file.  Close the editor when you are finished making the desired changes to return to the Open Watcom IDE Project window.

Using the IDE Log Window

• Stopping the Make Function
• Getting Help
• Editing the Source File
• Saving the Log

Stopping the Make Function

To stop the make function:

(1)

Choose Stop from the Log menu.
A message box appears asking if it is okay to interrupt the executing process.

(2)

Click on OK to continue.
The message box closes and the IDE stops the make function.  The IDE Log window displays the message Stop Invoked followed by the message Execution Complete.

Getting Help

To reveal help for an error message:

(1)

Click once on the error message in the IDE Log window on which you want information.
The selected error message is highlighted in the IDE Log window.

(2)

Choose Help on Message from the Log menu.
This opens the Help window.  Information on the selected error message appears in this window.

(3)

Choose Close from the system menu on the Help window to cancel the Help facility.
The Help window closes and you return to the IDE Log window.

Editing the Source File

To edit a source file:

(1)

Click once on the error message in the IDE Log window that you want to edit.
The selected error message is highlighted in the IDE Log window.

(2)

Choose Edit File from the Log menu.
or

Double-click on the selected error message.
Both of these actions open the appropriate editor.  If the Open Watcom Editor appears and the error message contained column and line details, your cursor will be positioned at the error in the source code.

(3)

Make the required changes to the source file and exit the Editor.

Saving the Log

To save the log:

(1)

Choose Save Log As from the Log menu.
The Save Log As dialog appears where you specify the filename by which you want to save the contents of the Log window.

(2)

Enter the desired log name in the File Name field.

(3)

Specify the directory to which you want to save the log.

(4)

Click on the OK button.
The IDE closes the Save Log As dialog and saves the current log as specified

The IDE Switches

• Release and Development Switches
• Target and Source File Switches
• The Autodepend Switch

Using Release and Development Switches

To change the selected set of switches for a target:

(1)

Click once on the target whose switches you want to change.
The title bar of the selected target is highlighted.

(2)

Choose Target Options from the Targets menu.
A submenu appears from the Target Options menu.

(3)

Choose Use Development Switches or Use Release Switches (whichever is not currently selected) from the submenu, as desired.
A message box appears asking if you want to mark the selected target and its source files for remake.

(4)

Choose Yes or No, as desired, to continue.
The message box closes and you return to the Open Watcom IDE window.  The next time you perform a make, the IDE will use the selected set of switches.

Setting Target and Source File Switches

Setting Target Switches

To set switches for a target:

(1)

Click once on the target window for which you want to set switches.
The title bar of the selected window is highlighted.

(2)

Choose Windows Linking Switches from the Options menu.
or

Choose Target Options from the Targets menu and then choose Windows Linking Switches from the Target Options submenu.
The Windows Linking Switches dialog appears on the screen.  The switches you access from this dialog affect only the currently selected target.  There are four Switches dialogs, each one allowing you to set the following types of switches:

• Basic
• Import, Export and Library
• Advanced
• Special
• Resource

You can use the forward (>>) and backward (<<) buttons or the drop-down list to choose the set of switches you want to set.


Figure 26. Use the Windows Linking Switches dialog to set command-line compiler and linker options.

The first dialog allows you to choose the debugging information you want to see.  Remember, if the option Use Development Switches is enabled in the Target Options submenu of the Targets menu, the Integrated Development Environment automatically sets switches to include all debugging information.  You can change this setting by selecting Use Release Switches from the Target Options submenu under the Targets menu or choosing specific switches in the Switches dialogs.

Select the CopyRel button in the Switches dialog to copy the set of Release switches to the current dialog.   You can then make further changes, as required.  This button is available only if the Development switches are selected in the Setup Target submenu under the Targets menu.

Select the CopyDev button in the Switches dialog to copy the set of Development switches to the current dialog.   You can then make further changes, as required.  This button is available only if the Release switches are selected in the Target Options submenu under the Targets menu.

Select the Reset button to reset the switches to the default Release or Development switches, as selected in the Target Options submenu under the Targets menu.

(3)

Click on OK when you are finished setting switches for the selected target.
The Switches dialog closes and you return to the Open Watcom IDE Project window.

Setting Source File Switches

To set switches for a source file group:

(1)

Click once on the target window that contains the relevant source files.

(2)

Choose the appropriate item from the Options menu.
For example, to set switches for all ".c" files in the selected target, choose C Compiler Switches from the Options menu.

The Compiler Switches dialog appears on the screen.  The switches you access from this dialog affect only the currently selected source file or source file group.  There are eleven Switches dialogs for Open Watcom C/C++, each one allowing you to set the following types of switches:

• File Option Switches
• Diagnostics Switches
• Source Switches
• Miscellaneous Switches
• Optimization Switches
• Debugging Switches
• CodeGen Strategy Switches
• Register Usage Switches
• CodeGen Option Switches
• Memory Model and Processor Switches
• C or C++ Compiler Switches

There are ten Switches dialogs for Open Watcom FORTRAN 77.

• File Option Switches
• Compile-time Diagnostic Switches
• Run-time Diagnostic Switches
• Debugging Switches
• Code Generation Strategy Switches
• Code Generation Option Switches
• Register Usage Switches
• Optimization Switches
• Application Type Switches
• Miscellaneous Switches

You can use the forward (>>) and backward (<<) buttons or the drop-down list to choose the set of switches you want to set.


Figure 27. Use the C Compiler Switches dialog to set switches for the compiler associated with the selected source file(s).

The first of several compiler switch dialogs appears.  Of note is the sixth screen, Debugging Switches, which allows you to choose the debugging information you want to see.  Remember, if the option Use Development Switches is enabled in the Target Options submenu of the Targets menu, the Integrated Development Environment automatically sets switches to include all debugging information.  You can change this setting by selecting Use Release Switches from the Target Options submenu under the Targets menu or choosing specific switches in the Switches dialogs.

Select the CopyRel button in the Switches dialog to copy the set of Release switches to the current dialog.   You can then make further changes, as required.  This button is available only if the Development switches are selected in the Target Options submenu under the Targets menu.

Select the CopyDev button in the Switches dialog to copy the set of Development switches to the current dialog.   You can then make further changes, as required.  This button is available only if the Release switches are selected in the Target Options submenu under the Targets menu.

Select the Reset button to reset the switches to the default Release or Development switches, as selected in the Target Options submenu under the Targets menu.

(3)

Click on OK when you are finished setting switches for the selected source file or group of source files.
The Switches dialog closes and you return to the Open Watcom IDE Project window.

To set switches for a specific source file:

(1)

Click once on the source file for which you want to set switches.
The selected source file is highlighted.

(2)

Choose Source Options from the Sources menu.
A submenu for the Source Options menu appears on the screen.

(3)

Choose the appropriate item from the Source Options submenu.
For example, if the selected source file has a ".c" extension, choose C Compiler Switches from the Options menu.

The Compiler Switches dialog appears on the screen.  The switches you access from this dialog affect only the currently selected source file.  There are eleven Switches dialogs for Open Watcom C/C++, each one allowing you to set the following types of switches:

• File Option Switches
• Diagnostics Switches
• Source Switches
• Miscellaneous Switches
• Optimization Switches
• Debugging Switches
• CodeGen Strategy Switches
• Register Usage Switches
• CodeGen Option Switches
• Memory Model and Processor Switches
• C or C++ Compiler Switches

There are ten Switches dialogs for Open Watcom FORTRAN 77.

• File Option Switches
• Compile-time Diagnostic Switches
• Run-time Diagnostic Switches
• Debugging Switches
• Code Generation Strategy Switches
• Code Generation Option Switches
• Register Usage Switches
• Optimization Switches
• Application Type Switches
• Miscellaneous Switches

You can use the forward (>>) and backward (<<) buttons or the drop-down list to choose the set of switches you want to set.


Figure 28. Use the C Compiler Switches dialog to set switches for the compiler associated with the selected source file(s).

The first of several compiler switch dialogs appears.  Of note is the sixth screen, Debugging Switches, which allows you to choose the debugging information you want to see.  Remember, if the option Use Development Switches is enabled in the Target Options submenu of the Targets menu, the Integrated Development Environment automatically sets switches to include all debugging information.  You can change this setting by selecting Use Release Switches from the Target Options submenu under the Targets menu or choosing specific switches in the Switches dialogs.

Select the CopyRel button in the Switches dialog to copy the set of Release switches to the current dialog.   You can then make further changes, as required.  This button is available only if the Development switches are selected in the Target Options submenu under the Targets menu.

Select the CopyDev button in the Switches dialog to copy the set of Development switches to the current dialog.   You can then make further changes, as required.  This button is available only if the Release switches are selected in the Target Options submenu under the Targets menu.

Select the Reset button to reset the switches to the default Release or Development switches, as selected in the Target Options submenu under the Targets menu.

(4)

Click on OK when you are finished setting switches for the selected source file or group of source files.
The Switches dialog closes and you return to the Open Watcom IDE Project window.

Using the Autodepend Switch

To set the Use Autodepend switch:

(1)

Choose Target Options from the Targets menu.
A submenu appears from the Target Options menu.  A check mark beside the menu option indicates that it is enabled.

(2)

Select the Use Autodepend option from the Target Options submenu.
If the option was enabled when you selected it, you have disabled the Use Autodepend feature.  If the option had no check mark when you selected it, you have enabled the Use Autodepend feature.

Configuring the Integrated Development Environment

• Show or hide the Toolbar
• Show or hide the Status Bar
• Enable or disable automatic updates of file status in the target windows
• Select your own text editor
• Select a source revision control system

Show Toolbar

To add or remove the toolbar:

(1)

Choose File from the menu bar.
A checkmark beside Show Tool Bar indicates that the toolbar is present on the screen.

(2)

Select Show Tool Bar.
The Show Tool Bar state will be toggled.  If the toolbar was on the screen, it will disappear.  If the toolbar was not on the screen, it will reappear.

Show Status Bar

To add or remove the status bar:

(1)

Choose File from the menu bar.
A checkmark beside Show Status Bar indicates that the status bar is present on the screen.

(2)

Select Show Status Bar.
The Show Status Bar state will be toggled.  If the status bar was on the screen, it will disappear.  If the status bar was not on the screen, it will reappear.

Auto Refresh

To enable or disable auto refresh:

(1)

Choose File from the menu bar.
A checkmark beside Auto Refresh indicates that auto refresh is enabled.

(2)

Select Auto Refresh.
The Auto Refresh state will be toggled.  When Auto Refresh is disabled, it may be necessary to select Refresh from the Window menu whenever the target window status becomes out of date.

Selecting Your Own Text Editor

To select your own text editor:

(1)

Choose Set Text Editor from the File menu.
The Set Text Editor dialog appears.  You can enter the name of the text editor in the first field.  You must also indicate whether the text editor is an executable file or a Dynamic Link Library (DLL).  If the editor is an executable file (rather than a DLL), then you can enter an argument line in the second field.  The argument line will be supplied to the editor whenever it is started by the IDE.  The argument line can include any of three different macros which will be filled in by the IDE.  The macros are:

%f

The name of the file to be edited.

%r

The row in the file at which to position the cursor.  If the editor is invoked from a diagnostic message which contains a line number then the row value is extracted from the message; otherwise the row value is 1.

%c

The column in the file at which to position the cursor.  If the editor is invoked from a diagnostic message which contains a column number then the column value is extracted from the message; otherwise the column value is 1.

For example, if the editor argument line that you specified was:

     
     file='%f' row='%r' col='%c'

and you double click on an error message in the Log window that names the file foobar.c with an error at line 215 and column 31, then the argument line that is passed to your editor is:

     
     file='foobar.c' row='215' col='31'

This flexibility allows you to specify the name of the file to edit and the row and/or column at which to position the text cursor.  If no row or column is available, then the IDE will supply the value of 1 as a default.

(2)

Select OK when you wish to confirm the selection of a new editor.
or

Select Cancel when you wish to cancel the selection of a new editor.
or

Select Default when you wish to restore the default editor selection and then select OK or Cancel.

Selecting a Source Revision Control System

To select a revision control system

(1)

Choose Set Source Control from the File menu.
A number of options are presented:

MKS RCS

Mortice Kern Systems Revision Control System

MKS SI

Mortice Kern Systems Source Integrity

PVCS

Intersolv Project Version Control System

Other

Any other flavour of revision control system (default)

None

No revision control system

Object Cycle

Powersoft's Object Cycle

Perforce

Perforce

MKS RCS

MKS_CO

for checking out/locking files with MKS RCS

MKS_CI

for checking in/unlocking files with MKS RCS

MKS SI

Checkout Dialog

a check out dialog will appear on the screen when using MKS SI

Checkin Dialog

a check in dialog will appear on the screen when using MKS SI

PVCS

PVCS_CO

for checking out/locking files with Intersolv PVCS

PVCS_CI

for checking in/unlocking files with Intersolv PVCS

Other

GEN_CO

a file which you can edit to provide check out (and lock) functionality to any generic revision control system

GEN_CI

a file which you can edit to provide check in (and unlock) functionality to any generic revision control system

None

When selected, Checkout Source and Checkin Source are disabled.

1. "pause" or "nopause" to enable optional screen pause after completion of action
2. full source file path specification
3. full project file path specification (.wpj file)
4. full target file path specification (.tgt file)

1. full source file path specification
2. full message file path specification (this file contains the textual message that you enter when checking in a file)
3. full project file path specification (.wpj file)
4. full target file path specification (.tgt file)

Executing Special Commands

To set Before or After directives:

(1)

Click once on the target for which you want to set a before or after directive.
The title bar of the selected target is highlighted.

(2)

Choose Target Options from the Targets menu.
A submenu appears from the Target Options menu.

(3)

Choose Execute Before or Execute After from the Target Options submenu.
A Target Before or Target After dialog appears on your screen.

Note:

If you want to set before or after directives to be executed when you make all targets, select the before and after commands from the File menu.

(4)

Enter the command you want to execute before or after the selected target is made.

Figure 29. Enter execute commands in the Target Before or Target After dialogs.

(5)

Click on OK to continue.
The IDE stores the information you entered and closes the dialog.  When you next perform a make on the selected target, the IDE will execute the before or after directive you entered.

Adding Resources to a Target

To add a resource to a target using the indirect method:

(1)

Create a new source file with the extension ".rc".

(2)

Click once on the new source file to select it.

(3)

Choose Edit Text from the Sources menu to invoke the Open Watcom Editor.
The editor opens on your screen with an empty window.  You can now add the resource file text.

(4)

Enter the resource statements in the editor.

(5)

Save your work and close the editor when you are finished.
You return to the Open Watcom IDE Project window.  You can now compile the new source file.

(6)

Click once on the new source file to select it.
The selected source file is highlighted in the target window.

(7)

Choose Make from the Sources menu to compile the new source file.
The IDE compiles the selected source file.  To do this, the IDE invokes the Resource Compiler which creates a ".res" file.  The ".res" file will be automatically included in the target when it is linked.

To add a resource to a target using the direct method:

(1)

Create a new source file with the extension ".res".

(2)

Click once on the new source file to select it.

(3)

Choose Edit Resources from the Sources menu to invoke the Open Watcom Resource Editor.
The editor opens on your screen with an empty window.  You can now create the resources.

(4)

Create the resources.

(5)

Save your work and close the editor when you are finished.
You return to the Open Watcom IDE Project window.  You can now compile the new source file.

(6)

Click once on the new source file to select it.
The selected source file is highlighted in the target window.

(7)

Choose Make from the Sources menu to compile the new source file.
The IDE compiles the selected source file.  The IDE does not need to invoke the Resource Compiler to create a ".res" file because you created the ".res" file directly using the Resource Editor.  The ".res" file will be automatically included in the target when it is linked.

Including Libraries in a Target

To create static and DLL libraries:

(1)

Create a new target entering the library name in the Target Name field and choosing the appropriate image type.
Clicking on OK on the New Target dialog closes the dialog and creates a new target with the specified name in the title bar.

(2)

Add the desired source files, new or existing, to the library you have created.

Note:

If you want one of your other targets to use that library, you must enter the library as a source file for that target.  When you enter the library as a source file you must give it the extension ".lib", regardless of whether the library is a static or DLL library.  For example, if your library is entitled Target A and you want your existing Target B to use that library, add Target A as a source file on Target B with the extension ".lib".

Targets and Image Types Supported by the IDE

Win32 Targets

Character-mode Executable [.exe]

The target is a non-GUI Win32 application.

Windowed Executable [.exe]

The target is a GUI Win32 application.

Dynamic Link Library [.dll]

The target is a Win32 DLL.

Library [.lib]

The target is a Win32 library.

Help File [.hlp]

The target is a help file.

Win16 Targets

Executable [.exe]

The target is a 16-bit Windows application.

Dynamic Link Library [.dll]

The target is a 16-bit Windows DLL.

Library [.lib]

The target is a 16-bit Windows library.

Help File [.hlp]

The target is a help file.

Win386 (Watcom Extender) Targets

Executable [.exe]

The target is a 32-bit Open Watcom Windows extender application.

Dynamic Link Library [.dll]

The target is a 32-bit Open Watcom Windows extender DLL.

Library [.lib]

The target is a 32-bit Open Watcom Windows extender library.

Help File [.hlp]

The target is a help file.

DOS - 16-bit Targets

Executable [.exe]

The target is a 16-bit DOS .exe file.

.COM Executable [.com]

The target is a 16-bit DOS .com file.

Library [.lib]

The target is a 16-bit DOS .lib file.

DOS - 32-bit Targets

CauseWay Executable [.exe]

The target is a 32-bit CauseWay .exe file.

CauseWay DLL (register based) [.dll]

The target is a 32-bit CauseWay dll using register-based calling conventions.

CauseWay DLL (stack based) [.dll]

The target is a 32-bit CauseWay dll using stack-based calling conventions.

DOS4GW Executable [.exe]

The target is a 32-bit DOS/4GW .exe file.

PMODW/W Executable [.exe]

The target is a 32-bit PMODE/W .exe file.

DOS32/A Executable [.exe]

The target is a 32-bit DOS32/A .exe file.

Pharlap Executable [.exp]

The target is a 32-bit PharLap "RUN386" .exe file.

Pharlap TNT Executable [.exe]

The target is a 32-bit PharLap TNT .exe file.

Flashtek Executable [.exe]

The target is a 32-bit FlashTek .exe file using register-based calling conventions.

Flashtek -- Stack based [.exe]

The target is a 32-bit FlashTek .exe file using stack-based calling conventions.

Library [.lib]

The target is a 32-bit DOS .lib file.

OS/2 - 16-bit Targets

Executable [.exe]

The target is a 16-bit OS/2 console application.

PM Executable [.exe]

The target is a 16-bit OS/2 Presentation Manager application.

Fullscreen Executable [.exe]

The target is a 16-bit OS/2 Fullscreen application.

Dynamic Link Library [.dll]

The target is a 16-bit OS/2 DLL.

Library [.lib]

The target is a 16-bit OS/2 library file.

Help File [.hlp]

The target is an OS/2 help file (HLP format).

INF File [.inf]

The target is an OS/2 help file (INF format).

OS/2 - 32-bit Targets

Executable [.exe]

The target is a 32-bit OS/2 console application.

PM Executable [.exe]

The target is a 32-bit OS/2 Presentation Manager application.

Fullscreen Executable [.exe]

The target is a 32-bit OS/2 Fullscreen application.

Virtual Device [.exe]

The target is a 32-bit OS/2 Virtual Device Driver application.

Dynamic Link Library [.dll]

The target is a 32-bit OS/2 DLL.

Library [.lib]

The target is a 32-bit OS/2 library file.

Help File [.hlp]

The target is an OS/2 help file (HLP format).

INF File [.inf]

The target is an OS/2 help file (INF format).

Linux Targets

Executable [.exe]

The target is a Linux application.

Shared Library [.dll]

Shared libraries are not yet supported.

Library [.lib]

The target is a Linux static library file.

Invoking Other Applications from the IDE

• Browser
• Open Watcom Debugger
• Open Watcom Execution Sampler
• Open Watcom Execution Profiler
• Open Watcom Disassembler
• Open Watcom Editor (text editor)
• Open Watcom Resource Editor
• Open Watcom Zoom
• Open Watcom Heap Walker
• Spy
• DDE Spy

Invoking DOS Applications from the IDE under OS/2

Using the Information of the IDE from outside

The Open Watcom Browser

Using the Browser

• Starting the Browser
• Starting the Browser through the Open Watcom Integrated Development Environment
• Quitting the Browser
• The Browser Menu Bar

Starting the Browser

Quitting the Browser

Select Cancel to return to the main Browser window without saving the options.
or

Select OK to close the dialog and exit the Browser session.

The Browser Menu Bar

File

Create, open, and configure Browser files; save and load options

View

Choose a global view for the current database file

Detail

View detailed information for a symbol

Tree

Choose the nodes to display for a tree view

Locate

Find symbols within the current global view

Options

Configure the Browser session

Windows

Select from the list of Browser windows currently open

Help

Access on-line help information

Browser Files

Creating a Browser Database File within the Browser

(1)

Choose New from the File menu.
This opens the New Browser File dialog where you enter the name of the Browser database file you are creating.


Figure 30. Use the New Browser File dialog to create a new Browser database file.

(2)

Type the name and path of the new Browser database file.
or

Click on the Files button to open a second dialog that allows you to browse the directory structure for an existing Browser database file.  Select an existing file and change its name.  If you do not change its name, a message box appears when you press OK asking if you want to overwrite the existing file.

(3)

Click on OK.
This opens a Module window that will eventually contain a list of the module files that will make up the database file.

(4)

Click on the Add button in the Module window.
This opens the Select Module File(s) dialog where you choose the module files to add to the database file.

(5)

Select the module files to add to the database file and click on OK.
or

Double click on the desired module file.
This closes the Select Module File(s) dialog and adds the selected module file to the Browser file component list.   Each module file on the components list has a check box.  When added, this check box is marked with an X, indicating that the module file is enabled.

(6)

Continue with steps 4 and 5 until you have added all desired module files to the component list.

Figure 31. The Modules dialog displays the selected module files.

(7)

Click on OK on the Module window.
This closes the Module window and creates the database file.

Creating a Browser Database File from the Command Line

Opening an Existing Browser Database File

(1)

Choose Open from the File menu.
This opens the Open Browser Database File dialog where you select the database file you want to open.

(2)

Select a database file to open and click on OK.
or

Double click on the desired database file.
This closes the Open Browser Database File dialog.

Note:

You can have only one database file open at a time.  If you open a second database file, the Browser discards the first and displays information for the second.

Working with Browser Module Files

• Add
• Remove
• Disable
• Enable

Adding a Module File

(1)

Choose Modules from the File menu.
This opens the Modules dialog for the current database file.  This dialog lists all module files that make up the database file.  Each module file has a check box.  An X in this box indicates that the module file is enabled.   The Browser browses only the enabled module files.

(2)

Click on the Add button in the Modules dialog.
This opens the Select Module File(s) dialog where you choose the module files to add to the current Browser file.

(3)

Select the module files to add to the Browser file and click on OK.  Select multiple module files by holding the Shift key while you click on the desired files.
Clicking on OK closes the Select Module File(s) dialog and adds the selected module file to the database file.   Each module file in the module list has a check box.  When added, this check box is marked with an X, indicating that the module file is enabled.

(4)

Continue with steps 2 and 3 until you have added all desired module files to the component list.

(5)

Click on OK in the Module dialog.
This closes the Modules dialog and updates the database file.

Removing a Module File

(1)

Choose Modules from the File menu.
This opens the Modules dialog for the current database file.  This dialog lists all module files that make up the database file.  Each module file has a check box.  An X in this box indicates that the module file is enabled.   The Browser browses only the enabled module files.

(2)

Click once on the module file you want to remove from the database file.
This highlights the selected module file.

(3)

Click on the Remove button in the Modules dialog.
This removes the selected module file from the list.

(4)

Click on OK in the Modules dialog.
This closes the Modules dialog and updates the database file.

Disabling a Module File

(1)

Choose Modules from the File menu.
This opens the Modules dialog for the current database file.  This dialog lists all module files that make up the database file.  Each module file has a check box.  An X in this box indicates that the module file is enabled.   The Browser browses only the enabled module files.

(2)

Click in the check box of the module file you want to disable.  Alternatively, use the up and down arrow keys to select the module file you wish to disable.  Press the space bar to disable the currently selected module file.
This removes the X.  The blank box indicates that the module file is disabled and will not be browsed.

(3)

Repeat step 2 until you have disabled all desired module files.

(4)

Click on OK on the Modules dialog.
This closes the Modules dialog and updates the database file.

Enabling a Module File

(1)

Choose Modules from the File menu.
This opens the Modules dialog for the current database file.  This dialog lists all module files that make up the database file.  Each module file has a check box.  An X in this box indicates that the module file is enabled.   The Browser browses only the enabled module files.

(2)

Click in the check box of the module file you want to enable.  Alternatively, use the up and down arrow keys to select the module file you wish to enable.  Press the space bar to enable the currently selected module file.
This places an X in the box indicating that the module file is enabled and will be browsed.

(3)

Repeat step 2 until you have enabled all desired module files.

(4)

Click on OK on the Module dialog.
This closes the Modules dialog and updates the database file.

Global Views

List

Displays a list of all symbols in your program

Inheritance

Displays the class inheritance graph for your program

Call

Displays the call graph for your program

The List View

F

Function

C

Class

T

Typedef

V

Variable

E

Enum

• The file folder icons are hot spots that display the detail view of the selected symbol.  To activate the hot spot, click once on the symbol name to select it and press ENTER to reveal the detail view.
• Click once on the file folder to reveal the detail view for that symbol.
• Click once on the symbol name to select it and choose Detail from the Detail menu.
• Double click on the symbol name.

The Class Inheritance View

Graph view

The graph view displays each class in a box.  A box, or node, is connected to another node if one is a derived class of the other.  The root node of the tree is the base class for all nodes in the tree.  The tree is initially fully expanded.  See the section entitled Manipulating the Tree Views for more information on removing and expanding nodes from the tree.

Outline view

The outline view displays the same information as the graph view but in a different way.  The outline view is initially fully collapsed.  That is, only the base classes are displayed.  In order to view the derived classes of a node, you must single click on the node.  This expands the node, displaying all its immediate derived classes.  See the section entitled Manipulating the Tree Views for more information on removing and expanding nodes from the tree.

The Function Call Tree View

Graph view

The graph view displays each function in a box.  A box, or node, is connected to another node if one function calls the other.  The tree is initially fully expanded.  See the section entitled Manipulating the Tree Views for more information on removing and expanding nodes from the tree.

Outline view

The outline view displays the same information as the graph view but in a different way.  The outline view is initially fully collapsed.  In order to view the functions called by the function specified in the node, you must single click on the node.  This expands the node, displaying all functions it calls.  See the section entitled Manipulating the Tree Views for more information on removing and expanding nodes from the tree.

Manipulating the Tree Views

• select the root nodes you want to view
• expand any node in the view
• collapse any node in the view

• choose the desired function from the Tree menu
• click on the node (applies only to the outline view)

Selecting Root Nodes

(1)

Click in the check box of the root node you want to disable.  Alternatively, use the up and down arrow keys to select the root node you wish to disable.  Press the space bar to disable the currently selected root node.
The X disappears meaning that the root node is disabled and will not appear in the display.

(2)

Repeat step one until you have disabled all desired root nodes.

(3)

Click on OK in the Select Root Nodes dialog.
The Select Root Nodes dialog closes and the display is updated.

Note:

This disables the selected root nodes only for the active view window.

(1)

Click in the check box of the root node you want to enable.  Alternatively, use the up and down arrow keys to select the root node you wish to enable.  Press the space bar to enable the currently selected root node.
An X appears in the box indicating that the root node is enabled and will appear in the display.

(2)

Repeat step one until you have enabled all desired root nodes.

(3)

Click on OK in the Select Root Nodes dialog.
The Select Root Nodes dialog closes and the display is updated.

Note:

This enables the selected root nodes only for the active view window.

Expanding Nodes

Expand One Level

Choose Expand One Level from the Tree menu to display all of the immediate children for the selected node.

Expand Branch

Choose Expand Branch from the Tree menu to display all descendants of the selected node.

Expand All

Choose Expand All from the Tree menu to fully expand all of the enabled root nodes.  Disabled root nodes do not appear in the display.

Collapsing Nodes

Collapse Branch

Choose Collapse Branch from the Tree menu to hide all descendants of the selected node.

Collapse All

Choose Collapse All from the Tree menu to collapse all of the nodes and display only the root nodes.

+

Expand the symbol one level

-

Collapse the symbol one level

*

Expand all descendants of the selected node.  This is the same as choosing Expand Branch from the Tree menu.

CTRL *

Expands all of the enabled root nodes.  This is the same as choosing Expand All from the Tree menu.

CTRL -

Collapses all of the symbols and displays only the root nodes.  This is the same as choosing Collapse All from the Tree menu.

Viewing Detail Information

• Double click on the desired symbol.
• Click once on the desired symbol to select it; then choose Detail from the Detail menu.
• Click once on the desired symbol to select it then press ENTER.

• Click once on the icon to the left of the symbol.

Functions

The list box displays, where applicable, local variables for the function.

Classes

The list box displays member variables and member functions for the selected class and any inherited classes.  The Browser divides this information into three categories:

• Public
• Private
• Protected

Enums

The list box displays enumerator values for the selected enumerator.

Goto Definition

Source References

To view the source references for a symbol:

(1)

Position yourself at the detail view of the symbol whose source references you want to view.

(2)

Choose Source References from the Detail menu.
This opens the Source References window for the selected symbol.  This window displays the filename, line number, and column number of each occurrence of the selected symbol in the source code.

Symbol References

To view the symbol references for a symbol:

(1)

Position yourself at the detail view of the symbol whose symbol references you want to view.

(2)

Choose Symbol References from the Detail menu.
This opens the Symbol Referencing window for the selected symbol.  This window displays a list of all symbols that use the selected symbol.  The display is the same as the list view of symbols.  Each symbol has a icon indicating its symbol type.


Figure 39. Use the Symbols window to view a list of all symbols that use the selected symbol.

You can perform the same actions in this window as from the List window.  Refer to the section entitled The List View for more information.

• Double click on the desired reference.
• Click once on the desired reference to select it and press ENTER.

Locating Symbols

• Find
• Find Selected

Find

Find Pattern

Match Case

When enabled, the Browser performs a case sensitive compare when attempting to find a match.

Match Whole Symbols Only

When enabled, the Browser locates symbols that exactly match the specified pattern.  This switch only applies when the Use Regular Expressions switch is disabled.

Use Regular Expressions

When enabled, the Browser interprets the pattern specified as a regular expression.  The Edit button, when pressed, displays the Regular Expression Options dialog.  This dialog allows you to specify the regular expression.

Find Filters

Member of Class:

Specify the class that the symbol must be a member of in order to be located.

Local Symbols of Function:

Specify the function that the symbol must be local to in order to be located.

Performing the Find

Find Selected

Configuring the Browser

• Regular expression processing for find and query
• Global Symbol Queries
• Enumerator styles for detail views of enumeration constants
• Member filters for detail views of classes
• Auto-arranging of graph views
• Line drawing method for graph views
• Orientation of graph views
• Line styles and colors for inheritance graphs
• Line styles and colors for call graphs
• Selection of text editor
• Automatic saving of options on exit

Regular Expressions for Find and Query

Starts With

Matches only if the pattern is found at the beginning of the symbol

Contains

Matches if it occurs anywhere in the symbol

Set All

Click on Set All to enable all of the characters.

Clear All

Click on Clear All to disable all of the characters.

Defaults

Click on Defaults to discard the current settings in this dialog and replace them with the settings configured at the start of the Browser session.

OK

Click on OK to close this dialog.  This changes the configuration for the current Browser session.

Global Symbol Queries

Query Pattern

Match Case

When enabled, the Browser performs a case sensitive compare when attempting to find a match.

Match Whole Symbols Only

When enabled, the Browser includes symbols that exactly match the specified pattern.  This switch only applies when the Use Regular Expressions switch is disabled.

Use Regular Expressions

When enabled, the Browser interprets the pattern specified as a regular expression.  The Edit button is enables and, when pressed, displays the Regular Expression Options dialog.  This dialog allows you to specify the regular expression.

Query Filters

Member of Class:

Specify the class that the symbol must be a member of in order to be displayed.

Local Symbols of Function:

Specify the function that the symbol must be local to in order to be displayed.

Enumerator Styles

Member Filters for Classes

(1)

Choose Member Filters from the Options menu.
This opens the Member Filters dialog where you specify the information you want to appear in detail views for classes.


Figure 46. Use the Member Filters dialog to select the information to appear in detail views for classes.

(2)

Choose the inheritance level from the Inherited Members section of the dialog.
The options are:

None

Do not show inherited members.

Visible

Show the local members of a class and visible members of inherited classes.

All

Show all local and inherited members of a class.

(3)

Click on the check boxes in the Access Level section of the dialog to select the desired access levels.
The options are Public, Protected, and Private.  Only members with the selected attributes will appear in the detail view for a class.

(4)

Select the desired members in the Members section of the dialog.
Show data members in a class by enabling the variables check box.  When the variables check box is enabled, you may also enable or disable static data members by clicking on the static check box.

Show function members in a class by enabling the functions check box.  When the functions check box is enabled, you may also enable or disable static and virtual function members by clicking on the static and virtual check boxes.

(5)

Click on OK to accept the member filter query.
This closes the dialog and returns you to the active window.

Note:

The Default button on the Member Filter dialog resets the query to the default settings.

Auto-arranging of Graph Views

Line Drawing Method for Graph Views

Changing the Graph Orientation

Defining Graph View Legends

(1)

Click once on the line or node style or use the up, down, right and left arrow keys to select the line or node style you want to change.
A box appears around the selected line.

(2)

Click on the Modify button.
This opens the Draw Style dialog for the selected line or node style.

(3)

Click once on the desired line or node style
or

use the up and down arrow keys to select the desired line or node style.
The sample appearing in the Example field at the top of the dialog now reflects the currently selected line or node style.

(4)

Click once on the desired color or use the up and down arrow keys to select the desired color.
The sample appearing in the Example field at the top of the dialog now reflects the currently selected color.

(5)

Click on OK to accept the new style and color setting.
The Draw Style dialog closes, returning you to the Inheritance Legend or Call Legend dialog.  Select another line or node style to change and repeat this procedure.

(6)

Click on OK in the Inheritance Legend or Call Legend dialog when you have changed all desired colors and styles for lines and nodes.
Clicking OK closes the dialog and updates all open inheritance or call graph views with the selected colors and line and node styles.

Selecting a Text Editor

To select your own text editor:

(1)

Choose Set Text Editor from the Options menu.
The Set Text Editor dialog appears.  You can enter the name of the text editor in the first field.  You must also indicate whether the text editor is an executable file or a Dynamic Link Library (DLL).  If the editor is an executable file (rather than a DLL), then you can enter an argument line in the second field.  The argument line will be supplied to the editor whenever it is started by the Browser.  The argument line can include any of three different macros which will be filled in by the Browser.  The macros are:

%f

The name of the file to be edited.

%r

The row in the file at which to position the cursor.  If the editor is invoked from a diagnostic message which contains a line number then the row value is extracted from the message; otherwise the row value is 1.

%c

The column in the file at which to position the cursor.  If the editor is invoked from a diagnostic message which contains a column number then the column value is extracted from the message; otherwise the column value is 1.

For example, if the editor argument line that you specified was:

     
     file='%f' row='%r' col='%c'

and you double click on an error message in the Log window that names the file foobar.c with an error at line 215 and column 31, then the argument line that is passed to your editor is:

     
     file='foobar.c' row='215' col='31'

This flexibility allows you to specify the name of the file to edit and the row and/or column at which to position the text cursor.  If no row or column is available, then the Browser will supply the value of 1 as a default.

(2)

Select OK when you wish to confirm the selection of a new editor.
or

Select Cancel when you wish to cancel the selection of a new editor.
or

Select Default when you wish to restore the default editor selection and then select OK or Cancel.

Automatically Saving Options on Exit

Loading Options

Saving Options

• Save Options
• Save Options As
• Save Options on Exit

Note:

If you have made option changes during the Browser session and you choose Exit from the File menu without first saving the options, the Browser prompts you to save the options to a file.  Refer to the section entitled Quitting the Browser for more information.

Save Options

Selecting Save Options from the File menu saves the updated options information to the current options file.   To save options in this way, an options file must be specified in the caption bar. 

Save Options As

Save Options As in the File menu opens the Save Options As dialog.  Specify the filename of the option file to which you want to save the current options.  Click on OK to close the dialog and save the options.

Save Options on Exit

Save Options on Exit in the Options menu allows you to specify that the Browser is to automatically save the current options to an options file, if one exists.  When enabled, a check mark appears beside this menu item.
When enabled and an option file exists, the Browser saves the changes without prompting when you close the session.

When enabled and no option file exists, the Browser displays a message box prompting you to save the new options.   Choose No in this box to close the Browser session without saving.  Choose Yes in this box to display a Save As dialog where you specify the option file to which you want to save the new options.

Setting Source Search Paths

Profile Analysis Tools

• The Open Watcom Execution Sampler (the sampler)
• The Open Watcom Execution Profiler (the profiler)

Note

You must compile and link the program with debugging information.  Use at least the d1 option when compiling and the debug all option when linking.

The Open Watcom Execution Sampler

WSAMPLE

is one of several versions of the sampler.  See the section entitled Sampler Operating System Considerations for a description of how to run the sampler under various environments.

options

is a list of valid sampler options, each preceded by a slash ("/") or a dash ("-").  Options may be specified in any order.

program

is the name of the program to be sampled.

arguments

is the set of arguments passed to the program.  The program behaves just as if it were executed directly from the command line.  If you normally run your program using:
     
     C>program [arguments]

then it may be sampled using the following command:

     
     C>wsample program [arguments]

By default, the output of WSAMPLE is a sample file with the same name as the executable but with an extension of .SMP.   In the above example, it would be called PROGRAM.SMP.

Sampler Options Summary

Sampler Command Line Options

/r=<sample_rate>

Specifies the approximate time between execution samples (in milliseconds).  The sampler will set up the system so that the program will be interrupted in intervals of the number of milliseconds specified on the command line.  A smaller number will result in a more accurate sample file.  A larger number result in a less accurate sample.  If your program runs for a very short time, you should use the smallest interval possible.  The default value is system dependent and it will be displayed if you enter "WSAMPLE" with no arguments.  The following example will sample the program's execution 200 times per second.
Example:

     C>wsample /r=5 program

/b=<buffer_size>

Specifies the size of the sampler's internal buffer (in kilobytes).  The execution of the program will produce many samples which must be recorded in the sample file.  The sampler stores the samples in an internal buffer until the buffer is filled and must be written to the disk.  You may reduce the buffer size if you want to leave more memory for your application program.  You should not make the buffer size so small that the sampler would have to write samples to disk more than once a second.  The default size for the sample buffer is 63K.  In the following example, a buffer size of 10K will be used:
Example:

     C>wsample /b=10 program

/f=<fname>

Specify the name of the sample file.  Samples will be written to the specified file.  By default, a file with the same name as the executable and an extension of .SMP is created.

Sampler Operating System Considerations

Operating System:

Command:

DOS

WSAMPLE.EXE

OS/2

WSAMPLE.EXE

DOS/4GW or DOS/4G

WSAMPRSI.EXE

386|DOS-Extender

WSAMPPLS.EXP

Windows 3.x

WSAMPLEW.EXE

Win32

WSAMPLE.EXE

NetWare 386

WSAMPLE.NLM

Using the Sampler with DOS

/r=<rate>

Rates from 1ms to 55ms are allowed.

/b=<size>

Sizes from 1K to 64K are allowed.  Since DOS places a limit on the amount of memory available to all programs, you may need to use the "b" option to reduce the memory requirements of the sampler, leaving more memory for your program.

/f=<file>

Specify the name of the sample file.

/i=<interrupt>

specify an interrupt to monitor
This option allows you to assign any samples that occur while a service interrupt is executing to the instruction following the requesting INT instruction.  This will reveal the amount of time code spends "waiting" for interrupt services.   The interrupt number specified is in base 16 (hex) and can be in the range 20 to ff except for the range 34 to 3d which is reserved for 80x87 emulation.

Example:

     C>wsample /i=25 /i=26 program

/d

disable monitoring of the DOS interrupt
By default, the DOS version of the sampler assigns any samples that occur while a DOS interrupt is executing to the instruction following the requesting INT 21H instruction.  This will reveal the amount of time code spends "waiting" for DOS to complete a service.  This option can be used to disable this assignment of samples so that the total time spent executing in DOS code may be determined.

Using the Sampler with OS/2

/r=<rate>

Rates from 1ms to 1000ms are allowed.

/b=<size>

Sizes from 1K to 64K are allowed.

/f=<file>

Specify the name of the sample file.

/s

start the application in a new session.  By default the sampler starts your application in its own session.  Use /s if you application is a PM application, or requires its own session to run.

Using the Sampler with DOS/4GW or DOS/4G

/b=<size>

Sizes from 1K to 64K are allowed.

/f=<file>

Specify the name of the sample file.

Using the Sampler with the Phar Lap 386|DOS-Extender

/r=<rate>

Rates from 1ms to 55ms are allowed.

/b=<size>

Sizes from 1K to 64K are allowed.

/f=<file>

Specify the name of the sample file.

Using the Sampler with Windows 3.x

/r=<rate>

Rates from 1ms to 1000ms are allowed.

/b=<size>

Sizes from 1K to 64K are allowed.

/f=<file>

Specify the name of the sample file.

Using the Sampler with Win32

/r=<rate>

Rates from 1ms to 1000ms are allowed.

/b=<size>

Sizes from 1K to 64K are allowed.

/f=<file>

Specify the name of the sample file.

Using the Sampler with NetWare 386

/r=<rate>

Rates from 1ms to 55ms are allowed.

/b=<size>

Sizes from 1K to 64K are allowed.

/f=<file>

Specify the name of the sample file.

The Open Watcom Execution Profiler

Zoom-In and Backout

Sample

This is a sample file.  The profiler can show you information from several sample files at once.

Image

A sample file may consist of several images.  These are your main executable file and any Dynamic Link Libraries (DLL) or NetWare Loadable Modules (NLM) that your application called while executing.

Modules

An image may consist of several modules.  Each module is a compilation unit.  It consists of all the source code generated by one invocation of the compiler.

Files

A module may be made up of several files.  Your application may contain code that is generated by included files.

Functions

A file may contain several functions.  These are all of the global functions that are defined within that file.

Source Lines

A function is made up of one or more source lines.

Assembler instructions

Each source line generates zero or more lines of assembler instructions.  It is possible to get clues about expensive operations from the number of samples found at each instruction.  For example, the C statement "i = j + k * l" will generate a multiply instruction.  If you inspected the assembler instructions, you might find that the multiply instruction took the majority of the time in question.

Samples

Absolute and Relative Percentages

The Open Watcom Execution Profiler User Interface

The Title Area

The Information Area

The Detail View

• Image Names
• Module Names
• File Names
• Routine Names
• Source Lines
• Assembler Instructions

The Profiler Menu Bar

The File Menu

Open...

Open a new sample file.  A new window will be opened, and the data from the sample file will be displayed in it.

Close

Close the current sample file.  The current window will be closed.

Options

This allows you to set profiler options.  See the section entitled The Options Dialog for details.

System

Start a new operating system shell.  This option is only available in the DOS version of the profiler.

Exit

Close your profiler session and exit.

The Convert Menu

Current Module

Use this menu item to save out the information related to the current module.

Current Image

Use this menu item to save out the information related to the current image.

All Images

Use this menu item to save out the information related to the all of the sample images.

The Windows Menu

The Actions Menu

Zoom In (F3)

Zoom in to the currently selected line.  If the line is a source file, you will see a list of functions.  If the line is a function, you will see source lines, and so on.  You can also zoom into a line by double clicking on it.

Back Out (F4)

Back out of the current detail view to the previous view.  Double clicking in the title area will also achieve this.

Gather Small Values

Large portions of your program may be executed very little, if at all.  This menu item will cause lines with a smaller absolute percentage than the cutoff value to be grouped together.  They will be displayed on a single line starting with the text '***Gathered'.  To change the cutoff value, see The Options Dialog.

Bar Graph/Stretch

When looking at areas that are not executed very much, the histogram bars can get very small.  This menu item will stretch the histogram so that the largest bar goes all the way to the left of the screen.

Bar Graph/Absolute Bars

Use this menu item to turn the absolute (red) histogram bars on and off.

Bar Graph/Relative Bars

Use this menu item to turn the relative (green) histogram bars on and off.

Sort/Sample Count

Use this menu item to sort the detail view with the most heavily executed region at the top.

Sort/Name

Use this menu item to sort the detail view alphabetically by name.

The Help Menu

The Popup Menu

The Options Dialog

Stretch the Graphs

When looking at areas that are not executed very much, the histogram bars can get very small.  This menu item will stretch the histogram so that the largest bar goes all the way to the left of the screen.

Show Absolute Bar Graphs

Check this box to turn the absolute (red) histogram bars on or off.

Show Relative Bar Graphs

Check this box to turn the relative (green) histogram bars on or off.

Sort By Sample Count

Check this radio button to sort the detail views with the most heavily executed regions at the top.

Sort By Name

Check this radio button to sort the detail view alphabetically by name.

Gather Small Values

Large portions of your program may be executed very little, if at all.  This menu item will cause lines with a smaller absolute percentage than the cutoff value to be grouped together.  They will be displayed on a single line starting with the text '***Gathered'.

Cutoff Percentage

Specify a new cutoff percentage here.  You can specify any value between 0 and 100.

The Convert Dialog

Output File Name

The name of the sample file with the file extension most commonly used for the conversion type is displayed.  You may change this to any name, or use the Browse button to help select the name.

Format Type

Check this radio button to specify the data type that the sample information will be converted to.

The Status Line

How to Use the Profiler Effectively

Region

Percentage

1

10%

2

70%

3

20%

Open Watcom Execution Profiler Command Line Format

-DIP dip_name

Specify a DIP for use by the profiler.  All default DIPs are disabled by the first use of this option.  Successive uses of the option will add to the list of DIPs.  The DIPS will used in the order in which they are specified.

-NOCHarremap

The profiler uses character re-mapping to display many of the graphics characters.  When you are running the profiler in some DOS environments, you may see a number of strange characters on the screen.  This is a DOS only option to turn off character re-mapping.

-NOGrahicsmouse

This is a DOS only option to turn off the graphics mouse, and to use the block mouse cursor instead.

-?  or -Help

Display command line help.

Profiling a NetWare NLM

The Open Watcom Editor

Startup Options

Using Menus

Using Drag and Drop Palettes

Using the Right Mouse Button

When Less Than One Line is Selected

Windows Help

Choose Windows Help to find information about the currently selected text.

CLib Help

Choose CLib Help to find information from the C Library Reference manual about the currently selected text.

Open

Choose Open to open a new file.  The name of the new file is the selected text. 

Cut

Choose Cut to delete the selected text and place it on the Windows clipboard.

Copy

Choose Copy to copy the selected text to the Windows clipboard and leave the original.

Find

Choose Find to look for the first occurrence of the selected text.  The Find dialog appears.

Fgrep

Choose Fgrep to find all files in the current directory which match the grep default mask and contain the selected text. 

Tag

Choose Tag to look for a tag whose name is the selected text.

When More Than One Line is Selected

Cut

Choose Cut to delete the selected lines and place them on the Windows clipboard.

Copy

Choose Copy to copy the selected lines to the Windows clipboard and leave the original lines.

>>Shift Right

Choose Shift Right to move the selected lines right by a number of spaces equal to the shift width setting.

<<Shift Left

Choose Shift Left to move the selected lines left by a number of spaces equal to the shift width setting.

Starting and Quitting the Editor

Opening and Closing Files

New

Open a new file.

Open

Open an existing file.

Close

Close an open file.

Opening a New File

(1)

Start the Editor.

(2)

Choose New from the File menu.
An empty text window appears.

Opening an Existing File

(1)

Start the Editor.

(2)

Choose Open from the File menu.
The standard Windows Open dialog appears.

(3)

Choose the file and click on OK.
You may have to change the current drive and directory to find the file.  The file then opens.

Closing a File

Saving Files

Save

Save the changes made to the current file.

Save As...

Save the current file under a different name.  This is the standard Windows Save As...  dialog.  When you save the current file with a new name, only the new file remains open.

Save All

Save the changes made to all open files.

The Editor Toolbar

New

Open a new file.  This is equivalent to New in the File menu.

Open

Open a new or existing file.  This is equivalent to Open in the File menu.

Save

Save the current file.  This is equivalent to Save in the File menu.

Cut

Delete the selected text to the clipboard.  This is equivalent to Cut in the Edit menu.

Copy

Copy the selected text to the clipboard.  This is equivalent to Copy in the Edit menu.

Paste

Insert the clipboard contents at the current cursor position.  This is equivalent to Paste in the Edit menu.

Undo

Undo the last change to the current file.  This is equivalent to Undo in the Edit menu.

Redo

Undo the last undo.  This is equivalent to Redo in the Edit menu.

Find

Search for the specified text.  This is equivalent to Find in the Edit menu.

Find Next

Repeat the last search.  This is equivalent to Find Next in the Edit menu.

Match

Find matching brackets from the current cursor position.

File List

Display a list of all files being edited.  This is equivalent to File List in the File menu.

Previous File

Switch to the previous file.

Next File

Switch to the next file.

IDE

Reactivate the IDE.  This icon is present on the toolbar if the Editor was invoked from the IDE.

Searching Text

(1)

Choose Find from the Edit menu.
The cursor flashes in the Find box.

(2)

Enter the search string in the Find box.

(3)

Set the find options.

(4)

Click on the Find button.
When the search is successful, you are repositioned to the line containing the string.

Setting Search Options

Ignore Case

You can have the search match the case exactly or match the characters only and ignore the case.

Regular Expressions

You can use regular expressions in your "Find" text if you check this box.

Search Backwards

By default, a search is conducted through the lines that follow the current cursor position.  Select this option if you wish to search backwards from the current cursor position.

Wrap Search

By default, the search ends when it reaches the end of the file.  However, if your search begins in the middle of the file and you want to search through the whole file, you can set the search to go to the beginning of the file and continue until it reaches the search starting point.

Replacing Text

(1)

Choose Replace from the Edit menu.
The cursor flashes in the Find box.

(2)

Enter the search string in the Find box.

(3)

Press Tab.
The cursor moves to the Replace box.

(4)

Enter the replace string.

(5)

Set the replace options.

(6)

Click on the Replace button.
When the replace is complete, you return to the file.

If the Prompt on Replace option is turned on, you must confirm each replacement.  If it is off, all occurrences of the string are replaced automatically.

Setting Search and Replace Options

Ignore Case

You can have the search match the case exactly or match the characters only and ignore the case.

Regular Expressions

You can use regular expressions in your "Find" and "Replace" text if you check this box.

Prompt on Replace

By default, all found strings are replaced with the replace string.  Turn this option on to be prompted for each replacement.

Wrap Search

By default, the search ends when it reaches the end of the file.  However, if your search begins in the middle of the file and you want to search through the whole file, you can set the search to go to the beginning of the file and continue until it reaches the search starting point.

Changing the Font

(1)

Choose Fonts from the Options menu.

(2)

Choose the typeface, style, and point size that you want.  A sample of the text appears in the Drag and Drop box.

(3)

Click in the drag and drop box and drag the cursor to the element to which you want to apply the font characteristics.
All elements change to the new font style.  All buffers are affected when you change one.

Changing Colors

(1)

Choose Colors from the Options menu.

(2)

Click on the color you want and drag it to the screen or syntax element to which you want to apply the color The element is changed to the new color
Use the left mouse button to color foreground elements and the right mouse button to color background elements. 

Press Control and the right mouse button to affect the color of all backgrounds.  Press Control and the left mouse button to affect all foregrounds.

Accessing Help

Using Fgrep Capabilities

(1)

Choose Fgrep from the Edit menu.
A dialog appears.

(2)

Enter the text you want to search for.

(3)

Select any options you want to use during the search.

(4)

Click on OK.

Edit

Select an individual occurrence and open that file.  The file opens in the background, but the Fgrep dialog remains.

Goto

Open the selected file for editing at the first occurrence of the search pattern in the Fgrep dialog.

Get All

Open all found files.  The files open, with the last one in the list the currently open file.

Cancel

Leave the Fgrep dialog.

Configuring the Editor

Status Bar Contents

• Items
• Alignment
• Commands

Status Bar Contents :  Items

• Time of day
• Current date
• Current insertion mode
• Line number
• Column number
• Menu help text

Status Bar Contents :  Alignment

• Left aligned
• Center aligned
• Right aligned

Status Bar Contents :  Commands

• Split
• Clump
• Defaults

General Options

• Features
• VI Emulation
• Searching
• Word Definitions
• Filenames/Paths
• Miscellaneous

General Options :  Features

Undo

Turn this option on to allow an unlimited number of undo's.

AutoSave

Enable or disable the autosave option.  This option allows you to determine how often a copy of your file is saved to the Temp Directory.  Enter the time in seconds in the Interval box.

Save configuration on exit

Turn this option on if you want the Editor to save the current configuration when you leave the Editor.

Save files on IDE build

Turn this option on if you want the Editor to be notified whenever you start an IDE make.  It will cause the Editor to prompt you for each file that was modified and has not been saved to disk since the last make (build).

General Options :  VI Emulation

General Options :  Searching

Ignore case

Turn this option on if you do not want the Search function to match case when searching for a string.

Wrap at EOF

Turn this option on if you want the search to continue at the beginning of the file when it reaches the end of the file.  It will then continue to the starting point of the search.

General Options :  Word Definitions

General Options :  Filenames/Paths

General Options :  Miscellaneous

Beep on error

Turn this option on if you want an audible beep to sound when the Editor encounters an error.

Same-file check on open

Use this option to have the Editor check that a file you are opening is not already open.  You can open multiple copies of the same file, however, the Editor keeps only the last version of the file saved.  To open multiple copies of the same file, you must specify different paths.

Close rotates forward

Turn this option on if you want the Editor to rotate forward through the open files when you close the current file.

File Specific Options

• Source
• Language
• Tabs
• Tags
• Miscellaneous

File Specific Options :  Source

Read entire file

Turn this on if you want the Editor to read the entire file when it opens a new file.  Turn this option off if you want the Editor to load small pieces of the file as needed.

Check read-only flag

Turn this option on if you want files that you open to be read only.  You cannot change or write the files under the same name.

Ignore Ctrl-Z

Turn this option on if you want the Editor to ignore Ctrl-Z as the end of file marker.

CRLF Autodetect

Turn this option on if you want the Editor to detect if the file it is opening has CR and LF at the end of each line.  If it does, it will write the file in the same format.

Write CRLFs

Turn this option on if you want both a CR and an LF at the end of each line.  This is the standard format for DOS files.

Use eight-bit characters

Turn this option on if you want to edit the IBM extended characters, such as line drawing.  If this option is off, you can edit normal text only.

File Specific Options :  Language

File Specific Options :  Tabs

Tab amount

Set the tab width if real tabs has not been set.  Tab amount specifies the number of spaces indented by tab key.

Shiftwidth

Set the shiftwidth value.  The default is four characters.

Real Tabs

Turn Real Tabs on to use the ASCII tab character instead of spaces when you press TAB.  Turn this option off to have tabs replaced with the appropriate number of spaces.

Hard Tabs

Set the width of hard tabs.  The default is eight characters.

Autoindent

Turn on the Autoindent feature.  Each new line then indents to the same level as the previous line.

File Specific Options :  Tags

Tag File

Enter the name of the tag file that contains your ctags.

Ignore Case

Turn this option on, if you want the tag file to ignore the case of tags.

Prompt on multiple tags

Turn this option on, if you want to be prompted when you tag a function that has multiple entries in the tags file.

File Specific Options :  Miscellaneous

Grep extensions

Define the default file extension to grep when you choose fgrep from the right mouse button pop-up menu.

Show matching brackets

Turn this option on for the cursor to flash to the opening brace when you type the closing brace. 

Screen/Window Options

Screen/Window Options :  Editing

Jumpy Scrolling

Turn this option on to scroll two lines at a time instead of one.

Line-based Selection

Turn this option on to select a whole line no matter where you are in the line when you select more than one line.  You can still however, select part of one line.  If this option is off, you can select any part of the first and last line in the block of lines you select.

Paging

Enter the number of lines that you want to overlap when you use the Page Up and Page Down keys.

Screen/Window Options :  Miscellaneous

• Enter your own string to appear at the end of the file.  For example, you may want the word END to appear at the end of the file.
• Save the Editor's screen position when you exit the file.
• Clear messages after the next key is pressed instead of having them remain until the next error message occurs.

Saving the Configuration

Regular Expressions

• forward slash (/) command mode key (search forwards)
• question mark (?) command mode key (search backwards)
• forward slash (/) command line address (search forwards)
• question mark (?) command line address (search backwards)
• substitute command line command
• global command line command
• egrep command line command
• match command line command

• A backslash (\) followed by a single character other than new line matches that character
• The caret (^) matches the beginning of a line
• The dollar sign ($) matches the end of a line
• The dot (.) matches any character
• A single character that does not have any other special meaning matches that character
• A string enclosed in brackets [] matches any single character from the string.  Ranges of ASCII character codes may be abbreviated as in a "a-z0-9".  A ] may occur only as the first character of the string.  You must place a literal - where it cannot be mistaken as a range indicator.  If a caret (^) occurs as the first character inside the brackets, then any characters NOT in the string are matched
• A regular expression followed by an asterisk (*) matches a sequence of 0 or more matches of the regular expression
• A regular expression followed by a plus sign (+) matches one or more matches of the regular expression
• A regular expression followed by a question mark (?) matches zero or one matches of the regular expression
• Two regular expressions concatenated match a match of the first followed by a match of the second
• Two regular expressions separated by an or bar (|) match either a match for the first or a match for the second
• A regular expression enclosed in parentheses matches a match for the regular expression
• The order of precedence of operators at the same parenthesis level is the following:  {}, then *+?, then concatenation, then /.
• All regular expressions following an at sign (@) are treated as case sensitive
• All regular expressions following a tilde (~) are to be treated as case insensitive
• If an exclamation point (!) occurs as the first character in a regular expression, it causes the ignoring of the magic setting; that is, all magic characters are treated as magical.  An exclamation point (!) is treated as a regular character if it occurs anywhere but at the very start of the regular expression.

Regular Expression BNF

reg-exp

{branch}|{branch}|...

branch

{piece}{piece}...

piece

{atom{* or + or ?}}{atom {* or + or ?}}...  *-match 0 or more of the atom; +-match 1 or more of the atom; ?-match a match of the atom, or the null string.

atom

(reg-exp) or range or @ or ^ or $ or \char or char.

range

[{^} char and/or charlo-charhi].  ^ causes negation of range.

.

Match any character.

^

Match start of line.

$

Match end of line.

@

Search with case sensitivity.

~

Search without case sensitivity.

!

If it occurs as the first character in a regular expression, the magic setting is ignored; that is, all magic characters are treated as magical.  !  is treated as a regular character if it occurs anywhere but at the very start of the regular expression.

char

Any character.

\char

Forces \char to be accepted as char (no special meaning) except \t matches a tab character if realtabs is set.

File Matching Regular Expressions

1. A dot (.) specifies an actual dot in the file name.
2. An asterisk (*) is the same as .* (matches 0 or more characters).
3. A question mark (?) is the same as a regular expression dot (.); that is, a question mark matches exactly one character.
4. A caret (^) has no meaning.
5. A dollar sign ($) has no meaning.
6. The backslash (\) has no meaning.  It is used to separate directories.

a*.c

All files that start with a and end in .c.  Therefore, it matches a.c and abc.c

(a|b)*.c

All files that start with an a or a b and end in .c.  Therefore, it matches a.c, abc.c, and bcd.c

*d.c

All files that end in d.c.  Therefore, it matches bcd.c

*

All files.

*.*

All files that have a dot in them.  Therefore, it matches a.c, abc.c, bcd.c, xyz.c

Replacement Strings

&

Replace each instance of & in the replacement string with the entire string of matched characters

\\

Enter a \ in the replacement string

\n

Replace with a new line

\t

Replace with a tab (if realtabs is set)

\<n>

Replace each instance of < n >, where < n > is a digit from 0 to 9, with the n'th sub-expression in the regular expression

\u

Change the next item in the replacement string to upper case

\l

Change the next item in the replacement string to lower case

\U

Change all items following \U in the replacement string with upper case, until \e, or \E is encountered

\L

Change all items following \L in the replacement string with lower case, until \e, or \E is encountered

\e, \E

End the change to upper (\U) or lower case (\L)

\|<n>

Substitute spaces up to column <n>, so that the item that follows occurs at column <n>

\#

Substitute the current line number on which the match occurred.

Controlling Magic Characters

The Open Watcom Resource Editor

• Accelerators
• Bitmaps
• Cursors
• Dialogs
• Icons
• Menus
• Strings

Using the Open Watcom Resource Editor

• Starting the Resource Editor
• Quitting the Resource Editor
• The Resource Editor Menu Bar
• The Resource Editor Toolbar

Starting the Resource Editor

Quitting the Resource Editor

The Resource Editor Menu Bar

File

Open a new or existing resource file, save the current resource file, and exit the Resource Editor

Edit

Access the clipboard functions, delete the selected resource, and set the Resource Editor options

Resource

Open a new resource and work with existing resources

Window

Customize the Resource Editor workspace

Help

Access on-line help information

The Resource Editor Toolbar

CREATE

Create a new resource file.  This is equivalent to the New item in the File menu.

OPEN

Open an existing resource file.  This is equivalent to the Open item in the File menu.

SAVE

Save the resource file.  This is equivalent to the Save item in the File menu.

CUT

Cut the selected resource to the clipboard.  This is equivalent to the Cut item in the Edit menu.

COPY

Copy the selected resource to the clipboard.  This is equivalent to the Copy item in the Edit menu.

PASTE

Paste the resource on the clipboard to the specified resource file.  This is equivalent to the Paste item in the Edit menu.

Working with Resource Files

• Creating a New Resource File
• Opening an Existing Resource File
• Saving a Resource File

Creating a New Resource File with the Resource Editor

Opening an Existing Resource File with the Resource Editor

To open an existing resource file:

(1)

Choose Open from the File menu in the Open Watcom Resource Editor window.
An Open File dialog appears where you select the file you want to open.

(2)

Double click on the desired file
or

Click on the desired file to select it, then click on OK.
The Open File dialog closes and a Resource dialog for the selected resource file appears in the Resource Editor window.   This dialog displays a button representing each type of resource that exists in the resource file.  Clicking on the resource buttons displays a list of the resources of that type in the resource file.

From here, you can perform any of the functions in the section entitled Working with Resources.

Saving a Resource File with the Resource Editor

• Save
• Save As

Important:

You can have several resource files open in the Resource Editor window at one time.  The caption bar of the currently selected resource file appears highlighted.  Only this window is affected when you choose Save or Save As from the File menu.

Resource Editor:  Save

Resource Editor:  Save As

To save a resource file to another file:

(1)

Choose Save As from the File menu in the Open Watcom Resource Editor window to save any changes made to the resource file.
A Save File dialog appears where you specify the file to which you want to save the current resource file.

(2)

Specify the file to which you are saving by selecting an existing file or entering the name of a new file.

(3)

Click on OK when completed.

Figure 75. A Save File message box appears when you attempt to save the current resource file to an existing file.

The dialog closes and the Resource Editor saves the resource file, returning you to the Resource Editor window.

Note:

If you attempt to save the current resource file to an existing file, a Save File window appears informing you that the selected file already exists.  Choosing Yes on this dialog overwrites the selected existing file with the contents of the current resource file.

The dialog closes and the Resource Editor saves the resource file, returning you to the Resource Editor window.

The dialog closes and the Resource Editor saves the resource file, returning you to the Resource Editor window.

Working with Resources

• Creating a New Resource
• Editing an Existing Resource
• Saving a Resource
• Using Shortcuts to Create a Resource
• Deleting a Resource
• Renaming a Resource
• Changing Memory and Load Options

Creating a New Resource

• Accelerator
• Bitmap
• Cursor
• Dialog
• Icon
• Menu
• String

Editing an Existing Resource

To edit an existing resource:

(1)

Select the desired resource file on the Resource Editor window by selecting the appropriate Resource window.
This is the resource file whose resource you want to edit.

(2)

Select the resource type by selecting on the appropriate line in the type listbox.
A list of all resources of the selected type for this resource file appears in the Resource listbox.


Figure 76. Each resource type contained in the resource file appears in the Types listbox.

(3)

Double click on the resource you want to edit
or

Select the desired resource, then choose Edit from the Resource menu
or

Select the desired resource, then press ENTER.
The appropriate editor for the selected resource opens on top of the Resource Editor window.  Use this editor to make changes to the selected resource.

(4)

Refer to the appropriate editor section in this guide for information on using the editor to edit the selected resource.

Saving a Resource

(1)

Select the desired resource.
You can select only one resource at a time and the selected resource appears highlighted.  This is the resource you want to save to another resource file.

(2)

Choose Save As from the Resource menu.
A Save Resource dialog appears where you specify the resource file to which you are saving the selected resource.

(3)

Specify the file to which you are saving by selecting an existing file or entering the name of a new file.

(4)

Click on OK when completed.
How you proceed from here depends on whether you are saving the resource to a new or existing resource file.

Saving to a New Resource File

Saving to an Existing Resource File

To cancel the save:

(1)

Choose No
The Save Resource dialog reappears.

(2)

Select another file to which you can save the selected resource
or

Cancel the save function
The dialog closes and the Resource Editor returns you to the Resource Editor window.

To replace the existing file:

(1)

Choose Yes to replace the contents of the existing resource file with the selected resource.
The dialog closes and the Resource Editor saves the resource file, returning you to the Resource Editor window.

Copying Into an Existing Resource File

To copy a resource to another resource file:

(1)

Select the desired resource.
The selected resource appears highlighted in the Resource window.  This is the resource you want to copy to another resource file.  Copying a resource does not remove it from its current resource file.

(2)

Choose Copy To from the Resource menu.
A Copy Resource Into File dialog appears where you select an existing resource file to which you want to copy the selected resource.


Figure 78. In the Copy Resource Into File dialog, select the resource file to which you want to copy the selected resource.

(3)

Double click on the desired resource file
or

Click on the desired resource file to select it, then click on OK.
The Resource Editor copies the resource to the selected resource file.  The dialog closes and you return to the Open Watcom Resource Editor window.

Note:

If the resource file to which you copied the selected resource is open on the Resource Editor window, the copied resource will not appear.  To view the updated resource file, simply open that resource file again.  The copied resource now appears in the Resource window for the resource file.

Using Shortcuts to Create a Resource

• Cut
• Copy
• Paste

Cut

(1)

Select the resource you want to cut to the clipboard.
The selected resource appears highlighted in the Resource window.

(2)

Choose Cut from the Edit menu of the Resource Editor window.
The Resource Editor removes the selected resource from the Resource window and places it on the clipboard.

Copy

(1)

Select the resource you want to copy to the clipboard.
The selected resource appears highlighted in the Resource window.

(2)

Choose Copy from the Edit menu of the Resource Editor window.
The Resource Editor copies the selected resource to the clipboard.

Paste

(1)

Select the resource file in which you want to paste the resource that is currently on the clipboard.

(2)

Choose Paste from the Edit menu of the Resource Editor window.
The Resource Editor places the resource from the clipboard into the current resource file in the Resource Editor window.

Deleting a Resource

To delete an object from a resource file:

(1)

Select the resource you want to delete from a resource file on the Resource Editor window.
The selected resource appears highlighted in the Resource window.

(2)

Choose Delete from the Edit menu.
or

Press the Delete key on the keyboard.
A Delete Resource dialog box appears displaying the name of the resource chosen to delete.


Figure 79. The Delete Resource dialog prompts you to verify that you want to delete the resource indicated.

(3)

Click on OK to delete the selected resource.
The Delete Resource dialog closes and the Resource Editor removes the selected dialog from the Resource window.

Note:

Choosing Cancel on the Delete Resource dialog cancels the deletion and returns you to the Resource Editor window.

Renaming a Resource

To rename a resource:

(1)

Select the resource you want to rename.

(2)

Choose Rename from the Resource menu in the Open Watcom Resource Editor window.
A Rename Resource dialog appears containing two fields:

• Old Name
• New Name

Figure 80. In the Rename Resource dialog, you enter the new name of the selected resource.

(3)

Enter the new name for the resource in the New Name field.

(4)

Click on OK to close the Rename Resource dialog.
The dialog closes and the new resource name appears in the Resource window.  The Resource Editor automatically reorders the resources into alphabetical order.

Resource Editor:  Changing Memory Options

To set the memory options for a resource:

(1)

Select the resource whose memory options you want to change.

(2)

Choose Memory Flags from the Resource menu in the Open Watcom Resource Editor window.
The Memory Options dialog opens displaying the current memory options for the selected resource.


Figure 81. In the Memory Options dialog, you change the memory options for the selected resource.

(3)

Select the required flags in the Memory Options and Load Options sections of the dialog by clicking on the check box or radio button beside the appropriate field.
Following is a description of each option.

Moveable

Selecting this option marks this resource to be stored in moveable memory when it is loaded by an application.

Discardable

Selecting this option marks this resource to be stored in discardable memory when it is loaded by an application.

Pure

When marked as Pure, Windows does not allow the memory into which the resource is loaded to be modified.

Preload

All resources marked as Preload are loaded when the application for which the resource is created is loaded.

LoadOnCall

Resources marked as LoadOnCall are loaded only when an application issues a call to load them.

The Open Watcom Accelerator Editor

Using the Accelerator Editor

• Starting the Accelerator Editor
• Quitting the Accelerator Editor
• The Accelerator Editor Menu Bar
• The Accelerator Toolbar

Starting the Accelerator Editor

Creating a New Accelerator Table

To create a new accelerator table:

(1)

Double click on the Resource Editor icon in your Windows Program Manager.
The Open Watcom Resource Editor window opens.

(2)

Open a new or existing resource file.

(3)

Choose Accelerator from the cascading menu that appears when you choose New from the Resouce menu.
The Open Watcom Accelerator Editor window opens and displays an empty accelerator item list.

Opening an Existing Accelerator Table

To open an existing accelerator table:

(1)

Double click on the Resource Editor icon in your Windows Program Manager.
The Open Watcom Resource Editor window opens.

(2)

Open an existing resource file.
The Resource window for the existing resource file displays buttons representing each existing resource type.

(3)

Select the accelerator table button to view the existing accelerator tables.
or

Choose Accelerator from the cascading menu that appears when you choose View from the Resource menu.
The Accelerator Resources list appears revealing all accelerator tables in this resource file.

(4)

Double click on the existing accelerator table you want to open.
or

Click on the desired accelerator table to select it, then press ENTER
or

Click on the desired accelerator table to select it and choose Edit from the Resource menu on the Open Watcom Resource Editor window.
The Open Watcom Accelerator Editor window opens and displays the existing accelerator items for the selected accelerator table.

Quitting the Accelerator Editor

The Accelerator Editor Menu Bar

File

Clear and save the accelerator table, and exit the Accelerator Editor

Edit

Access the clipboard functions, hide or show the toolbar, and delete an accelerator item

Resource

Rename the accelerator table and change its memory flags

Accelerator

Insert and edit accelerator items

Help

Access on-line help information

The Accelerator Editor Toolbar

CLEAR

Clear the accelerator table.  This is equivalent to the Clear item in the File menu.

UPDATE

Update the resource file with this accelerator table.  This is equivalent to the Update item in the File menu.

CUT

Cut the current accelerator table to the clipboard.  This is equivalent to the Cut item in the Edit menu.

COPY

Copy the current accelerator table to the clipboard.  This is equivalent to the Copy item in the Edit menu.

PASTE

Paste the accelerator table from the clipboard to the current accelerator table.  This is equivalent to the Paste item in the Edit menu.

INSERT

Insert the new accelerator item into the accelerator table.  This is equivalent to the Insert New Item item in the Accelerator menu.

DELETE

Delete the selected accelerator item from the accelerator table.  This is equivalent to the Delete item in the Edit menu.

KEY VALUE

Set the accelerator item's key value using the keyboard.  This is equivalent to the Key Value item in the Accelerator menu.

Using the Accelerator Editor Window

• Resource Name Field
• Attributes Area
• Accelerator Item List
• Action Buttons

Accelerator Editor:  Resource Name Field

Accelerator Editor:  Attributes Area

Key

The Key field contains the key value used to activate the menu item.

Menu Item ID

The two Menu Item ID fields contain:

• the number of the menu item that is activated by the entry in the Key field.
• the symbol information for the selected menu item.

Key Type

This section indicates if the key value is in ASCII or virtual key.

Modifiers

An X appears in the check box for the modifiers that are part of the accelerator key value.  The available modifier keys are:

• Alt
• Control
• Shift

Accelerator Editor:  Accelerator Item List

Accelerator Editor:  Action Buttons

Accelerator Functions

• Adding a New Accelerator Item
• Changing an Existing Accelerator Item
• Deleting Accelerator Items
• Renaming an Accelerator Table
• Saving Accelerator Items
• Using Shortcuts to Create Accelerator Tables
• Changing Memory Options

Adding a New Accelerator Item

To add a new accelerator item:

(1)

Position the cursor in the Key field.

(2)

Enter the desired key value that will activate the menu item.
You can enter a single key, such as a letter or number, or a key sequence.  A key sequence may be made up of a modifier and a key, such as ^k for Ctrl+k.

(3)

Enter a symbol or numeric identifier for the menu item that is activated by the entry in the Key field.
The symbol or numeric identifier you enter here is the identifier associated with the menu item.  This relationship is defined in the Menu Editor.  If you do not know the desired menu item identifier, open the appropriate menu and look up the identifier.  It is not possible for the Accelerator Editor to get this information for you.

(4)

Specify ASCII or Virtual Key in the Key Type section of the window.

ASCII Keys

When the Key Type specified is ASCII, keys you press appear as characters, such as a, B, 2, or $.  In the Key field, the ASCII characters are surrounded by quotation marks.  For example, c appears as "c" and Ctrl+C appears as "^C".  When using ASCII characters as accelerators, you may combine them with the Ctrl key to form key sequences, such as Ctrl+X or Ctrl+P.  There is no symbol to represent the Shift key in ASCII.  Applying the Shift key with an ASCII character results in an upper case character in the Key field.  For example, Shift+d appears as "D".

Virtual Keys

When the Key Type specified is Virtual Key, you enter the standard Windows identifier for the desired key.  For example, the Windows identifier for the Home key is VK_HOME.  The header file WINDOWS.H defines these identifiers.  To avoid looking up these identifiers yourself, use the Key Value function explained in the section Editing the Key Value.   To specify whether the Alt, Ctrl, or Shift keys must be pressed with another key to form a key sequence, mark the appropriate check box in the Modifiers section of the attributes area.

(5)

Select the desired modifiers in the Modifiers section.
Modifiers are flags indicating keys that you must press in addition to the specified key value to activate the menu item.   When the ASCII option is selected, the Control and Shift modifiers are not available.

(6)

Press the Insert action button
or

Choose Insert New Item from the Accelerator menu.
or

Select the Insert New Item button on the toolbar.
The Accelerator Editor adds the new accelerator item to the accelerator table.  When accelerator items exist in the accelerator table, one item is always selected.  Choosing the Insert New Item menu item or button positions the new accelerator item directly after the selected accelerator item in the list.

Changing an Existing Accelerator Item

To modify an existing accelerator item:

(1)

Click the accelerator item you want to modify.
The selected accelerator item appears highlighted in the accelerator item list and the accelerator item details appear in the attributes area of the window.

(2)

Enter the new accelerator item details in the attributes area.

(3)

Press the Change action button
These actions update the selected accelerator item with the modified accelerator item attributes.

Editing the Key Value

To use the Key Value function:

(1)

Choose the accelerator table you want to work with from the Resource window on the Open Watcom Resource Editor window.
The Accelerator Editor window appears displaying all of the accelerator items for the selected accelerator table.

(2)

Click on the accelerator item you want to modify.
The selected accelerator item appears highlighted in the accelerator table and the accelerator item details appear in the attributes area of the window.

(3)

Choose Select Key Value from the Accelerator menu
or

Select the Key Value button on the toolbar.
The accelerator table disappears and instructions for using the Key Value function appear in its place.

(4)

Press the desired key on the keyboard.
This is the key that you want to activate the menu item specified in the Menu Item field.  The instructions disappear from the window revealing the modified accelerator table.  The updated accelerator item is still selected.

(5)

Change modifiers, if required.

Deleting Accelerator Items

• Delete
• Clear

Deleting an Accelerator Item

(1)

Select the accelerator item you want to delete from the accelerator item list by clicking on it.
The selected accelerator item is highlighted.

(2)

Choose Delete from the Edit menu
or

Select the Delete button from the toolbar.
The Accelerator Editor removes the selected item from the accelerator item list.

(3)

Choose Update from the File menu to save the accelerator table changes.

Deleting All Accelerator Items

(1)

Choose Clear from the File menu
or

Select the Clear button from the toolbar.
A message box appears prompting you to verify that you want to clear all accelerator items from the current accelerator table.

(2)

Choose Yes or No to continue.
Choosing Yes removes all accelerator items from the current accelerator table.  The accelerator item list is empty.   Choosing No cancels the operation.

Renaming an Accelerator Table

To rename an accelerator table:

(1)

Choose Rename from the Resource menu on the Open Watcom Accelerator Editor window.
or

Double click or right click on the Resource Name field.
A Rename Resource dialog box appears containing two fields:

• Old Name
• New Name

Figure 90. In the Rename Resource dialog, you enter the new name of the accelerator table.

(2)

Enter the desired accelerator table name in the New Name field.

(3)

Click on OK to close the Rename Resource dialog.
The dialog closes and the new accelerator table name appears in the Resource Name field.

Saving Accelerator Items

• Update
• Save As
• Copy To

Accelerator Editor:  Update

Accelerator Editor:  Save As

Important:

If the resource file to which you are saving the accelerator table already contains resources, the existing resources will be discarded and replaced with the accelerator table you are saving.

Accelerator Editor:  Copy To