docs: add taos_print_row desc

docs/en/14-reference/05-connector/10-cpp.md

@@ -327,6 +327,15 @@ This section introduces APIs that are all synchronous interfaces. After being ca
     - res: [Input] Result set.
   - **Return Value**: Non-`NULL`: Success, returns a pointer to a TAOS_FIELD_E structure, where each element represents the metadata of a column. `NULL`: Failure.
 
+- `int taos_print_row(char *str, TAOS_ROW row, TAOS_FIELD *fields, int num_fields)`
+
+  - **Interface Description**: Formats a row of query results as text according to column types and writes it to the `str` buffer for logging or debugging output.
+  - **Parameter Description**:
+    - `str`: [Output] A user-provided character buffer that receives the entire line of formatted text. Ensure that the capacity meets the output requirements. If the result exceeds the buffer size, it will be truncated (possibly incomplete output).
+    - `fields`: [Input] An array of column metadata, returned by `taos_fetch_fields()`. Used to format each column according to its column type.
+    - `num_fields`: [Input] The number of columns, typically the return value of `taos_num_fields()`.
+  - **Return Value**: `>=0` indicates the number of characters actually written to `str` (excluding the trailing `'\0'`); `<0` indicates a failure error code.
+
 - `void taos_stop_query(TAOS_RES *res)`
 
   - **Interface Description**: Stops the execution of the current query.

docs/examples/c-ws-new/query_data_demo.c

