SQL_CONNECTION

Concept Link IconSee also Concept Link IconExample

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
Running = 1
Failed = 2

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.
SQLCONNAME_PARAM_NOT_STR_OR_NOT_READ
STATUSVARIABLE_PARAM_NOT_STR_OR_NOT_READ
STATUSVARIABLE_NOT_REGISTER_OR_DOES_NOT_EXIST
ERRORTEXTVARIABLE_PARAM_NOT_STR_OR_NOT_READ
ERRORTEXTVARIABLE_NOT_TEXT_OR_DOES_NOT_EXIST
SQLCON_DOES_NOT_EXIST
SEND_COMMAND_FAILED

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.
SQLCONNAME_PARAM_NOT_STR_OR_NOT_READ
SQLCON_DOES_NOT_EXIST
SEND_COMMAND_FAILED

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.
SQLCONNAME_PARAM_NOT_STR_OR_NOT_READ
SQLCON_DOES_NOT_EXIST
SEND_COMMAND_FAILED

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