IDBInfo::GetLiteralInfo

Returns information about literals used in text commands, ITableDefinition, IIndexDefinition, and IOpenRowset, or any interface that takes DBIDs as arguments.

HRESULT GetLiteralInfo(
   ULONG                  cLiterals,
   const DBLITERAL         rgLiterals[],
   ULONG *                  pcLiteralInfo,
   DBLITERALINFO **   prgLiteralInfo,
   OLECHAR **            ppCharBuffer);

Parameters

cLiterals

[in]
The number of literals being asked about. If this is 0, the provider ignores rgLiterals and returns information about all of the literals it supports.

rgLiterals

[in]
An array of cLiterals literals about which to return information. If the consumer specifies an invalid DBLITERAL value in this array, GetLiteralInfo returns FALSE in fSupported in the corresponding element of the *prgLiteralInfo array.

If cLiterals is 0, this parameter is ignored.

pcLiteralInfo

[out]
A pointer to memory in which to return the number of literals for which information was returned. If cLiterals is 0, this is the total number of literals supported by the provider. If an error other than DB_E_ERRORSOCCURRED occurs, *pcLiteralInfo is set to 0.

prgLiteralInfo

[out]
A pointer to memory in which to return a pointer to an array of DBLITERALINFO structures. One structure is returned for each literal. The provider allocates memory for the structures and returns the address to this memory; the consumer releases this memory with IMalloc::Free when it no longer needs the structures. If *pcLiteralInfo is 0 on output or an error other than DB_E_ERRORSOCCURRED occurs, the provider does not allocate any memory and ensures that *prgLiteralInfo is a null pointer on output. For information about DBLITERALINFO structures, see the Comments section.

ppCharBuffer

[out]
A pointer to memory in which to return a pointer for all string values (pwszLiteralValue, pwszInvalidChars, and pwszInvalidStartingChars) within a single allocation block. The provider allocates this memory and the consumer releases it with IMalloc::Free when it no longer needs it. If *pcLiteralInfo is 0 on output or an error occurs, the provider does not allocate any memory and ensures that *ppCharBuffer is a null pointer on output. Each of the individual string values stored in this buffer is terminated by a null-termination character. Therefore, the buffer may contain one or more strings, each with its own null-termination character, and may contain embedded null-termination characters.

Return Code

S_OK
The method succeeded. In each structure returned in *prgLiteralInfo, the fSupported element is set to TRUE.

DB_S_ERRORSOCCURRED
rgLiterals contained at least one unsupported or invalid literal. In the structures returned in *prgLiteralInfo for unsupported or invalid literals, the fSupported element is set to FALSE.

E_FAIL
A provider-specific error occurred.

E_INVALIDARG
cLiterals was not equal to zero and rgLiterals was a null pointer.

pcLiteralInfo, prgLiteralInfo, or ppCharBuffer was a null pointer.

E_OUTOFMEMORY
The provider was unable to allocate sufficient memory in which to return the DBLITERALINFO structures or the strings containing the valid and starting characters.

E_UNEXPECTED
The data source object was in an uninitialized state.

DB_E_ERRORSOCCURRED
All literals were either invalid or unsupported. The provider allocates memory for *prgLiteralInfo and sets the value of the fSupported element in all of the structures to FALSE. The consumer frees this memory when it no longer needs the information.

Comments

In the context of GetLiteralInfo, a literal is one of several things:

A special character or characters used by text commands, such as the character used to quote identifiers. GetLiteralInfo returns the character or characters.
A literal data value, such as a character literal in an SQL statement. For such literal data values, GetLiteralInfo returns the maximum length of the literal in characters, a list of the characters that cannot be used in the literal, and a list of the characters that cannot be used as the first character of the literal.
The name of a database object such as a column or table. For such names, GetLiteralInfo returns the maximum length of the name in characters, a list of the characters that cannot be used in the name, and a list of the characters that cannot be used as the first character of the name.

Information about literals is returned in the DBLITERALINFO structure:

typedef struct tagDBLITERALINFO {
 LPOLESTR  pwszLiteralValue;
 LPOLESTR  pwszInvalidChars;
 LPOLESTR  pwszInvalidStartingChars;
 DBLITERAL lt;
 BOOL    fSupported;
 ULONG   cchMaxLen;
} DBLITERALINFO;

