FB_SqlDbRequest

概述

类型：	功能块
最低适用版本：	V2.0.0.0

任务

FB_SqlDbRequest 功能块用于：

o建立到 SQL Gateway 的永久且安全（非安全）的 TCP 连接。有关详细信息，请参阅 ST_ExtendedConnectionSettings。

o执行从 SQL 数据库读取数据的 SQL 请求。返回的数据为二维数组的形式，数据大小通过全局参数定义。

o执行更新或修改 SQL 数据库的 SQL 请求。这些请求不会返回任何数据。

功能描述

启用了功能块后（i_xEnable 设置为 TRUE）的，会使用变量 iq_stExtendedConnSettings 中定义的设置来建立到 SQL Gateway 的 TCP 连接（要么是通过 TLS V1.2 建立的安全连接，要么是非安全连接）。

一旦连接建立，输出 q_xReady 便设置为 TRUE，且功能块能够向 SQL Gateway 发送 SQL 请求，后者再将此请求发送到使用连接名称配置的 SQL 数据库。

若检测到 i_xExecute 的上升沿，则表示功能块正在将 SQL 请求发送至 SQL Gateway 并且正在处理响应。

状态消息和诊断信息使用输出 q_xError（如果检测到错误则为 TRUE）、q_etResult 和 q_etResultMsg 提供。

命令执行失败时显示的诊断消息可以通过将输入 i_xErrorQuit 设置为 TRUE 来确认。功能块保持活动状态，且 TCP 连接不关闭。

与 SQL 数据库的数据交换完成后，禁用此功能块。将 i_xEnable 设置为 FALSE，可关闭连接。

注意：是否支持使用 TLS 建立连接取决于使用 FB_SqlDbRequest 的控制器。请参阅控制器的相应手册，确认是否支持使用 TLS 开展 TCP 通讯。

接口

输入	数据类型	描述
i_xEnable	BOOL	在此输入的上升沿，功能块建立到 SQL Gateway 的连接。如果输入设置为 FALSE，则功能块复位，并关闭现有连接或者中止连接建立操作。有关更多信息，另请参阅功能块在输入 i_xEnable、i_xExecute 和 i_xErrorQuit 下的行为。
i_xExecute	BOOL	这个功能块执行 SQL 请求以便在该输入的上升沿上从 SQL 数据库读取数据或将数据写入到 SQL 数据库。有关更多信息，另请参阅功能块在输入 i_xEnable、i_xExecute 和 i_xErrorQuit 下的行为。
i_xErrorQuit	BOOL	在此输入的上升沿，功能块确认 q_xError 所指示的检出错误。有关更多信息，另请参阅功能块在输入 i_xEnable、i_xExecute 和 i_xErrorQuit 下的行为。
i_etSqlRequest	ET_SqlRequest	定义要执行的 SQL 请求类型（读或写）。默认值：ET_SqlRequest.Read
i_refRequestWstring	REFERENCE TO [RequestWstring]	引用包含一个 SQL 查询请求（读或写）的请求数据。任何 SQL 请求都必须划分成独立的字符串，这些字符串的长度各自不超过 200 个字符。根据应用程序中使用的 SQL 请求的长度，调节全局参数 Gc_uiMaxRequest 和 Gc_uiRequestWstringLength 的大小。注意：如要合并 WSTRINGS，则使用 Standard64 库的 WCONCAT 功能。
i_uiNumOfWstrings	UINT	所需的包含拆分 SQL 请求的 WSTRINGS 的数量。最大数量由全局参数 Gc_uiMaxRequest 限制。
i_refUserData	REFERENCE TO [UserData]	对 UserData 的引用，它在控制器中必须是可用的，以便存储从 SQL 数据库读取的 SQL 数据。

In_Out	数据类型	描述
iq_stExtendedConnSettings	ST_ExtendedConnectionSettings	包含连接 SQL Gateway 时所需的信息。

输出	数据类型	描述
q_xActive	BOOL	指示功能块执行已激活。只要此输出为 TRUE，就必须循环执行功能块。
q_xReady	BOOL	表示初始化已成功且 TCP 连接已建立。只要功能块能够接受输入，该输出便一直指示 TRUE。
q_xBusy	BOOL	如果此输出设置为 TRUE，则正在执行功能块。
q_xDone	BOOL	如果此输出设置为 TRUE，则执行已成功完成。
q_xError	BOOL	如果此输出设置为 TRUE，则检测到错误。有关详细信息，请参阅 q_etResult和 q_etResultMsg。
q_etResult	ET_Result	提供诊断和状态信息。
q_sResultMsg	STRING[255]	提供附加诊断和状态信息。
q_uiRetNumOfRows	UINT	返回数据的行数。根据从 SQL 数据库接收到的记录的数量，来更新这个输出。注意：只有在读取请求处理成功后才有效。
q_uiRetNumOfColumns	UINT	返回数据的列数。根据从 SQL 数据库接收到的记录的数量，来更新这个输出。注意：只有在读取请求处理成功后才有效。

有关更多信息，另请参阅常规输入和输出。

定义用户数据的 ARRAY

二维 ARRAY 在控制器中必须是可用的，以便立即存储从数据库读取的 SQL 数据。二维 ARRAY 在 ALIAS UserData 中定义。

ARRAY 的大小可通过全局参数 Gc_uiMaxRows、Gc_uiMaxColumns 和 Gc_uiTableWstringLength 来调节。

在配置这些参数时，应考虑预期接收的 SQL 数据量。在开始传输数据之前，根据该缓冲区的大小对 SQL 数据分段。

如果所接收的 SQL 数据超出 ARRAY 的大小，则 SQL 数据传输会停止，并且功能块会指示错误。

注意：即使应用程序仅正执行写请求，也必须有有效的二维数组连接到功能块。否则便会发生编译问题。