Restore error printing for non-timeout errors and add documentation

- Changed GetLocalServerInstances() to return ([]string, error)
- Only return error if NOT os.ErrDeadlineExceeded (timeout is expected)
- ListLocalServers() prints errors to stderr (matches ODBC sqlcmd behavior)
- Expanded README documentation for :serverlist command
- Added batch script examples for error handling and automation

Author: dlevy-msft-sql

README.md

@@ -155,7 +155,40 @@ switches are most important to you to have implemented next in the new sqlcmd.
 - The new `--driver-logging-level` command line parameter allows you to see traces from the `go-mssqldb` client driver. Use `64` to see all traces.
 - Sqlcmd can now print results using a vertical format. Use the new `--vertical` command line option to set it. It's also controlled by the `SQLCMDFORMAT` scripting variable.
 - `:help` displays a list of available sqlcmd commands.
-- `:serverlist` lists local SQL Server instances discovered via the SQL Server Browser service.
+- `:serverlist` lists local SQL Server instances discovered via the SQL Server Browser service (UDP port 1434). The command queries the SQL Browser service and displays the server name and instance name for each discovered instance. If no instances are found or the Browser service is not running, no output is produced. Non-timeout errors are printed to stderr.
+
+```
+1> :serverlist
+MYSERVER\SQL2019
+MYSERVER\SQL2022
+```
+
+#### Using :serverlist in batch scripts
+
+When automating server discovery, you can capture the output and check for errors:
+
+```batch
+@echo off
+REM Discover local SQL Server instances and connect to the first one
+sqlcmd -Q ":serverlist" 2>nul > servers.txt
+if %errorlevel% neq 0 (
+    echo Error discovering servers
+    exit /b 1
+)
+for /f "tokens=1" %%s in (servers.txt) do (
+    echo Connecting to %%s...
+    sqlcmd -S %%s -Q "SELECT @@SERVERNAME"
+    goto :done
+)
+echo No SQL Server instances found
+:done
+```
+
+To capture stderr separately (for error logging):
+```batch
+sqlcmd -Q ":serverlist" 2>errors.log > servers.txt
+if exist errors.log if not "%%~z errors.log"=="0" type errors.log
+```
 
 ```
 1> select session_id, client_interface_name, program_name from sys.dm_exec_sessions where session_id=@@spid

pkg/sqlcmd/serverlist.go

@@ -5,9 +5,11 @@ package sqlcmd
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"io"
 	"net"
+	"os"
 	"sort"
 	"strings"
 	"time"
@@ -18,15 +20,19 @@ import (
 // ListLocalServers queries the SQL Browser service for available SQL Server instances
 // and writes the results to the provided writer.
 func ListLocalServers(w io.Writer) {
-	instances := GetLocalServerInstances()
+	instances, err := GetLocalServerInstances()
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+	}
 	for _, s := range instances {
 		fmt.Fprintf(w, "  %s\n", s)
 	}
 }
 
 // GetLocalServerInstances queries the SQL Browser service and returns a list of
 // available SQL Server instances on the local machine.
-func GetLocalServerInstances() []string {
+// Returns an error for non-timeout network errors.
+func GetLocalServerInstances() ([]string, error) {
 	bmsg := []byte{byte(msdsn.BrowserAllInstances)}
 	resp := make([]byte, 16*1024-1)
 	dialer := &net.Dialer{}
@@ -35,20 +41,26 @@ func GetLocalServerInstances() []string {
 	conn, err := dialer.DialContext(ctx, "udp", ":1434")
 	// silently ignore failures to connect, same as ODBC
 	if err != nil {
-		return nil
+		return nil, nil
 	}
 	defer conn.Close()
 	dl, _ := ctx.Deadline()
 	_ = conn.SetDeadline(dl)
 	_, err = conn.Write(bmsg)
 	if err != nil {
-		// Silently ignore errors, same as ODBC
-		return nil
+		// Only return error if it's not a timeout
+		if !errors.Is(err, os.ErrDeadlineExceeded) {
+			return nil, err
+		}
+		return nil, nil
 	}
 	read, err := conn.Read(resp)
 	if err != nil {
-		// Silently ignore errors, same as ODBC
-		return nil
+		// Only return error if it's not a timeout
+		if !errors.Is(err, os.ErrDeadlineExceeded) {
+			return nil, err
+		}
+		return nil, nil
 	}
 
 	data := parseInstances(resp[:read])
@@ -73,7 +85,7 @@ func GetLocalServerInstances() []string {
 			instances = append(instances, fmt.Sprintf(`%s\%s`, serverName, s))
 		}
 	}
-	return instances
+	return instances, nil
 }
 
 func parseInstances(msg []byte) msdsn.BrowserData {

pkg/sqlcmd/serverlist_test.go

@@ -22,8 +22,12 @@ func TestListLocalServers(t *testing.T) {
 
 func TestGetLocalServerInstances(t *testing.T) {
 	// Test that GetLocalServerInstances returns a slice (may be empty if no servers)
-	instances := GetLocalServerInstances()
+	instances, err := GetLocalServerInstances()
 	// instances may be nil or empty if no SQL Browser is running, that's OK
+	// err may be non-nil for non-timeout network errors
+	if err != nil {
+		t.Logf("GetLocalServerInstances returned error (expected in some environments): %v", err)
+	}
 	t.Logf("Found %d instances", len(instances))
 	for _, inst := range instances {
 		assert.NotEmpty(t, inst, "Instance name should not be empty")