Deprecated Statement Functions

Describes the deprecated statement functions.

Table E-3 lists the deprecated Statement functions that are described in this section.

Table E-3 Deprecated Statement Functions

Function Purpose

OCIStmtFetch()

Fetch rows from a query.

OCIStmtPrepare()

Prepares a SQL or PL/SQL statement for execution.

OCIStmtFetch()

This function was deprecated in a release previous to Oracle 11g R2 (11.2).

Purpose

Fetches rows from a query. This function is deprecated. Use OCIStmtFetch2().

Syntax

sword OCIStmtFetch ( OCIStmt     *stmtp,
                     OCIError    *errhp, 
                     ub4          nrows,
                     ub2          orientation,
                     ub4          mode );

Parameters

stmtp (IN)

A statement (application request) handle.

errhp (IN)

An error handle that you can pass to OCIErrorGet() for diagnostic information when there is an error.

nrows (IN)

Number of rows to be fetched from the current position.

orientation (IN)

Before release 9.0, the only acceptable value is OCI_FETCH_NEXT, which is also the default value.

mode (IN)

Pass as OCI_DEFAULT.

Comments

The fetch call is a local call, if prefetched rows suffice. However, this is transparent to the application.

If LOB columns are being read, LOB locators are fetched for subsequent LOB operations to be performed on these locators. Prefetching is turned off if LONG columns are involved.

This function can return OCI_NO_DATA on EOF and OCI_SUCCESS_WITH_INFO when one of these errors occurs:

  • ORA-24344 - Success with compilation error

  • ORA-24345 - A truncation or NULL fetch error occurred

  • ORA-24347 - Warning of a NULL column in an aggregate function

If you call OCIStmtFetch() with the nrows parameter set to 0, this cancels the cursor.

Use OCI_ATTR_ROWS_FETCHED to find the number of rows that were successfully fetched into the user's buffers in the last fetch call.

OCIStmtPrepare()

Purpose

Prepares a SQL or PL/SQL statement for execution.

Syntax

sword OCIStmtPrepare ( OCIStmt       *stmtp,
                       OCIError      *errhp,
                       const OraText *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 that you can pass to OCIErrorGet() for diagnostic information when there is 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 must be in the encoding specified by the charset parameter of a previous call to OCIEnvNlsCreate().

Always cast the parameter to (text *). After a statement has been prepared in UTF-16, the character set for the bind and define buffers default to UTF-16.

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 as follows:

  • OCI_V7_SYNTAX - V7 ORACLE parsing syntax.

  • OCI_NTV_SYNTAX - Syntax depends upon the version of the server.

    OCI_FOREIGN_SYNTAX - Specifies the statement to be translated according to the SQL translation profile set in the session.

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) or OCI_PREP2_IMPL_RESULTS_CLIENT. The mode should be passed as OCI_PREP2_IMPL_RESULTS_CLIENT when this call is made in an external procedure and implicit results need to be processed. See "OCI Support for Implicit Results" for more details. The statement handle stmtp uses whatever is specified by its parent environment handle.

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 code points or in number of bytes, depending on the encoding.

Although 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 are stored in a bind handle that uses settings in this statement handle as the default.

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

Before reexecuting a DDL statement, call this function a second time.

See Also:

"About Preparing Statements" for more information about using this call