OCIEnquoteLiteral()

The OCIEnquoteLiteral() API is a C callable equivalent to the DBMS_ASSERT function DBMS_ASSERT.ENQUOTE_LITERAL

Purpose

OCIEnquoteLiteral() returns a SQL string literal derived from the input by ensuring it is enclosed in single quotes ('...') and verifying that all single quotes, except leading and trailing characters, are paired with adjacent single quotes. If the input is already quoted as a literal, no additional quotes are added.

Syntax

sword OCIEnquoteLiteral(
    OCIEnv   *envhp,
    OCIError *errhp,
    oratext  *in_str,
    ub4       in_str_len,
    oratext  *out_str,
    ub4      *out_str_len,
    ub4       mode
);

Parameters

envhp (IN)

OCI environment handle that determines character set and OCI runtime context.

errhp (IN/OUT)

OCI error handle. On error, contains diagnostic information including the ORA error code.

in_str (IN)

Input string buffer (not required to be NULL-terminated).

in_str_len (IN)

Length of in_str in bytes (or code units per OCI conventions for the environment charset).

out_str (IN/OUT)

Output buffer to receive the enquoted literal (NULL-terminated on success).

out_str_len (IN/OUT)

IN: Size of out_str buffer.

OUT: actual size of result output string, including NULL terminated string.

mode (IN)

Mode of operation. (reserved/implementation-defined)

Returns

Returns one of the following:
  • OCI_SUCCESS - Verification succeeded; out_str contains the result; *out_str_len stores the length of result output string.
  • OCI_ERROR -
    • ORA-6502 - Verification failed. Error message in errhp (invalid literal quoting/format)
    • ORA-22620 - Insufficient output buffer.

Usage

Use OCIEnquoteLiteral() only when you must embed a literal into SQL text; otherwise prefer bind variables for values.

Buffer Size Requirement

The caller must allocate sufficient space for out_str. Example of minimum recommended buffer size:
  • (size of out_str) >= (size of in_str + 2 (quotes) + 1 (null-terminator)) unless the input is already quoted and null-terminated.

Comments

  • The input string does not need to be null-terminated.
  • Input (in_str) can be ASCII or UTF-16 charset depending on the environment (envhp) configuration.
  • For UTF-16 charset, the environment must be created using OCI_UTF16 mode. (for example, with OCIEnvCreate(..., OCI_UTF16, ...)).