SQL: ODBC: document extra connection string parameters (#40476)

* document ODBC's extra connection string parameters

Document the connection string parameters that are currently not
configurable from the GUI.

Add a note about SmartScreen possible warning on driver MSI
installation.

Add a note about the TLS certificate file not being supported as bundled
or password-protected.

* rephrasing and restructuring the list of params

- addressing PR review notes

* rephrasings and reference linking

- addressing PR review notes

(cherry picked from commit ca90190226c0a8c63f51c2603b27df299ce8d503)

docs/reference/sql/endpoints/odbc.asciidoc

@@ -9,9 +9,12 @@
 [float]
 === Overview
 
-{odbc} is a feature-rich 3.80 ODBC driver for {es}.
+{odbc} is a 3.80 compliant ODBC driver for {es}.
-It is a core level driver, exposing all of the functionality accessible through the {es}'s SQL ODBC API, converting ODBC calls into
+It is a core level driver, exposing all of the functionality accessible through
-{es-sql}.
+the {es}'s SQL API, converting ODBC calls into {es-sql}.
+
+In order to make use of the driver, the server must have {es-sql} installed and
+running with the valid license.
 
 * <<sql-odbc-installation, Driver installation>>
 * <<sql-odbc-setup, Configuration>>

docs/reference/sql/endpoints/odbc/configuration.asciidoc

@@ -162,6 +162,8 @@ In case the server uses a certificate that is not part of the PKI, for example u
 +
 The driver will only read the contents of the file just before a connection is attempted. See <<connection_testing>> section further on how to check the validity of the provided parameters.
 +
+NOTE: The certificate file can not be bundled or password protected since the driver will not prompt for a password.
++
 If using the file browser to locate the certificate - by pressing the _Browse..._ button - only files with _.pem_ and _.der_ extensions
 will be considered by default. Choose _All Files (\*.*)_ from the drop down, if your file ends with a different extension:
 +
@@ -260,7 +262,95 @@ image:images/sql/odbc/env_var_log.png[]
 
 NOTE: When enabling the logging through the environment variable, the driver will create *one log file per process*.
 
-Both ways of configuring the logging can coexist and both can use the same destination logging directory. However, one logging message
+Both ways of configuring the logging can coexist and both can use the same
-will only be logged once, the connection logging taking precedence over the environment variable logging.
+destination logging directory. However, one logging message will only be logged
+once, the connection logging taking precedence over the environment variable
+logging.
+
+[[odbc-cfg-dsnparams]]
+[float]
+==== Connection string parameters
+
+The following is a list of additional parameters that can be configured for a
+particular connection, in case the default behavior of the driver is not
+suitable. This can be done within the client application, in a manner
+particular to that application, generally in a free text input box (sometimes
+named "Connection string", "String extras", or similar).  The format of the
+string is `Attribute1=Value1`. Multiple attributes can be specified, separated
+by a semicolon `Attribute1=Value1;Attribute2=Value2;`. The attribute names are
+given below.
+
+`Timeout` (default: `0`)::
+The maximum time (in seconds) a request to the server can take. This can be
+overridden by a larger statement-level timeout setting. The value 0 means no
+timeout.
+
+`Follow` (default: `yes`)::
+A boolean value (`yes`|`no` / `true`|`false` / `0`|`1`) controlling if the
+driver will follow HTTP redirects.
+
+
+`MaxFetchSize` (default: `0`)::
+The maximum number of rows that {es-sql} server should send the driver for one
+page. This corresponds to {es-sql}'s request parameter `fetch_size` (see
+<<sql-rest-fields>>). The value 0 means server default.
+
+
+`MaxBodySizeMB` (default: `100`)::
+The maximum size (in megabytes) that an answer can grow to, before being
+rejected as too large by the driver.
+This is concerning the HTTP answer body of one page, not the cumulated data
+volume that a query might generate.
+
+
+`ApplyTZ` (default: `no`)::
+A boolean value controlling the timezone of:
+
+* the context in which the query will execute (especially relevant for functions dealing with timestamp components);
+
+* the timestamps received from / sent to the server.
+If disabled, the UTC timezone will apply; otherwise, the local machine's set
+timezone.
+
+
+`ScientificFloats` (default: `default`)::
+Controls how the floating point numbers will be printed, when these are
+converted to string by the driver. Possible values given to this parameter:
+
+* `scientific`: the exponential notation (ex.: 1.23E01);
+
+* `default`: the default notation (ex.: 12.3);
+
+* `auto`: the driver will choose one of the above depending on the value to be
+printed.
+Note that the number of decimals is dependent on the precision (or ODBC scale)
+of the value being printed and varies with the different floating point types
+supported by {es-sql}.
+This setting is not effective when the application fetches from the driver the
+values as numbers and then does the conversion subsequently itself.
+
+
+`VersionChecking` (default: `strict`)::
+By default, the version of the driver and that of the server must be the same.
+This parameter will allow a driver to connect to a server of different version.
+The variation however can only be of the minor version, both endpoints must be
+of same major version number.
+Possible values:
+
+* `strict`: the versions must be in sync;
+
+* `major`: the versions must have the same major number.
+
+WARNING: This parameter can only be used for troubleshooting purposes. Running
+with versions out of sync is not supported.
+
+
+`MultiFieldLenient` (default: `true`)::
+This boolean parameter controls the behavior of the server in case a
+multi-value field is queried. In case this is set and the server encounters
+such a field, it will pick a value in the set - without any guarantees of what
+that will be, but typically the first in natural ascending order - and return
+it as the value for the column. If not set, the server will return an error.
+This corresponds to {es-sql}'s request parameter `field_multi_value_leniency`
+(see <<sql-rest-fields>>).
 
-// vim: set noet fenc=utf-8 ff=dos sts=0 sw=4 ts=4 tw=138

docs/reference/sql/endpoints/odbc/installation.asciidoc

@@ -21,6 +21,11 @@ If you fail to meet any of the prerequisites the installer will show an error me
 
 NOTE: It is not possible to inline upgrade using the MSI. In order to upgrade, you will first have to uninstall the old driver and then install the new driver.
 
+NOTE: When installing the MSI, the Windows Defender SmartScreen might warn
+about running an unrecognized app. If the MSI has been downloaded from
+Elastic's web site, it is safe to acknowledge the message by allowing the
+installation to continue (`Run anyway`).
+
 [[download]]
 ==== Download the `.msi` package(s)