IFUPDT (HLI function)

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

Summary

Description

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

Thread type

multiple cursor IFSTRT

IFCALL function number

115

Syntax

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

Compile-only form

IFCALL function number: 116

IFUPDTC|IFUPDC(RETCODE,CURSOR_NAME,EDIT_SPEC,UPDT_NAME)

Execute-only form

IFCALL function number: 117

IFUPDTE|IFUPDE(RETCODE,DATA_AREA,UPDT_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.
DATA_AREA	[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.
CURSOR_NAME	[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 call.
EDIT_SPEC	[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: 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. This is equivalent to fieldname(1). If the field does not occur in the current record, IFUPDT 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, IFUPDT adds it. fieldname(*) adds the named field to the current record. If the field already exists in the current record, IFUPDT 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, IFUPDT adds it. fieldname(+n) 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 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 format 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 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.
UPDT_NAME	[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.
%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 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.
%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 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 or IFSTOR call.

The IFUPDT call operates in the multiple cursor environment similarly to the single cursor IFPUT.

Completion return code (RETCODE)

If the IFUPDT call is unsuccessful, Model 204 returns an error code for the following conditions:

Code	Error condition
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 occurred (field level constraint).
202	An AT-MOST-ONE violation occurred (field level constraint).

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