Skip Headers

Oracle® Call Interface Programmer's Guide
10g Release 1 (10.1)

Part Number B10779-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Feedback

Go to previous page
Previous
Go to current chapter
Up
Go to next page
Next
View PDF

OCI Messaging Functions

The user message API provides a simple interface for cartridge developers to retrieve their own messages as well as Oracle messages.

See Also:

Oracle Data Cartridge Developer's Guide

Table 21-8 lists the OCI messaging functions.

Table 21-8 OCI Messaging Functions  
Function/Page Purpose

OCIMessageClose()

Closes a message handle and frees any memory asosciated with the handle.

OCIMessageGet()

Retrieves a message. If the buffer is not zero, then the function copies the message into the buffer.

OCIMessageOpen()

Opens a message handle in a specified language.

OCIMessageClose()

Purpose

Closes a message handle and frees any memory associated with this handle.

Syntax

sword OCIMessageClose ( dvoid     *hndl, 
                        OCIError  *errhp, 
                        OCIMsg    *msgh );

Parameters

hndl (IN/OUT)

Pointer to an OCI environment or user session handle for message language.

errhp (IN/OUT)

The OCI error handle. If there is an error, then it is recorded in errhp and the function returns a NULL pointer. Diagnostic information can be obtained by calling OCIErrorGet().

msgh (IN/OUT)

A pointer to a message handle that was previously opened by OCIMessageOpen().

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR.

OCIMessageGet()

Purpose

Gets a message with the given message number.

Syntax

OraText *OCIMessageGet ( OCIMsg      *msgh, 
                         ub4         msgno, 
                         OraText     *msgbuf, 
                         size_t      buflen );

Parameters

msgh (IN/OUT)

Pointer to a message handle which was previously opened by OCIMessageOpen().

msgno (IN)

The message number

msgbuf (OUT)

Pointer to a destination buffer for the retrieved message. If buflen is zero, then it can be a NULL pointer.

buflen (IN)

The size of the destination buffer.

Comments

If buflen is not zero, then the function copies the message into the buffer pointed to by msgbuf. If buflen is zero, then the message is copied into a message buffer inside the message handle pointed to by msgh.

Returns

It returns the pointer to the NULL-terminated message string. If the translated message cannot be found, then it tries to return the equivalent English message. If the equivalent English message cannot be found, then it returns a NULL pointer.

OCIMessageOpen()

Purpose

Opens a message-handling facility in a specified language.

Syntax

sword OCIMessageOpen ( dvoid            *hndl, 
                       OCIError         *errhp, 
                       OCIMsg           *msghp, 
                       CONST OraText    *product, 
                       CONST OraText    *facility, 
                       OCIDuration      dur );

Parameters

hndl (IN/OUT)

Pointer to an OCI environment or user session handle for message language.

errhp (IN/OUT)

The OCI error handle. If there is an error, then it is recorded in errhp, and the function returns a NULL pointer. Diagnostic information can be obtained by calling OCIErrorGet().

msghp (OUT)

A message handle for return.

product (IN)

A pointer to a product name. The product name is used to locate the directory for messages. Its location depends on the operating system. For example, in Solaris, the directory of message files for the rdbms product is $ORACLE_HOME/rdbms.

facility (IN)

A pointer to a facility name in the product. It is used to construct a message file name. A message file name follows the conversion with facility as prefix. For example, the message file name for the img facility in the American language is imgus.msb, where us is the abbreviation for the American language and msb is the message binary file extension.

dur (IN)

The duration for memory allocation for the return message handle. It can have the following values:

Comments

It first tries to open the message file corresponding to hndl. If it succeeds, then it uses that file to initialize a message handle. If it cannot find the message file that corresponds to the language, then it looks for a primary language file as a fallback. For example, if the Latin American Spanish file is not found, then it tries to open the Spanish file. If the fallback fails, then it uses the default message file, whose language is AMERICAN. The function returns a pointer to a message handle into the msghp parameter.

Returns

OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR.