FIND

Syntax

   F[IND] [#LIMIT=i;] {relation

                       item identifier M[ATCHING] "pattern"}

   [{AND

     OR} {relation

          item identifier M[ATCHING] "pattern"}] ... [END]

For example:

   >FIND BADGE# IS "09.18"

Where relation = BADGE# IS "09.18"

   >FIND L-NAME IS MARTENSEN AND F-NAME IS SALLY

Where relation = L-NAME IS MARTENSEN AND F-NAME IS SALLY

   >F STATE M "C?"

Where item identifier = STATE and pattern = "C?"

Methods of Retrieval

If a FIND command is entered, QUERY will use either a keyed (indexed) or a serial method of retrieval. A keyed retrieval occurs when master or detail data set search keys can be used to locate entries. A serial read occurs when the data set requires serial scanning without the benefit of search keys.

In some cases, a serial method of retrieval may take a great deal of time. If you decide you do not want to wait for completion, you can abort a search by entering CONTROL Y. QUERY will print the number of qualifying entries and ask you if you want to continue the search. A "NO" reply will store the record addresses of retrieved entries in a select file and discontinue retrieval of additional entries. Search time can also be controlled with the #LIMIT = parameter, which specifies the maximum number of qualifying entries you want to retrieve.

U and X Type Values

When entering values for X and U type data items, the values must appear exactly as the data was originally entered. For example, if the data item STREET-ADDRESS has a value with three spaces between the street number and name, you must enter those spaces or QUERY will not find the item. Leading blanks must also be entered if they appear in the item. Since blanks or spaces are special characters, all such values must be enclosed in quotation marks.

Logical Connectors

To make more than one comparison for each entry selected, you connect relations with the logical connectors AND or OR. The AND connector instructs QUERY to select only those entries whose data item values satisfy the relations on both sides of the AND. The OR connector indicates that the entries are selected if one (or both) of the two relations on either side of the OR is satisfied

Both types of logical connectors can appear in a FIND command. All relations connected with AND are examined as if they were surrounded by parenthesis. Any relation or set of relations separated from others by OR are compared to the data entry and the entry is selected if the relations are true. For example, the command:

   >FIND A = 3 AND B = 4 OR C IGT 9 END

locates all entries with both A equal to 3 and B equal to 4 as well as all entries containing a C value greater than 9. The command:

   >FIND A = 3 OR A = 2 AND B = 5 AND C = 8 OR B = 9 END

locates all entries with either A equal to 3 or A equal to 2 and B equal to 5 and C equal to 8, or entries with B equal to 9.

Parentheses cannot be used in a command, but you can create constructs which act as parentheses and force an OR comparison to take precedence over an AND comparison. For example, if Cn stands for a relation:

   (C1 and C2) and C3

is represented as:

   C1 and C3 or C2 and C3

Up to 50 logical connectors may be used in one FIND command.

Compound Items

A compound data item is an item that occurs more than once in the same data entry. Each occurrence of the data item is called a sub-item. Each may have a value and any or all sub-items in a data entry can be accessed.

For example, if you have defined a compound item called MONTHLY-SALES with 12 sub-items (1 for each month), a retrieval of all entries with June sales of greater than $2000 could look like this:

   >FIND MONTHLY-SALES(6) > 2000

If no subscript is specified, the subscript is assumed to be the first sub-item.

Multiple Values

To specify more than one value for the same data item, list the values one after the other, separated by commas. For example, the command:

   >FIND STATE IS "CALIFORNIA","NEVADA","WASHINGTON"

locates the entries with the value of data item STATE equal to either CALIFORNIA, NEVADA, OR WASHINGTON. The above command is equal to:

   >FIND STATE IS "CALIFORNIA" OR STATE IS "NEVADA" OR STATE IS "WASHINGTON"

Multiple values can only be used with the "equal" or "not equal" relational operators.

Using Null Values

The FIND command can prompt you for data item values to be compared with data item values in the data entries of the data set. To do this, you use null data item values in the command. Null values are represented by a pair of quotation marks without any intervening characters or blank spaces (""). When the command is executed, you are prompted to enter a value for each null value in the command. This is useful when the FIND command is stored as a procedure in a Proc-file.

