ELowell at 19:41, 13 July 2016

2016-07-13T19:41:31Z

ELowell at 23:03, 11 July 2016

2016-07-11T23:03:01Z

ELowell: /* Usage notes */

2016-07-08T22:55:17Z

Usage notes

ELowell: Created page with " ==Summary==

Description

The IFUPDT call (UPDATE) updates the current record with specified data. IFUPDT specifies the cursor for the current record.

2016-07-08T22:54:27Z

Created page with " ==Summary== <dl> <dt>Description</dt> <dd>The IFUPDT call (UPDATE) updates the current record with specified data. IFUPDT specifies the cursor for the current record.</dd> <d..."

New page

==Summary==
<dl>
<dt>Description</dt>
<dd>The IFUPDT call (UPDATE) updates the current record with specified data. IFUPDT specifies the cursor for the current record.</dd>
<dt>Thread type</dt>
<dd>multiple cursor IFSTRT</dd>
<dt>IFCALL function number</dt>
<dd>115</dd>
</dl>

==Syntax==
IFUPDT(RETCODE,DATA_AREA,CURSOR_NAME,EDIT_SPEC,UPDT_NAME,%VARBUF,%VARSPEC)

<dl>
<dt>Compile-only form</dt>
<dd>IFCALL function number: 116
IFUPDTC|IFUPDC(RETCODE,CURSOR_NAME,EDIT_SPEC,UPDT_NAME)</dd>
<dt>Execute-only form</dt>
<dd> IFCALL function number: 117
IFUPDTE|IFUPDE(RETCODE,DATA_AREA,UPDT_NAME,%VARBUF,%VARSPEC)</dd>
</dl>

Specify the parameters in the syntax order shown above.
<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>DATA_AREA</td>
<td>[I,c,r] The data area is a required input parameter that specifies the address of the user's data area. Specify a character string variable.

The area contains the data that is used to update the fields that are defined in the EDIT_SPEC parameter.
</td>
</tr>
<tr>
<td>CURSOR_NAME</td>
<td>[I,s,r] The cursor name is a required input parameter that specifies the name of the cursor whose current record is to be updated. This is a short character string, the name previously assigned to the cursor in a corresponding [[IFOCUR (HLI function)|IFOCUR call]].
</td>
</tr>
<tr>
<td>EDIT_SPEC</td>
<td>[I,c,r] The edit specification is a required input parameter that defines the fields that are to be updated in the current record. The specification describes the format of the data that is read at the data area (described above). Specify a character string using one of the following LIST, DATA, or EDIT format options:
LIST (fieldname list);
DATA;
EDIT (fieldname list) (edit formats);

where:

<var class="term">fieldname list</var> is required for the LIST or EDIT specification and specifies a field name or names. Specify elements in the field name list using one of the following options:
<ul>
<li><var class="term">fieldname</var></li>
<li><var class="term">fieldname</var>(<var class="term">n</var>)</li>
<li><var class="term">fieldname</var>()</li>
<li><var class="term">fieldname</var>(%<var class="term">variable</var>)</li>
<li><var class="term">fieldname</var>(+<var class="term">n</var>) </li>
<li><var class="term">fieldname</var>(+%<var class="term">variable</var>)</li>
</ul>

where:
<ul>
<li>
<var class="term">fieldname</var> updates the first occurrence of the named field. This is equivalent to <var class="term">fieldname</var>(1). If the field does not occur in the current record, IFUPDT adds it.</li>
<li>
<var class="term">fieldname</var>(<var class="term">n</var>) updates the nth occurrence of the named field for a multiply occurring field. If the <var class="term">n</var>th occurrence does not exist in the current record, IFUPDT adds it.</li>
<li>
<var class="term">fieldname</var>() adds the named field to the current record. If the field already exists in the current record, IFUPDT adds another occurrence of the field. </li>
<li>
<var class="term">fieldname</var>(%<var class="term">variable</var>) retrieves the occurrence of the field specified by the %VARBUF and %VARSPEC parameters. If the <var class="term">n</var>th occurrence does not exist in the current record, IFUPDT adds it.</li>
<li>
<var class="term">fieldname</var>(+<var class="term">n</var>) inserts a new occurrence of the named field to the current record. This is analogous to the INSERT statement in SOUL and is useful for adding new occurrences of a field where the order of the values is important. Insert the new occurrence as the <var class="term">n</var>th occurrence. </li>
<li>
<var class="term">fieldname</var> (+%<var class="term">variable</var>) inserts a new occurrence of the field into the current record. The occurrence number is retrieved from the %VARBUF and %VARSPEC parameters.</li>
</ul>
Note: If there is a current <var class="term">n</var>th (or %<var class="term">variable</var>) occurrence, make it the one after the <var class="term">n</var>th occurrence. If <var class="term">n</var> is greater than the current number of occurrences, add the new occurrence at the end. If the field does not occur in the current record, add it. If <var class="term">n</var> is 0 or is not specified, treat it as though <var class="term">n</var>=1 and insert the field as the first occurrence.

<var class="term">edit format</var> is required in the EDIT specification and specifies a code or codes, which indicate(s) the format of the data to be returned for the named field in the field name list-edit format pair. See [[HLI: Field formatting options for HLI calls#Using EDIT format codes for an updating call|Using EDIT format codes for an updating call]] for a detailed description of the EDIT format codes that are used with IFUPDT.
Note: See [[HLI: Field formatting options for HLI calls]] for a description of LIST, DATA, and EDIT formatting.
</td>
</tr>
<tr>
<td>UPDT_NAME</td>
<td>[I,s,o] The name of the IFUPDT 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.
Note: You may optionally specify the name of a saved IFFTCH compilation for the IFUPDT call. In other words, IFFTCH and IFUPDT may share compilations.
</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 or expressions 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]].</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 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.</td>
</tr>
</table>

==Usage notes==

Use the IFUPDT call to change or delete fields in an existing record, or to add new fields to a record. 

When FOPT=X'10' and the date/time stamp feature is installed, the IFUPDT function is not supported for DTS files.

Issue the IFUPDT call after an [[IFFTCH (HLI function)|IFFTCH]] or [[IFSTOR (HLI function)|IFSTOR]] call.

The IFUPDT call operates in the multiple cursor environment similarly to the single cursor [[IFPUT (HLI function)]].

==Completion return code (RETCODE)==

If the IFUPDT call is unsuccessful, Model 204 returns an error code for the following conditions:
<table>
<tr class="head">
<th>Code</th>
<th>Error condition</th>
</tr>
<tr>
<td>10</td>
<td>Model 204 encountered invalid data values for BINARY and FLOAT numeric field for a file having FILEMODL set to NUMERIC VALIDATION.</td>
</tr>
<tr>
<td>200</td>
<td>A uniqueness violation occurred (field level constraint).</td>
</tr>
<tr>
<td>202</td>
<td>An AT-MOST-ONE violation occurred (field level constraint).</td>
</tr>
</table>

For information about BINARY and FLOAT field values, see [[Data maintenance#Storing data in fields|Storing data in fields]].

==Coding example (COBOL)==
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 CURSOR-NAME PIC X(5) VALUE "CUR1;".
05 EDIT-SPEC PIC X(28) VALUE "EDIT (SSN,NAME)
(A(9),A(30));".
.
.
.
PROCEDURE DIVISION.
.
.
.
CALL "IFUPDT" USING RETCODE, WORK-REC, CURSOR-NAME,
EDIT-SPEC.

[[Category: HLI functions]]

IFUPDT (HLI function) - Revision history

ELowell at 19:41, 13 July 2016

ELowell at 23:03, 11 July 2016

ELowell: /* Usage notes */