The elements of this structure are used as follows.

Element	Description
pwszLiteralValue	A pointer to a string in the *ppCharBuffer buffer containing the actual literal value. For example, if lt is DBLITERAL_LIKE_PERCENT, and the percent character (%) is used to match zero or more characters in a LIKE clause, this would be "%". This is used for DBLITERAL_CATALOG_SEPARATOR, DBLITERAL_ESCAPE_PERCENT_PREFIX, DBLITERAL_ESCAPE_UNDERSCORE_PREFIX, DBLITERAL_LIKE_PERCENT, DBLITERAL_LIKE_UNDERSCORE, DBLITERAL_QUOTE_PREFIX, and DBLITERAL_SCHEMA_SEPARATOR. For all other DBLITERAL values, pwszLiteralValue is not used and is set to a null pointer.
pwszInvalidChars	A pointer to a string in the *ppCharBuffer buffer containing the characters that are not valid in the literal. For example, if table names can contain anything other than a numeric character, this would be "0123456789" when lt is DBLITERAL_TABLE_NAME. If the literal can contain any valid character, this is a null pointer. This is not used for DBLITERAL_BINARY_LITERAL, DBLITERAL_CATALOG_SEPARATOR, DBLITERAL_ESCAPE_PERCENT_PREFIX, DBLITERAL_ESCAPE_UNDERSCORE_PREFIX, DBLITERAL_LIKE_PERCENT, DBLITERAL_LIKE_UNDERSCORE, DBLITERAL_QUOTE_PREFIX, and DBLITERAL_SCHEMA_SEPARATOR; pwszInvalidChars is set to a null pointer for these DBLITERAL values.
pwszInvalidStartingChars	A pointer to a string in the *ppCharBuffer buffer containing the characters that are not valid as the first character of the literal. If the literal can start with any valid character, this is a null pointer. For example, if table names can begin with anything other than a numeric character, this would be "0123456789" when lt is DBLITERAL_TABLE_NAME. This is not used for DBLITERAL_BINARY_LITERAL, DBLITERAL_CATALOG_SEPARATOR, DBLITERAL_ESCAPE_PERCENT_PREFIX, DBLITERAL_ESCAPE_UNDERSCORE_PREFIX, DBLITERAL_LIKE_PERCENT, DBLITERAL_LIKE_UNDERSCORE, DBLITERAL_QUOTE_PREFIX, and DBLITERAL_SCHEMA_SEPARATOR; pwszInvalidStartingChars is set to a null pointer for these DBLITERAL values.
lt	The literal described in the structure. For more information, see the following section.
fSupported	TRUE if the provider supports the literal specified by lt. If cLiterals is 0, this is always TRUE, because GetLiteralInfo only returns information about literals it supports in this case. FALSE if the provider does not support the literal; or the value of the corresponding element of the rgLiterals array was not a valid value in the DBLITERAL enumerated type.
cchMaxLen	The maximum number of characters in the literal. If there is no maximum or the maximum is unknown, cchMaxLen is set to ~0 (bitwise, the value is not 0; that is, all bits are set to 1). For DBLITERAL_CATALOG_SEPARATOR, DBLITERAL_ESCAPE_PERCENT_PREFIX, DBLITERAL_ESCAPE_UNDERSCORE_PREFIX, DBLITERAL_LIKE_PERCENT, DBLITERAL_LIKE_UNDERSCORE, DBLITERAL_QUOTE_PREFIX, and DBLITERAL_SCHEMA_SEPARATOR, this is the actual number of characters in the literal.

The following values of DBLITERAL are supported.

