Developing 32-Bit Open Data Services Applications for the Microsoft Windows NT Operating System

Christopher Moffatt
Microsoft Technical Resource Group

Abstract

The Microsoft® Windows NT™ operating system is an ideal platform for building robust, feature-rich applications for Microsoft Open Data Services and Microsoft SQL Server. The SQL Server Programmer's Toolkit for Windows NT contains a 32-bit, Win32™-based version of Open Data Services, making it possible to develop Open Data Services–based server applications for the Windows NT platform.

The purpose of this technical article is to introduce Open Data Services developers to the Windows NT platform, address issues involved in porting existing Open Data Services applications for the OS/2® operating system to the Windows NT operating system, and outline some ways in which Open Data Services applications can take advantage of the Win32 application programming interface (API).

This technical note assumes that you are familiar with the Open Data Services API, C programming in a multithreaded environment, and the following documentation:

• Microsoft Open Data Services Programmer's Reference
  
  
• Microsoft Open Data Services Application Source Book
  
  
• Microsoft Win32 API Programmer's Reference, Volumes 1 & 2
  
  
• Converting OS/2 Applications to Windows

Building Win32-Based Open Data Services Applications

The following sections describe issues relevant to building Open Data Services applications using the Microsoft® Win32™ Application Programming Interface (API).

Libraries

The Open Data Services functions for the Win32 API are located in OPENDSNT.DLL. Set the PATH environment variable to include the directory where this dynamic-link library (DLL) resides.

Another file, OPENDSNT.LIB, contains import definitions that your application will use. Set the LIB environment variable to include the directory where OPENDSNT.LIB resides.

The Win32 API version of Open Data Services implements an installable server-side Net-Library architecture. Set the PATH environment variable to include the directory where this DLL resides. Currently, only support for named pipes is supported through a DLL called SSNMPNTW.DLL.

Include Files

In the SQL Server Programmer's Toolkit for Microsoft Windows NT™, the Open Data Services disk contains the following include files:

SRV.H is the only Open Data Services include file that you must include in your application source code. This file includes all other header files.

You can append the path to the INCLUDE environment variable to include the directory where the include files reside. Or you can use the /I compile line switch to point to the include file directory.

Compiling and Linking

The following example shows a simple build file that can be used with the NMAKE utility to compile and link Win32-based Open Data Services applications. NMAKE is a powerful utility for controlling the compilation and linking of development projects; however, the simplest NMAKE file is presented here in the interests of clarity.

The compile lines include the statement -DDBNTWIN32 to specify the target platform for DB-Library. This statement is included only because the GATEWAY sample application calls DB-Library; it would not be included for an Open Data Services application that does not call DB-Library.

NTLIB=\nt\sdk\lib\i386
DBLIB=\ntsql\dblib\lib
OPENDS=\ntsql\opends\lib
NTLIBS = kernel32.lib ntdll.lib libcmt.lib ntwDBLIB.lib
all: gateway.exe
# Update the object files if necessary
gateway.obj: gateway.c
  cl386 -c -Fs -G3d -DDBNTWIN32 -Di386=1 -DWIN32 gateway.c
gatecbs.obj: gatecbs.c
  cl386 -c -Fs -G3d  -DDBNTWIN32 -Di386=1 -DWIN32 gatecbs.c
# Update the exe file if necessary
gateway.exe: gateway.obj gatecbs.obj makefile
  link -machine:i386 -subsystem:console -out:gateway.exe \
   -entry:mainCRTStartup -map:gateway.map gateway.obj gatecbs.obj \ 
   $(NTLIBS) $(DBLIB)\ntwdblib.lib $(OPENDS)\opendsnt.lib

Porting OS/2-Based Open Data Services Applications

All Open Data Services API calls are completely portable between the OS/2® and Win32 APIs; you should not have to make modifications to any of your Open Data Services calls.

If you have existing OS/2-based Open Data Services applications that you want to run with the Windows NT operating system, there are two basic approaches you can take:

• Change your source code to replace base OS/2 and Presentation Manager® API calls with equivalent Win32 API calls. Because the C run-time calls and Open Data Services API calls are completely portable between the OS/2 and Windows NT platforms, if you decide to port an OS/2-based application to the Windows NT platform, you need to replace only base OS/2 and/or Presentation Manager API calls with equivalent Win32 API calls. Converting OS/2 Applications to Windows is an exhaustive treatment of this topic and provides an overview of porting considerations, as well as providing in-depth treatment of using Win32 API calls to replace base OS/2 and Presentation Manager API calls. Win32 provides equivalent, and in some cases superior, functionality in replacing OS/2 API calls.
  
  
• Run your character-mode OS/2 application unchanged. The initial release of the Windows NT operating system will provide an OS/2 subsystem that will run OS/2 character-mode applications with binary compatibility. If you have a character-mode Open Data Services application written for OS/2, you should be able to run this on the Windows NT platform without making any changes or having to rebuild the application. Consult the documentation for Windows NT to determine which OS/2 APIs are supported in the OS/2 subsystem.

