FB_SqlDbRead
Task
The FB_SqlDbRead function block is used to perform SQL requests that read data from the SQL database. The return data is provided in a two-dimensional array of data whose size is defined with global parameters.
Functional Description
The FB_SqlDbRead function block is the user-interface for reading data from the SQL database.
After a rising edge on i_xExecute has been detected, a connection to the SQL Gateway is established using the parameters defined in the structure ST_ConnectionSettings. As soon as the connection has been established, the function block is capable of sending an SQL request to the SQL database.
Status messages and diagnostic information are provided using the outputs q_xError (TRUE if an error has been detected), q_etResult, and q_etResultMsg.
Interface
|
Input |
Data type |
Description |
|---|---|---|
|
i_xExecute |
BOOL |
The function block performs an SQL request in order to read data from the SQL database upon rising edge of this input. For more information, also refer to Behavior of Function Blocks with the Input i_xExecute. |
|
i_refRequestWstring |
REFERENCE TO [RequestWstring] |
Reference to the request data that contains one SQL query request (such as Any SQL request must be divided into individual strings that do not exceed a length of 200 characters each. Adapt the size of the global parameters Gc_uiMaxRequest and Gc_uiRequestWstringLength according to the length of the SQL requests that you use in your application.
NOTE: To concatenate WSTRINGS, use the WCONCAT function of Standard64 library.
|
|
i_uiNumOfWstrings |
UINT |
The number of needed WSTRINGS that contain the split SQL request. The maximum number is limited by the global parameter Gc_uiMaxRequest. |
|
i_refUserData |
REFERENCE TO [UserData] |
Reference to the UserData that must be available on the controller for storing the SQL data read from the database. |
|
In_Out |
Data type |
Description |
|---|---|---|
|
iq_stConnSettings |
ST_ConnectionSettings |
Contains the information for connecting to an SQL Gateway and information on the SQL database. |
|
Output |
Data type |
Description |
|---|---|---|
|
q_xBusy |
BOOL |
If this output is set to TRUE, the function block execution is in progress. |
|
q_xDone |
BOOL |
If this output is set to TRUE, the execution has been completed successfully. |
|
q_xError |
BOOL |
If this output is set to TRUE, an error has been detected. For details, refer to q_etResult and q_etResultMsg. |
|
q_etResult |
ET_Result |
Provides diagnostic and status information. |
|
q_sResultMsg |
STRING[255] |
Provides additional diagnostic and status information. |
|
q_uiRetNumOfRows |
UINT |
Number of rows in the returning data. This output is updated with the number of records which was received from the SQL database. |
|
q_uiRetNumOfColumns |
UINT |
Number of columns in the returning data. This output is updated with the number of records which was received from the SQL database. |
For more information, also refer to Common Inputs and Outputs.
Defining an ARRAY of User Data
A two-dimensional ARRAY must be available on the controller for intermediate storage of SQL data read from the database. The two-dimensional ARRAY is defined in ALIAS UserData.
The size of the ARRAY can be adapted via the global parameters Gc_uiMaxRows, Gc_uiMaxColumns, and Gc_uiTableWstringLength.
When you configure these parameters, consider the amount of SQL data that you expect to be received. Before data transfer is started, SQL data is segmented according to the size of this buffer.
If the SQL data that is received exceeds the size of the ARRAY, the SQL data transfer is stopped and the function block signals a detected error.