Oracle® Call Interface Programmer's Guide, 10g Release 2 (10.2) Part Number B14250-02 |
|
|
View PDF |
The user message API provides a simple interface for cartridge developers to retrieve their own messages as well as Oracle messages.
Table 21-8 lists the OCI messaging functions.
Table 21-8 OCI Messaging Functions
Function/Page | Purpose |
---|---|
|
Closes a message handle and frees any memory asosciated with the handle. |
|
Retrieves a message. If the buffer is not zero, then the function copies the message into the buffer. |
|
Opens a message handle in a specified language. |
Purpose
Closes a message handle and frees any memory associated with this handle.
Syntax
sword OCIMessageClose ( dvoid *hndl, OCIError *errhp, OCIMsg *msgh );
Parameters
Pointer to an OCI environment or user session handle for message language.
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()
.
A pointer to a message handle that was previously opened by OCIMessageOpen()
.
Returns
OCI_SUCCESS
, OCI_INVALID_HANDLE
, or OCI_ERROR
.
Purpose
Gets a message with the given message number.
Syntax
OraText *OCIMessageGet ( OCIMsg *msgh, ub4 msgno, OraText *msgbuf, size_t buflen );
Parameters
Pointer to a message handle which was previously opened by OCIMessageOpen()
.
The message number
Pointer to a destination buffer for the retrieved message. If buflen
is zero, then it can be a NULL
pointer.
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.
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
Pointer to an OCI environment or user session handle for message language.
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()
.
A message handle for return.
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
.
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.
The duration for memory allocation for the return message handle. It can have the following values:
OCI_DURATION_PROCESS
OCI_DURATION_SESSION
OCI_DURATION_STATEMENT
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
.