OS/2 to Win32 API Conversion

As mentioned earlier, the topic of converting applications from OS/2 to Win32 is covered extensively in Converting OS/2 Applications to Windows. This section highlights two major areas of functionality that are found in a large number of Open Data Services applications: thread management and synchronization mechanisms. (The information given here is taken directly from Converting OS/2 Applications to Windows.)

Processes and threads

The Win32 API provides equivalent functionality to the OS/2 process and thread calls. You can consider their functionality to be conceptually equivalent, except in the following areas:

• Security: The Win32 API on the Windows NT platform provides complete security, and security access can be assigned to all objects including processes and threads.
  
  
• Parent Process: There is no concept of a parent process in Win32.
  
  
• Exit List Processing: Exit List Processing is not supported in the Win32 API. However, in some cases the DLL load and unload entry point can be used to similar effect.
  
  
• Handles and IDs: In OS/2, processes and threads are identified by an ID that is a global value. In Win32, processes and threads have IDs that are global and HANDLEs that are only valid within a particular process. All functions that manipulate processes and threads require a valid HANDLE.

Semaphores and synchronization

There are two types of synchronization provided by both OS/2 and the Win32 API set: mutual exclusion and signaling.

Mutual exclusion

Mutual exclusion involves denying other threads of execution access to a critical section of code. Both OS/2 and Win32 have mechanisms designed to facilitate mutual exclusion within a process and mutual exclusion between processes.

• DosEnterCritSec and DosExitCritSec provide for mutual exclusion in OS/2 by preventing other threads within a process from executing while a thread is between these two calls. Win32 does not have a similar mechanism. Programs using these calls should organize their code so that all code that accesses a protected resource is located in one place and therefore protectable by the other mutual exclusion mechanisms.
  
  
• DosFSRamSemClear and DosFSRamSemRequest are used for mutual exclusion within a process. Win32 provides the Mutex object to implement this functionality. Calls valid on a Mutex object include CreateMutex, OpenMutex, ReleaseMutex, WaitForSingleObject, and CloseHandle. A Mutex may be shared by more than one process.
  
  
• DosCreateSem, DosOpenSem, DosCloseSem, DosSemRequest, and DosSemClear are used for mutual exclusion between processes. Win32 provides the Semaphore object that provides a superset of these functions. The Win32 Semaphore may be either named or unnamed, thus providing a replacement for either RAM semaphores or System semaphores. Win32 functions that manage Semaphore objects include CreateSemaphore, OpenSemaphore, CloseSemaphore, ReleaseSemaphore, and WaitForSingleObject.

Signaling

OS/2 semaphores can be used for signaling between processes. The OS/2 functions used for this purpose are DosSemSet, DosSemWait, DosSemSetWait, and DosMuxSemWait. Win32 provides the Event object that implements a superset of this functionality. The Win32 functions used to manage the Event object include CreateEvent, OpenEvent, SetEvent, PulseEvent, and ResetEvent.

Porting the GATEWAY Sample Application

This section uses the sample program GATEWAY that is provided with Open Data Services as an example of porting an OS/2 version 1.3 Open Data Services application to the Windows NT platform. Although it is a fairly simple application, it serves as an example of the ease with which the majority of Open Data Services application programs can be ported to the Windows NT platform.

Note   The SQL Server Programmer's Toolkit for Windows NT contains a Windows NT–based version of the sample GATEWAY application.

To port the GATEWAY application:

1. Modify GATEWAY.MAK to build Win32 source code. For more information, see "Compiling and Linking," earlier in this technical article.
   
   
2. In GATEWAY.C:

   a. Replace the OS.H include file:

   OS/2:	INCL_BAS #include <os2.h>
   Win32:	#include <windows>

   
   

   b. Change the exit call:

   OS/2:	DosExit(EXIT_PROCESS, 1);
   Win32:	ExitProcess(1);

   
   

   c. Remove all references to FAR keyword (not required).

