OCIStmtPrepare()

Purpose

This call prepares a SQL or PL/SQL statement for execution.

Syntax

sword OCIStmtPrepare ( OCIStmt       *stmtp,
                       OCIError      *errhp,
                       CONST text    *stmt, 
                       ub4           stmt_len,
                       ub4           language,
                       ub4           mode );

Parameters

stmtp (IN)

A statement handle associated with the statement to be executed. By default, it contains the encoding setting in the environment handle from which it is derived. A statement can be prepared in UTF-16 encoding only in a UTF-16 environment.

errhp (IN)

An error handle you can pass to OCIErrorGet() for diagnostic information in the event of an error.

stmt (IN)

SQL or PL/SQL statement to be executed. Must be a null-terminated string. That is, the ending character is a number of NULL bytes, depending on the encoding. The statement should be in UTF-16 if the environment handle is created with OCI_UTF16 mode.

Always cast the parameter to (text *). After a statement has been prepared in UTF-16, the character set for the bind and define buffers will default to UTF-16. The pointer to the text of the statement must be available as long as the statement is executed, or data is fetched from it.

stmt_len (IN)

Length of the statement in characters or in number of bytes, depending on the encoding. Must not be zero.

language (IN)

Specifies V7, or native syntax. Possible values are:

• OCI_V7_SYNTAX - V7 ORACLE parsing syntax
• OCI_NTV_SYNTAX - syntax depends upon the version of the server.

mode (IN)

Similar to the mode in the OCIEnvCreate() call, but this one has higher priority because it can override the "naturally" inherited mode setting.

The possible values are:

• OCI_DEFAULT - default mode. The statement handle stmtp uses whatever is specified by its parent environment handle.
• OCI_NO_SHARING - disables sharing mode for the SQL statement. See "Shared Data Mode".

Comments

An OCI application uses this call to prepare a SQL or PL/SQL statement for execution. The OCIStmtPrepare() call defines an application request.

The mode parameter determines whether the statement content is encoded as UTF-16 or not. The statement length is in number of codepoints or in number of bytes, depending on the encoding.

While the statement handle inherits the encoding setting from the parent environment handle, the mode for this call can also change the encoding setting for the statement handle itself.

Data values for this statement initialized in subsequent bind calls will be stored in a bind handle which use settings in this statement handle as default.

This call does not create an association between this statement handle and any particular server.

Related Functions

OCIAttrGet(), OCIStmtExecute()