IFFAC (HLI function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
No edit summary
 
Line 34: Line 34:
<tr>
<tr>
<td>FIND_SPEC</td>
<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. Specify a character string. See [[#FIND_SPEC|FIND_SPEC]] for a detailed description of the find specification used for the IFFIND call that is also valid for IFFAC.
<td>[I,c,r] The find specification is a required input parameter which is the selection criteria to be used for retrieving records. Specify a character string. See the <var>IFFIND</var> [[IFFIND (HLI function)#FIND_SPEC|Find spec description]]; those details apply to both <var>IFFIND</var> and <var>IFFAC</var>.
<p>
<p>
The file context can change on a multiple cursor thread and, if the file specification is omitted, IFFAC processes records from the file or group that is the default on the thread at the time that the IFFAC is compiled. </p>
The file context can change on a multiple cursor thread and, if the file specification is omitted, IFFAC processes records from the file or group that is the default on the thread at the time that the IFFAC is compiled. </p>

Latest revision as of 16:00, 4 September 2018

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

Summary

Description
The IFFAC call (FIND AND COUNT) creates a found set and returns the record count in an output parameter.
Thread type
multiple cursor IFSTRT, single cursor IFSTRT
IFCALL function number
126

Syntax

IFFAC(RETCODE,FIND_SPEC,COUNT,FAC_NAME,%VARBUF,%VARSPEC)

Compile-only form
IFCALL function number: 127

IFFACC(RETCODE,FIND_SPEC,FAC_NAME)

Execute-only form
IFCALL function number: 128

IFFACE(RETCODE,COUNT,FAC_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. Specify a character string. See the IFFIND Find spec description; those details apply to both IFFIND and IFFAC.

The file context can change on a multiple cursor thread and, if the file specification is omitted, IFFAC processes records from the file or group that is the default on the thread at the time that the IFFAC is compiled.

COUNT [O,i,r] The count parameter is a required parameter which specifies the location of the output parameter for the return count value. Specify an integer variable. Model 204 returns the record count as a fullword binary number.
FAC_NAME [I,s,r/o] The name of the IFFAC 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 (IFFACC and IFFACE). 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 more information, 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 IFFAC call to retrieve records and to obtain a count of the records that meet the retrieval conditions.

Note: The IFFAC call is permitted on all types of IFSTRT threads and is useful for reducing CRAM overhead.

The IFFAC call is the equivalent of the FIND AND PRINT COUNT statement in SOUL in the host language environment. For information about the FIND AND PRINT COUNT statement, see Counting records.

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 and 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 COUNT PIC 9(5) COMP SYNC. 05 FDSPEC PIC X(12) VALUE "MAKE='FORD';END;". 05 FDNAME PIC X(7) VALUE "FDFORD;". . . . PROCEDURE DIVISION. . . . CALL "IFFAC" USING RETCODE, FDSPEC, COUNT, FDNAME.