3. In GATECBS.C:

   a. Replace the OS.H include file:

   OS/2:	INCL_BAS #include <os2.h>
   Win32:	#include <windows.h

   
   

   b. Change semaphore calls:

       Declaration

   OS/2:	ULONG init_remote_SEM;
   Win32:	HANDLE init_remote_SEM;

   
   

   c. Create semaphore in init_server function:

   OS/2:	N/A (Not required)
   Win32:	init_remote_SEM = CreateSemaphore(NULL, 1,1,NULL);

   
   

   d. Set semaphore in init_remote function:

   OS/2:	DosSemSet(&init_remote_SEM);
   Win32:	WaitForSingleObject(init-remote_SEM, -1);

   
   

   e. Clear semaphore in init_remote function (five times):

   OS/2:	DosSemClear(&init_remote_SEM);
   Win32:	ReleaseSemaphore(init_remote_SEM, 1,NULL);

   
   

   f. Remove all references to FAR keyword (not required).

Taking Advantage of Win32 API Features in Open Data Services Applications

The following sections describe how to take advantage of the unique features of the Win32 API.

Memory Management in Win32

The 32-bit linear virtual memory address space available to processes in the Win32 API makes memory management simpler and cleaner. This applies to Open Data Services programming as well as to any other programming for the Win32 API.

When you develop applications to run only on the Win32 API, consider using the C run-time functions malloc and free to perform dynamic memory management. The malloc and free functions are not safe to use with Windows 3.x and OS/2 because of the segmented architecture of those systems. However, with Win32 these functions are both safe and elegant. In addition to the standard memory management functions (Global and Local functions, C run-time support), Win32 also provides heap and virtual memory management functions for applications that require specialized memory management.

Threads in Win32

The functionality of the process and thread management functions are roughly equivalent in Win32 and OS/2. However, because the Win32 API supports 32-bit linear memory, the number of threads that an application can create per process is greatly increased. In OS/2, a process can create only a maximum of 53 threads. This is a limitation for the Open Data Services library, because it creates an operating system thread for each client connection. In OS/2, to connect more than 53 DB-Library clients to an Open Data Services application, you must run multiple instances of the application. In Win32, the limit of 53 threads no longer exists.

Structured Exception Handling

The Win32 API supports structured exception handling to aid the development of robust software and is available to developers through compiler support. Consider using this functionality in your application. For more information about structured exception handling, see the Microsoft Win32 API Programmer's Reference, Volume 1 (Chapter 11).

Symmetric Multiprocessing

The Windows NT operating system supports symmetric multiprocessing (SMP), allowing applications with multiple threads of execution to run across multiple processors. Because Open Data Services creates a new operating system thread for each client connection, your Open Data Services application can take advantage of Windows NT SMP support without any additional work being done.

Sample Code: SQLSNIFF

SQLSNIFF is a sample Windows NT–based Open Data Services application. It can be used to view or log the Transact-SQL queries being sent to SQL Server from multiple clients. Instead of connecting directly to a SQL Server, clients connect to this Open Data Service application. Queries received are passed on to SQL Server and the results are returned to the respective clients. SQLSNIFF allows you to view queries, results, and error messages in MDI child windows or to log this data to a file or a SQL Server table.

The SQLSNIFF sample application is useful as a debugging aid in the following two scenarios:

• Understanding the queries being generated and sent to SQL Server by a third-party front end. If you are experiencing problems with a third-party application, it is often useful to look at the queries that are being generated and sent to SQL Server. Although you cannot view the source code of a third-party application, SQLSNIFF gives you the ability to view the queries being sent to SQL Server by redirecting the client's conversation with SQL Server through SQLSNIFF.
  
  
• Viewing and logging the queries being sent to SQL Server by multiple clients.

The sample code described above can be found in the Microsoft Online Software Library or in the Microsoft Forum Software Library on CompuServe® in a file called SQLSNIFF.ZIP. It can be located by searching on the keyword SQLSNIFF, the Q number of this article in the Microsoft KnowledgeBase (Q87961), or S13581. SQLSNIFF.ZIP was archived using the PKWARE file-compression utility.

SQLSNIFF.ZIP contains the following files:

References

Books

Microsoft Open Data Services Programmer's Reference (Part number 28641)

Microsoft Open Data Services Application Source Book (Part number 098-32078)

Microsoft Win32 API Programmer's Reference, Volumes 1 & 2 (Microsoft Press)

OS/2 to Windows Conversion Guide (Part number 098-35176)

Converting OS/2 Applications to Windows (Part number 098-35176)

Available Technical Notes

Using Microsoft SQL Server on a Banyan VINES Network (Part number 098-30193)

Query Optimization Techniques: Contrasting various optimizer implementations with Microsoft SQL Server (Part number 098-30199)

Microsoft Open Data Services: Application sourcebook (Part number 098-32078)

Using Microsoft SQL Server on a Novell NetWare Network (Part number 098-32655)

Developing 32-Bit SQL Server Applications for the Microsoft Windows NT Operating System (Part number 098-32659)

Additional Information

To receive more information, contact Microsoft Inside Sales, Systems Software, at 1-800-227-4679.