IFPUT (HLI function)

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

Summary

Description

The IFPUT call (PUT) updates the current record.

Thread type

single cursor IFSTRT

IFCALL function number

18

Syntax

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

Compile-only form

IFCALL function number: 54

IFPUTC(RETCODE,EDIT_SPEC,PUT_NAME)

Execute-only form

IFCALL function number: 55

IFPUTE(RETCODE,BUFFER,PUT_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.
BUFFER	[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.
EDIT_SPEC	[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: fieldname list 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: fieldname fieldname(n) fieldname(*) fieldname(%variable) fieldname(+n) fieldname(+%variable) where: fieldname updates the first occurrence of the named field. Note that this is equivalent to fieldname(1). If the field does not occur in the current record, IFPUT adds it. fieldname(n) updates the nth occurrence of the named field for a multiply occurring field. If the nth occurrence does not exist in the current record, IFPUT adds it. fieldname(*) adds the named field to the current record. If the field already exists in the current record, IFPUT adds another occurrence of the field. fieldname(%variable) retrieves the occurrence of the field specified by the %VARBUF and %VARSPEC parameters. If the nth occurrence does not exist in the current record, IFPUT adds it. fieldname(+n) 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. fieldname (+%variable) inserts a new occurrence of the field into the current record. The occurrence number is retrieved from the %VARBUF and %VARSPEC parameters. Note: If there is a current nth (or %variable) occurrence, make it the one after the nth occurrence. If n 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 n is 0 or is not specified, treat it as though n=1 and insert the field as the first occurrence. edit formats 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 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.
PUT_NAME	[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.
%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 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.

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 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:

Code	Error condition
4	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.
10	Model 204 encountered invalid data values for BINARY and FLOAT numeric field for a file having FILEMODL set to NUMERIC VALIDATION.
200	A uniqueness violation has occurred (field level constraint).
202	An AT_MOST_ONE violation has occurred (field level constraint).

For information about field level constraints, see:

• Field and content constraints
• AT-MOST-ONE versus UNIQUE attributes

For information about BINARY and FLOAT field values, see 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