Merge pull request #29436 from taosdata/fix/TD-32471

fix:[TD-32471]set error code to terrno if tmq_consumer_poll return NULL

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

@@ -509,7 +509,7 @@ For the OpenTSDB text protocol, the parsing of timestamps follows its official p
   - **Interface Description**: Used for polling to consume data. Each consumer can only call this interface in a single thread.
     - tmq: [Input] Points to a valid ws_tmq_t structure pointer, which represents a TMQ consumer object.
     - timeout: [Input] Polling timeout in milliseconds, a negative number indicates a default timeout of 1 second.
-  - **Return Value**: Non-`NULL`: Success, returns a pointer to a WS_RES structure, which contains the received message. `NULL`: Failure, indicates no data. WS_RES results are consistent with taos_query results, and information in WS_RES can be obtained through various query interfaces, such as schema, etc.
+  - **Return Value**: Non-`NULL`: Success, returns a pointer to a WS_RES structure, which contains the received message. `NULL`: indicates no data, the error code can be obtained through ws_errno (NULL), please refer to the reference manual for specific error message. WS_RES results are consistent with taos_query results, and information in WS_RES can be obtained through various query interfaces, such as schema, etc.
 
 - `int32_t ws_tmq_consumer_close(ws_tmq_t *tmq)`
   - **Interface Description**: Used to close the ws_tmq_t structure. Must be used in conjunction with ws_tmq_consumer_new.
@@ -1195,7 +1195,7 @@ In addition to using SQL or parameter binding APIs to insert data, you can also
   - **Interface Description**: Used to poll for consuming data, each consumer can only call this interface in a single thread.
     - tmq: [Input] Points to a valid tmq_t structure pointer, representing a TMQ consumer object.
     - timeout: [Input] Polling timeout in milliseconds, a negative number indicates a default timeout of 1 second.
-  - **Return Value**: Non-`NULL`: Success, returns a pointer to a TAOS_RES structure containing the received messages. `NULL`: Failure, indicates no data. TAOS_RES results are consistent with taos_query results, and information in TAOS_RES can be obtained through various query interfaces, such as schema, etc.
+  - **Return Value**: Non-`NULL`: Success, returns a pointer to a TAOS_RES structure containing the received messages. `NULL`: indicates no data, the error code can be obtained through taos_errno (NULL), please refer to the reference manual for specific error message. TAOS_RES results are consistent with taos_query results, and information in TAOS_RES can be obtained through various query interfaces, such as schema, etc.
 
 - `int32_t tmq_consumer_close(tmq_t *tmq)`
   - **Interface Description**: Used to close a tmq_t structure. Must be used in conjunction with tmq_consumer_new.

docs/en/14-reference/09-error-code.md

@@ -534,4 +534,7 @@ This document details the server error codes that may be encountered when using
 | 0x80004000 | Invalid message       | The subscribed data is illegal, generally does not occur     | Check the client-side error logs for details |
 | 0x80004001 | Consumer mismatch     | The vnode requested for subscription and the reassigned vnode are inconsistent, usually occurs when new consumers join the same consumer group | Internal error, not exposed to users         |
 | 0x80004002 | Consumer closed       | The consumer no longer exists                                | Check if it has already been closed          |
+| 0x80004017 | Invalid status, please subscribe topic first | tmq status invalidate                 | Without calling subscribe, directly poll data     |
+| 0x80004018 | TMQ poll timeout | timeout is too small or there is no data to consume               | Adjust the timeout parameter appropriately or check if the data has been consumed     |
 | 0x80004100 | Stream task not exist | The stream computing task does not exist                     | Check the server-side error logs             |
+

docs/zh/14-reference/05-connector/10-cpp.mdx

@@ -509,7 +509,7 @@ TDengine 推荐数据库应用的每个线程都建立一个独立的连接，
   - **接口说明**：用于轮询消费数据，每一个消费者，只能单线程调用该接口。
     - tmq：[入参] 指向一个有效的 ws_tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
     - timeout：[入参] 轮询的超时时间，单位为毫秒，负数表示默认超时1秒。
-  - **返回值**：非 `NULL`：成功，返回一个指向 WS_RES 结构体的指针，该结构体包含了接收到的消息。`NULL`：失败，表示没有数据。WS_RES 结果和 taos_query 返回结果一致，可通过查询的各种接口获取 WS_RES 里的信息，比如 schema 等。
+  - **返回值**：非 `NULL`：成功，返回一个指向 WS_RES 结构体的指针，该结构体包含了接收到的消息。`NULL`：表示没有数据, 可通过 ws_errno(NULL) 获取错误码，具体错误码参见参考手册。WS_RES 结果和 taos_query 返回结果一致，可通过查询的各种接口获取 WS_RES 里的信息，比如 schema 等。
 
 - `int32_t ws_tmq_consumer_close(ws_tmq_t *tmq)`
   - **接口说明**：用于关闭 ws_tmq_t 结构体。需与 ws_tmq_consumer_new 配合使用。
