Add documentation for SetQueryNotification

doc/how-to-use-setquerynotification.md

@@ -0,0 +1,25 @@
+# How create a Query Notification
+
+Query notifications subscriptions can be set on queries to request that the application be notified when the results of the query change. After using the driver's `Conn` type to `Prepare` a query, call `SetQueryNotification()` method to set the contents of the query notification header.
+
+```go
+    sqlstmt.SetQueryNotification("Message", "service=myService", time.Hour)
+```
+
+The parameters of the `SetQueryNotification()` method are: `message`, `options`, and `timeout`. The `options` parameter takes a string containing the service name as well as the database or broker instance. `options` must be in the following format:
+
+`service=<service-name>[;(local database=<database> | broker instance=<broker instance>)]`
+
+The time unit for the `timeout` parameter is milliseconds.
+The query for notification must be in the correct [format](https://docs.microsoft.com/en-us/previous-versions/sql/sql-server-2008-r2/ms175110(v=sql.105)) or the subscription will fail on the server.
+
+## Example
+
+[Query Notification Example](..\setquerynotification_example_test.go)
+
+## Useful Links
+
+- [Using Query Notifications](https://docs.microsoft.com/en-us/previous-versions/sql/sql-server-2008-r2/ms175110(v=sql.105))
+- [Working with Query Notifications](https://docs.microsoft.com/en-us/sql/relational-databases/native-client/features/working-with-query-notifications?view=sql-server-2017)
+- [Creating a Query for Notification](https://docs.microsoft.com/en-us/previous-versions/sql/sql-server-2008-r2/ms181122(v=sql.105))
+- [Query Notifications Header](https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-tds/e168d373-a7b7-41aa-b6ca-25985466a7e0)

mssql.go

@@ -396,6 +396,10 @@ func (s *Stmt) Close() error {
 	return nil
 }
 
+// Sets a Query Notification for the query in Stmt.
+// Options must be in the format:
+//  service=<service-name>[;(local database=<database> | broker instance=<broker instance>)]
+// https://docs.microsoft.com/en-us/previous-versions/sql/sql-server-2008-r2/ms181122(v=sql.105)
 func (s *Stmt) SetQueryNotification(id, options string, timeout time.Duration) {
 	to := uint32(timeout / time.Second)
 	if to < 1 {

setquerynotification_example_test.go

@@ -0,0 +1,47 @@
+package mssql_test
+
+import (
+	"fmt"
+	"log"
+	"time"
+
+	mssql "github.com/denisenkom/go-mssqldb"
+)
+
+// This example shows the how to set query notifications on a pre-existing table
+func ExampleStmt_SetQueryNotification() {
+	password := ""
+	port := 1433
+	server := ""
+	user := ""
+	database := ""
+
+	connString := fmt.Sprintf("server=%s;user id=%s;password=%s;port=%d;database=%s;", server, user, password, port, database)
+
+	mssqldriver := &mssql.Driver{}
+	cn, err := mssqldriver.Open(connString)
+	if err != nil {
+		log.Fatal("Open connection failed:", err.Error())
+	}
+	defer cn.Close()
+	conn, _ := cn.(*mssql.Conn)
+
+	// Supported SELECT statements: https://docs.microsoft.com/en-us/previous-versions/sql/sql-server-2008-r2/ms181122(v=sql.105)
+	stmt, err := conn.Prepare("SELECT [myColumn] FROM [mySchema].[myTable];")
+	if err != nil {
+		log.Fatal("Prepare failed:", err.Error())
+	}
+	defer stmt.Close()
+
+	sqlstmt, _ := stmt.(*mssql.Stmt)
+	defer sqlstmt.Close()
+	sqlstmt.SetQueryNotification("Message", "service=myService", time.Hour)
+
+	// Query will return the result of the above select statement and subscription for the query notification will be created.
+	rows, err := sqlstmt.Query(nil)
+	if err != nil {
+		log.Fatal("Query failed:", err.Error())
+	} else {
+		rows.Close()
+	}
+}