Building libraries using Open Watcom

Being able to bundle blocks of your code (and data to some extent) into library files is quite a productive step forward when developing applications. Being able to port these pieces around means a higher level of code-reuse, and a less number of times you’ll spend re-writing the same stuff.

In today’s post, I’ll take you through creating a very minimal library. We’ll create a library module from this code and I’ll also show you how to consume it.

Howdy!

Our example library will expose one function, called greet. greet will take in a person’s name and will print a greeting to the console. Here’s the header:

/* greeter.h */

#ifndef __greeter_h_
#define __greeter_h_

#include <stdio.h>

void greet(const char *name);

#endif 

The implementation is basic. It doesn’t even really matter, but is included for completeness:

/* greeter.c */

#include "greeter.h"

void greet(const char *name) {
  printf("Greetings, %s!", name);
}

Make me a library

Making a library is all about compiling your code to produce object files and then bundling your object files into a library file. So, the first step is to compile greeting.c into an object file:

C:\SRC> wcc386 greeter.c

After this, you’ll now have GREETER.OBJ in your project folder. You can turn this into a library with the following:

C:\SRC> wlib greeter +greeter

The command itself says invoke wlib to create (or modify) a library called greeter (the .lib extension is handled for us). Finally the +greeter says that we want to add greeter.obj into the library. We’ll now have a .LIB file that we can link against.

Consuming the library

Writing code that actually uses the library is as easy as including the header and calling functions. Here’s a test:

/* test.c */

#include "greeter.h"

int main(int argc, char *argv[]) {
  greet("Joe");
  return 0;
}

