The old search constraints are used, but their values (the parameters) are read again from the user buffers. This allows you to increase performance in situations where you want to repeat a search using a query that is identical except for the specific values used.
For example, suppose that a particular user or connection always searches a particular table based on the ID column in that table, but uses a different ID value in each search. Instead of creating a "new" query to search for the next ID, you can reset the existing query and use a new value.
As an example, suppose that your existing code looks similar to the following example:
/* Bind variable(s) to column(s). */ SaCursorColInt(scur, "MY_COL_NAME", &search_parameter1);
/* Repeat a query using different values each time. */ while (there_are_more_values_to_look_for) { /* Set the parameter to the value that you want to search for. */ search_parameter1 = some_value; /* Specify the search criterion. */ rc = SaCursorEqual(scur, "MY_COL_NAME"); /* Create new query that uses that search criterion and paramvalue */ rc = SaCursorSearch(scur); /* Get the row (or rows) that match the search criteria. */ rc = SaCursorNext(scur); /* Process the retrieved data... */ foo(); ... /* Get rid of the old query before the next loop iteration. */ rc = SaCursorClearConstr(scur); } ...
You can improve performance in most cases by changing your code to look like the following example:
... /* Bind variable(s) to column(s). */ SaCursorColInt(scur, "MY_COL_NAME", &search_parameter1);
/* Create a new query. */ rc = SaCursorEqual(scur, "MY_COL_NAME"); rc = SaCursorSearch(scur);
/* Set the parameter to the value that you want to search for. */ search_parameter1 = some_value;
/* Repeat a query using different values each time. */ while (there_are_more_values_to_look_for) { /* Get the row (or rows) that match the search criteria. */ rc = SaCursorNext(scur); /* Process the retrieved data... */ foo(); ...
/* Set the param to the next value that you want to search for. */ search_parameter1 = some_value; /* Reset the existing query to use the latest value in the param. */ rc = SaCursorSearchReset(scur); } ...
When you use SaCursorSearchReset(), you no longer have to re-specify the constraint condition ("Equal", in the example above) and call SaCursorSearch() each time.
SaCursorSearchReset resets the cursor to the beginning of the new result set. For example, if you reset a search with no constraints at all, it will reposition the cursor to the beginning of the table.
Note Ensure that you update the values of the search parameters in the buffers before you call this function; the new values are read during this function call.
Limitations
1 SaCursorSearchReset() can not be used in the following scenarios:
▪ The search has a local sort (not all sorting criteria could be solved by the index used for the search)
▪ The search is done by rowid with SaCursorSearchByRowid
In these cases, SaCursorSearchReset returns SA_ERR_NORESETSEARCH.
2 Each "like" value that you use in constraints must be the same length. The reason for this is that SaCursorLike() takes the length of the "like" constraint as an argument, but it is not possible to change this length when SaCursorSearchReset() is called. For example, the function will work correctly if you use the following sequence of "like" values, because they are all the same length:
"SMITH" "JONES"
However, the function will not work correctly if you use the following sequence of "like" values:
"SMITH" "JOHNSON"
3 Using SaCursorSearchReset is usually impractical if you set multiple constraints using the same column binding. For example, suppose that you want to search for values of "col" in the range between 1 and 10 (inclusive). Your code would look like the following example:
SaCursorColInt(scur, "col", &i); i = 1; SaCursorAtleast(scur, "col"); i = 10; SaCursorAtmost(scur, "col");
If you reset a search like this, the new value for the column is read from the variable i only one time. Therefore, the server reads one value and uses it as both the upper and lower bound. For example, suppose that you use the following code:
i = 5; SaCursorSearchReset(scur);
This code makes the search 5 <= i <= 5, which is not the desired result.