15
OCI Relational Functions

This chapter begins to describe the Oracle OCI relational functions for C. It includes information about calling OCI functions in your application, along with detailed descriptions of each function call.

See Also:

For code examples, see the demonstration programs included with your Oracle installation. For additional information, refer to Appendix B, "OCI Demonstration Programs".

This chapter contains the following sections:

Introduction to the Relational Functions

This chapter describes the OCI relational function calls. This chapter and the next, cover the functions in the basic OCI.

See Also:

For information about return codes and error handling, refer to the section "Error Handling"

Function Syntax

For each function, the following information is listed:

Purpose

A brief description of the action performed by the function.

Syntax

The function declaration.

Parameters

A description of each of the function's parameters. This includes the parameter's mode. The mode of a parameter has three possible values, as described below.

Mode	Description
IN	A parameter that passes data to the OCI
OUT	A parameter that receives data from the OCI on this call
IN/OUT	A parameter that passes data on the call and receives data on the return from this or a subsequent call.

Comments

More detailed information about the function (if available). This may include restrictions on the use of the function, or other information that might be useful when using the function in an application.

Example

A complete or partial code example demonstrating the use of the function call being described. Not all function descriptions include an example.

Related Functions

A list of related function calls.

Calling OCI Functions

Unlike earlier versions of the OCI, in and after release 8, you cannot pass -1 for the string length parameter of a null-terminated string.When you pass string lengths as parameters, do not include the null terminator byte in the length. The OCI does not expect strings to be null-terminated.

Buffer lengths that are OCI parameters are in bytes, except:

the amount parameters in some LOB calls are in characters,
when UTF-16 encoding of text is used in function parameters, the length is in character points.

Server Round-trips for LOB Functions

For a table showing the number of server round-trips required for individual OCI LOB functions, refer to Appendix C, "OCI Function Server Round-trips".

Connect, Authorize, and Initialize Functions

This section describes the OCI connect, authorize, and initialize functions.

Table 15-1 Connect, Authorize, and Initialize Functions

Function	Purpose
`OCIConnectionPoolCreate()`	Initializes the connection pool.
`OCIConnectionPoolDestroy()`	Destroys the connection pool.
`OCIEnvCreate()`	Creates and initializes an OCI environment.
OCIEnvNlsCreate()	Creates and initializes an environment for OCI functions to work under. Allows you to set character set id and national character set id at environment creation time.
`OCIEnvInit()`	Initialize an environment handle
`OCIInitialize()`	Initialize OCI process environment
`OCILogon()`	Simplified single-session logon
`OCILogon2()`	This function is used to create a logon session in various modes.
`OCIServerAttach()`	Attach to a server; initialize server context handle
`OCIServerDetach()` on page 15-30on page 15-30	Detach from a server; uninitialize server context handle
`OCISessionBegin()`	Authenticate a user
`OCISessionEnd()`	Terminate a user session
`OCISessionGet()`	Get a session from a session pool.
`OCISessionPoolCreate()`	Initializes a session pool.
`OCISessionPoolDestroy()`	Destroys a session pool.
`OCISessionRelease()`	Releases a session.
`OCITerminate()`	Detaches from a shared memory subsystem.

15 OCI Relational Functions