Converting this into a callable executable is achieved with `wcl386’.

C:\SRC> wcl386 test.c greeter.lib

That’s all there is to it.

32bit DOS Development with Open Watcom

The Watcom Compiler is an open source C & C++ compiler that has a very successful history when it was discovered that the DOOM developers were using it. That was a very long time ago, but that shouldn’t stop us having a go!

Installation

I’ve grabbed the dos bundle from the Open Watcom FTP site and installed it into DosBox. The only problem with this setup, it that I much prefer to use a text editor that’s outside of the DOS environment (like emacs/sublime, etc.) DosBox sometimes has a bit of difficulty picking up file system changes that have been mounted in.

Shift + Ctrl + F4 (documented as just Ctrl + F4) forces DosBox to refresh its mounts.

Very handy.

The Tools

There are a bucket of binaries that are bundled with the installation.

For convenience, we’ll use wcl386.exe as this will perform the compilation and linking step in one for us.

Compiling and Linking

Prior to compilation and linking, things will go a lot smoother if you’ve prepared your environment variables correctly.

SET PATH C:\WATCOM\BINW;%PATH%;
SET INCLUDE=C:\WATCOM\H;
SET WATCOM=C:\WATCOM
SET EDPATH=C:\WATCOM\EDDAT
SET WIPFC=C:\WATCOM\WIPFC

Open up your favorite editor and create a hello world application, called hello.cpp.

#include <stdio.h>

int main(int argc, char *argv[]) {
  printf("Hello, world!\n");
  return 0;
}

Now build it with wcl386.exe:

C:\SRC> wcl386 hello.cpp
Open Watcom C/C++32 Compile and Link Utility Version 1.9
Portions Copyright (c) 1988-2002 Sybase, Inc. All Rights Reserved.
Source code is available under the Sybase Open Watcom Public License.
See http://www.openwatcom.org/ for details.
  wpp386 HELLO.CPP 
DOS/4GW Protected Mode Run-time  Version 1.97
Copyright (c) Rational Systems, Inc. 1990-1994 
Open Watcom C++32 Optimizing Compiler Version 1.9
Portions Copyright (c) 1989-2002 Sybase, Inc. All Rights Reserved.
Source code is available under the Sybase Open Watcom Public License.
See http://www.openwatcom.org/ for details.
HELLO.CPP: 7 lines, included 1160, no warnings, no errors
  wlink @__wcl__.lnk
DOS/4GW Protected Mode Run-time  Version 1.97
Copyright (c) Rational Systems, Inc. 1990-1994 
Open Watcom Linker Version 1.9
Portions Copyright (c) 1985-2002 Sybase, Inc. All Rights Reserved.
Source code is available under the Sybase Open Watcom Public License.
See http://www.openwatcom.org/ for details.
loading object files
searching libraries
creating a DOS/4G executable

We can now run our application:

C:\SRC> hello.exe
DOS/4GW Protected Mode Run-time  Version 1.97
Copyright (c) Rational Systems, Inc. 1990-1994 
Hello, world

What is DOS/4GW?

To a lot of us, the DOS/4GW is a very familiar banner that we saw when we’d fire up one of our favorite games. But, what is it?

Wikipedia’s article defines its role pretty well:

DOS/4G is a 32-bit DOS extender developed by Rational Systems (now Tenberry Software). It allows DOS programs to eliminate the 640 KB conventional memory limit by addressing up to 64 MB of extended memory on Intel 80386 and above machines.

It’s the resident binary that gets packaged with your compiled application that facilitates access to the computers’ full array of resources. Without it, you’d be stuck with what DOS provides you by default.

Conclusion

Well, it’s always nice to go over this old stuff. In my next posts, I’ll cover inline assembly and mode 13/x to get a head start on writing DOS games in the 90’s!

Using FreeTDS to connect to MSSQL

In today’s post, I’ll outline the steps required to connect to a Microsoft Sql Server database from within an Ubuntu Linux environment using FreeTDS and ODBC.

Get the software

Using apt-get, we can satisfy all of the system-level requirements (libraries):

sudo apt-get install freetds-dev freetds-bin unixodbc-dev tdsodbc

FreeTDS now needs to be defined as a driver in the /etc/odbcinst.ini file.

[FreeTDS]
Description=FreeTDS Driver
Driver=/usr/lib/odbc/libtdsodbc.so
Setup=/usr/lib/odbc/libtdsS.so

Hitting the can

Now that we’ve got a driver up and running, we can use a library like sqlalchemy to run some queries. Before we can do that though, we need to install python’s odbc bindings pyodbc.

pip install pyodbc sqlalchemy

We can now start running some queries.

import urllib
import sqlalchemy as sa

cstr = urllib.quote_plus('DRIVER=FreeTDS;SERVER=host;PORT=1433;DATABASE=db;UID=user;PWD=password;TDS_Version=8.0;')

engine = sa.create_engine('mssql+pyodbc:///?odbc_connect=' + cstr)
    
for row in engine.execute('SELECT 1 AS Test;'):
    print row.Test

Using resource files in your masm projects

In a previous post we built a boilerplate program that we can start to work with. For today’s post, we’re going to go through the development of a resource file that you can incorporate into your own projects.

What are resource files?

You can use resource files to organise your external resources (images, audio, text, etc.) into a compilable (and ultimately linkable) resource. The items that you add to your resource file are then statically added to your resulting executable, ready for you to reference.

From the Microsoft site:

You should place every element of the user interface that needs to be localized in a Windows resource file, including pictures, strings, messages, menus, dialog boxes, and version information. The table below lists the individual resource elements defined by Windows.

What does a resource file look like?

The .RC file itself is just text. There are IDs that are defined throughout that you can create symbolic constants for in your code, just so you’re not doing so much “magic number” work. Here’s a simple menu:

600 MENUEX MOVEABLE IMPURE LOADONCALL DISCARDABLE
BEGIN
    POPUP "&File", , , 0
    BEGIN
        MENUITEM "&Exit", 1000
    END
    POPUP "&Help", , , 0
    BEGIN
        MENUITEM "&About", 1900
    END
END

600 in this example is the ID of the menu. Referencing this menu in your code is as simple as passing 600 to the menu name parameter of a LoadMenu call:

invoke LoadMenu, hInstance, 600
invoke SetMenu, hWnd, eax

How do I compile one?

rc.exe is the resource compiler that comes along with masm32. You give it your resource script and it’ll give you back a compiled .RES file.

rc /v rsrc.rc

You then take the .RES file that was output; in this case it was rsrc.res and feed it into another utility cvtres.exe.

cvtres /machine:ix86 rsrc.res

This utility converts your compiled .RES file into object code. It produces you an .OBJ file that you can then link into your exe.

Windows programs with masm32

In a previous post I wrote about the basics of getting a program written and compiled using masm32 for the windows platform. In today’s post, I’m going to walkthrough the basic anatomy of a windows program that play the key roles in your application.

This information is language agnostic. It’s standard windows programming knowledge that I’ll present in the form of assembly programming with masm32. By the end of this blog post, you’ll have a good starting point (in boilerplate code) for any program that you want to write with masm32.

The basic pieces

In any windows program (using the Win32 API) there are some basic pieces that you’ll see most of the time.

• Main entry point (WinMain)
• Window creation
• Window handler procedure (WNDPROC)
• Message pump

These basic building blocks that you’ll see in just about all windows applications.

WinMain

This is your application’s main entry point. It’s analogous to the main function that you use when writing applicatioons in C/C++. From Microsoft’s site:

The user-provided entry point for a graphical Windows-based application.

Its function signature takes the following form:

int CALLBACK WinMain(
  _In_ HINSTANCE hInstance,
  _In_ HINSTANCE hPrevInstance,
  _In_ LPSTR     lpCmdLine,
  _In_ int       nCmdShow
);

This definition needs to be translated from C into assembly language. The HINSTANCE, LPSTR and int data types all reduce down to DWORD easily, so:

WinMain proc 	hInst 		:dword, 
				hPrevInst 	:dword,
				szCmdLine 	:dword,
				nShowCmd 	:dword

Being at the assembly layer, we’re exposed a little earlier in the process than what WinMain affords us, so we have extra work to do in terms of getting our application running. We as the implementers of the program need to invoke WinMain directly as this is not done for us.

invoke 	GetModuleHandle, NULL
mov		hInstance, eax

invoke	GetCommandLine
mov		lpszCmdLine, eax

invoke 	WinMain, hInstance, NULL, lpszCmdLine, SW_SHOWDEFAULT
invoke	ExitProcess, eax

GetModuleHandle allows us to fill the hInstance parameter and GetCommandLine gives us lpszCmdLine. hPrevInstance, according to the documentation is always NULL and nShowCmd is an SW_ series value that controls how our main application window is shown.

Window creation

The creation of a window is broken down into a few smaller steps:

• Register a window class
• Create the window
• Show the window

Registering a window class is just filling out the WNDCLASSEX structure and calling RegisterClassEx. Registering a windows class establishes base or common attributes about a window that you can re-use in subsequent calls to CreateWindow.

local 	wc 		:WNDCLASSEX
local 	msg 	:MSG
local 	hWnd 	:HWND

szText	szClassName, "BasicWindow"
szText	szWindowTitle, "First Window"

mov		wc.cbSize, sizeof WNDCLASSEX
mov		wc.style, CS_HREDRAW or CS_VREDRAW or CS_BYTEALIGNWINDOW
mov 	wc.lpfnWndProc, WndProc
mov 	wc.cbClsExtra, NULL
mov		wc.cbWndExtra, NULL

push	hInst
pop 	wc.hInstance

mov		wc.hbrBackground, COLOR_BTNFACE + 1
mov		wc.lpszMenuName, NULL
mov 	wc.lpszClassName, offset szClassName

invoke	LoadIcon, hInst, IDI_APPLICATION
mov		wc.hIcon, eax
mov		wc.hIconSm, eax

invoke	LoadCursor, hInst, IDC_ARROW
mov		wc.hCursor, eax

invoke	RegisterClassEx, addr wc

The macro szText is setup to allow you to ad-hoc define string variables where ever you need to. The rest of this is mainly filling out the structure and finally registering it. Setting lpfnWndProc has special significance to us here as we’ll go on to describe WNDPROC and its role in the application.

WindowProc callback function

When an application receives messages from the operating system, it handles this information through the window procedure. The window procedure interface is defined as:

LRESULT CALLBACK WindowProc(
  _In_ HWND   hwnd,
  _In_ UINT   uMsg,
  _In_ WPARAM wParam,
  _In_ LPARAM lParam
);

Again, translating this into assembly:

WndProc proc 	hWin 	:dword,
				uMsg 	:dword,
				wParam 	:dword,
				lParam 	:dword

The message pump

Finally, the thing that’s keeping our application alive is the message pump. It’s a loop of GetMessage, TranslateMessage and DispatchMessage.

MessagePump:

	invoke 	GetMessage, addr msg, NULL, 0, 0

	cmp 	eax, 0
	je 		MessagePumpEnd

	invoke	TranslateMessage, addr msg
	invoke	DispatchMessage, addr msg

	jmp 	MessagePump

MessagePumpEnd:

All together now

The following gist is all of the pieces assembled in a basic application that’s runnable (once assembled and linked).