Searches the information catalog to locate instances of a particular object type based on user-defined search criteria.
Authorization
Administrator or user
Syntax
APIRET APIENTRY FLGSearch( PSZ pszObjTypeID,
PFLGHEADERAREA pSelCriteriaStruct,
PFLGHEADERAREA * ppListStruct,
PFLGEXTCODE pExtCode );
Parameters
If this value is NULL, then the Information Catalog Manager returns all instances of the specified object type.
Each instance has the following information:
All instances are sorted by the 80-byte external name (value of Name) in ascending order according to the collating order of the underlying database management system.
The maximum number of object instances that can be returned by FLGSearch is approximately 5000, depending on the storage available on your machine.
If there is no output structure, then the pointer to the output structure is set to NULL.
See Appendix D, Information Catalog Manager reason codes for an explanation of the returned reason codes.
Input structure
To use FLGSearch, you must define the input structure shown in Figure 138. This structure contains only the header area and the definition area.
Figure 138. FLGSearch input structure
The definition area for the FLGSearch input structure must be specified as shown in Figure 138, although you can specify any and all of the properties defined for the object type. You must provide a corresponding search criteria value in the object area for each property specified in the definition area. For an explanation of the meanings of the byte offsets, see The Information Catalog Manager API output structure.
When the database is DB2 UDB for OS/390, the maximum length for search criteria is 254.
Output structure
FLGSearch produces an output structure containing a list of objects retrieved using the search criteria, as shown in Figure 139.
The object area of the output structure contains a list of all the object instances that match the input search criteria. The returned object instances are identified by the values of the FLGID and object instance external name.
Figure 139. FLGSearch output structure
Usage
FLGSearch searches for instances of only one object type. To search for instances of all object types, use the FLGSearchAll API call.
To search for instances of more than one object type, but not all object types, call FLGSearch for each object type that you want to search.
The input structure contains the property specifications and values of the search criterion:
Although you can use different wildcard characters in the user interface, you can only use the % and _ characters with FLGSearch.
Because DB2 databases treat trailing blanks as significant, you should include a wildcard at the end of search criteria on CHAR type properties, otherwise you might receive less objects than you expected from the call to FLGSearch.
If you include wildcard characters in the search criterion, you must set the fuzzy-search flag (fs) to Y.
If your information catalog is located on DB2 UDB for OS/390 and:
Controlling updates to your information catalog
FLGSearch commits changes to the database. Your program should issue FLGCommit or FLGRollback before issuing FLGSearch to ensure that the Information Catalog Manager does not also commit unexpected changes that occurred before the FLGSearch call.
Freeing memory allocated for an output structure
If FLGSearch returned data in the output structure, you must save the data returned in the output structure and then call FLGFreeMem (see FLGFreeMem). Do not use other methods, for example, C language instructions, to free memory.
The sample code in Figure 140 performs a search for glossary instances. This search is an exact search because the fuzzy search flag in byte 129 of the definition area is set to N, as shown in Figure 141. However, the case of the characters in the values (uppercase or lowercase) is not significant because the case-sensitivity flag in byte 128 is set to N. You must have already found the object type identifier using an FLGListObjTypes or FLGGetType call.
Figure 140. Sample C language call to FLGSearch
APIRET rc; // reason code from FLGSearch
UCHAR pszObjTypeID[FLG_OBJTYPID_LEN + 1];
PFLGHEADERAREA pSelCriteria; // search criterion input structure pointer
PFLGHEADERAREA * ppListStruct; // pointer to search result pointer
FLGEXTCODE ExtCode = 0; // Declare extended code
.
. /* provide values for input parameters */
.
strcpy (pszObjTypeID, "000006");
rc = FLGSearch (pszObjTypeID, // Information Catalog Manager object type ID
pSelCriteria, // input structure pointer
ppListStruct, // pass the address of
// output structure pointer
&ExtCode);
Figure 141 shows the search condition input structure(pointed to by pSelCriteria) that carries the property and value information for the search.
The case sensitivity flag at byte 128 and the fuzzy search flag at byte 129 of the definition area must be set to N, because the user wants an exact search, but is not concerned about the case of the property value.
Figure 141. Sample input structure for FLGSearch
Figure 142 shows the output structure (ppListStruct points to the address of the pointer to this output structure) that carries glossary instances as the search result.
Figure 142. Sample output structure for FLGSearch
The CONTEXT value Customer Orders is used as the search criterion. Any glossary instance with this CONTEXT value is returned in the output structure. Because the case-sensitivity flag is set to N, even CONTEXT values like customer orders or CUSTOMER ORDERS would have been returned if they existed.
This example shows how your program can use fuzzy searches to locate instances that contain values fitting a pattern.
The values specified in the input structure shown in Figure 143 specify a wildcard search for glossary instances that contain the letters metadata. The multiple-character wildcards (%) indicate where any other characters can occur in the value and still fit the search criterion.
Figure 143 shows the input structure(pointed to by pSelCriteria) that your program passes to FLGSearch.
Figure 143. Sample input structure for FLGSearch
Because this is a wildcard search, the fuzzy search flag at byte 129 must be set to Y. If the fuzzy search flag is set to N, then the % character becomes a literal part of the search criterion; that is, any instances that are returned must have % in the specified property value.
The case sensitivity flag at byte 128 of the definition area is set to Y because the case of metadata is significant in this example. Figure 144 shows the output structure (ppListStruct points to the address of the pointer to the output structure) that carries glossary instances as the search result.
Figure 144. Sample output structure for FLGSearch
The value of the Definition property, %metadata%, is used as the search criterion. Any glossary instance with a Definition property value containing metadata is returned in the output structure. Because the case sensitivity flag is set to Y, all instances found in the example also match the case of metadata.
This example shows how your program can use fuzzy searches to locate instances that contain values fitting a pattern.
The values specified in the input structure shown in Figure 145 uses the single-character wildcard (_) to search for glossary instances that have the specified property value with only one variable character.
Figure 145 shows the input structure(pointed to by pSelCriteria) that your program passes to FLGSearch.
Figure 145. Sample input structure for FLGSearch
Because the search criterion contains the single-character wildcard (_), the fuzzy search flag at byte 129 must be set to Y. If the fuzzy search flag is set to N, the Information Catalog Manager assumes that _ is a literal part of the search criterion, and only returns object instances that have _ as part of the specified property value.
In this example, the values for both NAME and UPDATIME are used as the search criterion.
Figure 146 shows the output structure (ppListStruct points to the address of the pointer to the output structure) that carries glossary instances as the search result.
Figure 146. Sample output structure for FLGSearch
Any glossary instance with Dept as the prefix for the five-character Name value and updated on the first day of each month in year 1995 is returned in the output structure.