IFFILE (HLI function)
The conventions used on this page are described in Function call notation conventions.
Summary
- Description
- The IFFILE call (FILE) adds the specified field to each record in a found set and saves the updated records.
- Thread type
- multiple cursor IFSTRT, single cursor IFSTRT
- IFCALL function number
- 22
Syntax
IFFILE(RETCODE,FIELD_SPEC,SET_QUAL)
- Compile-only form
- Not available
- Execute-only form
- Not available
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. |
| FIELD_SPEC | [I,c,r] The field specification is a required input parameter which specifies the name and value pair for the field that will be added to the records in the set. Specify a character string using the following name=value pair format:
fieldname=fieldvalue; where: fieldname is the name of the predefined Model 204 field to be added to each record in the set. You may specify only one field per IFFILE call. The field must be predefined to Model 204 as having both KEY and INVISIBLE attributes. Specify the name as a character string, up to 255 characters in length. fieldvalue is the value for the specified field in the pair. A value is required. Values may be specified in decimal form, such as 193, in hexadecimal form, such as X`C1', or in character form, such as C`A'. |
| SET_QUAL | [I,c,r] The set qualifier is available only for use with a multiple cursor IFSTRT thread and it is required for specifying the record set or list that will be used to add fields to records in a file or group. Specify a character string using either one of the following formats:
{IN label | ON [LIST} listname} where: label is the name of a saved IFFIND, IFFNDX, IFFWOL, or IFFAC compilation from the previously compiled call which established the record set. listname specifies the name of a list which contains the found set. Note: The set qualifier is not a valid parameter for use with a single cursor IFSTRT thread. |
Usage notes
Use the IFFILE call to update and retain a set of records for future use. The IFFILE call adds the specified field to all the records that are in the found set. IFFILE does not enqueue on a set of records. Note that you cannot use IFFILE with a sorted record set.
When FOPT=X'10' and the date/time stamp feature is installed, the IFFILE function is supported for DTS files.
Once records are updated with the IFFILE call, you can retrieve all the records in the found set by referencing the added field in a retrieval call. Overall, this is more efficient than updating records one at a time.
The IFFILE call is valid on all types of IFSTRT threads. You must specify the found set of records that are to be updated on a multiple cursor IFSTRT thread. On a single cursor IFSTRT thread, IFFILE updates records using the found set that is current.
Note: IFFILE deletes a field from a record in a file or group if the field already exists. Use IFFILE with caution because it can delete a field from records which are not in the current set.
Coding example (COBOL)
WORKING-STORAGE SECTION. 01 ARGS-FOR-CALL. 05 RETCODE PIC 9(5) COMP SYNC. 05 KEY-INV-FIELD PIC X(10) VALUE "SAVREC=2;". . . . PROCEDURE DIVISION. . . . CALL "IFFILE" USING RETCODE, KEY-INV-FIELD.