ELowell at 19:33, 13 July 2016

2016-07-13T19:33:27Z

← Older revision		Revision as of 19:33, 13 July 2016
Line 1:		Line 1:
	The conventions used on this page are described in [[HLI: Function ~~call list~~#Function call notation conventions\|Function call notation conventions]].		The conventions used on this page are described in [[HLI: Function summary#Function call notation conventions\|Function call notation conventions]].

	==Summary==		==Summary==

ELowell at 22:51, 11 July 2016

2016-07-11T22:51:49Z

← Older revision		Revision as of 22:51, 11 July 2016
Line 1:		Line 1:
			The conventions used on this page are described in [[HLI: Function call list#Function call notation conventions\|Function call notation conventions]].

	==Summary==		==Summary==

ELowell: Created page with " ==Summary==

Description

The IFPUT call (PUT) updates the current record.

Thread type

single cursor IFSTRT

IFCALL function number<..."

2016-07-08T16:52:30Z

Created page with " ==Summary== <dl> <dt>Description</dt> <dd>The IFPUT call (PUT) updates the current record.</dd> <dt>Thread type</dt> <dd>single cursor IFSTRT</dd> <dt>IFCALL function number<..."

New page

==Summary==
<dl>
<dt>Description</dt>
<dd>The IFPUT call (PUT) updates the current record.</dd>
<dt>Thread type</dt>
<dd>single cursor IFSTRT</dd>
<dt>IFCALL function number</dt>
<dd>18</dd>
</dl>

==Syntax==
IFPUT(RETCODE,BUFFER,EDIT_SPEC,PUT_NAME,%VARBUF,%VARSPEC)

<dl>
<dt>Compile-only form</dt>
<dd>IFCALL function number: 54
IFPUTC(RETCODE,EDIT_SPEC,PUT_NAME)</dd>
<dt>Execute-only form</dt>
<dd> IFCALL function number: 55
IFPUTE(RETCODE,BUFFER,PUT_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>BUFFER</td>
<td>[l,c,r] The buffer location is a required input parameter that specifies the address of the data that will be used to update the fields defined in the EDIT_SPEC parameter. Specify a character string variable.</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 returned from the specified record. The specification describes the format of the data that is returned at the buffer location (see BUFFER 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. Note that this is equivalent to <var class="term">fieldname</var>(1). If the field does not occur in the current record, IFPUT adds it. </li>
<li><var class="term">fieldname</var>(<var class="term">n</var>) updates the <var class="term">n</var>th 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, IFPUT 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, IFPUT adds another occurrence of the field.</li>
<li><var class="term">fieldname</var>(%variable) 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, IFPUT 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 SOUL INSERT statement and is useful for adding new occurrences of a field where the order of the values is important. Insert the new occurrence as the nth 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 formats</var> 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 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 IFPUT.
Note: See [[HLI: Field formatting options for HLI calls]] for a description of LIST, DATA, and EDIT formatting.
</td>
</tr>
<tr>
<td>PUT_NAME</td>
<td>[I,s,r/o] The name of the IFPUT compilation is an input parameter that is only required if using the Compiled IFAM facility (IFPUTC and IFPUTE). Model 204 saves the compilation using this name. Specify the name as unique, and as a short character string. Any characters except the following are valid in the name: blank, comma, parenthesis, equal sign, or semicolon. A null value is equivalent to omitting the name parameter.</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 nowrap>%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 IFPUT to update the current record. IFPUT changes or deletes fields in an existing record and adds new fields to an existing or newly created record. Typically, you issue the IFPUT call after an IFGET, IFBREC, or IFPOINT function.

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

You cannot update the sort key field in a sorted file or the hash key field in a hashed file. In these cases, the old record must be deleted and a new record built. The new record contains the updated sort or hash key field.

You can use IFPUT to add INVISIBLE fields to the current record. To change an INVISIBLE field, first call IFDVAL to delete the field. Then, use IFPUT to add the new value. Also, use IFDVAL to delete an INVISIBLE field or to delete a particular occurrence of a field when the occurrence order is not known. You can also use IFPUT with the G edit format to delete field occurrences. 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 information about using the G edit format.

To use IFPUT to delete fields, update the field with a null value.

==Completion return code (RETCODE)==

If the IFPUT call is unsuccessful, Model 204 returns the following completion codes:
<table>
<tr class="head">
<th>Code</th>
<th>Error condition</th>
</tr>
<tr>
<td>4</td>
<td>An undefined field is encountered in a precompiled field name list. The IFPUT updating operation for the current call stops (error message begins with CANCELLING CALL).
Note: If the IFPUT specification is not precompiled, an undefined field name prevents all updating for the current call.
</td>
</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 has occurred (field level constraint).</td>
</tr>
<tr>
<td>202</td>
<td>An AT_MOST_ONE violation has occurred (field level constraint).</td>
</tr>
</table>
For information about field level constraints, see:
<ul>
<li>[[Field_design#Field and content constraints|Field and content constraints]]</li>
<li>[[Field attributes#AT-MOST-ONE versus UNIQUE attributes|AT-MOST-ONE versus UNIQUE attributes]]</li>
</ul>

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

==Updating with UPDATE IN PLACE fields==

Field values are read from left to right from the data area to correspond to names in the field name list. Changes to existing fields are applied to a record one field at a time. If the UPDATE IN PLACE attribute has been specified for a field (see IFDFLD), then the order of the fields is not affected when the contents of the field are changed.

When many occurrences of an UPDATE IN PLACE field are being changed, a subscripted field name should appear in the IFPUT name list for each value to be changed. If a field name appears more than once with the same or no subscript, the specified occurrence is changed many times and all the other occurrences remain unchanged.

==Updating with UPDATE AT END fields==

If you specify UPDATE AT END for a field, as each occurrence is updated the old occurrence is deleted and the new one is added following other occurrences of the same field. New fields are added to the end, regardless of the update option in effect. Deletions always preserve the order of the remaining occurrences.

For example, suppose that you specify UPDATE AT END and a record appears as:
LAST NAME=SMITH CHILD=TOM CHILD=DICK CHILD=HARRY 

Then, if the field name list specifies (CHILD(1), CHILD(2)), the system first updates CHILD=TOM and the record appears as:
LAST NAME=SMITH CHILD=DICK CHILD=HARRY CHILD=THOMAS

The field list specification then directs Model 204 to change the second occurrence of CHILD, which is now CHILD=HARRY. The result is:
LASTNAME=SMITH CHILD=DICK CHILD=THOMAS CHILD=HAROLD

Specifying (CHILD,CHILD), which is equivalent to (CHILD(1), CHILD(1)), would have changed CHILD=TOM and then CHILD=DICK in the original record.

==Coding example (COBOL)==

If the current record contains the following information:
NAME=SMITH,SALARY=15000,SCHOOL=HIGH

and the work area contains the following information (in most applications, the values would be moved into the work area and not set up by VALUE clauses):
WORKING-STORAGE SECTION.
01 ARGS-FOR-CALL.
05 RETCODE PIC 9(5) COMP SYNC.
01 WORKAREA.
05 NAME1 PIC X(5) VALUE `SMITH'.
05 SCHOOL1 PIC X(7) VALUE `COLLEGE'.
05 SALARY1 PIC 9(5) VALUE '16000'.
05 AGE PIC 9(2) VALUE `29'.
.
.
.
05 EDITLIST PIC X(54) VALUE
`EDIT(NAME,SALARY,SCHOOL(*),AGE)
(A(20),J(6),A(7),J(2));'.
.
.
.
PROCEDURE DIVISION.
.
.
.
CALL "IFPUT" USING RETCODE, WORKAREA, EDITLIST.

The current record is updated. If SALARY is UPDATE IN PLACE, the current record appears after the changes as:
NAME=SMITH,SALARY=16000,SCHOOL=HIGH,SCHOOL=COLLEGE,AGE=29

[[Category: HLI functions]]

IFPUT (HLI function) - Revision history

ELowell at 19:33, 13 July 2016

ELowell at 22:51, 11 July 2016

ELowell: Created page with " ==Summary== Description The IFPUT call (PUT) updates the current record. Thread type single cursor IFSTRT IFCALL function number<..."

ELowell: Created page with " ==Summary==

Description

The IFPUT call (PUT) updates the current record.

Thread type

single cursor IFSTRT

IFCALL function number<..."