INF: Reading ODBC SQL Server Driver Network Messages

This article discusses the meaning of the various pieces of information returned to SQLError if the Microsoft ODBC SQL Server driver encounters a network error when communicating with SQL Server, and how this information can offer insight into the cause of the problem.

If the Microsoft ODBC SQL Server driver encounters a network problem when communicating with SQL Server, it will return SQL_ERROR to the ODBC function call. If the application then calls SQLError, the driver will return information similar to the following: The pfNative code and szErrorMsg string contain information that can give you clues about the nature of the underlying network problem.

The szErrorMsg string breaks down as follows:

• [Microsoft][ODBC SQL Server Driver]: This is the standard header for szErrorMsg strings coming from the Microsoft SQL Server driver, it indicates the error was detected in the driver itself.
• [dbnmpntw]: This is the name of the Microsoft Network library, and will be one of the following:
  dbnmpntw - Win32 Named Pipes
  dbmssocn - Win32 Winsock TCP/IP
  dbmsspxn - Win32 SPX/IPX
  dbmsvinn - Win32 Banyan Vines
  dbmsrpcn - Win32 Multi-Protocol (Windows RPC)
  dbnmp3 - Win16 Named Pipes
  dbmssoc3 - Win16 Winsock TCP/IP
  dbmsspx3 - Win16 SPX/IPX
  dbmsvin3 - Win16 Banyan Vines
  dbmsrpc3 - Win16 Multi-Protocol (Windows RPC)
• ConnectionOpen: A network library internal function name. The network library takes generic requests for network services from the Microsoft ODBC SQL Server driver and maps it down to a particular network protocol API call (or calls).
• (CreateFile()): The function in the network API that returned the error. These functions are documented in the programmer's references for the underlying network.

The most important part of the szErrorMsg is the name of the network library. This indicates what network protocol is being used, and therefore how the network error code should be interpreted.

The Microsoft SQL Server driver returns the error code it received from the underlying network in the pfNative parameter. Users can look up the error codes for the network protocol to see what type of error is indicated by the pfNative value. The network protocol error codes are documented in different places:

• dbnmpntw, dbnmp3: The codes returned from the named pipe API are consistent across Windows, Windows NT, and OS/2.
• dbmssocn, dbmssoc3: The codes returned by the Winsock API are listed in Appendix A, Error Codes, of the Windows Sockets Specification 1.1. The Windows Sockets Specification can be found on the MSDN CD.
• dbmsspxn, dbmsspx3: The codes returned from Novell can be found in the Novell NetWare Client Protocol Transport API for C under the section for the API function listed in the szErrorMsg. For example, if the pfNative is 253, and szErrorMsg lists SPXListenForSequencedPacket as the function, the reference manual states a 0xFD (253) return is a 'Packet Overflow.'
• dbmsvinn, dbmsvin3: The codes returned from Banyan Vines are listed in Appendix A of the Vines Client Developers Guide.
• dbmsrpcn, dbmsrpc3: The codes returned by the RPC API are listed in the RPC section of WINERROR.H.

To assist you in deciphering the messages returned, the following examples explain how to interpret the information returned on SQLError() if you attempt to connect with some of the network libraries to a SQL Server that is shut down:

• dbnmpntw:

     szSqlState = "01000"
     pfNativeError = 2
     szErrorMsg = "[Microsoft][ODBC SQL Server Driver][dbnmpntw]
                  ConnectionOpen (CreateFile())"
  						

  This indicates that the network error was received from the named pipe API function CreateFile.
• dbmsrpcn:

     szSqlState = "01000"
     pfNativeError = 1753
     szErrorMsg = "[Microsoft][ODBC SQL Server Driver][dbmsrpcn]
                  ConnectionOpen (RpcEpResolveBinding())"
  						

  This indicates that the network error was received from the RPC API function RpcEpResolveBinding. If you reference WINERROR.H, you will see that this indicates the pfNative value of 1753 is an EPT_S_NOT_REGISTERED, or an 'Endpoint not registered' error.
• dbmssocn:

     szSqlState = "01000"
     pfNativeError = 10061
     szErrorMsg = "[Microsoft][ODBC SQL Server Driver][dbmssocn]
                  ConnectionOpen (connect())"
  						

  This indicates that the network error was received from the Winsock API function connect. If you reference the Windows Socket Specification, you will see that this indicates the pfNative value of 10061 is an WSAECONNREFUSED, or a 'Connection Refused' error.

As you can see from these examples, the error codes returned are not always clear pointers to the underlying problems, but in many cases they are enough to give a network administrator or support professional some clues as to what may be wrong.