@@ -1187,7 +1187,7 @@ TDengine 的异步 API 均采用非阻塞调用模式。应用程序可以用多
   - **接口说明**：用于轮询消费数据，每一个消费者，只能单线程调用该接口。
     - tmq：[入参] 指向一个有效的 tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
     - timeout：[入参] 轮询的超时时间，单位为毫秒，负数表示默认超时1秒。
-  - **返回值**：非 `NULL`：成功，返回一个指向 TAOS_RES 结构体的指针，该结构体包含了接收到的消息。。`NULL`：失败，表示没有数据。TAOS_RES 结果和 taos_query 返回结果一致，可通过查询的各种接口获取 TAOS_RES 里的信息，比如 schema 等。
+  - **返回值**：非 `NULL`：成功，返回一个指向 TAOS_RES 结构体的指针，该结构体包含了接收到的消息。。`NULL`：表示没有数据，可通过taos_errno(NULL) 获取错误码，具体错误码参见参考手册。TAOS_RES 结果和 taos_query 返回结果一致，可通过查询的各种接口获取 TAOS_RES 里的信息，比如 schema 等。
 
 - `int32_t tmq_consumer_close(tmq_t *tmq)`
   - **接口说明**：用于关闭 tmq_t 结构体。需与 tmq_consumer_new 配合使用。

docs/zh/14-reference/09-error-code.md

@@ -554,5 +554,7 @@ description: TDengine 服务端的错误码列表和详细说明
 | 0x80004000 | Invalid message       | 订阅到的数据非法，一般不会出现                                                   | 具体查看client端的错误日志提示 |
 | 0x80004001 | Consumer mismatch     | 订阅请求的vnode和重新分配的vnode不一致，一般存在于有新消费者加入相同消费者组里时 | 内部错误，不暴露给用户         |
 | 0x80004002 | Consumer closed       | 消费者已经不存在了                                                               | 查看是否已经close掉了          |
+| 0x80004017 | Invalid status, please subscribe topic first | 数据订阅状态不对                                                                 | 没有调用 subscribe，直接poll数据     |
+| 0x80004018 | TMQ poll timeout | 数据订阅超时，超时时间太短，或者数据消费完毕                                                               | 可适当调大timeout 参数或者检测数据是否消费完毕     |
 | 0x80004100 | Stream task not exist | 流计算任务不存在                                                                 | 具体查看server端的错误日志     |
 

include/common/tcommon.h

@@ -123,6 +123,10 @@ enum {
   TMQ_MSG_TYPE__POLL_BATCH_META_RSP,
 };
 
+static char* tmqMsgTypeStr[] = {
+    "data", "meta", "ask ep", "meta data", "wal info", "batch meta"
+};
+
 enum {
   STREAM_INPUT__DATA_SUBMIT = 1,
   STREAM_INPUT__DATA_BLOCK,

include/util/taoserror.h

@@ -47,6 +47,7 @@ const char* terrstr();
 
 char*    taosGetErrMsgReturn();
 char*    taosGetErrMsg();
+void     taosClearErrMsg();
 int32_t* taosGetErrno();
 int32_t* taosGetErrln();
 int32_t  taosGetErrSize();
@@ -1014,6 +1015,8 @@ int32_t  taosGetErrSize();
 #define TSDB_CODE_TMQ_REPLAY_NOT_SUPPORT         TAOS_DEF_ERROR_CODE(0, 0x4014)
 #define TSDB_CODE_TMQ_NO_TABLE_QUALIFIED         TAOS_DEF_ERROR_CODE(0, 0x4015)
 #define TSDB_CODE_TMQ_NO_NEED_REBALANCE          TAOS_DEF_ERROR_CODE(0, 0x4016)
+#define TSDB_CODE_TMQ_INVALID_STATUS             TAOS_DEF_ERROR_CODE(0, 0x4017)
+#define TSDB_CODE_TMQ_POLL_TIMEOUT               TAOS_DEF_ERROR_CODE(0, 0x4018)
 
 // stream
 #define TSDB_CODE_STREAM_TASK_NOT_EXIST          TAOS_DEF_ERROR_CODE(0, 0x4100)

source/client/src/clientRawBlockWrite.c

@@ -2572,6 +2572,7 @@ int32_t tmq_write_raw(TAOS* taos, tmq_raw_data raw) {
     SET_ERROR_MSG("taos:%p or data:%p is NULL or raw_len <= 0", taos, raw.raw);
     return TSDB_CODE_INVALID_PARA;
   }
+  taosClearErrMsg(); // clear global error message
 
   return writeRawImpl(taos, raw.raw, raw.raw_len, raw.raw_type);
 }