INF: DB-Library Version 4.20.50 Enhancements

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

<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);
   }

   DB-Library Error 10010:
       Possible network error: Read from SQL Server failed.
   Net-Library Error 53:
       ConnectionRead (read()).

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

   ISBN 1-55615-321-X) on pages 3-123 - 3-124

   ISBN 1-55615-157-8) on pages 453-455,

   pages 1461-1462.

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

   pages 193-203.

- "Microsoft Win32 Programmer's Reference" Volume 2 (ISBN 1-55615-516-6)

   in Appendix A on pages 819-869.

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;

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)

   MORE_DATA (0x0001)

   NET_NOT_AVAILABLE (0x0002)

   OUT_OF_MEMORY (0x0004)

   NOT_SUPPORTED (0x0008)

   ENUM_INVALID_PARAM (0x0010)

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.