Input arguments on catalog functions

Input arguments identify or constrain the amount of information that a catalog function returns.

All of the catalog functions include the input arguments CatalogName and SchemaName (and their associated lengths). Catalog functions can also include the input arguments TableName, ProcedureName, and ColumnName (and their associated lengths). CatalogName, however, must always be a null pointer (with its length set to 0) because Db2 ODBC does not support three-part naming.

Each input argument is described either as a pattern-value argument or an ordinary argument. Argument descriptions vary between catalog functions. For example, SQLColumnPrivileges() treats SchemaName and TableName as ordinary arguments, whereas SQLTables() treats these arguments as pattern-value arguments.

Ordinary arguments are inputs that are taken literally. These arguments are case-sensitive. Ordinary arguments do not qualify a query, but rather they explicitly identify the input information. If you pass a null pointer to this type of argument, the results are unpredictable.

Pattern-value arguments constrain the size of the result set as though the underlying query were qualified by a WHERE clause. If you pass a null pointer to a pattern-value input, that argument is not used to restrict the result set (that is, no WHERE clause restricts the query). If a catalog function has more than one pattern-value input argument, these arguments are treated as though the WHERE clauses in the underlying query were joined by AND. A row appears in the result set only if it meets the conditions of all pattern-value arguments that the catalog function specifies.

Each pattern-value argument can contain:
  • The underscore (_) character, which stands for any single character.
  • The percent (%) character, which stands for any sequence of zero or more characters.
  • Characters that stand for themselves. The case of a letter is significant.

These argument values are used on conceptual LIKE predicates in the WHERE clause. To treat metadata characters (_ and %) literally, you must include an escape character immediately before the _ or % character. To use the escape character itself as a literal part of a pattern-value argument, include the escape character twice in succession. You can determine the escape character that an ODBC driver uses by calling SQLGetInfo() with the InfoType argument set to SQL_SEARCH_PATTERN_ESCAPE.

You can use catalog functions with EBCDIC, Unicode, and ASCII encoding schemes. The CURRENTAPPENSCH keyword in the initialization file determines which one of these encoding schemes you use. For EBCDIC, Unicode UTF-8, and ASCII input strings use generic catalog functions. For UCS-2 input strings, use suffix-W catalog functions. For each generic catalog function, a corresponding suffix-W API provides UCS-2 support.