Merge pull request #685 from taosdata/feature/prepare

documentation of statement preparation API

documentation/webdocs/markdowndocs/Connector.md

@@ -8,7 +8,7 @@ C/C++ APIs are similar to the MySQL APIs. Applications should include TDengine h
 ```C
 #include <taos.h>
 ```
-Make sure TDengine library _libtaos.so_ is installed and use _-ltaos_ option to link the library when compiling. The return values of all APIs are _-1_ or _NULL_ for failure.
+Make sure TDengine library _libtaos.so_ is installed and use _-ltaos_ option to link the library when compiling. In most cases, if the return value of an API is integer, it return _0_ for success and other values as an error code for failure; if the return value is pointer, then _NULL_ is used for failure.
 
 
 ### C/C++ sync API
@@ -78,6 +78,51 @@ The 12 APIs are the most important APIs frequently used. Users can check _taos.h
 
 **Note**: The connection to a TDengine server is not multi-thread safe. So a connection can only be used by one thread.
 
+### C/C++ parameter binding API
+
+TDengine also provides parameter binding APIs, like MySQL, only question mark `?` can be used to represent a parameter in these APIs.
+
+- `TAOS_STMT* taos_stmt_init(TAOS *taos)`
+
+  Create a TAOS_STMT to represent the prepared statement for other APIs.
+
+- `int taos_stmt_prepare(TAOS_STMT *stmt, const char *sql, unsigned long length)`
+
+  Parse SQL statement _sql_ and bind result to _stmt_ , if _length_ larger than 0, its value is used to determine the length of _sql_, the API auto detects the actual length of _sql_ otherwise.
+
+- `int taos_stmt_bind_param(TAOS_STMT *stmt, TAOS_BIND *bind)`
+
+  Bind values to parameters. _bind_ points to an array, the element count and sequence of the array must be identical as the parameters of the SQL statement. The usage of _TAOS_BIND_ is same as _MYSQL_BIND_ in MySQL, its definition is as below:
+
+  ```c
+  typedef struct TAOS_BIND {
+    int            buffer_type;
+    void *         buffer;
+    unsigned long  buffer_length;  // not used in TDengine
+    unsigned long *length;
+    int *          is_null;
+    int            is_unsigned;    // not used in TDengine
+    int *          error;          // not used in TDengine
+  } TAOS_BIND;
+  ```
+
+- `int taos_stmt_add_batch(TAOS_STMT *stmt)`
+
+  Add bound parameters to batch, client can call `taos_stmt_bind_param` again after calling this API. Note this API only support _insert_ / _import_ statements, it returns an error in other cases.
+
+- `int taos_stmt_execute(TAOS_STMT *stmt)`
+
+  Execute the prepared statement. This API can only be called once for a statement at present.
+
+- `TAOS_RES* taos_stmt_use_result(TAOS_STMT *stmt)`
+
+  Acquire the result set of an executed statement. The usage of the result is same as `taos_use_result`, `taos_free_result` must be called after one you are done with the result set to release resources.
+
+- `int taos_stmt_close(TAOS_STMT *stmt)`
+
+  Close the statement, release all resources.
+
+
 ### C/C++ async API
 
 In addition to sync APIs, TDengine also provides async APIs, which are more efficient. Async APIs are returned right away without waiting for a response from the server, allowing the application to continute with other tasks without blocking. So async APIs are more efficient, especially useful when in a poor network.

documentation/webdocs/markdowndocs/connector-ch.md

@@ -4,13 +4,13 @@ TDengine提供了丰富的应用程序开发接口，其中包括C/C++、JAVA、
 
 ## C/C++ Connector
 
-C/C++的API类似于MySQL的C API。应用程序使用时，需要包含TDengine头文件 _taos.h_（安装后，位于_/usr/local/taos/include_）：
+C/C++的API类似于MySQL的C API。应用程序使用时，需要包含TDengine头文件 _taos.h_（安装后，位于 _/usr/local/taos/include_）：
 
 ```C
 #include <taos.h>
 ```
 
-在编译时需要链接TDengine动态库_libtaos.so_（安装后，位于/usr/local/taos/driver，gcc编译时，请加上 -ltaos）。 所有API都以返回_-1_或_NULL_均表示失败。
+在编译时需要链接TDengine动态库 _libtaos.so_ （安装后，位于 _/usr/local/taos/driver_，gcc编译时，请加上 -ltaos）。 如未特别说明，当API的返回值是整数时，_0_ 代表成功，其它是代表失败原因的错误码，当返回值是指针时， _NULL_ 表示失败。
 
 ### C/C++同步API
 
@@ -79,6 +79,51 @@ C/C++的API类似于MySQL的C API。应用程序使用时，需要包含TDengine
 
 **注意**：对于单个数据库连接，在同一时刻只能有一个线程使用该链接调用API，否则会有未定义的行为出现并可能导致客户端crash。客户端应用可以通过建立多个连接进行多线程的数据写入或查询处理。
 
+### C/C++ 参数绑定接口
+
+除了直接调用 `taos_query` 进行查询，TDengine也提供了支持参数绑定的Prepare API，与 MySQL 一样，这些API目前也仅支持用问号`?`来代表待绑定的参数，具体如下：
+
+- `TAOS_STMT* taos_stmt_init(TAOS *taos)`
+
+  创建一个 TAOS_STMT 对象用于后续调用。
+
+- `int taos_stmt_prepare(TAOS_STMT *stmt, const char *sql, unsigned long length)`
+
+  解析一条sql语句，将解析结果和参数信息绑定到stmt上，如果参数length大于0，将使用此此参数作为sql语句的长度，如等于0，将自动判断sql语句的长度。
+
+- `int taos_stmt_bind_param(TAOS_STMT *stmt, TAOS_BIND *bind)`
+
+  进行参数绑定，bind指向一个数组，需保证此数组的元素数量和顺序与sql语句中的参数完全一致。TAOS_BIND 的使用方法与 MySQL中的 MYSQL_BIND 一致，具体定义如下：
+
+  ```c
+  typedef struct TAOS_BIND {
+    int            buffer_type;
+    void *         buffer;
+    unsigned long  buffer_length;  // 未实际使用
+    unsigned long *length;
+    int *          is_null;
+    int            is_unsigned;    // 未实际使用
+    int *          error;          // 未实际使用
+  } TAOS_BIND;
+  ```
+
+- `int taos_stmt_add_batch(TAOS_STMT *stmt)`
+
+  将当前绑定的参数加入批处理中，调用此函数后，可以再次调用`taos_stmt_bind_param`绑定新的参数。需要注意，此函数仅支持 insert/import 语句，如果是select等其他SQL语句，将返回错误。
+
+- `int taos_stmt_execute(TAOS_STMT *stmt)`
+
+  执行准备好的语句。目前，一条语句只能执行一次。
+
+- `TAOS_RES* taos_stmt_use_result(TAOS_STMT *stmt)`
+
+  获取语句的结果集。结果集的使用方式与非参数化调用时一致，使用完成后，应对此结果集调用 `taos_free_result`以释放资源。
+  
+- `int taos_stmt_close(TAOS_STMT *stmt)`
+
+  执行完毕，释放所有资源。
+
+
 ### C/C++异步API
 
 同步API之外，TDengine还提供性能更高的异步调用API处理数据插入、查询操作。在软硬件环境相同的情况下，异步API处理数据插入的速度比同步API快2~4倍。异步API采用非阻塞式的调用方式，在系统真正完成某个具体数据库操作前，立即返回。调用的线程可以去处理其他工作，从而可以提升整个应用的性能。异步API在网络延迟严重的情况下，优点尤为突出。