The breath and depth the Watcom products is large. It's difficult to get a handle on it all. For example:
- Where do I start?
- What elements of the installation should I learn right away?
- What elements should I ignore, or perhaps delay until later?
- What is the best way to organize the reference materials:
- Hard copies of the Watcom online books, or portions of them?
- Other references that would be helpful?
There is no one set of correct answers to the above. The best set of answers depends on you and what you want to accomplish with the Watcom products
Here are some suggestions that might help:
- Other reference sources:
- Teach Yourself C in 21 Days, Peter Aitken and Bradley L. Jones, Sams Publishing, 2000
- The Design of OS/2, H.M. Deitel and M.S. Kogan; Addison-Wesley Publishing Company, 1992
- OS/2 Warp Unleashed, Deluxe Edition, David Moskowitz and David Kerr, et al; Sams Publishing, 1995
- Writing OS/2 2.1 Device Drivers in C, Second Edition, Steven J. Mastrianni, Van Nostrand Reinhold, 1993
- Watcom reference sources:
- Watcom C/C++ Master Index (provides a quick overview of several of the Watcom online documentation, or manuals):
- Watcom C/C++ User's Guide
- Watcom C/C++ Programmer's Guide
- Watcom C/C++ Tools User's Guide
- Watcom Linker User's Guide
- Watcom Debugger User's Guide
- Watcom C Language Reference
- Watcom C Library Reference
- Watcom C++ Class Library Reference
- Watcom C/C++ Getting Started:
- Introduction to Watcom C/C++
- Installation of Watcom C/C++
- Hands on introduction to Watcom C/C++ (a tutorial)
- Watcom C Language Reference
- A description of the C programing language as implemented by the Watcom C/16 and C/32 compilers
- Intended to be an easy-to-read description of the C language
- Watcom C Library Reference:
- Introduces the individual functions and macros that comprise the Watcom C library
- The C library provides much of the power usually associated with the C language
- Library functions are called as if they had been defined within the program. When the program is linked, the code for these routines is incorporated into the program by the linker
- Watcom C/C++ Programmer's Guide:
- Contains guides to application development for several environments, including 16-bit DOS, 32-bit extended DOS, Windows 3.x, 32-bit extended Windows 3.x, Windows NT, OS/2, AutoCAD and Novell NLMs
- Describes mixed language (C, FORTRAN) application development
- Tutorials:
- The Watcom C/C++ Tutorial in the Watcom C/C++ Getting Started:
- Test out the new graphical tools (Watcom IDE, Debugger and Browser) in version 11 using an existing set of C source files
- Create a project in the Watcom Integrated Environment (IDE)
- Perform several tasks, such as: adding multiple targets, making targets, executing the program, debugging the program and using the browser
- 16-bit or 32-bit OS/2 sample application in the Watcom C/C++ Programmer's Guide:
- Compile and run each program from the command line and from the IDE
- Verify your use of the commandline and the IDE
- Verify the proper installation and use of OS/2 16-bit and 32-bit Toolkit library functions on your system
- Learn how to use the Watcom IDE, Watcom Debugger and the OS/2 Enhanced Editor (EPM) to create and complete your C/C++ projects:
- The following example project uses sample C source code to demonstrate linking, compiling and debugging in the Watcom graphical environment:
- The sample code is located in the "Sample_Project" folder inside the "SCOUG_Presentation" folder
- The code creates an OS/2 commandline executable, which reads a selected text file into memory, line by line
- The source code observes the modularity programming concept espoused in C. It consists of a main module, a secondary module and a header file:
- The main module calls the text file read function, "FileRead". After "FileRead" performs its task the main module takes the results from memory and writes it to a new file
- The secondary module defines the function, "FileRead"
- The header file contains linked source code support for "FileRead"
- Link, compile and edit the source code, using the IDE and EPM:
- Refer also to the tutorial in Watcom C/C++ Getting Started
- Start the IDE
- Start the project, using the "File" main menu. Select "New Project...". In the dialog that results:
- Switch to the directory, ...,\Watcom\SCOUG_Presentation\Sample_Project
- Under the "Open filename" field write the name of the new project as "fileread.wpj"
- Click the "Open" button
The IDE creates a project file, fileread.wpj, which manages our project. It contains the names of all of the target files (*.tgt) related to the project and housekeeping information about the project and the current IDE session
- The "New Target" dialog pops up:
- Select, or write in, "fileread" under the "New Target" field
- Select "OS/2 - 32 bit" under the "Target Environment" field
- Under the "Image Type" field, select "Executable [.exe]"
- Click the "OK" button
The IDE creates a target file, fileread.tgt, which describes the target. It contains the name and type of the target executable, a reference to a rule describing how to build the target, and a list of relevant switches the rule uses. In addition, it contains the names of all of the source files used to construct the target program, references to similar rules for compiling them and relevant switches
- In the IDE main window a "Source files:" subwindow will now appear. Place the names of the main and secondary module files in this subwindow. Do so by using the "Sources" main menu. Select "New Source...". In the dialog that results:
- Select "Browse". In the resulting dialog change "*.cpp" to "*.c" in the "Open filename" field
- The "Directory" field probably points to the "...,\Sample_Project" folder. If not, change it to point there
- The "fileread.c" and "filesvc.c" files will now be visible in the "File:" field. Select both files, the main module, "fileread.c", first, and the secondary module, "filesvc.c", next
- Use the EPM to edit the source code in the "fileread.c" file to reflect the correct path to "Watcom\SCOUG_Presentation\Sample_Project" on your system:
- Do so by highlighting "fileread.c" in the "Source files" subwindow. Then, click on the "Edit the selected source file" icon just below the IDE main menu. Alternatively, double left mouse click on "fileread.c" in the "Source files" subwindow
- The EPM will open with "fileread.c" loaded. Edit lines 10 and 11 in this file to reflect the path to the "Watcom\SCOUG_Presentation\Sample_Project\" folder on your system
- In both lines change "C:\\" to wherever the folder resides. Use 2 backward slashes ("\\") to separate the drive and folder names (required in C/C++)
- In line 10 the variable, "ReadFileName", holds the path to the ASCII text that will be read by the executable program that we are creating
- Similarly, in line 11 "WriteFileName" holds the path to the ASCII file that will be created by the executable. It will be an exact copy of the file that is read, proving that the executable works
- Attempt to link and compile the source code (make the target, or create the executable):
- Make sure that "fileread.c" is highlighted in the "Source files" subwindow
- Click the "Make all targets in the project"" icon just below the IDE main menu. Alternatively, select "Targets" and then "Make" from the IDE main menu
- The "IDE Log" subwindow will now appear below the "Source files" subwindow
- The log indicates that an error is present on line 10 of "fileread.c". Because of the error the make execution is terminated
- Right mouse click on the line in the log subwindow that indicates an error on line 10 of "fileread.c". A pop-up submenu opens for the log. Select "Help on message" to show context-sensitive online help for the error
- Actually, the error is on line 9, because the ";" is missing at the end of that line. Often, the "IDE Log" will indicate an error on a particular line, when it is really on the line directly above
- Use the EPM to correct the error and save the correction. Double left mouse click on the error line in the log to open the EPM. Alternatively, right mouse click on that line to open the log pop-up submenu. Select "Edit file".
The EPM opens with the cursor on line 10 of "fileread.c" and with that line highlighted in red
- Attempt to link and compile the source code again:
- The "IDE Log" now indicates that an error exists on line 161 of "filesvc.c". Right mouse click on the error line statement in the "IDE Log" and select "Help on message" to show help on the error
- The error is caused by the fact that the variable address, "ReturnResult" (actually, it's a structure address), is defined as a local (and automatic) variable, not a static one. As such, it is destroyed after the "FileRead" function terminates. Therefore, that address cannot be returned to the calling module, "fileread.c"
- To fix this problem we must declare the "ReturnResult" structure outside of the "FileRead" function so that it remains in effect after that function terminates
- Move the "ReturnResult" structure declaration from line 20 to just after line 10 (make it the new line 11). Use EPM to edit and save the result
- Link and compile the source code again. This time the "IDE Log" indicates no errors
- Run the created executable file. Click on the "Run the current target" icon just below the IDE main menu. The file runs without any problems. It creates the "ReadTestResults.TXT" file in our "Sample_Project" folder. It is an exact copy of the "CSAMP.TEX" file in our folder, proving that the executable works
- Use the Debugger to debug the source code:
- Even though the source code links and compiles without error, the resulting executable may not run as planned (for example, if you try to read a binary file)
- Configure the IDE to enable all debugging information. Do so by selecting "Targets", "Target Options" and "Use Development Switches" from the IDE main menu. Link and recompile the code under the development switches
- Open the Debugger in the IDE. Click on the "Debug the current target" icon just below the IDE main menu. Alternatively, in the main menu select "Targets" then "Debug"
- After it opens, resize the Debugger window to your liking. Then, select "File", "Save Setup...," and "OK" from the Debugger main menu to save it
- The Debugger has 4 subwindows. Normally they are as follows:
- Source (displays the source code of a given C/C++ module)
- Locals (displays the variables local to the currently executing function)
- Watches (add/delete variables in this window; evaluate complex expressions)
- Modules (switch to the code of the selected module)
- Change the focus to any 1 of the 4 subwindows by clicking the mouse on the blue title bar at the top of the desired subwindow. Alternatively, choose the "Window" main menu and select the desired window in the bottom half of that drop down list
- Change purpose of the "Sources" subwindow. Select "Window" from the Debugger main menu:
- Select "Assembly" from the bottom half of the drop down list
- The "Source" subwindow now becomes the "Assembly" subwindow
- Go to the "Assembly" subwindow. Move it aside, slightly. The "Source" subwindow is now visible under it
- Arrange the "Source" and "Assembly" subwindows side-by-side, or one under the other
- If the "Source" and "Assembly" subwindows are both visible, they will always be positioned at the same point in the code. If you scroll one, the other will follow
- In the same fashion, use the "Window" main menu to change the "Locals" subwindow to the "CPU Registers" subwindow. Arrange them side-by-side, or one under the other