oosqlPrepare



Prepares a SQL statement to be executed by the database engine. To execute a SQL statement, SQLite first compiles the statement into a byte-code program. This can be thought of as preparing, or initializing the statement.

Arguments: The arguments are:
db [required] The Handle to an oosqlOpen database connection. The handle can not be null and the connection can not have been oosqlClose .
sql [required] The SQL statement to prepare.
_stmt [required] The stringnameof a variable in the Rexx program that will be set to the Handle to the prepared statement. Note that this is the string name of the variable, not the variable itself. The variable may, but does not need to, already exist in the program.
_tail [optional] The stringnameof a variable in the Rexx program that will be set to the value of thetailto the prepared statement. Note that this is the string name of the variable, not the variable itself. The variable may, but does not need to, already exist in the program. SQLite only compiles the first SQL statement insql. That is up to the first semi-colon insql. If_tailis not omitted, the the variable named by_tailto the substring that follows the first semicolon. This may of course be the empty string.
Return value: Returns one of the SQLite Result Code Constants codes. OK on success, otherwise an error code.
Remarks: The variable named by the_stmtargument will always be set on return from this function call. On success this will be a handle to a prepared statement which can be used in any function requiring a prepared statement. On an error return this handle will always be null. Never use a null handle in any function. Each successful call tooosqlPreparemust be matched with a call to oosqlFinalize to prevent resource leaks.oosqlFinalizecan be called at any time afteroosqlPrepare. Normally it would be called when the program is done with the prepared statement. Note thatoosqlFinalizeis one exception to never use a null handle in a function call. It is a harmless no-op to calloosqlFinalizewith a null handle. Never use the prepared statement after it has been finalized. It is a grievous error for the application to try to use a prepared statement after it has been finalized. Any use of a prepared statement after it has been finalized can result in undefined and undesirable behavior such as segfaults and heap corruption. Notethat if thesqlargument is the empty string or contains only a comment the handle to the prepared statement will be null. Experimentation has shown the return code in this case is OK.
Details The functionality of theoosqlPrepare()routine is similar to that of the sqlite3_prepare_v2 SQLite API.
Example: This example creates a handle to a prepared statement and, if there is no error, executes it using the oosqlStep function:
...
ret = oosqlPrepare(dbConn, "SELECT * FROM foods", 'stmt')
if ret == .ooSQLite~OK & \\ oosqlIsHandleNull(stmt) then do
index = oosqlColumnIndex(stmt, 'name')
do while oosqlStep(stmt) == .ooSQLite~ROW
say oosqlColumnText(stmt, index)
end
end