The procedure can be executed using different comparison values without modifying the procedure each time. For example, the following command would prompt you for a value of ACCOUNT with the following message.

      >FIND SALES.ACCOUNT <> ""

      WHAT IS THE VALUE OF - ACCOUNT

      >>24536173

      USING SERIAL READ

      10  ENTRIES QUALIFIED

QUERY searches the appropriate data set for the values you specify. The value should be entered without the surrounding quotes since all characters entered (including leading blanks, quotes, and other special characters) are significant. Lowercase characters are upshifted unless the data item type is X. The maximum value size is 72 characters.

You are prompted once for each null value in the command. You must supply a value for each null value in the procedure. You can use a known invalid response if you do not want to find another entry. For example:

      >FIND CUSTOMER.CITY IS "",""

      WHAT IS THE VALUE OF - CITY

      >>PETALUMA

      WHAT IS THE VALUE OF - CITY

      >>X

      USING SERIAL READ

      1 ENTRIES QUALIFIED.

When using null values from a FIND command in an XEQ file, the XEQ parameter NODATA must be used. This parameter indicates that the values to be searched for are not included in the FIND command but must be entered by you. Refer to the XEQ command for more information about using null values.

In session mode, supply the desired value after each prompt message. In job mode, you must anticipate the order of prompts and supply the desired values, one per record, following the FIND command.

Examples

Example 1

To determine whether or not a customer is already in the data set, you can try to find the name.

      >FIND LAST-NAME IS MARTENSEN

      USING SERIAL READ

      0  ENTRIES QUALIFIED

Example 2

Since ACCOUNT is in more than one data set you can either qualify the data item name or let QUERY prompt you for it. The response, SALES, is automatically entered in the data set list.

      >FIND CUSTOMER.ACCOUNT EQ 24536173

      USING SERIAL READ

      1  ENTRIES QUALIFIED

      >DATA SETS=

      >FIND ACCOUNT EQ 24536173

      ACCOUNT            IS A MEMBER OF THESE SETS:

      CUSTOMER,SALES

      WHICH SET DO YOU WISH TO USE?

      >>SALES

      3  ENTRIES QUALIFIED

Example 3

In the example below, QUERY uses the data set list to determine which of the three data sets containing STOCK# to use. Since SALES was placed in the data set list in the previous example, it is used. However, the data item DESCRIPTION is in the PRODUCT data set, and the FIND command can only refer to one data set so an error results. It is usually best to clear the data set list if you are unsure about what it contains. PRODUCT was entered in the data set list automatically as a result of the previous command, so QUERY uses PRODUCT and does not prompt for the data set name.

      >F STOCK# IGT 33333333 AND DESCRIPTION IS "NEHRU JACKET"

      RETRIEVAL FROM MORE THAN ONE DATA SET

      >S=

      >F STOCK# IGT 33333333 AND DESCRIPTION IS "NEHRU JACKET"

      STOCK#       IS A MEMBER OF THESE SETS:

      PRODUCT, SALES, INVENTORY

      WHICH SET DO YOU WISH TO USE?

      >>PRODUCT

      USING SERIAL READ

      0 ENTRIES QUALIFIED

      >F STOCK# IGT 33333333 AND DESCRIPTION IS "NEHRU JACKET"

      USING SERIAL READ

      0  ENTRIES QUALIFIED

Example 4

The following error occurs because an ampersand is used to continue the line but there is no space before it or at the beginning of the next line.

      >F ACCOUNT IGT 55555555 AND STATE IS CA OR ACCOUNT IS 121212121&

      >>AND STATE IS MA OR CUSTOMER.STATE IS AZ

      ACCOUNT     IS A MEMBER OF THESE SETS:

      CUSTOMER,SALES

      WHICH SET DO YOU WISH TO USE?

      >>CUSTOMER

      INVALID NUMERIC DIGIT

Example 5

