IFEFCC (HLI function)

From m204wiki
Revision as of 22:14, 12 July 2016 by ELowell (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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

Summary

Description
The IFEFCC call (EXAMINE FIELD CONSTRAINT CONFLICT) returns specific information about field values or record numbers that cause a field constraint conflict using the IFSTOR, IFUPDT, or IFPUT HLI calls.

IFEFCC is similar to the SOUL ON FCC statement and its related $functions.

Thread type
multiple cursor IFSTRT, single cursor IFSTRT
IFCALL function number
139

Syntax

IFEFCC(RETCODE,FIELDNAME,VALUE,RECNUM,STATEMENT,OLD-VALUE,OLD-RECNUM,FILENAME)

Compile-only form
Not available
Execute-only syntax
Not available

Specify the parameters in the syntax order shown above.

Parameter Description
RETCODE [O,i,r] The Model 204 return code is the required output parameter. The code is a binary integer value.

If no field constraint conflict is found, IFEFCC returns an error code of 15.

FIELDNAM [O,c,o] The field name is an optional output parameter that returns the name of the field in which the constraint violation occurred. In SOUL this name is available through $UPDFLD. The name is a character string.
VALUE [O,c,o] The value is an optional output parameter that returns the field value causing the constraint violation. In SOUL this value is available through $UPDVAL. The value is returned as a character string.
RECNUM [O,c,o] The record number is an optional output parameter that returns the internal number of the record whose update causes the conflict. In SOUL this name is available through $UPDREC. This parameter is a character string.
STATEMENT [O,c,o] The statement is an optional output parameter that returns the type of update operation causing the conflict. In SOUL it is available through $UPDSTMT.

The possible values are:

Value Use
STORE For IFSTOR call
ADD When the field name(*) form is used in the IFUPDT call
INSERT When the field name(+n) form is used in the IFUPDT call
CHANGE When the field name or field name(n) form is used in the IFUPDT call

This parameter is a character string.

OLD-VALUE [O,c,o] The old value is an optional output parameter that, in the case of an AT-MOST-ONE violation, returns the value of the original field occurrence causing the constraint violation. Otherwise, it returns a blank. In SOUL this value is available through $UPDOVAL. The value is returned as a character string.
OLD-RECNUM [O,c,o] The old record number is an optional output parameter that, in the case of a uniqueness violation, returns the internal record number of the record already containing the field=value pair. Otherwise, it returns a -1. In SOUL this name is available through $UNQREC. This parameter is a character string.
FILENAME [O,c,o] The file name is an optional output parameter that returns the name of the file in which the constraint violation occurred. In SOUL this name is available through $UPDFILE. The name is a character string.

Usage notes

Use the IFEFCC call to determine the exact cause of a field constraint conflict when updating or storing data. Field constraint conflicts are caused when fields within a file violate either the UNIQUE or AT-MOST-ONE Model 204 field-level attribute.

A uniqueness conflict (return code 200) occurs when you try to store a non-unique field value (such as a duplicate telephone number) into a file. An AT-MOST-ONE conflict (return code 202) occurs when you try to store a second occurrence of a field into a record (such as a HEIGHT or EYE_COLOR field).

For more information about uniqueness and AT-MOST-ONE violations, see AT-MOST-ONE, REPEATABLE, and EXACTLY-ONE attributes.

Coding example (COBOL)

WORKING-STORAGE SECTION. 01 CALL-ARGS. 05 RETCODE PIC 9(5) COMP SYNC. 05 FIELDNAM PIC X(255). 05 VALUE PIC X(255). 05 RECNUM PIC X(11). 05 STATEMENT PIC X(6). 05 OLD-VALUE PIC X(255). 05 OLD-RECNUM PIC X(11). 05 FILENAME PIC X(8) VALUE "FN1;". . . . PROCEDURE DIVISION. . . . CALL "IFEFCC" USING RETCODE, FIELDNAM, VALUE, RECNUM, STATEMENT, OLD-VALUE, OLD-RECNUM, FILENAME.