From 2530d6756123d277b7785cafffcd9dd059e16806 Mon Sep 17 00:00:00 2001
From: "S.Listl" <S.Listl@SLISTL.aditosoftware.local>
Date: Thu, 30 Jan 2020 12:06:49 +0100
Subject: [PATCH] Sql_lib documentation: added chapter for .build and .toString

---
 process/Sql_lib/documentation.adoc | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/process/Sql_lib/documentation.adoc b/process/Sql_lib/documentation.adoc
index f0e32539c1..1ff588dee8 100644
--- a/process/Sql_lib/documentation.adoc
+++ b/process/Sql_lib/documentation.adoc
@@ -274,6 +274,24 @@ var costData = newSelect("CAMPAIGNCOSTID, CAMPAIGNSTEP_ID, CAMPAIGNSTEP.NAME, CA
 
 `orderBy(pFields)` adds an order by statement to the SQL code. The parameter can be filled the same way as `.select(pFields)`.
 
+=== building the SQL statement
+
+==== prepared array
+
+`.build(pDefaultConditionIfNone)` generates a prepared-statement array from the SqlBuilder in the correct form for several `db.` functions.
+
+==== string
+
+`.toString(pDefaultConditionIfNone)` translates the query into a SQL-string.
+
+==== When to use build and when to use toString
+
+`.build()` has to be called before the statement is given to a `db.` method, like `db.cell()` or `db.table()`. But SqlBuilder also provides own functions for executing the query, if you use these, you don't need `.build()`. These methods are explained in the next chapter. Because of a more concise syntax and additional checks that are done in these functions, you should prefer them over the default `db.` methods.
+
+`.toString()` is for cases where you need the query as string, but you should prefer `.build()` whenever possible. Processes like the "conditionProcess" in a dbRecordContainer and the "expression" from a dbRecordContainer field require a string as result, so you should use it there. If `result.string()` is used, you can omit the `.toString()`, since it would then be called implicitly.
+
+TIP: `.toString()` can be useful for logging, as you get an easy to read SQL string.
+
 === db. function wrappers
 
 ==== select functions
-- 
GitLab