ELowell at 22:54, 12 July 2016

2016-07-12T22:54:20Z

ELowell at 22:03, 11 July 2016

2016-07-11T22:03:55Z

ELowell: Created page with " ==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
2016-07-07T19:18:57Z

Created page with " ==Summary== <dl> <dt>Description</dt> <dd>The IFFIND call (FIND) selects records from a Model 204 file or group in share mode and creates a found set.</dd> <dt>Thread type</d..."

New page

==Summary==
<dl>
<dt>Description</dt>
<dd>The IFFIND call (FIND) selects records from a Model 204 file or group in share mode and creates a found set.</dd>
<dt>Thread type</dt>
<dd>multiple cursor IFSTRT, single cursor IFSTRT</dd>
<dt>IFCALL function number</dt>
<dd>13</dd>
</dl>

==Syntax==
IFFIND|IFFD(RETCODE,FIND_SPEC,FIND_NAME,%VARBUF,%VARSPEC)
<dl>
<dt>Compile-only form</dt>
<dd>IFCALL function number: 46
IFFINDC|IFFDC(RETCODE,FIND_SPEC,FIND_NAME)</dd>
<dt>Execute-only form</dt>
<dd> IFCALL function number: 47
IFFINDE|IFFDE(RETCODE,FIND_NAME,%VARBUF,%VARSPEC)</dd>
</dl>

Specify the parameters in the syntax order shown above.
<table>
<tr class="head">
<th>Parameter</th>
<th>Description</th>
</tr>
<tr>
<td>RETCODE</td>
<td>[O,i,r] The Model 204 return code is the required first parameter. The code is a binary integer value.</td>
</tr>
<div id="FIND_SPEC"></div>
<tr>
<td>FIND_SPEC</td>
<td>[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.

<var class="term">filename</var>|<var class="term">groupname</var> 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.
<var class="term">set_qualifier</var> 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: 
<ul>
<li><var class="term">label</var> is the name of a saved IFFIND or IFFAC compilation from a previously compiled call. </li>
<li><var class="term">listname</var> specifies the name of a list.</li>
</ul>

<var class="term">spec</var> is a valid retrieval specification (1 through <var class="term">n</var>). 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:
<ul>
<li>Files from the current group</li>
<li>Lists of records</li>
<li>Physical record numbers</li>
<li>Sort fields</li>
<li>KEY or NON-KEY fields</li>
<li>NUMERIC RANGE or NON-RANGE (alphanumeric) fields</li>
<li>ORDERED or NON-ORDERED fields.</li>
</ul>


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 [[Basic SOUL statements and commands#Find statement|Find statement]].
</td>
</tr>
<tr>
<td>FIND_NAME</td>
<td>[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).
<ul>
<li>On a single cursor IFSTRT thread, any characters except the following are valid in the name: blank, comma, parenthesis, equal sign, or semicolon.</li>
<li>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 (_).</li>
</ul>

Note: A null value is equivalent to omitting the name parameter, and is not valid for a multiple cursor thread.
</td>
</tr>
<tr>
<td>%VARBUF</td>
<td>[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]].</td>
</tr>
<tr>
<td>%VARSPEC</td>
<td>[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.
</td>
</tr>
</table>

==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:
<ul>
<li>An incorrect find specification (Model 204 does not save the compilation, the compilation name that is specified is not defined). </li>
<li>A field name variable replaced by a nonexistent field (Model 204 saves the compilation but does not execute the find function).</li>
<li>An incorrect %variable parameter </li>
</ul>

===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.

[[Category: HLI functions]]

IFFIND (HLI function) - Revision history

ELowell at 22:54, 12 July 2016

ELowell at 22:03, 11 July 2016