OCIEnquoteName()

The OCIEnquoteName() API is a C callable equivalent to the DBMS_ASSERT function DBMS_ASSERT.ENQUOTE_NAME

Purpose

OCIEnquoteName() returns a valid quoted SQL identifier by ensuring the input is enclosed in double quotes ("...") and validating that the result is a valid SQL identifier. If the input is already in double quotes, no additional quotes are added. This is typically used for identifiers that must be embedded into SQL text (e.g., table names, column names) where bind variables cannot be used.

Syntax

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

Parameters

envhp (IN)

OCI environment handle.

errhp (IN/OUT)

OCI error handle.

in_str (IN)

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

in_str_len (IN)

Length of in_str in bytes.

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 the NULL terminator.
capitalize (IN)

If TRUE, converts the output to uppercase when the input is not already quoted. This aligns with Oracle semantics for unquoted identifiers (which are generally normalized to uppercase).

mode (IN)

Mode of operation (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-44003 - Verification failed. Error message in errhp (Invalid SQL name/identifier)
    • ORA-22620 - Insufficient output buffer.

Usage

Use OCIEnquoteName() when embedding identifiers into dynamic SQL; identifiers cannot be bind variables.

Buffer sizing 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 (str_in) 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, ...)).