INF: DB-Library Version 4.20.50 Enhancements

ID: Q107479

The information in this article applies to:
  • Microsoft SQL Server Programmer's Toolkit, version 4.2

SUMMARY

The following is a list of enhancements in DB-Library version 4.20.50.


MORE INFORMATION

NEW NET-LIBRARY ERROR REPORTING

The new Net-Library files have enhanced run-time error reporting. If a network or operating system error is encountered during run-time, the Net-Library will pass the network or operating system error code back to the application's DB-Library error handler.

The network or operating system errors reported by the Net-Library will usually have the following format
Net-Library Error <net/os error code>:
<Net-Library function> (<net/os function>).

where:
<net/os error code> is the error code returned by the <net/os function> during run-time. The meaning of this error code is dependent on the <net/os function> that returned this error code, and the Net-Library in use at the time the error occurred. Please examine your network or operating system documentation for complete information about this error code.

<Net-Library function> is the Net-Library function that was in use when the run-time error occurred.

<net/os function> is the network or operating system function that returned the error code. Please examine your network or operating system documentation for complete information.

To properly distinguish DB-Library, Net-Library, and operating system errors, a DB-Library application should have an error handler similar to the following: 

   int err_handler(dbproc, severity, dberr, oserr, dberrstr, oserrstr)

   DBPROCESS   *dbproc;
   int         severity;
   int         dberr;
   int         oserr;
   char        *dberrstr;
   char        *oserrstr;
   {
       printf("DB-Library error %d: %s\n", dberr, dberrstr);

       if (severity == EXCOMM && (oserr != DBNOERR || oserrstr))
           printf(Net-Library error %d: %s\n"' oserr, oserrstr);

       if (oserr != DBNOERR)
           printf("Operating system error %d: %s\n", oserr, oserrstr);

       if ((dbproc == NULL) || (DBDEAD(dbproc))
           return(INT_CANCEL);
       else
           return(INT_CANCEL);
   }

For example, you can get the following error while using the named pipe Net-Library on a Microsoft LAN Manager-based network:
DB-Library Error 10010:

Possible network error: Read from SQL Server failed.

Net-Library Error 53:

ConnectionRead (read()).

If you do get the above error, this would mean that LAN Manager error 53 occurred when the named pipe Net-Library function ConnectionRead called the network read() function.

The meaning of LAN Manager error 53 can be determined by examining the LAN Manager documentation, or typing NET HELPMSG 53 at the command prompt. This returns:
SYS0053: The network path was not found.

EXPLANATION: The server that you specified does not exist or has not been started.
ACTION: Verify that you specified the path name correctly. Contact your network administrator if you continue to have problems.

OPERATING SYSTEM ERROR DOCUMENTATION

For a 16-bit MS-DOS or Microsoft Windows DB-Library client, the operating system errors are standard MS-DOS extended error and are documented in the following sources:
  • "Microsoft MS-DOS Programmer's Reference" (ISBN 1-55615-329-5) in Appendix C on pages 447-449


  • "The Programmer's PC Sourcebook" by Thom Hogan (second edition, ISBN 1-55615-321-X) on pages 3-123 - 3-124


  • "Advanced MS-DOS Programming" by Ray Duncan (second edition, ISBN 1-55615-157-8) on pages 453-455,


  • "The MS-DOS Encyclopedia" (ISBN 1-55615-174-8) in Appendix C on pages 1461-1462.



They are the same codes returned by Microsoft C run-time function _dosexterr(), and also MS-DOS Int 21 Function 59H.

For a 16-bit OS/2 DB-Library client, the operating system errors are standard OS/2 errors (many common with the MS-DOS errors) and are documented in the following sources:
  • "Microsoft OS/2 Programmer's Reference" Volume 3 (ISBN 1-55615-222-1) in Appendix A on pages 409-413


  • "Essential OS/2 Functions" by Ray Duncan (ISBN 1-55615-177-2) on pages 193-203.



For a 32-bit Windows NT DB-Library client, the operating system errors are standard Windows NT errors (many common with the MS-DOS errors) and are documented in the following source:
  • "Microsoft Win32 Programmer's Reference" Volume 2 (ISBN 1-55615-516-6) in Appendix A on pages 819-869.



They are the same codes returned by Win32 function GetLastError().

NEW DB-LIBRARY FUNCTION

DB-Library for Windows, MS-DOS, and OS/2 includes a new function, dbserverenum. Using the dbserverenum function, you can obtain the names of servers to which you can connect. The dbserverenum function can search for the names of SQL Servers either locally or over the network. For network searches, the Net-Library DLL used must support the dbserverenum function. A Net-Library DLL registers and finds servers on networks for a specific network environment such as Microsoft LAN Manager-based networks.

Syntax

The dbserverenum function has the following syntax: 

   RETCODE dbserverenum(searchmode, servnamebuf, sizeservnamebuf,
   numentries)

   unsigned short  searchmode;
   char            *servnamebuf;
   unsigned short  sizeservnamebuf;
   unsigned short  *numentries;

where:

searchmode defines whether the dbserverenum function checks for server names locally, on the network, or both.

To search for the names of servers listed in your WIN.INI file (Windows), or in OS2.INI (OS/2), set searchmode to LOC_SEARCH.

The LOC_SEARCH constant has the value 0x0001.

To search for the names of servers registered by the default Net Library, set searchmode to NET_SEARCH. The NET_SEARCH constant has the value 0x0002.

To search both locally and on the network for server names, use a bitwise OR operation (NET_SEARCH | LOC_SEARCH) to combine the values of LOC_SEARCH and NET_SEARCH. In this case, a server name is duplicated if the server name is defined both locally and on the network.

DB-Library first tries to load the default Net-Library set by the DSQUERY entry in the .INI file (Windows and OS/2). If no default entry exists, DB-Library loads the appropriate named pipe Net-Library.

servnamebuf is a pointer to a buffer that stores the server names returned by a search. When the dbserverenum function successfully returns a list of server names, the servnamebuf buffer contains the server names separated by null characters. The end of the list is designated by two consecutive null characters.

Only complete server names are copied to the buffer. When a buffer is full and there are additional names that could not be copied to the buffer, dbserverenum returns the value MORE_DATA. Server names are returned in a non-sorted order; names found using the LOC_SEARCH constant are returned before those names found using the NET_SEARCH constant.

NOTE: dbserverenum can return server names even when SQL Server is not running. Therefore, although a server name is returned in the list of servers, it does not guarantee that you can access the server.

sizeservnamebuf specifies the size of the buffer for the server names returned by a successful search. The buffer size limits the maximum number of names that dbserverenum can return in a single call.

numentries returns the number of server names copied to the buffer by the current call to dbserverenum.

Returns

The dbserverenum function returns one or more of the following status code constants: 

   ENUM_SUCCESS (0x0000)

Indicates that the search to detect server names succeeded. ENUM_SUCCESS can be returned even when no servers are detected (when numentries = 0). 

   MORE_DATA (0x0001)

Indicates that DB Library has enough memory to service the dbserverenum request but the buffer passed to dbserverenum is not large enough to hold all the names returned. Increasing the size of sizeservnamebuf enables the buffer to hold more server names. 

   NET_NOT_AVAILABLE (0x0002)

Indicates that the Net-Library DLL is unavailable. A Net-Library DLL might be unavailable because no DLL is found or because the available Net-Library DLL does not support the dbserverenum function. When the searchmode parameter includes the NET_SEARCH mode, dbserverenum calls the default Net-Library DLL. When searchmode includes both the NET_SEARCH and LOC_SEARCH modes (NET_SEARCH | LOC_SEARCH), dbserverenum can return both MORE_DATA and NET_NOT_AVAILABLE (MORE_DATA | NET_NOT_AVAILABLE). 

   OUT_OF_MEMORY (0x0004)

Indicates that DB Library cannot allocate enough memory to service the dbserverenum request. 

   NOT_SUPPORTED (0x0008)

Indicates that the capability is not supported by the current Net-Library version or the current server platform. 

   ENUM_INVALID_PARAM (0x0010)

Indicates that an invalid parameter, such as a null pointer, was passed to the function.

Remarks

When the search mode is set to NET_SEARCH, dbserverenum calls the default Net-Library DLL (for example, named pipes or Novell* IPX/SPX). Because only one Net-Library DLL can be the default, those servers discernible to the specific server are enumerated using the NET_SEARCH parameter. You must add a specific server entry in the .INI file (Windows and OS/2) to use a Net-Library DLL other than the default Net-Library DLL. Servers listed in the .INI file (Windows and OS/2) are enumerateed when the search mode is set to LOC_SEARCH.

Additional query words: 4.20.50 dblib

Keywords : SSrvDB_Lib
Version : 4.2
Platform :
Issue type :


Last Reviewed: March 19, 1999
© 2000 Microsoft Corporation. All rights reserved. Terms of Use.