IFFTCH (HLI function)

Summary

Description: The IFFTCH call (FETCH) processes the next logical record or value and returns specified data to the user. IFFTCH specifies the cursor for the next logical record from which data is to be processed.
Thread type: multiple cursor IFSTRT
IFCALL function number: 98

Syntax

IFFTCH(RETCODE,BUFFER,DIRECTION,CURSOR_NAME,EDIT_SPEC,FTCH_NAME,%VARBUF,%VARSPEC,RECNUM)

Compile-only form: IFCALL function number: 99
IFFTCHC|IFFCHC(RETCODE,CURSOR_NAME,EDIT_SPEC,FTCH_NAME)
Execute-only form: IFCALL function number: 100
IFFTCHE|IFFCHE(RETCODE,BUFFER,DIRECTION,FTCH_NAME,%VARBUF,%VARSPEC,RECNUM)

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.
BUFFER	[O,c,r] The buffer location is a required output parameter which specifies the address of the user's data area. The buffer contains the data returned by IFFTCH for the fields that are defined by the EDIT_SPEC parameter. Specify a character string.
DIRECTION	[I,i,r] The direction is a required input parameter which indicates the direction to move in the cursor for the specified found set. Specify the direction as a fullword binary number using a value in the range of -2,147,483,647 to 2,147,483,647. The cursor moves forward or backward a number of positions equal to your DIRECTION value. For example, if you specify a DIRECTION of 5, Model 204 processes every fifth record.
CURSOR_NAME	[I,c,r] Is a required input parameter which specifies the name of the cursor that points to the current record or value from which data is to be selected. This is a character string, the name previously assigned to the cursor in a corresponding IFOCUR call. See CURSOR_NAME for a description of the cursor name for the IFOCUR call.
EDIT_SPEC	[I,c,r] The edit specification is a required input parameter which defines the fields that are to be returned from the specified record or value set. The specification describes the format of the data which is returned at the buffer location (see BUFFER on the previous page). For a record set, specify a character string using one of the following LIST, DATA, or EDIT format options: LIST (fieldname list); DATA (fieldname list); DATA; EDIT (fieldname list) (edit format); EDIT (fieldname list1) (edit format1) (fieldname list2) (edit format2); where: `fieldname list` is required and specifies a field name or names. Specify elements in the field name list using one of the following options: `fieldname` `fieldname`(`n`) `fieldname`() `fieldname`(%`variable`) where: `fieldname` retrieves the first occurrence of the named field. `fieldname`(`n`) retrieves the `n`th occurrence of the named field. `fieldname`() retrieves all occurrences of the named field in the order of occurrence. `fieldname`(%`variable`) retrieves the occurrence of the field specified by the %VARBUF and %VARSPEC parameters. `edit format` is required in the EDIT specification and specifies a code or codes indicating the format of the data to be returned for the named field in the `fieldname list`-`edit format` pair. See EDIT_SPEC for a detailed description of the EDIT format codes that are used with IFFTCH. For a value set, specify a character string using either of the following LIST or EDIT format options: LIST; IT (edit format); `edit format` is required in the EDIT specification. See EDIT_SPEC for a detailed description of the EDIT format codes that are used with IFFTCH. See HLI: Field formatting options for HLI calls for a description of LIST, DATA, and EDIT formatting. See Special data handling for information about using multiple edit specifications for a data record.
FTCH_NAME	[I,s,o] The name of the IFFTCH compilation is an optional input parameter. If specified, Model 204 saves the compilation using this name. Specify the name as unique, and as a short character string (maximum 32 characters). 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 (_). A null value is equivalent to omitting the name parameter, and is not valid.
%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.
RECNUM	[O,i,o] Record number is an optional output parameter that will return the Model 204 internal record number. The number is displayed as an integer. For value set cursors, RECNUM always returns a zero.

Usage notes

Use the IFFTCH call to access records or data. For a record set, the IFFTCH call operates in the following ways:

No single record lock is obtained on the record that is being processed
The record is not removed from the base record set after being returned.

Except for the record processing operations listed above, the IFFTCH call operates in the multiple cursor environment similarly to the single cursor IFGET and IFGETV calls, and (using DIRECTION=0) the IFMORE call. See the IFGET, IFGETV, and IFMORE calls.

Special data handling

You might need to use more than one IFFTCH call to assemble a record. To fetch data in segments, issue two or more successive IFFTCH calls, each having an EDIT_SPEC for a different portion of the record. Note that the second IFFTCH call must specify DIRECTION=0.

Specifying a cursor for IFFTCH

To successfully issue an IFFTCH call, you must specify a cursor which is open on the thread. See the IFOCUR (open cursor) call.

Using forward and backward skip processing

IFFTCH allows you to skip records or values when going either forward or backward. IFFTCH accepts either a positive or negative value of n and will skip to the next nth record. For example, if you specify a DIRECTION of 5, Model 204 will process every fifth record. Specify the direction as a fullword binary number using a value in the range of -2,147,483,647 to 2,147,483,647. If you set DIRECTION to 0, Model 204 assumes that you are fetching the same record.

Forward and backward skip processing can be used with the following types of record sets:

Ordered Index record or value sets
UNORDERED record or value sets
SORTED record or value sets
SORTED file record sets

Backward skip processing

You can use backward skip processing with Ordered Index record sets if one of the following is true:

EACH is specified in the IFOCUR call.
The field being processed is defined as OCCURS 1.
The field being processed is defined as AT-MOST-ONE.

Negative settings invoke backward skipping. However, you cannot skip backward in a given record set until you have first skipped forward in the record set. That is, you cannot start at the beginning of the record set and skip backward.

Coding example (COBOL)

In the coding example below, Model 204 fetches every second (every other) record as specified by the DIRECTION option.

WORKING-STORAGE SECTION. 01 WORK-REC. 05 WORK-SSN PIC 9(9). 05 WORK-NAME PIC X(30). . . . 01 CALL-ARGS. 05 RETCODE PIC 9(5) COMP SYNC. 05 DIRECTION PIC 9(9) COMP SYNC VALUE "2". 05 CURSOR-NAME PIC X(5) VALUE "CUR1;". 05 EDIT-SPEC PIC X(28) VALUE "EDIT (SSN,NAME) (A(9),A(30));". . . . PROCEDURE DIVISION. . . . CALL "IFFTCH" USING RETCODE, WORK-REC, DIRECTION, CURSOR-NAME, EDIT-SPEC.