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).

Windows Development with NASM

In this post, I’ll walk through the steps required to bootstrap your development experience against the Win32 API using the Netwide Assembler.

Prerequisites

Before starting, you’ll need some software. I’ve used the following software set, however you can use any linker and resource compiler that you like.

• Nasm
• ALink
• Gorc
• Win32 include file

You’ll use Nasm to reduce your assembly source code into COFF object files. Gorc will take your resource scripts and produce linkable object files from these. Finally, ALink will bind all of your object files into a windows executable.

Finally, you’re going to need a copy of the include file for the Win32 API. The API itself is huge; the number of constants and structures is mind boggling. The link above handles all of these for you.

Test program

Probably the easiest thing to accomplish, is showing a message box. You need to show the message box and then return control back to Windows. You do this with calls to MessageBoxA and ExitProcess. The “A” in MessageBoxA as we’re not dealing with the wide-char version of these functions.

Here’s the code.

%include "win32n.inc"

extern MessageBoxA
import MessageBoxA user32.dll

extern ExitProcess
import ExitProcess kernel32.dll

segment .data USE32

	title	db "A message for you", 0
	message db "This is your first message", 0

segment	.bss USE32

segment .code USE32

..start:

	; show the message box
	push MB_OK
	push title
	push message
	push 0
	call [MessageBoxA]

	; return control back to windows
	push 0
	call [ExitProcess]

Functions are imported from the api using import, and are called in a very assembler-traditional fashion here. Taking a look at the definition for the MessageBox function, we can see the order of parameters:

int WINAPI MessageBox(
  HWND    hWnd,
  LPCTSTR lpText,
  LPCTSTR lpCaption,
  UINT    uType
);

Arguments are pushed to the stack in reverse order.

Assembling and linking

Now that you’ve got your source file, hello.asm you can produce an object file with the following:

C:\src> nasm -i c:\nasm\include -f obj hello.asm

You can now link the object file into an executable with the following:

C:\src> alink -c -oPE -subsys gui hello

Ready to go.

Making things a little more high-level

You can make your assembly code a little more high-level by using the nagoa+.inc include file. This include file provides your programs with some really handy constructs (as well as the win32 api bindings), so function invocations now look like this:

call MessageBoxA, 0, message, title, MB_OK
call ExitProcess, 0

Conclusion

This will get you started at least with Nasm in Windows development. Here is a great resource, full of links on assembly development.