@@ -43,7 +43,8 @@ static int DemoQueryData() {
 
   TAOS_ROW    row = NULL;
   int         rows = 0;
-  int         num_fields = taos_field_count(result);
+  char        buffer[1024];
+  int         num_fields = taos_num_fields(result);
   TAOS_FIELD *fields = taos_fetch_fields(result);
 
   fprintf(stdout, "query successfully, got %d fields, the sql is: %s.\n", num_fields, sql);
@@ -53,6 +54,15 @@ static int DemoQueryData() {
     // Add your data processing logic here
 
     rows++;
+
+    // Print the data for easy debugging. You can uncomment them if needed.
+    // code = taos_print_row(buffer, row, fields, num_fields);
+    // if (code > 0) {
+    //   fprintf(stdout, "row %d: %s\n", rows, buffer);
+    // } else {
+    //   fprintf(stderr, "Failed to print row %d data, ErrCode: 0x%x, ErrMessage: %s\n", rows, taos_errno(NULL),
+    //           taos_errstr(NULL));
+    // }
   }
   fprintf(stdout, "total rows: %d\n", rows);
   taos_free_result(result);

docs/examples/c-ws-new/tmq_demo.c

@@ -78,6 +78,7 @@ void* prepare_data(void* arg) {
 
 // ANCHOR: msg_process
 int32_t msg_process(TAOS_RES* msg) {
+  char        buffer[1024];
   int32_t     rows = 0;
   const char* topicName = tmq_get_topic_name(msg);
   const char* dbName = tmq_get_db_name(msg);
@@ -91,6 +92,17 @@ int32_t msg_process(TAOS_RES* msg) {
     // Add your data processing logic here
 
     rows++;
+
+    // Print the data for easy debugging. You can uncomment them if needed.
+    // int         num_fields = taos_num_fields(msg);
+    // TAOS_FIELD* fields = taos_fetch_fields(msg);
+    // int         code = taos_print_row(buffer, row, fields, num_fields);
+    // if (code > 0) {
+    //   fprintf(stdout, "row %d: %s\n", rows, buffer);
+    // } else {
+    //   fprintf(stderr, "Failed to print row %d data, ErrCode: 0x%x, ErrMessage: %s\n", rows, taos_errno(NULL),
+    //           taos_errstr(NULL));
+    // }
   }
 
   return rows;

docs/examples/c-ws-new/with_reqid_demo.c

@@ -44,7 +44,8 @@ static int DemoWithReqId() {
 
   TAOS_ROW    row = NULL;
   int         rows = 0;
-  int         num_fields = taos_field_count(result);
+  char        buffer[1024];
+  int         num_fields = taos_num_fields(result);
   TAOS_FIELD *fields = taos_fetch_fields(result);
 
   fprintf(stdout, "query successfully, got %d fields, the sql is: %s.\n", num_fields, sql);
@@ -54,6 +55,15 @@ static int DemoWithReqId() {
     // Add your data processing logic here
 
     rows++;
+
+    // Print the data for easy debugging. You can uncomment them if needed.
+    // code = taos_print_row(buffer, row, fields, num_fields);
+    // if (code > 0) {
+    //   fprintf(stdout, "row %d: %s\n", rows, buffer);
+    // } else {
+    //   fprintf(stderr, "Failed to print row %d data, ErrCode: 0x%x, ErrMessage: %s\n", rows, taos_errno(NULL),
+    //           taos_errstr(NULL));
+    // }
   }
   fprintf(stdout, "total rows: %d\n", rows);
   taos_free_result(result);

docs/examples/c/query_data_demo.c

@@ -34,7 +34,7 @@ static int DemoQueryData() {
   TAOS *taos = taos_connect(host, user, password, NULL, port);
   if (taos == NULL) {
     fprintf(stderr, "Failed to connect to %s:%hu, ErrCode: 0x%x, ErrMessage: %s.\n", host, port, taos_errno(NULL),
-           taos_errstr(NULL));
+            taos_errstr(NULL));
     taos_cleanup();
     return -1;
   }
@@ -45,15 +45,16 @@ static int DemoQueryData() {
   code = taos_errno(result);
   if (code != 0) {
     fprintf(stderr, "Failed to query data from power.meters, sql: %s, ErrCode: 0x%x, ErrMessage: %s\n.", sql, code,
-           taos_errstr(result));
+            taos_errstr(result));
     taos_close(taos);
     taos_cleanup();
     return -1;
   }
 
   TAOS_ROW    row = NULL;
   int         rows = 0;
-  int         num_fields = taos_field_count(result);
+  char        buffer[1024];
+  int         num_fields = taos_num_fields(result);
   TAOS_FIELD *fields = taos_fetch_fields(result);
 
   fprintf(stdout, "query successfully, got %d fields, the sql is: %s.\n", num_fields, sql);
@@ -63,6 +64,15 @@ static int DemoQueryData() {
     // Add your data processing logic here
 
     rows++;
+
+    // Print the data for easy debugging. You can uncomment them if needed.
+    // code = taos_print_row(buffer, row, fields, num_fields);
+    // if (code > 0) {
+    //   fprintf(stdout, "row %d: %s\n", rows, buffer);
+    // } else {
+    //   fprintf(stderr, "Failed to print row %d data, ErrCode: 0x%x, ErrMessage: %s\n", rows, taos_errno(NULL),
+    //           taos_errstr(NULL));
+    // }
   }
   fprintf(stdout, "total rows: %d\n", rows);
   taos_free_result(result);
@@ -74,6 +84,4 @@ static int DemoQueryData() {
   // ANCHOR_END: query_data
 }
 
-int main(int argc, char *argv[]) {
-  return DemoQueryData();
-}
+int main(int argc, char *argv[]) { return DemoQueryData(); }

docs/examples/c/tmq_demo.c

@@ -41,17 +41,15 @@ typedef struct {
   const char* auto_offset_reset;
 } ConsumerConfig;
 
-ConsumerConfig config = {
-  .enable_auto_commit = "true",
-  .auto_commit_interval_ms = "1000",
-  .group_id = "group1",
-  .client_id = "client1",
-  .td_connect_host = "localhost",
-  .td_connect_port = "6030",
-  .td_connect_user = "root",
-  .td_connect_pass = "taosdata",
-  .auto_offset_reset = "latest"
-};
+ConsumerConfig config = {.enable_auto_commit = "true",
+                         .auto_commit_interval_ms = "1000",
+                         .group_id = "group1",
+                         .client_id = "client1",
+                         .td_connect_host = "localhost",
+                         .td_connect_port = "6030",
+                         .td_connect_user = "root",
+                         .td_connect_pass = "taosdata",
+                         .auto_offset_reset = "latest"};
 
 void* prepare_data(void* arg) {
   const char* host = "localhost";
@@ -61,7 +59,8 @@ void* prepare_data(void* arg) {
   int         code = 0;
   TAOS*       pConn = taos_connect(host, user, password, NULL, port);
   if (pConn == NULL) {
-    fprintf(stderr, "Failed to connect to %s:%hu, ErrCode: 0x%x, ErrMessage: %s.\n", host, port, taos_errno(NULL), taos_errstr(NULL));
+    fprintf(stderr, "Failed to connect to %s:%hu, ErrCode: 0x%x, ErrMessage: %s.\n", host, port, taos_errno(NULL),
+            taos_errstr(NULL));
     taos_cleanup();
     return NULL;
   }
@@ -81,7 +80,8 @@ void* prepare_data(void* arg) {
     pRes = taos_query(pConn, buf);
     code = taos_errno(pRes);
     if (code != 0) {
-      fprintf(stderr, "Failed to insert data to power.meters, ErrCode: 0x%x, ErrMessage: %s.\n", code, taos_errstr(pRes));
+      fprintf(stderr, "Failed to insert data to power.meters, ErrCode: 0x%x, ErrMessage: %s.\n", code,
+              taos_errstr(pRes));
     }
     taos_free_result(pRes);
     sleep(1);
@@ -93,9 +93,10 @@ void* prepare_data(void* arg) {
 // ANCHOR: msg_process
 int32_t msg_process(TAOS_RES* msg) {
   int32_t     rows = 0;
+  char        buffer[1024];
   const char* topicName = tmq_get_topic_name(msg);
-  const char* dbName    = tmq_get_db_name(msg);
-  int32_t     vgroupId  = tmq_get_vgroup_id(msg);
+  const char* dbName = tmq_get_db_name(msg);
+  int32_t     vgroupId = tmq_get_vgroup_id(msg);
 
   while (true) {
     // get one row data from message
@@ -105,6 +106,17 @@ int32_t msg_process(TAOS_RES* msg) {
     // Add your data processing logic here
 
     rows++;
+
+    // Print the data for easy debugging. You can uncomment them if needed.
+    // int         num_fields = taos_num_fields(msg);
+    // TAOS_FIELD* fields = taos_fetch_fields(msg);
+    // int         code = taos_print_row(buffer, row, fields, num_fields);
+    // if (code > 0) {
+    //   fprintf(stdout, "row %d: %s\n", rows, buffer);
+    // } else {
+    //   fprintf(stderr, "Failed to print row %d data, ErrCode: 0x%x, ErrMessage: %s\n", rows, taos_errno(NULL),
+    //           taos_errstr(NULL));
+    // }
   }
 
   return rows;
@@ -119,7 +131,8 @@ TAOS* init_env() {
   int         code = 0;
   TAOS*       pConn = taos_connect(host, user, password, NULL, port);
   if (pConn == NULL) {
-    fprintf(stderr, "Failed to connect to %s:%hu, ErrCode: 0x%x, ErrMessage: %s.\n", host, port, taos_errno(NULL), taos_errstr(NULL));
+    fprintf(stderr, "Failed to connect to %s:%hu, ErrCode: 0x%x, ErrMessage: %s.\n", host, port, taos_errno(NULL),
+            taos_errstr(NULL));
     taos_cleanup();
     return NULL;
   }
@@ -172,13 +185,12 @@ TAOS* init_env() {
 }
 
 void deinit_env(TAOS* pConn) {
-  if (pConn)
-    taos_close(pConn);
+  if (pConn) taos_close(pConn);
 }
 
 int32_t create_topic(TAOS* pConn) {
-  TAOS_RES*   pRes;
-  int         code = 0;
+  TAOS_RES* pRes;
+  int       code = 0;
 
   if (!pConn) {
     fprintf(stderr, "Invalid input parameter.\n");
@@ -193,7 +205,9 @@ int32_t create_topic(TAOS* pConn) {
   }
   taos_free_result(pRes);
 
-  pRes = taos_query(pConn, "CREATE TOPIC IF NOT EXISTS topic_meters AS SELECT ts, current, voltage, phase, groupid, location FROM meters");
+  pRes = taos_query(
+      pConn,
+      "CREATE TOPIC IF NOT EXISTS topic_meters AS SELECT ts, current, voltage, phase, groupid, location FROM meters");
   code = taos_errno(pRes);
   if (code != 0) {
     fprintf(stderr, "Failed to create topic topic_meters, ErrCode: 0x%x, ErrMessage: %s.\n", code, taos_errstr(pRes));
@@ -204,8 +218,8 @@ int32_t create_topic(TAOS* pConn) {
 }
 
 int32_t drop_topic(TAOS* pConn) {
-  TAOS_RES*   pRes;
-  int         code = 0;
+  TAOS_RES* pRes;
+  int       code = 0;
 
   if (!pConn) {
     fprintf(stderr, "Invalid input parameter.\n");
@@ -231,7 +245,7 @@ int32_t drop_topic(TAOS* pConn) {
 }
 
 void tmq_commit_cb_print(tmq_t* tmq, int32_t code, void* param) {
-  count +=1;
+  count += 1;
   fprintf(stdout, "tmq_commit_cb_print() code: %d, tmq: %p, param: %p, count: %d.\n", code, tmq, param, count);
 }
 
@@ -313,8 +327,9 @@ tmq_list_t* build_topic_list() {
   if (code) {
     // if failed, destroy the list and return NULL
     tmq_list_destroy(topicList);
-    fprintf(stderr, "Failed to create topic_list, topic: %s, groupId: %s, clientId: %s, ErrCode: 0x%x, ErrMessage: %s.\n",
-          topic_name, config.group_id, config.client_id, code, tmq_err2str(code));
+    fprintf(stderr,
+            "Failed to create topic_list, topic: %s, groupId: %s, clientId: %s, ErrCode: 0x%x, ErrMessage: %s.\n",
+            topic_name, config.group_id, config.client_id, code, tmq_err2str(code));
     return NULL;
   }
   // if success, return the list
@@ -370,13 +385,13 @@ void consume_repeatly(tmq_t* tmq) {
 
     code = tmq_offset_seek(tmq, topic_name, p->vgId, p->begin);
     if (code != 0) {
-      fprintf(stderr, "Failed to seek offset, topic: %s, groupId: %s, clientId: %s, vgId: %d, ErrCode: 0x%x, ErrMessage: %s.\n",
+      fprintf(stderr,
+              "Failed to seek offset, topic: %s, groupId: %s, clientId: %s, vgId: %d, ErrCode: 0x%x, ErrMessage: %s.\n",
               topic_name, config.group_id, config.client_id, p->vgId, code, tmq_err2str(code));
       break;
     }
   }
-  if (code == 0)
-    fprintf(stdout, "Assignment seek to beginning successfully.\n");
+  if (code == 0) fprintf(stdout, "Assignment seek to beginning successfully.\n");
 
   // free the assignment array
   tmq_free_assignment(pAssign);
@@ -402,7 +417,8 @@ void manual_commit(tmq_t* tmq) {
       // commit the message
       int32_t code = tmq_commit_sync(tmq, tmqmsg);
       if (code) {
-        fprintf(stderr, "Failed to commit offset, topic: %s, groupId: %s, clientId: %s, ErrCode: 0x%x, ErrMessage: %s.\n",
+        fprintf(stderr,
+                "Failed to commit offset, topic: %s, groupId: %s, clientId: %s, ErrCode: 0x%x, ErrMessage: %s.\n",
                 topic_name, config.group_id, config.client_id, code, tmq_err2str(code));
         // free the message
         taos_free_result(tmqmsg);
@@ -451,22 +467,23 @@ int main(int argc, char* argv[]) {
             config.td_connect_host, config.group_id, config.client_id);
     return -1;
   } else {
-    fprintf(stdout, "Create consumer successfully, host: %s, groupId: %s, clientId: %s.\n", 
-            config.td_connect_host, config.group_id, config.client_id);
+    fprintf(stdout, "Create consumer successfully, host: %s, groupId: %s, clientId: %s.\n", config.td_connect_host,
+            config.group_id, config.client_id);
   }
 
   // ANCHOR_END: create_consumer_2
 
   // ANCHOR: subscribe_3
   tmq_list_t* topic_list = build_topic_list();
   if (NULL == topic_list) {
-    fprintf(stderr, "Failed to create topic_list, topic: %s, groupId: %s, clientId: %s.\n",
-            topic_name, config.group_id, config.client_id);
+    fprintf(stderr, "Failed to create topic_list, topic: %s, groupId: %s, clientId: %s.\n", topic_name, config.group_id,
+            config.client_id);
     return -1;
   }
 
   if ((code = tmq_subscribe(tmq, topic_list))) {
-    fprintf(stderr, "Failed to subscribe topic_list, topic: %s, groupId: %s, clientId: %s, ErrCode: 0x%x, ErrMessage: %s.\n",
+    fprintf(stderr,
+            "Failed to subscribe topic_list, topic: %s, groupId: %s, clientId: %s, ErrCode: 0x%x, ErrMessage: %s.\n",
             topic_name, config.group_id, config.client_id, code, tmq_err2str(code));
   } else {
     fprintf(stdout, "Subscribe topics successfully.\n");
@@ -485,7 +502,8 @@ int main(int argc, char* argv[]) {
   // unsubscribe the topic
   code = tmq_unsubscribe(tmq);
   if (code) {
-    fprintf(stderr, "Failed to unsubscribe consumer, topic: %s, groupId: %s, clientId: %s, ErrCode: 0x%x, ErrMessage: %s.\n",
+    fprintf(stderr,
+            "Failed to unsubscribe consumer, topic: %s, groupId: %s, clientId: %s, ErrCode: 0x%x, ErrMessage: %s.\n",
             topic_name, config.group_id, config.client_id, code, tmq_err2str(code));
   } else {
     fprintf(stdout, "Consumer unsubscribed successfully.\n");

docs/examples/c/with_reqid_demo.c

@@ -54,7 +54,8 @@ static int DemoWithReqId() {
 
   TAOS_ROW    row = NULL;
   int         rows = 0;
-  int         num_fields = taos_field_count(result);
+  char        buffer[1024];
+  int         num_fields = taos_num_fields(result);
   TAOS_FIELD *fields = taos_fetch_fields(result);
 
   fprintf(stdout, "query successfully, got %d fields, the sql is: %s.\n", num_fields, sql);
@@ -64,6 +65,15 @@ static int DemoWithReqId() {
     // Add your data processing logic here
 
     rows++;
+
+    // Print the data for easy debugging. You can uncomment them if needed.
+    // code = taos_print_row(buffer, row, fields, num_fields);
+    // if (code > 0) {
+    //   fprintf(stdout, "row %d: %s\n", rows, buffer);
+    // } else {
+    //   fprintf(stderr, "Failed to print row %d data, ErrCode: 0x%x, ErrMessage: %s\n", rows, taos_errno(NULL),
+    //           taos_errstr(NULL));
+    // }
   }
   fprintf(stdout, "total rows: %d\n", rows);
   taos_free_result(result);