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.

Search objects and associated fields for C/C++

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 Search objects and associated fields for C/C++. 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.

If the IP enables schema search pattern handling

OAIP_getInfo(IP_INFO_SUPPORT_SCHEMA_SEARCH_PATTERN) => TRUE

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

OAIP_getInfo(IP_INFO_SUPPORT_SCHEMA_SEARCH_PATTERN) => FALSE

1. For regular queries, the IP Schema sees no change.
2. For Schema queries, if arguments have search patterns, the search object is not passed to the IP and escape characters are removed.
   • SQLColumns(TableName=’EMP_TABLE’) => IP gets Search Object with TableName=’EMP_TABLE’
   • SQLColumns(TableName=’EMP%’) => IP does not get a search object
   • SQLColumns(TableName=’C:\DATA\EMP.DBF’) => IP gets Search Object with TableName=’C:\DATA\EMP.DBF’

How the IP accesses a search object

Here the damobj_table object is used as an example.

1. Typecast the SearchObj passed in the SCHEMA call to the type of object that is being requested. Assume damobj_table in this case:

   damobj_table * pDamobj = (damobj_table *) SearchObj

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().