************************************************************************
     MICROSOFT SQL SERVER PROGRAMMER'S TOOLKIT SPECIAL INFORMATION
************************************************************************

This file contains information pertaining to the use of the Microsoft(R) 
SQL Server Programmer's Toolkit (PTK). The information contained in this 
file is intended to supplement the manuals included in your Microsoft 
SQL Server PTK package.

************************************************************************

DB-LIBRARY SAMPLE APPLICATIONS
------------------------------

The samples described in the "Building Applications" chapter of the 
"Programmer's Reference for C" are targeted to specific client operating 
systems: Windows NT(TM), Windows(TM), MS-DOS(TM) and OS/2(TM). Some 
additional platform-specific samples are also included. Each of these 
samples has an associated .MAK file for building with the NMAKE utility. 
The following is a complete list:  

   Windows NT
      SQLTESTC.*     Windows NT-based Console sample.
      SQLTESTN.*     Windows NT-based GUI sample.
      
   MS-DOS
      SQLTESTR.*     MS-DOS-based sample.
      SQLTESTR.BOR   MS-DOS-based sample for use with Borland(R).

   Windows
      SQLTEST.ICO    Icon used by all Windows-based samples.
      SQLTEST3.*     Windows-based sample.
      SQLCURSW.*     Windows-based cursor sample.

   OS/2
      SQLTESTP.*     OS/2 character-based sample.
      SQLPM.*        OS/2 based Presentation Manager-based sample.

In addition, the PTK includes the following cross-platform sample 
applications, as described in the "Example Programs" and "Two-Phase 
Commit Special Library" chapters of the "Programmer's Reference for C." 
These samples are character-based. Batch files are included to build all 
of these samples on a given platform.

      EXAMPLE1.C     Sending queries in a command batch.
      EXAMPLE2.C     Working with data files.
      EXAMPLE3.C     Binding aggregate and compute results.
      EXAMPLE4.C     Using row buffering.
      EXAMPLE5.C     Converting data with dbconvert.
      EXAMPLE6.C     Querying and updating the database.
      EXAMPLE7.C     Using browse-mode functions.
      EXAMPLE8.C     Using remote stored procedures and return 
                     parameters.
      SQLEXAMP.C     Command-line interpreter.
      SQLCURS.C      Using cursor functions.
      TWOPHASE.C     Two-phase commit example.
      DATAFILE.      Data file used by some of the examples.
      
   Build Tools -- Use "?" to display options.
   
      BUILDN.BAT/MAK    Builds the examples for Windows NT.
      BUILDR.BAT/MAK    Builds the examples for DOS.
      BUILDBOR.BAT/MAK  Builds the examples for DOS using Borland C.
      BUILDP.CMD/MAK    Builds the examples for OS/2.


DB-LIBRARY STORED PROCEDURE HANDLING FUNCTIONS
----------------------------------------------

In addition to the stored procedure handling functions included in your 
documentation, DB-Library(TM) includes a dbrpcexec function, which 
signals the end of a parameter list for a remote stored procedure and 
sends the remote stored procedure to SQL Server for execution. For 
additional information about this function, see either of the DB-Library 
on-line Help files.


OPEN DATA SERVICES SAMPLE APPLICATIONS
--------------------------------------

In the \SQL\OPENDS\SAMPLES directory, there are two new samples that are 
not discussed in the main section of the "Microsoft Open Data Services 
Programmer's Reference." These two samples are described below. In 
addition, there are a few changes to the other sample applications in 
the "Open Data Services Programmer's Reference." The on-line samples 
should be used as the most current reference to Open Data Services (ODS) 
programming.

ODSODBC Sample
--------------
This sample code shows how to customize the ODS gateway ODBC driver. The 
use of this driver is discussed in Appendix E of the "Microsoft Open 
Data Services Programmer's Reference."

MAPI Sample
-----------
This sample shows how to call messaging API (MAPI) functions from a SQL 
Server Extended Stored Procedure. MAPI functions are included with 
Windows NT as part of the built-in mail support. MAPI currently allows 
only a single thread in a process to be logged on to mail at a given 
time, so this sample shows how to serialize access to a resource.  

Source files:
	SQLMAIL.C	Extended stored procedure functions and serialization 
			code
	MAILUTIL.C	General purpose functions to log in, prepare, send, 
			and log out
	UTIL.H	Defines for this sample
	MAPI.H	Standard MAPI headers
	MAPINIT.H	Standard MAPI headers

To Install: 
	Run the script INSTMAIL.SQL in \SQL\OPENDS\SAMPLES\MAPI\BUILD. 

To Run:
	Start the Windows NT mail client application on your server 
	machine, log in to a mail server, and leave it running. You 
	can then issue the following calls from a SQL Server client 
	application or from a stored procedure:

	xp_mailproclist
		Gives a list of the MAPI extended procedures.

	xp_loginmail 
		Piggybacks a mail session on top of the running mail client. 
		If successful, gains ownership of the mail channel until 
		this client logs off.

	xp_sendmail "to", "cc", "subject", "body" 
		Sends a single-line message up to 255 characters. The "to" 
		and "cc" fields can be multiple recipients, separated by 
		semicolons.
		
	xp_prepmsg "to","cc","subject" 
	xp_addmsgline "line"   
	xp_addattach "file1[;file2...]"   
	xp_sendmsg 
		These four calls are used in combination to prepare longer 
		messages and messages with attached files.

	xp_logoffmail
		Logs off the current logged in session and frees the mail 
		channel, allowing another user to access the mail extended 
		stored procedures.


BUILDING SAMPLE APPLICATIONS WITH MICROSOFT VISUAL C++ FOR WINDOWS NT
---------------------------------------------------------------------

The sample makefiles included with this PTK are designed to work with 
tools shipped in the Win32 Software Development Kit (SDK). To use these 
makefiles with the tools in Microsoft Visual C++ for Windows NT, do the 
following:

1.  Change "CL386" to "CL" (in all makefiles).
2.  Change "LINK32" to "LINK" (in all makefiles).
3.  Change "CRTDLL.LIB" to "MSVCRT.DLL" (in the ODS XPDLL and MAPI 
    samples).
4.  Remove the CVTRES step in producing a resource file (in the 
    DB-Library SQLTESTN sample).

Additional information about migrating from the Win32 SDK to Visual C++ 
for Windows NT can be found in the MIGRATE.HLP file included with Visual 
C++.




















-----
Microsoft, MS, and MS-DOS are registered trademarks and Windows and 
  Windows NT are trademarks of Microsoft Corporation. Operating System/2
  and OS/2 are registered trademarks licensed to Microsoft Corporation.

DB-Library is a trademark of Sybase, Inc.

Borland is a registered trademark of Borland International, Inc.
