Find_record()
Provides a search function for values in a table field data set.
Syntax
returnfield = [callproc] find_record(
[form = formname, ]
[table_field = tablefieldname, ]
[column = columnname, ]
[value = value, ]
[noscroll = noscroll ] )
The following are optional keyword parameters for the find_record() procedure:
returnfield
Specifies the name of an integer field into which the result is returned
formname
Specifies a string expression whose value is the name of the form containing the table field to be searched. Default: the current form. If you specify formname, you must also specify both the tablefieldname and columnname parameters for find_record().
tablefieldname
Specifies a string expression whose value is the name of the table field to be searched. Default: the current table field. Required if the cursor is not on a table field. If you specify tablefieldname, you also must specify columnname.
columnname
Specifies a string expression whose value is the name of the column to be searched. This column must be of same type as value. Default: the column on which the cursor is positioned. Required if the cursor is not on a table field.
value
Specifies an expression (of any type) that specifies the value that is the object of the search. Must be of same type as column being searched. Can be a pattern-match string, if the column is a string type. If not specified, find_record prompts user for a value.
noscroll
Indicates whether to scroll to the matching data set record. If 0, scroll to the matching data set record. If non-zero, do not scroll. Can be used to find out if a record is in the data set without showing the record. The default is to scroll.
Description
The 4GL find_record() procedure searches a column of a table field for the first record after the current one that matches an input value, and scrolls to that row if the value exists. Find_record() can prompt you for this value or the programmer can specify it.
When find_record is passed a search parameter, the search is case sensitive and retrieves only an exact match for the value in a column or pattern-match if specified.
If no search parameter is specified, you are prompted for one. If your response:
• Contains a pattern-matching character, a case‑sensitive search is performed
• Does not contain a pattern-matching character, a case‑insensitive search is performed for a string that begins with your response
Find_record() optionally accepts keyword parameters to specify the form, table, table field, column, and an optional search value. If you do not specify a parameter, find_record() prompts for a search value and operates on the table field and column on which the cursor is currently resting.
Find_record() starts at the current row and wraps around to the beginning of the data set to continue the search when it reaches the end. If a value is found, find_record() returns the record number in the underlying table data set; otherwise it returns -1.
You can use pattern matching characters as input string values (as defined for the query language of the calling 4GL code). Use "\" as the escape character. For example, a 4GL/SQL frame can specify a pattern using SQL pattern matching characters.
If value is not specified, values you specify through a prompt behave slightly differently. The prompt value consisting of a single period (.) tells find_record() to use the last value entered through a prompt. This can be the search value for a different column and even for a different table field. To match a single "." Add "\" as an escape character. Unless you specify a pattern match character in the prompt string, the value is converted to a data type that matches the column to be searched. If the prompt string cannot be converted, the search is unsuccessful.
II_PATTERN_MATCH controls which pattern match characters are recognized. For details on setting II_PATTERN_MATCH, see the System Administrator Guide.
Finally, prompt strings used to search columns containing strings without pattern match characters perform an anchored match of the string column values. That is, the string value prefix matches the values in the column. This is equivalent to a pattern match of string% (or string*).
Examples
Prompt the user for a value and search for it in the current column of the table field.
Callproc find_record();
Implement a Find function key:
key frskey7(explanation = 'Locate a
specified string in the table field.') =
begin
record_number = callproc find_record();
end
Last modified date: 08/28/2024