(index ("make-connection" 0) ("call-with-connection" 810) ("connection-close" 1370) ("connection-open?" 1520) ("connection-reset!" 1704) ("connection?" 1988) ("send-query" 2113) ("send-query*" 2789) ("call-with-result-set" 3267) ("row-fold" 3939) ("row-fold*" 3939) ("column-fold" 5142) ("column-fold*" 5142) ("row-fold-right" 5920) ("row-fold-right*" 5920) ("column-fold-right" 6249) ("column-fold-right*" 6249) ("row-for-each" 6490) ("row-for-each*" 6490) ("column-for-each" 6814) ("column-for-each*" 6814) ("row-map" 7033) ("row-map*" 7033) ("column-map" 7639) ("column-map*" 7639) ("result?" 8015) ("result-cleanup!" 8161) ("result-values" 8432) ("result-values/alist" 8621) ("result-value" 8877) ("result-row" 9249) ("result-column" 9449) ("result-row/alist" 9661) ("column-name" 9888) ("column-names" 10113))
(def (sig (procedure "(make-connection HOST USERNAME PASSWORD [DATABASE-NAME])" (id make-connection))) (p "Opens a connection to the database on the host in the " (tt "HOSTNAME") " string. This string may optionally contain a colon followed by a port number if it's not the default (1434?).  " (tt "USERNAME") " and " (tt "PASSWORD") " must be strings which are to be used for logging in.") (p "The string " (tt "DATABASE-NAME") " is optional; if it is not supplied it will use the default database.  You can easily switch databases later by running a " (tt "\"USE dbname\"") " query.") (p "The return value is a connection-object.") (p (b "Note") ": You cannot use the same connection from multiple threads. If you need to talk to the same server from different threads, simply create a second connection."))
(def (sig (procedure "(call-with-connection HOST USERNAME PASSWORD [DATABASE-NAME] PROCEDURE)" (id call-with-connection))) (p "A convenience wrapper which opens a connection and invokes " (tt "PROCEDURE") " with the connection object as an argument, analogously to " (tt "call-with-input-file") " or " (tt "call-with-output-file") ".") (p "This closes the connection when control leaves " (tt "PROCEDURE") "'s dynamic extent and re-opens it when it is re-entered (more importantly, this ensures the connection is closed when an unhandled exception occurs)."))
(def (sig (procedure "(connection-close CONNECTION)" (id connection-close))) (p "Closes the " (tt "CONNECTION") " and disconnects from the server."))
(def (sig (procedure "(connection-open? CONNECTION)" (id connection-open?))) (p "Returns " (tt "#t") " when the " (tt "CONNECTION") " is still open, " (tt "#f") " if it was closed."))
(def (sig (procedure "(connection-reset! CONNECTION)" (id connection-reset!))) (p "Resets the connection by canceling all currently open commands (queries).  You can use this on the REPL when something got stuck (but likely this will only happen if there's a bug in this library)."))
(def (sig (procedure "(connection? OBJECT)" (id connection?))) (p "Returns true if OBJECT is a FreeTDS connection-object."))
(def (sig (procedure "(send-query CONN QUERY . PARAMS)" (id send-query))) (p "Execute " (tt "QUERY") ", which is a string containing one SQL statement. " (tt "CONN") " indicates the connection on which to execute the query, and " (tt "PARAMS") " is an arbitrary number of optional arguments indicating positional parameters represented by " (tt "?") " markers in " (tt "QUERY") ".  Each marker must have a corresponding " (tt "PARAM") ".") (p "This returns a result object (see below).") (highlight scheme "(use freetds)\n\n(let ((conn (make-connection \"localhost\" \"user\" \"pass\")))\n  (result-values (send-query conn \"SELECT ?, 2\" \"hello\")))\n => ((\"hello\" 2))"))
(def (sig (procedure "(send-query* CONN QUERY PARAMS)" (id send-query*))) (p "An alternative of the " (tt "send-query") " procedure which is not limited in number of params by Chicken's argument count limit because " (tt "PARAMS") " is passed in as one argument in the form of a list.") (highlight scheme "(use freetds)\n\n(let ((conn (make-connection \"localhost\" \"user\" \"pass\")))\n  (result-values (send-query conn \"SELECT ?, 2\" '(\"hello\"))))\n => ((\"hello\" 2))"))
(def (sig (procedure "(call-with-result-set CONN QUERY [PARAM0 [PARAM1 ... ]] PROCEDURE)" (id call-with-result-set))) (p "A convenience wrapper which issues a query and invokes " (tt "PROCEDURE") " with the result object as an argument, analogously to " (tt "call-with-input-file") " or " (tt "call-with-output-file") ".") (p "This cleans up the result set when control leaves " (tt "PROCEDURE") "'s dynamic extent (more importantly, this ensures the result is cleaned up when an unhandled exception occurs).") (p (b "Important") ": When the dynamic extent is re-entered, the result object will be invalid because it was cleaned up.  The query is " (i "not") " resent."))
(def (sig (procedure "(row-fold KONS KNIL RESULT)" (id row-fold)) (procedure "(row-fold* KONS KNIL RESULT)" (id row-fold*))) (p "This is the fundamental result set iterator. It calls " (tt "(kons row seed)") " for every row, where " (tt "row") " is the list of values in the current row and " (tt "seed") " is the accumulated result from previous calls (initially " (tt "knil") "), ie its pattern looks like " (tt "(KONS ROWN ... (KONS ROW2 (KONS ROW1 KNIL)))") ".  It returns the final accumulated result.") (p "The starred version works the same, except it calls " (tt "(kons rowN-col1 rowN-col2 ... seed)") " instead of " (tt "(kons rowN seed)") ", so the procedure must know how many columns you have in the result set.") (highlight scheme "(use freetds)\n\n(let ((conn (make-connection \"localhost\" \"user\" \"pass\")))\n   (row-fold (lambda (row sum) (+ (car row) sum))\n             0\n             (query conn \"SELECT 1 UNION SELECT 2\")))\n => 3\n\n(let ((conn (make-connection \"localhost\" \"user\" \"pass\")))\n   (row-fold* (lambda (value str) (string-append str value))\n              \"\"\n              (query conn \"SELECT 'hello, ' UNION SELECT 'world'\")))\n => \"hello, world\""))
(def (sig (procedure "(column-fold KONS KNIL RESULT)" (id column-fold)) (procedure "(column-fold* KONS KNIL RESULT)" (id column-fold*))) (p "As " (tt "row-fold") "/" (tt "row-fold*") ", except this iterates sideways through the columns instead of lengthways through the columns, calling " (tt "KONS") " with all values in all the rows of the current column, from left to right.") (p "The starred version is much less useful here since you often don't know the number of returned columns, but it is provided for consistency.") (highlight scheme "(use freetds)\n\n(let ((conn (make-connection \"localhost\" \"user\" \"pass\")))\n  (column-fold (lambda (col sum) (+ (car col) sum))\n               0\n               (query conn \"SELECT 1, 100 UNION SELECT 2, 200\")))\n => 101"))
(def (sig (procedure "(row-fold-right KONS KNIL RESULT)" (id row-fold-right)) (procedure "(row-fold-right* KONS KNIL RESULT)" (id row-fold-right*))) (p "The fundamental result set recursion operator;  Calls " (tt "(KONS COL1 (KONS COL2 (KONS ... KNIL)))") " instead of " (tt "(KONS COLN ... (KONS COL2 (KONS COL1 KNIL)))") "."))
(def (sig (procedure "(column-fold-right KONS KNIL RESULT)" (id column-fold-right)) (procedure "(column-fold-right* KONS KNIL RESULT)" (id column-fold-right*))) (p "Column variants of " (tt "row-fold-right") "/" (tt "row-fold-right*") "."))
(def (sig (procedure "(row-for-each PROC RESULT)" (id row-for-each)) (procedure "(row-for-each* PROC RESULT)" (id row-for-each*))) (p "Simple " (tt "for-each") ", calling the " (tt "(PROC row)") " on each row, in turn, only for the purpose of its side-effects.  The starred version calls " (tt "(PROC col1 col2 ...)") "."))
(def (sig (procedure "(column-for-each PROC RESULT)" (id column-for-each)) (procedure "(column-for-each* PROC RESULT)" (id column-for-each*))) (p "Column variants of " (tt "row-for-each") "/" (tt "row-for-each*") "."))
(def (sig (procedure "(row-map PROC RESULT)" (id row-map)) (procedure "(row-map* PROC RESULT)" (id row-map*))) (p "Maps rows to lists by applying " (tt "PROC") " to every row and using its result in the result list on the position corresponding to that of the row.  This procedure is not guaranteed to walk the result set in any particular order, so do " (i "not") " rely on the order " (tt "PROC") " will be called.") (highlight scheme "(use freetds)\n\n(let ((conn (make-connection \"localhost\" \"user\" \"pass\")))\n   (row-map* + (query conn \"SELECT 1, 100 UNION SELECT 2, 200\")))\n => (101 202)"))
(def (sig (procedure "(column-map PROC RESULT)" (id column-map)) (procedure "(column-map* PROC RESULT)" (id column-map*))) (p "Column variants of " (tt "row-map") "/" (tt "row-map*") ".") (highlight scheme "(use freetds)\n\n(let ((conn (make-connection \"localhost\" \"user\" \"pass\")))\n   (column-map* + (query conn \"SELECT 1, 100 UNION SELECT 2, 200\")))\n => (3 300)"))
(def (sig (procedure "(result? OBJ)" (id result?))) (p "Returns " (tt "#t") " when " (tt "OBJ") " is a result object, " (tt "#f") " otherwise."))
(def (sig (procedure "(result-cleanup! RES)" (id result-cleanup!))) (p "Directly clean up all memory used by the result object.  This is normally deferred until garbage collection, but it's made available for when you want more control over when results are released."))
(def (sig (procedure "(result-values RES)" (id result-values))) (p "Returns a list of all the rows in the result set " (tt "RES") ", with each row represented as a list of field values."))
(def (sig (procedure "(result-values/alist RES)" (id result-values/alist))) (p "Similar to " (tt "result-values") ", except each row is now represented as an alist which maps column names (symbols) to values, so this procedure returns a list of alists."))
(def (sig (procedure "(result-value RES [COLUMN [ROW]])" (id result-value))) (p "Returns the value at the specified " (tt "COLUMN") " and " (tt "ROW") ".") (p "If " (tt "ROW") " or " (tt "COLUMN") " are not specified, they default to zero. This makes for more convenient syntax if you're just reading out a result of a query which always has one row or even one value."))
(def (sig (procedure "(result-row RES [ROW])" (id result-row))) (p "Returns a list of all the columns' values at the given " (tt "ROW") " number. If " (tt "ROW") " is omitted, it defaults to zero."))
(def (sig (procedure "(result-column RES [COLUMN])" (id result-column))) (p "Returns a list of all the rows' values at the given " (tt "COLUMN") " number. If " (tt "COLUMN") " is omitted, it defaults to zero."))
(def (sig (procedure "(result-row/alist RES [ROW])" (id result-row/alist))) (p "Returns an alist of the values at the given " (tt "ROW") " number.  The keys of the alist are made up by the matching column names, as symbols."))
(def (sig (procedure "(column-name RES INDEX)" (id column-name))) (p "Returns the name of the column (a symbol) at the position in the result set specified by " (tt "INDEX") ".  This is its aliased name in the result set."))
(def (sig (procedure "(column-names RES)" (id column-names))) (p "Returns a list of all the column names (symbols) in the result set. The position in the list reflects the position of the column in the result set."))
