<Source>.PrepareSQLQuery (Function)

ONLINE HELP
WINDEV, WEBDEV AND WINDEV MOBILE

Version:

Home | Sign in | English

Help / WLanguage / Managing databases / HFSQL / HFSQL functions

When to use <Source>.PrepareSQLQuery?
How to use the <Source>.PrepareSQLQuery function?
Condition on a composite key in an SQL query

WINDEV

WEBDEV

WINDEV Mobile

Others

See also

<Source>.PrepareSQLQuery (Function)

In french: <Source>.PrépareRequêteSQL

Available only with this kind of connection

Initializes a query written in SQL language and declares this query to the database server in order to optimize the next executions of this query. This query is not run. Then, the query can be run with <Source>.ExecuteSQLQuery. This function is available for queries with or without bind.

To free the resources of this query, use <Source>.CancelDeclaration.

We recommend that you use this function when the same query is run successively and when only some of the query parameters are modified at each execution.

This function is optional and it can only be used on the Client/Server databases (available for Oracle, Oracle Lite, Sybase and SQL Server). In SQL Server, Native Connector via OLE DB or ODBC may be required.

For the other databases accessed by a Native Connector, OLEDB or ODBC, <Source>.PrepareSQLQuery runs the query.

This function cannot be used on the HFSQL databases (HFSQL Classic or Client/Server) and on the xBase databases.

Example

// Exécution d'une même requête sous Oracle
// Déclaration d'une source de données
// Cette source de données correspond à la requête
Insert1 is Data Source
i is int
// Déclaration d'un des paramètres de la requête
// Le type de ce paramètre est un entier
Insert1.Age = 0
// Préparation de la requête pour de multiples exécutions
Insert1.PrépareRequêteSQL(ConnexionBase, ...
	hQueryWithoutCorrection, "INSERT INTO PERSONE VALUES (:nom, :prenom, :age )")
// Boucle d'exécution de la requête
// Seuls quelques paramètres sont modifiés
FOR i = 1 TO 10
	Insert1.nom = "Nom" + i
	Insert1.prenom = "Prenom" + i
	Insert1.Age = i
	Insert1.ExecuteSQLQuery()
END

Syntax

<Result> = <Source>.PrepareSQLQuery(<Connection> , <Mode> , <SQL query text>)

<Result>: Boolean

True if no problem occurred,
False otherwise. HErrorInfo returns more details about the problem.

<Source>: Data source

Name of the Data Source variable that corresponds to the request to initialize.

<Connection>: Character string

Name of connection used to run the query. This connection corresponds to:
the name of the connection defined in the data model editor or with HDescribeConnection or <Connection variable>.OpenConnection.
the name of a variable of type Connection.
<Result> is set to False if this parameter does not correspond to an existing connection.

<Mode>: Integer constant

hQueryWithoutCorrection Native connector only: No verification is performed by the HFSQL engine on the query text.

<SQL query text>: Character string

Text of the SQL query to execute.

Remarks

When to use <Source>.PrepareSQLQuery?

In some cases, it may be interesting to run the same query several times while modifying one or more variables. For example, you may want to run an Insert query several times to add several records into a file.

Several solutions can be implemented:

Execute the query directly (with <Source>.ExecuteSQLQuery) as many times as necessary, and modify the desired variable(s) each time.
Prepare the query to be executed (<Source>.PrepareSQLQuery) as well as the different variables to be modified. Then, execute the query as many times as necessary with <Source>.ExecuteSQLQuery. This second solution is much faster and optimizes the query result traversal time (in the case of a selection query).

SQL Server: Limits The function <Source>.PrepareSQLQuery function cannot be used to prepare a stored procedure that returns records. You must use <Source>.ExecuteSQLQuery.

How to use the <Source>.PrepareSQLQuery function?

To prepare and execute a query multiple times:

Declare a data source. This data source will contain the result of the SQL query.
Declare the different variables of the query.
The variables are string variables by default. You can specify their type by using the Type property with the variable.
Prepare the query with <Source>.PrepareSQLQuery.
Specify the value of the different parameters to take into account and run the query with <Source>.ExecuteSQLQuery. Only the name of the data source that corresponds to the query must be specified.

This last step must be repeated as many times as necessary.

Remarks:

<Source>.PrepareSQLQuery must be used with:
- the connection name,
- the hQueryWithoutCorrection constant.
The declared variables must be identical to the ones used. Otherwise, a WLanguage error occurs.
In the call to the stored procedure, you must use the syntax specific to the database used, including for the syntax of parameters.
Therefore, for Oracle, the parameters are specified with the :ParamName syntax. Warning: the ":" character must be followed by at least one letter (:1 syntax is forbidden).
In SQL Server, the parameters are specified via the following notation: @ParamName.
The same parameter can be used several times. In this case, the corresponding variable will be reused.

Condition on a composite key in an SQL query

To define a condition on a composite key in an SQL query, the conditions must be specified for each component of the key.

Do not attempt to directly assign a value to the composite key (indeed, the composite keys are stored as binary values).

Example: The composite key is made of LASTNAME and FIRSTNAME items (LASTNAMEFIRSTNAME item):

SELECT AFile.AnItem, AFile.AnItem1
FROM AFile
WHERE AFile.LastName = "Clark" AND AFile.FirstName = "Vince"

Component: wd300hf.dll