Value	Description
DBLITERAL_INVALID	An invalid value.
DBLITERAL_ BINARY_LITERAL	A binary literal in a text command.
DBLITERAL_ CATALOG_NAME	A catalog name in a text command.
DBLITERAL_ CATALOG_SEPARATOR	The character that separates the catalog name from the rest of the identifier in a text command.
DBLITERAL_ CHAR_LITERAL	A character literal in a text command.
DBLITERAL_ COLUMN_ALIAS	A column alias in a text command.
DBLITERAL_ COLUMN_NAME	A column name used in a text command or in a data-definition interface.
DBLITERAL_ CORRELATION_NAME	A correlation name (table alias) in a text command.
DBLITERAL_ CURSOR_NAME	A cursor name in a text command.
DBLITERAL_ ESCAPE_PERCENT_PREFIX	The character used in a LIKE clause to escape the character returned for the DBLITERAL_LIKE_PERCENT literal. For example, if a percent sign (%) is used to match zero or more characters and this is a backslash (\), the characters "abc\%%" match all character values that start with "abc%".
	Some SQL dialects support a clause (the ESCAPE clause) that can be used to override this value.
DBLITERAL_ESCAPE_PERCENT_SUFFIX	The escape character, if any, used to suffix the character returned for the DBLITERAL_LIKE_PERCENT literal. For example, if a percent sign (%) is used to match zero or more characters, and percent signs are escaped by enclosing in open and close square brackets, DBLITERAL_ESCAPE_PERCENT_PREFIX is "[", DBLITERAL_ESCAPE_PERCENT_SUFFIX is "]", and the characters "abc[%]%" match all character values that start with "abc%". Providers that do not use a suffix character to escape the DBLITERAL_ESCAPE_PERCENT character do not return this literal value, and set the lt member of the DBLITERAL structure to DBLITERAL_INVALID if requested.
DBLITERAL_ ESCAPE_UNDERSCORE_PREFIX	The character used in a LIKE clause to escape the character returned for the DBLITERAL_LIKE_UNDERSCORE literal. For example, if an underscore (_) is used to match exactly one character and this is a backslash (\), the characters "abc\_ _" match all character values that are five characters long and start with "abc_". Some SQL dialects support a clause (the ESCAPE clause) that can be used to override this value.
DBLITERAL_ESCAPE_UNDERSCORE_SUFFIX	The escape character, if any, used to suffix the character returned for the DBLITERAL_LIKE_UNDERSCORE literal. For example, if an underscore (_) is used to match exactly one character, and underscores are escaped by enclosing in open and close square brackets, DBLITERAL_ESCAPE_UNDERSCORE_PREFIX is "[", DBLITERAL_ESCAPE_UNDERSCORE_SUFFIX is "]", and the characters "abc[_]_" match all character values that are five characters long and start with "abc_". Providers that do not use a suffix character to escape the DBLITERAL_ESCAPE_UNDERSCORE character do not return this literal value, and set the lt member of the DBLITERAL structure to DBLITERAL_INVALID if requested.
DBLITERAL_ INDEX_NAME	An index name used in a text command or in a data-definition interface.
DBLITERAL_ LIKE_PERCENT	The character used in a LIKE clause to match zero or more characters. For example, if this is a percent sign (%), the characters "abc%" match all character values that start with "abc".
DBLITERAL_ LIKE_UNDERSCORE	The character used in a LIKE clause to match exactly one character. For example, if this is an underscore (_), the characters "abc_" match all character values that are four characters long and start with "abc".
DBLITERAL_ PROCEDURE_NAME	A procedure name in a text command.
DBLITERAL_ SCHEMA_NAME	A schema name in a text command.
DBLITERAL_ SCHEMA_SEPARATOR	The character that separates the schema name from the rest of the identifier in a text command.
DBLITERAL_ TABLE_NAME	A table name used in a text command or in a data-definition interface.
DBLITERAL_ TEXT_COMMAND	A text command, such as an SQL statement.
DBLITERAL_ USER_NAME	A user name in a text command.
DBLITERAL_ VIEW_NAME	A view name in a text command.
DBLITERAL_QUOTE_PREFIX	The character used in a text command as the opening quote for quoting identifiers that contain special characters.
DBLITERAL_QUOTE_SUFFIX	The character used in a text command as the closing quote for quoting identifiers that contain special characters. 1.x providers that use the same character as the prefix and suffix may not return this literal value, and set the lt member of the DBLITERAL structure to DBLITERAL_INVALID if requested.

Note If a provider returns non-NULL CATALOG or SCHEMA column values in schema rowsets, then it must support IDBInfo to describe how a fully qualified name is assembled. A provider that does not support IDBInfo must return NULL values for CATALOG and SCHEMA columns in all schema rowsets.