All items which appear in multiple sets must be qualified unless the set name is in the set list. After entries are located, you can use the REPORT command to print the data.

      >F CUSTOMER.ACCOUNT IGT 55555555 AND STATE IS CA OR ACCOUNT&

      >>     IS 121212 AND STATE IS MA OR STATE IS AZ

      STATE IS A MEMBER OF THESE SETS

      CUSTOMER,SUP-MASTER

      WHICH SET DO YOU WISH TO USE?

      >>CUSTOMER

      6  ENTRIES QUALIFIED

      >REPORT D,ACCOUNT,10;D,STATE,15;END





      76623455   CA

      74001813   CA

      87654321   CA

      80808080   CA

      77765555   CA

      99998877   CA

Example 6

A simpler technique for determining the data set to be used is to enter it into the data set list with a DATA-SETS= command.

      >S=CUSTOMER

      >F ACCOUNT IGT 55555555 AND STATE IS CA OR ACCOUNT IS 12121212&

      >>      AND STATE IS MA OR STATE IS AZ

      USING SERIAL READ

      6  ENTRIES QUALIFIED

Generic Search

A pattern consists of a series of the following special characters that indicate the type of data that can be entered in that position:

   text

      a    upper or lowercase alphabetic character (A-Z, a-z)

      u    uppercase alphabetic character (A-Z)

      l    lowercase alphabetic character (a-z)

      b    blank

      d    digit (0-9)

      ?    any character

Note: A pattern must specify the maximum number of characters allowed for the data item length. Therefore, to find data item values of varying lengths, you must specify that the rest of the data item value is filled with blanks. Refer to the discussion of repetition for more information.

The beginning of the pattern is defined by a beginning quotation mark and the end is defined by an ending quotation mark. QUERY does not read spaces as blanks; therefore, you can leave spaces inside a pattern to allow for better readability.

The matching pattern can include specific characters in addition to the types listed above. For example:

MATCHING "Aaa-dddd"

The pattern above means that the value must start with the letter "A" followed by any two upper or lowercase letters, followed by a hyphen and any four digits. For example, the values "Acs-1234" and "AAA-9999" are acceptable, but the values "Bcs-1223" and "A12-345" are not acceptable.

Transparency

A special operator can be used to indicate that a pattern is to be used as an actual value. For example, suppose you want the lowercase letter "a" to be an exact value in the pattern, you can do this by preceding it, or any of the other special characters, with an exclamation point (!). For example:

The exclamation point (called the transparency operator) is also used to allow inclusion of any of the pattern operators listed below and described in Table 3-2 “MATCHING Pattern Operators”.

   !    transparency

   ,    choice

   :    range

   { }  grouping

   [ ]  optional

   +    repetition  (1 or more)

   *    repetition  (0 or more)

Choice

You can indicate a selection of acceptable patterns as part of the MATCHING pattern. Each possible choice is separated by a comma. For example:

Range

A range of acceptable characters for a single character position can be indicated with the colon. All characters within the range are acceptable. This acts as shorthand for listing a series of single characters in ASCII sequence. For example:

Grouping and Optional

You can group pattern specifications by enclosing the pattern in braces { } or brackets [ ]. Braces indicate that data must correspond to one item in the group. Brackets make the pattern optional, indicating that data can correspond to one or none of the items in the pattern. For example:

Repetition

Repetition of any character or sets of characters can be indicated by an asterisk (*) or by a plus sign (+) following any pattern character or pattern group within braces { }. A plus sign (+) means that at least one occurrence of the pattern is required for the match. An asterisk (*) means that zero or more occurrences can be matched. (These repetition indicators cannot follow items enclosed within brackets [ ].) For example:

When you use a pattern to find variable length values such as "1", "12" and "123", you must indicate that blanks following the value fill the rest of the length of the item. For example, if a data item type is X6 and the value contained in the item is "123", there are three blanks following the value. In this case, the pattern "ddd" will not find the value. The pattern must account for the blanks that fill the item length. The pattern "dddb*" will find the value if blanks follow the value. If other characters or unknown characters follow the value, you can use the pattern "ddd?*".

Operator Hierarchy

The pattern operators are evaluated in the following order, where x and y are any patterns.

   Highest     !x           Transparency

      |        x:y          Range

      |        x+ or x*     Repetition

      v        xy           Concatenation

    Lowest     x,y          Choice

Some further examples of the MATCHING statement are:

Table 3-2 “MATCHING Pattern Operators” summarizes the operators allowed in a MATCHING pattern.