IFOCUR (HLI function)

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

Summary

Description

The IFOCUR call (OPEN CURSOR) opens a cursor on the thread to a previously established found set.

Thread type

multiple cursor IFSTRT

IFCALL function number

95

Syntax

IFOCUR(RETCODE,CURSOR_SPEC,CURSOR_NAME,%VARBUF,%VARSPEC,FILE_SPEC)

Compile-only form

IFCALL function number: 106

IFOCURC|IFOCRC(RETCODE,CURSOR_SPEC,CURSOR_NAME,FILE_SPEC)

Execute-only form

IFCALL function number: 107

IFOCURE|IFOCRE(RETCODE,CURSOR_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.
CURSOR_SPEC	[I,c,r] The cursor specification is a required input parameter that indicates an existing found set of records or values that was established by a previously compiled call. Specify the found set as a character string using one of the following formats: {IN setname [ordering clause] | ON [list] listname [ordering clause] | OF fieldname [value set specification]} where: IN setname specifies the compilation name for the previously compiled IFFIND, IFFNDX, IFFWOL, IFFAC, IFSORT, IFFDV, or IFSRTV call that established the set. ON listname specifies the name of a list of records. If the list does not exist, it is created in context of the default file or group. ordering clause is optional and specifies ordering criteria, and it is valid only for cursors opened against an unsorted record set. Ordering criteria cannot be specified for cursors opened against a value set or against a record set that is sorted (with IFSORT). Specify the ordering clause using only the IN ORDER clause for sorted file ordering, or the following format line in full for B-tree ordering: IN [ASCENDING | DESCENDING] ORDER [BY [EACH] fieldname] [(FROM value1) (TO value2)] [LIKE pattern] [BY [ASCENDING | DESCENDING] RECORD] where: ASCENDING and DESCENDING are mutually exclusive keywords that indicate the order in which the record set will be processed. ASCENDING order is the default. fieldname specifies the name of the field to be used for ordering the records. The FROM and TO clauses specify the range of values for fieldname, where value1 specifies the beginning value, and value2 specifies the ending value. You can specify the range using both FROM and TO, or using only FROM (for all values greater than or equal to) or only TO (for all values less than or equal to). Note: Specifying a range limits the selection of records to process. If a range is specified, records that do contain the field are not processed. pattern specifies a field value as a character string that is used to match against the record. Enclose the pattern string inside single quotation marks. Note: Specifying a pattern limits the selection of records to process. Only records that meet the pattern matching criteria are processed. See Record loops for a description of the valid pattern characters and examples of their use. The BY ASCENDING|DESCENDING RECORD clause specifies how records within each Ordered Index value are processed by IFFTCH. If BY DESCENDING RECORD is not specified, IFFTCH processes records in ascending order. Ordering clause options are similar to the ordering options available in a FOR EACH RECORD statement in SOUL. For IFOCUR, the WHERE|WITH retrieval conditions clause is not supported. For information about the FOR EACH RECORD IN ORDER statement, see Operations on multiply occurring fields. OF fieldname specifies a value set specification that is compiled and saved as a part of the IFOCUR/IFOCURC compilation. At execution time (IFOCUR or IFOCURE) this specification is executed and a value set is created. A cursor then opens against this value set. Subsequent IFFTCH or IFFTCHE calls fetch the values from the value set. When the cursor is closed using IFCCUR, the value set empties. IFOCUR with OF fieldname is similar to the Model 204 FOR EACH VALUE OF statement. value set specification is optional and allows you to specify selection or ordering criteria against a value set. [FROM value1] [TO value2] [[NOT] LIKE pattern] [IN [ASCENDING | DESCENDING] [NUMERIC | CHARACTER | RIGHT-ADJSTED] ORDER] where: FROM and TO clauses are optional and specify a minimum (greater than or equal to) value (FROM), a maximum (less than or equal to) value (TO), or a range of values (FROM and TO) for selection criteria. LIKE|NOT LIKE clause is optional and specifies a string pattern for selection criteria. See Record loops for a description of the valid pattern characters and examples of their use. ASCENDING and DESCENDING are mutually exclusive keywords that indicate the order in which the value set will be processed. ASCENDING order is the default. CHARACTER, RIGHT-ADJUSTED, and NUMERIC are mutually exclusive keywords: CHARACTER specifies values sorted in standard EBCDIC collating sequence. RIGHT-ADJUSTED specifies that values are temporarily right-justified before sorting so that shorter fields sort first. NUMERIC specifies a sort of number values with the usual numeric order relationships.
CURSOR_NAME	[I,s,r] The name to be assigned to the cursor is a required input parameter. Specify the cursor name as a short character string variable from 1 to 32 characters in length. The cursor name must be unique and must begin with a letter (A-Z or a-z) followed by one or more of the following characters: a letter, a digit (0-9), a period (.), or an underscore (_).
%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 that 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 it lists the %variables to be assigned. %VARSPEC specifies the contents of the variable buffer, described above. Specify a character string that follows a LIST, DATA, or EDIT syntax. %VARSPEC is a required input parameter if %VARBUF is specified. Note: For IFOCUR, use these parameters to assign values to the %variables in the ordering clause before executing the call.
FILE_SPEC	[I,c,o/r] The file specification is a required input parameter only when using the OF fieldname form of the IFOCUR call. FILE_SPEC identifies the Model 204 file that will be updated to contain the new record. Specify the file as a character string using a standard Model 204 IN clause.

Usage notes

Use the IFOCUR call to open a cursor to a record or a value in a set that has been named on a thread. You can open more than one cursor against the same named set to maintain different positions within the set. You can also open several cursors against several different record sets.

When executing an IFOCURC (compile-only) call, Model 204 maps the cursor to the specified named set. The initial cursor position is located prior to the first record or value in the set. If ordering criteria is specified, Model 204 also validates the ordering criteria.

When executing an IFOCURE (execute-only) call, Model 204 performs the following actions:

1. Resets the cursor position prior to the first record or value in the set.
2. Assigns percent variables (%variable) in the ordering clause, for any FROM/TO conditions or ordered field names that are specified.

Using OF fieldname to create value set specifications

The OF fieldname form of IFOCUR allows you to use IFOCUR to create a value set without first calling either IFFDV or IFSRTV. If OF fieldname... is specified, an IFOCUR/IFOCURC call does not reference a previously compiled HLI call.

Instead, a value set specification is compiled and saved as a part of the IFOCUR/IFOCURC compilation. At execution time, this specification is executed and a value set is created. A cursor is then opened against this value set.

Subsequent IFFTCH or IFFTCHE calls will fetch the values from the value set. When the cursor is closed using IFCCUR, the value set is emptied.

Choosing IFOCUR or IFFDV and IFSRTV

IFOCUR with the OF fieldname clause performs much the same function as IFFDV. The main difference is that IFFDV creates a value set (and if IFSRTV is called, sorts it) and stores it in CCATEMP, whereas IFOCUR does not use CCATEMP space to save the compilation. Rocket Technical Support suggests the following:

• The IFFDV call is more efficient if you are fetching through the same value set multiple times. This is especially true if you have a large value set or are sorting the values using the IFSRTV call.
• The IFOCUR call with the OF fieldname clause is more efficient if you use this value set only once.

The IFOCUR call with the OF fieldname clause is similar to the Model 204 FOR EACH VALUE OF statement. IFFDV and IFSRTV are similar to the FDV (FIND ALL VALUES) and SORT VALUES statements.

For information about doing efficient value retrievals, see Find statement.

Record number processing for ORDERED fields

With IFOCUR, Ordered Index records can be processed in either ascending or descending order. Use the BY ASCENDING | DESCENDING RECORD option on the IFOCUR call to specify how you want records within each Ordered Index value to be processed by IFFTCH.

• The first two columns of the following table show how IFFTCH processes records within the Ordered Index value when IN DESCENDING ORDER is specified and no record order is specified (or BY ASCENDING RECORD is specified).

  Note: If no record order is specified, BY ASCENDING RECORD is assumed.

• The last two columns of the following table show how IFFTCH processes the records within Ordered Index value when IN DESCENDING ORDER and BY DESCENDING RECORD are both specified.

IFFTCH processing of records within an Ordered Index

When either no record order or BY ASCENDING ORDER is specified ...		When IN DESCENDING ORDER and BY DESCENDING RECORD both are specified ...
LAST_NAME	RECNO	LAST_NAME	RECNO
SMITH	08	SMITH	09
SMITH	09	SMITH	08
MARTIN	05	MARTIN	07
MARTIN	06	MARTIN	06
MARTIN	07	MARTIN	05
JONES	01	JONES	04
JONES	02	JONES	03
JONES	03	JONES	02
JONES	04	JONES	01

Rules for cursor processing

The following rules apply to cursor processing:

• You can only open a cursor to a record, value set, or list that has been established (named) by the saved compilation of one of the following calls: IFFIND, IFFNDX, IFFWOL, IFFAC, IFFDV, IFSORT, or IFSRTV.
• You cannot modify a record set that is established by an IFFIND, IFFNDX, IFFWOL, IFFAC, IFFDV, IFSORT, or IFSRTV while a cursor is open against it.
• You can issue calls that modify a list while a cursor is open in it. Note, however, that a record that is added to a list while a cursor is open might or might not be processed, depending on its position relative to the current cursor location.
• You can successfully issue the IFOCUR call to be executed only for a cursor that is in a "closed" state. A cursor is in a closed state before it is first allocated in response to an IFOCUR call and thereafter, after an IFCCUR call is executed.

Coding example (COBOL)

WORKING-STORAGE SECTION. 01 CALL-ARGS. 05 RETCODE PIC 9(5) COMP SYNC. 05 FDSPEC PIC X(12) VALUE "MAKE='FORD';". 05 DNAME PIC X(7) VALUE "FDFORD;". 05 CURSPEC PIC X(10) VALUE "IN FDFORD;". 05 CURSOR-NAME PIC X(7) VALUE "CRFORD;". . . . PROCEDURE DIVISION. . . . CALL "IFFIND" USING RETCODE, FDSPEC, FDNAME. CALL "IFOCUR" USING RETCODE, CURSPEC, CURSOR-NAME.

Note: This example illustrates a key concept in multiple cursor processing. In the example, IFOCUR opens a cursor (named CRFORD) to a found set (saved as FDFORD) that was established by the IFFIND call. Alternatively, the found set could have been established by an IFFNDX, IFFWOL, IFFDV, IFFAC, IFSORT, or IFSRTV call. In any case, a cursor can only reference an existing found set or a list, one that was established by a previously compiled call.