Filtering schema objects based on the search object
The IP can filter the objects that it sends to the OpenAccess SDK SQL engine by looking at a search object, if any, that is passed into the SCHEMA function. This is optional. If the IP does not want to use this information, then it can let the OpenAccess SDK SQL engine handle the required filtering. This is only an issue when an application invokes a catalog function like SQLTables. The search object is of the same type as the schema objects that are requested and contains data members that are set to the values to filter on. For each type of object, there are only a few data members to examine. The IP can examine the search object and build objects for the OpenAccess SDK SQL engine that match the specified filter.
The following table defines the filter object for each type of schema object for C/C++. If you are programming in Java or .NET, refer to the OpenAccess SDK Programmer’s Reference for that language.
Table 31: Search objects and associated fields for C/C++
Schema object type
Associated data structure
Data members to filter on
DAMOBJ_TYPE_TABLE
damobj_table
int table_qualifier_len
char * table_qualifier
int table_owner_len
char * table_owner
int table_name_len
char * table_name
DAMOBJ_TYPE_COLUMN
damobj_column
int table_qualifier_len
char * table_qualifier
int table_owner_len
char * table_owner
int table_name_len
char * table_name
DAMOBJ_TYPE_STAT
damobj_stat
int table_qualifier_len
char * table_qualifier
int table_owner_len
char * table_owner
int table_name_len
char * table_name
DAMOBJ_TYPE_FKEY
damobj_fkey
int pktable_qualifier_len
char * pktable_qualifier
int pktable_owner_len
char * pktable_owner
int pktable_name_len
char * pktable_name
DAMOBJ_TYPE_PROC
damobj_proc
int qualifier_len
char * qualifier
int owner_len
char * owner
int name_len
char * name
DAMOBJ_TYPE_PROC_COLUMN
damobj_proc_column
int qualifier_len
char * qualifier
int owner_len
char * owner
int name_len
char * name
Each data member consists of a value and its length. A member has a valid value if its length is not set to DAM_OBJ_NOTSET. You can check for this by using the macro:
DAMOBJ_IS_SET( pDamobj->member_len)
where pDamobj is the SearchObj typecast to request the type of object, and the member_len is one of the possible data member lengths as defined in Table 31. This function evaluates to true if the member contains a valid value.
A filter value can contain the special characters “_” and “%” which can be interpreted as wildcards or as is. This is based on how the client made the catalog request. For example, if an application calls SQLTables(“VER_DATA”), then the schema function should return all tables with TABLE_NAME starting with the characters "VER", any character in the fourth position, and followed by the characters "DATA" (for example, VERADATA, VERZDATA), VER2DATA).
If the client application needs columns for a table called EMP_DATA, then it would escape the “_” through the call SQLColumns(“EMP_DATA”). In this case the schema function would get EMP_DATA as a filter and should return all columns for the table object EMP_DATA. The IP can determine if a filter value contains “_” or “%”, which should be treated as special pattern-matching characters, by calling dam_isSearchPatternObject. The IP indicates to the OpenAccess SDK SQL engine its ability to handle these special characters for pattern matching by returning TRUE or FALSE when GETINFO(IP_INFO_SUPPORT_SCHEMA_SEARCH_PATTERN) is called. By default, the OpenAccess SDK SQL engine assumes that the IP cannot handle this processing.
When queries on user tables are processed and the IP is called to validate the schema, non-pattern Search Objects are always passed. If pattern values are included in the arguments when queries on schema tables (OA_TABLES, OA_COLUMNS, OA_PROC, OA_PROCCOLUMNS) are processed, the OpenAccess SDK SQL engine sends the pattern-search-object only if the IP supports it. When queries on schema tables do not include any pattern values, the search object is passed to the IP.
1. For regular queries, the IP Schema sees no change and the schema search object is a non-pattern object.
2. For Schema queries, if arguments have search patterns that are escaped, the escape character is removed and a non-pattern search object is passed to the IP:
• SQLColumns(TableName=’EMP\_TABLE’) => IP gets Search Object with TableName=’EMP_TABLE’
• SQLColumns(TableName=’C:\\DATA\\EMP.DBF’) => IP gets Search Object with TableName=’C:\DATA\EMP.DBF’
3. For Schema queries, if arguments have search patterns, a pattern search object is passed to the IP:
• SQLColumns(TableName=’EMP_TABLE’) => IP gets Search Object with TableName=’EMP_TABLE’
• SQLColumns(TableName=’EMP%’) => IP gets Search Object with TableName=’EMP%’
If required, the IP can use dam_strlikecmp to perform pattern matching.
If the IP does not support search pattern handling
2. For each member field to filter on, check the length to see if the field value is specified. For example, check the table_owner field for damobj_table by checking the table_owner_len field using the following code:
if (DAMOBJ_IS_SET(pDamobj->table_owner_len)) {
/* get the value for pDamobj->table_owner and use as the
table_owner in searching for tables*/
}
3. Using the filter data, build schema objects that match the filter criteria and add to the pList sent in with the SCHEMA call dam_add_damobj_table().
