SQL_CONNECTION
Manage PcVue's runtime objects used to handle Sql connections.
WebVue support - Yes.
The use of pre-configured Sql connections along with the instructions SQL_CONNECTION, SQL_COMMAND and SQL_QUERY is preferred to using the verb SVSQL (based on ODBC).
Pre-configured Sql connections are configured in the Application Explorer. See the Data Connections book for information.
Some of the modes are asynchronous. The application developer must ensure that the value of the status variable is monitored and take adequate actions when it changes.
This verb can be executed either locally on the producer station of the Sql connection or from any client station of the producer. In the latter case, commands and returned data are routed transparently through the multi-station messaging system. Multiple connections to the same data source are only allowed if using different Sql Connections. Multiple connections using the same Sql Connection will be refused, however, multiple simultaneous requests using the same Sql Connection is possible.
A connection, and the data associated to it, are managed in the context of user sessions. A connection should only be handled in the context of the session that had originally initiated it; and all related objects must be properly released/closed before the session is ended. For example, it is not possible to initiate a connection at start up and have requests executed in any user context.
Mode | Mnemonic | Syntax |
1 | TESTCONNECTION | 1 |
2 | START | 2 |
3 | STOP | 2 |
Arguments common to more than one mode
Argument |
Meaning |
SqlConnectionName | The name of a Sql connection as configured in General.Data connections in the Application Explorer. Type STR. |
Syntax 1
IntVal = SQL_CONNECTION(Mode, SqlConnectionName, StatusVariable, ErrorTextVariable);
Return type: INTEGER
Argument |
Meaning |
StatusVariable |
The name of the register variable used to monitor the status of an asynchronous operation. Type STR. Succeeded = 0 |
ErrorTextVariable |
The name of a text variable used to return additional information when the status variable value is set to failed (2). Type STR. |
Execution
Mode |
Mnemonic |
Action |
1 | TESTCONNECTION |
Test the connection end-to-end with a Data Source using the specified Sql connection. It is equivalent to the Test connection task available in the Application Explorer. Return: 0 if successful, else a negative number indicating one of the following errors. See the table below for return values. |
This mode is asynchronous. The program must monitor the value of the status variable.
Syntax 2
IntVal = SQL_CONNECTION(Mode, SqlConnectionName);
Return type: INTEGER
Execution
Mode |
Mnemonic |
Action |
2 | START |
Change the specified Sql connection object state to 'started'. No action is performed if it is already started. Return: 0 if successful, else a negative number indicating one of the following errors. See the table below for integer return values. |
3 | STOP |
Change the Sql connection state to 'stopped'. No action is performed if it is already stopped. Return: 0 if successful, else a negative number indicating one of the following errors. See the table below for return values. |
Similar to the state of communication objects, these modes are designed to prevent a Sql connection's producer station to execute actual commands towards the Data Source by giving the application designer the ability to set Sql connections in a state (stopped) in which actual commands are not processed. The modes START and STOP are always executed locally (as opposed to routed to the station producing the Sql connection). As a consequence, they must be executed on producer stations of the Sql connection to be truly effective - as opposed to being executed on stations issuing requests that are routed to the Sql connection producer over the multi-station network.
List of possible return values and meanings
Return value | Enum | Description |
0 | OPERATION_SUCCEEDED | Operation completed successfully |
-1 | SQLCONNAME_PARAM_NOT_STR_OR_NOT_READ | The parameter SqlConnectionName is not of type string or could not be read |
-2 | STATUSVARIABLE_PARAM_NOT_STR_OR_NOT_READ | The parameter StatusVariable is not of type string or could not be read |
-3 | ERRORTEXTVARIABLE_PARAM_NOT_STR_OR_NOT_READ | The parameter ErrorTextVariable is not of type string or could not be read |
-4 |
SQLCON_DOES_NOT_EXIST |
The specified Sql connection does not exist in the configuration |
-5 |
STATUSVARIABLE_NOT_REGISTER_OR_DOES_NOT_EXIST |
The status variable passed as parameter (StatusVariable) is not a register variable or it does not exist |
-6 |
ERRORTEXTVARIABLE_NOT_TEXT_OR_DOES_NOT_EXIST |
The additional information variable passed as parameter (ErrorTextVariable) is not a text variable or it does not exist |
-7 | SEND_COMMAND_FAILED | Failed to send the Sql command. This error occurs if the underlying Windows service is stopped or if the user does not have enough privileges to execute the command |