IFFIND (HLI function)

The conventions used on this page are described in Function call notation conventions.

Summary

Description

The IFFIND call (FIND) selects records from a Model 204 file or group in share mode and creates a found set.

Thread type

multiple cursor IFSTRT, single cursor IFSTRT

IFCALL function number

13

Syntax

IFFIND|IFFD(RETCODE,FIND_SPEC,FIND_NAME,%VARBUF,%VARSPEC)

Compile-only form

IFCALL function number: 46

IFFINDC|IFFDC(RETCODE,FIND_SPEC,FIND_NAME)

Execute-only form

IFCALL function number: 47

IFFINDE|IFFDE(RETCODE,FIND_NAME,%VARBUF,%VARSPEC)

Specify the parameters in the syntax order shown above.

Parameter	Description
RETCODE	[O,i,r] The Model 204 return code is the required first parameter. The code is a binary integer value.
FIND_SPEC	[I,c,r] The find specification is a required input parameter which is the selection criteria to be used for retrieving records. This find specification can also be used for the IFFAC call. Specify the selection criteria as a character string: [IN {FILE filename: | GROUP groupname;}] FD [set_qualifier] spec1;...specn; END; where: the IN clause is available only for a multiple cursor thread and its use is optional for specifying a file or group context other than the default. Note: The file context can change on a multiple cursor thread and, if the file specification is omitted, IFFIND is compiled against the last file opened which is the default file or group on the thread. filename|groupname specifies the name of a particular file or group context for the record set. FD is a required keyword that must be specified if the IN clause is used. set_qualifier is available only for a multiple cursor thread and its use is optional for specifying the previously established record set or list from which records will be retrieved. Note: A set qualifier is illegal if the IN FILE clause is specified. Specify the set qualifier as a character string using one of the following formats: {IN label | ON [LIST} listname} where: label is the name of a saved IFFIND or IFFAC compilation from a previously compiled call. listname specifies the name of a list. spec is a valid retrieval specification (1 through n). End the specification with a semicolon (;). Note: To be selected, a record must meet all of the retrieval specifications. A specification can be any Boolean combination of conditions using the following elements: Files from the current group Lists of records Physical record numbers Sort fields KEY or NON-KEY fields NUMERIC RANGE or NON-RANGE (alphanumeric) fields ORDERED or NON-ORDERED fields. END; is the required keyword and semicolon delimiter which indicates the end of the find specification. For information about retrieval conditions and selection results, see Find statement.
FIND_NAME	[I,s,r/o] The name of the IFFIND compilation is an input parameter that is required for use with a multiple cursor IFSTRT thread, and is only required for a single cursor IFSTRT thread if using the Compiled IFAM facility (IFFINDC and IFFINDE). Model 204 saves the compilation using this name. Specify the name as unique, and as a short character string (maximum 32 characters). On a single cursor IFSTRT thread, any characters except the following are valid in the name: blank, comma, parenthesis, equal sign, or semicolon. On a multiple cursor IFSTRT thread, the first character in the name must be alphanumeric, and the name must begin with a letter (A-Z or a-z) which may be followed by a letter, a digit (0-9), a period (.), or underscore (_). Note: A null value is equivalent to omitting the name parameter, and is not valid for a multiple cursor thread.
%VARBUF	[I,c,o] The variable buffer is an optional input parameter that addresses a data area which accommodates up to 255 bytes of data per value. The buffer contains values which are defined by the %VARSPEC parameter, below, to be assigned to %variables. Specify a character string. For information about %variables, see Using variables and values in computation.
%VARSPEC	[I,c,o] The variable specification describes the format of the data that is contained in the %variable parameter and lists the %variables to be assigned. %VARSPEC specifies the contents of the variable buffer, described above. Specify a character string which follows a LIST, DATA, or EDIT syntax. %VARSPEC is a required input parameter if %VARBUF is specified.

Usage notes

Use the IFFIND call to retrieve records. The find specification is based on a specified combination of retrieval conditions, the selection criteria.

Note: IFFIND does not verify the number of records in the found set. A return code of 0 indicates normal completion of the call whether none, one, or many records are found. To determine whether or not the selected set is empty, use the IFCOUNT call.

The IFFIND call is permitted on all types of IFSTRT threads.

Completion return code (RETCODE)

A Model 204 return code of 4 indicates abnormal completion of the IFFIND call for any of the following error conditions:

• An incorrect find specification (Model 204 does not save the compilation, the compilation name that is specified is not defined).
• A field name variable replaced by a nonexistent field (Model 204 saves the compilation but does not execute the find function).
• An incorrect %variable parameter

Record locking behavior

Records in the found set are retrieved in share mode. Alternatively, to lock the records of the current set in exclusive mode, use the IFFNDX call, or to select records without obtaining any locks, use the IFFWOL call.

The IFFIND call is the equivalent of the FIND statement in SOUL in the host language environment. For information about the FIND statement, see Basic SOUL statements and commands.

Processing records from a found set

There are differences between single cursor and multiple cursor IFSTRT threads in processing records from a found set.

When a set is found on a single cursor IFSTRT thread, and while it is the current set, you can use IFGET to retrieve individual records. On a single cursor IFSTRT thread, you must save the current found set on a list before issuing any call which creates a new set if you want to access the previously found records.

On a multiple cursor thread, use IFOCUR to open a cursor to a found set any time after it is established. Use the IFFTCH call to retrieve individual records.

Coding example (COBOL)

WORKING-STORAGE SECTION. 01 CALL-ARGS. 05 RETCODE PIC 9(5) COMP SYNC. 05 QUAL-1 PIC X(75) VALUE 'SEX=FEMALE; OCCUPATION=DOCTOR OR DENTIST; CITY=BOSTON;NAME LIKE "PAT*";END;'. . . . PROCEDURE DIVISION. . . . CALL "IFFIND" USING RETCODE, QUAL-1.