SEARCH-OPTIONS (alphanumeric)

This property controls how searches are performed in the grid.

Note: The grid's search facility does not contain a user interface. You must supply one if you want to give the user a search function. One typical interface is a pop-up dialog box in which the user can set the search text and options desired. Another typical interface is an entry field in the same window as the grid, with a Find button beside the entry field.

The SEARCH-OPTIONS property should be assigned from a structure with the following layout: 

01 GRID-SEARCH-OPTIONS.
   03 GRID-SEARCH-DIRECTION         PIC 9.
      88 GRID-SEARCH-FORWARDS       VALUE ZERO,
                                    FALSE 1.

   03 GRID-SEARCH-WRAP-FLAG         PIC 9.
      88 GRID-SEARCH-WRAP           VALUE ZERO,
                                    FALSE 1.

   03 GRID-SEARCH-CASE-FLAG         PIC 9.
      88 GRID-SEARCH-IGNORE-CASE    VALUE ZERO,
                                    FALSE 1.

   03 GRID-SEARCH-MATCH-FLAG        PIC 9.
      88 GRID-SEARCH-MATCH-ANY      VALUE ZERO.
      88 GRID-SEARCH-MATCH-LEADING  VALUE 1.
      88 GRID-SEARCH-MATCH-ALL      VALUE 2.

   03 GRID-SEARCH-LOCATION-FLAG     PIC 9.
      88 GRID-SEARCH-VISIBLE        VALUE ZERO.
      88 GRID-SEARCH-HIDDEN         VALUE 1.
      88 GRID-SEARCH-ALL-DATA       VALUE 2.

   03 GRID-SEARCH-SKIP-FLAG         PIC 9.
      88 GRID-SEARCH-SKIP-CURRENT   VALUE ZERO,
                                    FALSE 1.

   03 GRID-SEARCH-CURSOR-FLAG       PIC 9.
      88 GRID-SEARCH-MOVES-CURSOR   VALUE ZERO,
                                    FALSE 1.

   03 GRID-SEARCH-COLUMN            PIC 9(5).
      88 GRID-SEARCH-ALL-COLUMNS    VALUE ZERO.

A copy of this structure can be found in the copy library acugui.def. It contains the default value settings for all the grid search parameters. Use the COPY statement in the Working Storage section to include this structure with its default values in your program.

To set the SEARCH-OPTIONS property, specify the name of the data structure described above in the screen description entry for the grid or via the MODIFY statement. The example below uses the MODIFY statement to assign the property: 

MODIFY GRID-1
SEARCH-OPTIONS = GRID-SEARCH-OPTIONS

To set new search values for a grid, start by using the INQUIRE statement to find out what the current values are (they may have been modified previously). Next, set the desired values to the chosen search parameters with the SETstatement, and finally, modify the grid to apply the new values.

The following sample shows how to change the values for two of the search parameters and apply the new search options to the grid. 

 
INQUIRE grid-1, SEARCH-OPTIONS
       IN GRID-SEARCH-OPTIONS
SET (option-1) TO TRUE
SET (option-2) TO TRUE
MODIFY grid-1,
       SEARCH-OPTIONS = GRID-SEARCH-OPTIONS

The SEARCH-OPTIONS parameters have the following traits:

GRID-SEARCH-FORWARDS When set to true the default, the search runs from left-to-right and top-to-bottom in the grid. This is the default behavior. When set to false, the search runs from right-to-left, bottom-to-top.
GRID-SEARCH-WRAP When set to true (the default), a search wraps around when it hits the top or bottom of the grid. This causes the search to proceed from the opposite end of the grid. When set to false, the search stops if it hits the top or bottom of the grid.
GRID-SEARCH-IGNORE-CASE When set to true (the default), the search ignores case differences between letters when determining if two strings match. When set to false, a difference in case between strings will cause them not to match. You should be certain to set this to "false" when searching for data that contains binary information (this could happen if you search the grid's hidden data).
GRID-SEARCH-MATCH-ANY When set to true (the default), a search string will match if the string is contained anywhere in the cell's data (similar to a substring search). For example, a search for "bcd" would match the string "abcde".
GRID-SEARCH-MATCH-LEADING When set to true, a search string will match if the string forms the beginning of the cell's data. For example, a search for "bcd" would match the string "bcde", but not the string "abcde".
GRID-SEARCH-MATCH-ALL When set to true, a search string matches only if it is identical to the string being searched. For example, "bcd" will match "bcd", but not "abcde" or "bcde".
GRID-SEARCH-VISIBLE When set to true (the default), the search is performed only against the grid's visible cell data.
GRID-SEARCH-HIDDEN When set to true, the search is performed only against the grid's hidden data.
GRID-SEARCH-ALL-DATA When set to true, the search is performed against both the grid's visible and hidden data.
GRID-SEARCH-SKIP-CURRENT When set to true (the default), the cell in which the search starts is not initially searched. If you allow the search to wrap, it will be searched last. If you do not allow the search to wrap, the starting cell will not be searched. This setting allows a find next function to work. When set to false, the starting cell is searched first. Note that if you start the search from a cell that is outside the range of existing cells, the starting cell is searched first regardless of the setting of this flag. This allows you to find the first occurrence of a string by starting your search at row 0 regardless of the setting of this flag.
GRID-SEARCH-MOVES-CURSOR When set to true (the default), the grid's cursor will move to the cell found by the search. The grid will also scroll to make that cell visible. If the search fails, the cursor is not moved. When set to false, the cursor is not moved by a successful search.
GRID-SEARCH-COLUMN When GRID-SEARCH-ALL-COLUMNS is set to true, the search runs through every column in the grid. Otherwise, if you set GRID-SEARCH-COLUMN to a non-zero value, the search runs through that column number only. Columns other than this column are ignored. Note that row and column headings are not normally searched. You can search the row headings by setting GRID-SEARCH-COLUMN to 1 (assuming that you have row headings). You cannot search the column headings.

If you need to limit your search to two or more columns, but not all the columns, you will need to program the limited search yourself by first setting GRID-SEARCH-ALL-COLUMNS and GRID-SEARCH-SKIP-CURRENT to true, and GRID-SEARCH-MOVES-CURSOR to "false". Then perform the search in a loop. Break out of the loop when GRID-SEARCH-COLUMN equals one of the desired columns or when the search fails. The search fails when it does not find a match or the search returns a cell that is the same cell as the first match it returned (in this case, the data you're searching for appears only in cells outside the desired columns). After finding a successful match, you can place the cursor in that cell using the CURSOR-X and CURSOR-Y properties.

The following example turns off wrapping and turns on forward searching for a particular grid. This shows you how to change some settings while leaving others unchanged: 

COPY "acugui.def".
INQUIRE GRID-1, SEARCH-OPTIONS
       IN GRID-SEARCH-OPTIONS
SET GRID-SEARCH-WRAP TO FALSE
SET GRID-SEARCH-FORWARDS TO TRUE
MODIFY GRID-1,
       SEARCH-OPTIONS = GRID-SEARCH-OPTIONS

The default settings are the same as the settings you get by moving ZEROS to the GRID-SEARCH-OPTIONS data structure.

Parent topic: Special Properties