IDBInfo::GetLiteralInfo

OLE DB Programmer's Reference

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 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, IDBInfo::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 if 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 IDBInfo::GetLiteralInfo, a literal is one of several things, including the following:

A special character or characters used by text commands, such as the character used to quote identifiers. IDBInfo::GetLiteralInfo returns the character or characters.
A literal data value, such as a character literal in an SQL statement. For such literal data values, IDBInfo::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, IDBInfo::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 described in the following table.

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_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_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 IDBInfo::GetLiteralInfo returns information only 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; 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_CONSTRAINT_NAME	A constraint name in a text command.
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 can 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 can 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 can 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, 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.

See Also