View source for IFOCUR (HLI function)


==Summary==
<dl>
<dt>Description</dt>
<dd>The IFOCUR call (OPEN CURSOR) opens a cursor on the thread to a previously established found set.</dd>
<dt>Thread type</dt>
<dd>multiple cursor IFSTRT</dd>
<dt>IFCALL function number</dt>
<dd>95</dd>
</dl>

==Syntax==
<p class="syntax">IFOCUR(RETCODE,CURSOR_SPEC,CURSOR_NAME,%VARBUF,%VARSPEC,FILE_SPEC)</p>
<dl>
<dt>Compile-only form</dt>
<dd>IFCALL function number: 106
<p class="syntax">IFOCURC|IFOCRC(RETCODE,CURSOR_SPEC,CURSOR_NAME,FILE_SPEC)</p></dd>
<dt>Execute-only form</dt>
<dd> IFCALL function number: 107
<p class="syntax">IFOCURE|IFOCRE(RETCODE,CURSOR_NAME,%VARBUF,%VARSPEC)</p></dd>
</dl>

<p>Specify the parameters in the syntax order shown above.</p>
<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>
<tr>
<td>CURSOR_SPEC</td>
<td>[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:

<p class="syntax">{IN <span class="term">setname</span> [<span class="term">ordering clause</span>] | ON [list] 
<span class="term">listname</span> [<span class="term">ordering clause</span>] | OF <span class="term">fieldname</span> 
[<span class="term">value set specification</span>]}</p>
<p>
where: </p>
<p>
IN <span class="term">setname</span> specifies the compilation name for the previously compiled IFFIND, IFFNDX, IFFWOL, IFFAC, IFSORT, IFFDV, or IFSRTV call that established the set. </p>
<p>
ON <span class="term">listname</span> 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.</p>
<p>
<span class="term">ordering clause</span> is optional and specifies ordering criteria, and it is valid only for cursors opened against an unsorted record set. Ordering criteria <i>cannot</i> be specified for cursors opened against a value set or against a record set that is sorted (with IFSORT).</p>
<p>
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:</p>
<p class="syntax">IN [<u>ASCENDING</u> | DESCENDING] ORDER [BY [EACH] <span class="term">fieldname</span>] 
[(FROM <span class="term">value1</span>) (TO <span class="term">value2</span>)] [LIKE <span class="term">pattern</span>] 
[BY [ASCENDING | DESCENDING] RECORD]</p>
<p>
where:</p>
<p>
ASCENDING and DESCENDING are mutually exclusive keywords that indicate the order in which the record set will be processed. ASCENDING order is the default.</p>
<p>
<var class="term">fieldname</var> specifies the name of the field to be used for ordering the records.</p>
<p>
The FROM and TO clauses specify the range of values for <var class="term">fieldname</var>, where <var class="term">value1</var> specifies the beginning value, and <var class="term">value2</var> 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).</p>
<p class="note"><b>Note:</b> Specifying a range limits the selection of records to process. If a range is specified, records that do contain the field are not processed.</p>
<p>
<var class="term">pattern</var> specifies a field value as a character string that is used to match against the record. Enclose the pattern string inside single quotation marks. </p>
<p class="note"><b>Note:</b> 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.</p>
<p>
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.</p>
<p>
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]].</p>
<p>
OF <var class="term">fieldname</var> 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.</p> 
<p>Subsequent IFFTCH or IFFTCHE calls fetch the values from the value set. When the cursor is closed using IFCCUR, the value set empties.</p>
<p>
IFOCUR with OF fieldname is similar to the Model 204 [[Value_loops#FOR_EACH_VALUE_statement|FOR EACH VALUE OF]] statement.</p>
<p>
<var class="term">value set specification</var> is optional and allows you to specify selection or ordering criteria against a value set. </p>
<p class="syntax">[FROM <span class="term">value1</span>] [TO <span class="term">value2</span>] [[NOT] LIKE <span class="term">pattern</span>] 
[IN [<u>ASCENDING</u> | DESCENDING] 
[NUMERIC | CHARACTER | RIGHT-ADJSTED] ORDER]</p>
<p>
where:</p>
<p>
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.</p>
<p>
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.</p>
<p>
ASCENDING and DESCENDING are mutually exclusive keywords that indicate the order in which the value set will be processed. ASCENDING order is the default. </p>
<p>
CHARACTER, RIGHT-ADJUSTED, and NUMERIC are mutually exclusive keywords:
<ul>
<li>CHARACTER specifies values sorted in standard EBCDIC collating sequence.</li>
<li>RIGHT-ADJUSTED specifies that values are temporarily right-justified before sorting so that shorter fields sort first.</li>
<li>NUMERIC specifies a sort of number values with the usual numeric order relationships.</li>
</ul></p>
</td>
</tr>
<div id="CURSOR_NAME"></div>
<tr>
<td>CURSOR_NAME</td>
<td>[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 (_).</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 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]].
</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 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.
<p class="note"><b>Note:</b> For IFOCUR, use these parameters to assign values to the %variables in the ordering clause before executing the call.</p>
</td>
</tr>
<tr>
<td>FILE_SPEC</td>
<td>[I,c,o/r] The file specification is a required input parameter only when using the OF <var class="term">fieldname</var> 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 [[Basic SOUL statements and commands#IN clauses|IN clause]].
</td>
</tr>
</table>

==Usage notes==
<p>
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.</p>
<p>
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.</p>
<p>
When executing an IFOCURE (execute-only) call, Model 204 performs the following actions:</p>
<ol>
<li>Resets the cursor position prior to the first record or value in the set.</li>
<li>Assigns percent variables (%variable) in the ordering clause, for any FROM/TO conditions or ordered field names that are specified.</li>
</ol>

===Using OF <i>fieldname</i> to create value set specifications===
<p>
The OF <var class="term">fieldname</var> form of IFOCUR allows you to use IFOCUR to create a value set without first calling either IFFDV or IFSRTV. If OF <var class="term">fieldname</var>... is specified, an IFOCUR/IFOCURC call does not reference a previously compiled HLI call.</p>
<p>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.</p> 
<p>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.</p>

===Choosing IFOCUR or IFFDV and IFSRTV===
<p>
IFOCUR with the OF <var class="term">fieldname</var> 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:</p>
<ul>
<li>
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. </li>
<li>
The IFOCUR call with the OF <var class="term">fieldname</var> clause is more efficient if you use this value set only once. </li>
</ul>
<p>
The IFOCUR call with the OF <var class="term">fieldname</var> clause is similar to the Model 204 FOR EACH VALUE OF statement. [[IFFDV (HLI function)|IFFDV]] and [[IFSRTV (HLI function)|IFSRTV]] are similar to the FDV (FIND ALL VALUES) and SORT VALUES statements.</p>
<p>
For information about doing efficient value retrievals, see [[Basic SOUL statements and commands#Find statement|Find statement]].</p>

===Record number processing for ORDERED fields===
<p>
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. </p>
<ul>
<li>
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).
<p class="note"><b>Note:</b> If no record order is specified, BY ASCENDING RECORD is assumed.</p>
</li>
<li>
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.
</li>
</ul>
<table>
<p class="caption" style="width:600px">IFFTCH processing of records within an Ordered Index</p>
<tr>
<td rowspan="1" colspan="2">
When either no record order or BY ASCENDING ORDER is specified ...
</td>
<td rowspan="1" colspan="2">
When IN DESCENDING ORDER and BY DESCENDING RECORD both are specified ...
</td>
</tr>
<tr class="head">
<th>LAST_NAME</th>
<th>RECNO</th>
<th>LAST_NAME</th>
<th>RECNO</th>
</tr>
<tr>
<td>SMITH</td>
<td>08</td>
<td>SMITH</td>
<td>09</td>
</tr>
<tr>
<td>SMITH</td>
<td>09</td>
<td>SMITH</td>
<td>08</td>
</tr>
<tr>
<td>MARTIN</td>
<td>05</td>
<td>MARTIN</td>
<td>07</td>
</tr>
<tr>
<td>MARTIN</td>
<td>06</td>
<td>MARTIN</td>
<td>06</td>
</tr>
<tr>
<td>MARTIN</td>
<td>07</td>
<td>MARTIN</td>
<td>05</td>
</tr>
<tr>
<td>JONES</td>
<td>01</td>
<td>JONES</td>
<td>04</td>
</tr>
<tr>
<td>JONES</td>
<td>02</td>
<td>JONES</td>
<td>03</td>
</tr>
<tr>
<td>JONES</td>
<td>03</td>
<td>JONES</td>
<td>02</td>
</tr>
<tr>
<td>JONES</td>
<td>04</td>
<td>JONES</td>
<td>01</td>
</tr>
</table>

===Rules for cursor processing===
<p>
The following rules apply to cursor processing: </p>
<ul>
<li>
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 (HLI function)|IFFIND]], [[IFFINDX (HLI function)|IFFNDX]], [[IFFWOL (HLI function)|IFFWOL]], [[IFFAC (HLI function)|IFFAC]], [[IFFDV (HLI function)|IFFDV]], [[IFSORT (HLI function)|IFSORT]], or [[IFSRTV (HLI function)|IFSRTV]]. </li>
<li>
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.</li>
<li>
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.</li>
<li>
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. </li>
</ul>

==Coding example (COBOL)==
<p class="code">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.</p>

<p class="note"><b>Note:</b> 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.</p>

[[Category: HLI functions]]