dbserverenum

Searches for the names of Microsoft® SQL Servers™locally, over the network, or both.

Syntax

INT dbserverenum (
USHORT searchmode,
LPSTR servnamebuf,
USHORT sizeservnamebuf,
LPUSHORT numentries );

Arguments

searchmode

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

Set searchmode to LOC_SEARCH to search for the names of servers in the Win.ini file (Microsoft Windows®) or in the following subtree of the Microsoft Windows NT® Registry:

HKEY_Local_Machine\
SOFTWARE\
Microsoft\
MSSQLServer\
Client\
ConnectTo

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 Windows NT Registry or in the .ini file (Windows). 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 unsorted order; names found using the LOC_SEARCH constant are returned before those names found using the NET_SEARCH constant. Note that dbserverenum can return server names even when the 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_AVAIL (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_AVAIL (MORE_DATA | NET_NOT_AVAIL).

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

Using dbserverenum, 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 LAN Manager - based networks.

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 Net-Library are enumerated using the NET_SEARCH parameter. You must add a specific server entry in the Windows NT Registry to use a Net-Library DLL other than the default Net-Library DLL. Servers listed in the Registry are enumerated when the search mode is set to LOC_SEARCH.

See Also