OCIStmtPrepare2()

Purpose

This call prepares a SQL or PL/SQL statement for execution. The user has the option of using the statement cache, if it has been enabled.

Syntax

sword OCIStmtPrepare2 ( OCISvcCtx      *svchp,
                        OCIStmt        **stmthp,
                        OCIError       *errhp,
                        CONST OraText  *stmttext,
                        ub4            stmt_len,
                        CONST OraText  *key,
                        ub4            keylen,
                        ub4            language,
                        ub4            mode );

Parameters

svchp (IN)

The service context to be associated with the statement.

errhp (IN)

A pointer to the error handle for diagnostics.

stmthp (OUT)

Pointer to the statement handle returned.

stmttext (IN)

The statement text. The semantics of the stmttext are same as that of OCIStmtPrepare, i.e, the string should be null-terminated.

stmt_len (IN)

The statement text length.

key (IN)

For statement caching only. The key to the returned statement in the cache. This can be used for future calls to OCIStmtPrepare2(), in which case there is no need to pass in the statement text and related parameters. If the key is passed in, then the statement text and other parameters are ignored and the search is solely based on the key.

keylen (IN)

For statement caching only. The length of the key.

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)

This function can be used with and without statement caching. This is determined at the time of connection or session pool creation. If caching is enabled for a session, then all statements in the session will have caching enabled, and if caching is not enabled, then all statements will not be cached.

The valid modes are:

• OCI_DEFAULT - For non-caching, this is the only valid setting. If the statement is not found in the cache, it allocates a new statement handle and prepares the statement handle for execution. If it is not found and
  • (a) Only the text has been supplied: a new statement will be allocated and prepared and returned. The tag will be null. OCI_SUCCESS will be returned.
  • (b) Only the tag has been supplied: stmthp will be null. OCI_ERROR will be returned.
  • (c) Both text and key were supplied: a new statement will be allocated and prepared and returned. The tag will be null. OCI_SUCCESS_WITH_INFO will be returned, as the returned statement differs from the requested statement in that the tag is null.
• OCI_STMTCACHE_SEARCH_ONLY - In this case, if the statement is not found (a NULL statement handle is returned), you must take further action. If the statement is found, OCI_SUCCESS will be returned. Otherwise, OCI_ERROR will be returned.

Related Functions

OCIStmtRelease()