IFBREC (HLI function)

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

Summary

Description

The IFBREC call (BEGIN RECORD) creates a new record and adds it to the specified file or to the file that is current.

Thread type

Single cursor IFSTRT

IFCALL function number

20

Syntax

IFBREC(RETCODE,KEY_SPEC,FILE_SPEC,%VARBUF,%VARSPEC)

Compile-only form

Not available

Execute-only form

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. See RETCODE.
KEY_SPEC	[I,c,o] The key specification is an optional input parameter that specifies a key value. If the file is sorted or hashed, the record's sort key value or hash key value must be supplied, and the value is automatically placed in the record by IFBREC. If the file is not sorted or hashed, a null value must be supplied to avoid receiving an error message. You can specify the key value as a single %variable. If you use a %variable, records that contain floating-point or bit string keys can be stored. Model 204 processes the %VARBUF and %VARSPEC parameters before KEY_SPEC. If you specify a %variable, do not include quotation marks in the entry. If you specify a character string instead of a %variable, you must use a single quotation mark to start and end the string if the key contains a reserved word, equal sign, or parenthesis. If the file is not hashed or sorted, you must enter a semicolon or null string.
FILE_SPEC	[I,s,o] The file specification is an optional input parameter that identifies the Model 204 file that will be updated to contain the new record. Guidelines for FILE_SPEC: In individual file context, the file parameter is not required. If you specify the parameter, it must contain the name of the current file. In a group context: This parameter is not required if IFBREC is to create the record in the group update file. The group update file, named in the group CREATE command, receives all new records in the group unless you specify otherwise. This parameter is required if: a group update file has not been defined for the group, or: IFBREC is to create the record in a file of the group other than the group update file. The file parameter must contain the name of the file in which the new record is to be placed. Specify the file name as a short character string. Alternatively, you can use one of the following special functions in place of a known file name string constant: $Curfile function (the current file of the group) $Update function (the group update file)
%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 more information about %variables, see Declaring %variables and %variable arrays. %VARSPEC [I,c,o] The variable specification describes the format of the data that is contained in the %VARBUF 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 IFBREC call to create and store a record. The new record becomes the current record. Use the IFPUT call after IFBREC to fill in the data fields in the record.

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

Completion return code (RETCODE)

If the IFBREC call is unsuccessful, Model 204 returns one of the following completion return codes:

Code	Error condition
4	The sort or hash key is a preallocated field that has a LENGTH attribute and the value specified in IFBREC is null or too long.
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 (field level constraint) has occurred.

Note: The current record number is not changed if an error occurs. If an error occurs, avoid IFPUT calls that are aimed at building the new record.

For information about BINARY and FLOAT field values, see Storing data in fields.

Coding example (PL/1)

The PL/1 coding example below is for a sorted file, and the key is a required entry.

KEY='JONES,JACK'; CALL IFBREC (ERROR, KEY);

Coding examples (COBOL)

The COBOL coding example below is for an unsorted file.

WORKING-STORAGE SECTION. 01 CALL-ARGS. 05 RETCODE PIC 9(5) COMP SYNC. 05 NULL PIC X(1) VALUE ';'. . . . PROCEDURE DIVISION. . . . CALL "IFBREC" USING RETCODE, NULL.

The COBOL example below is for an unsorted file in a group. In this example, FILE-NAM is nine characters long, which enables you to store the maximum file name size. Blanks following the file name or the semicolon are ignored.

WORKING-STORAGE SECTION. 01 CALL-ARGS. 05 RETCODE PIC 9(5) COMP SYNC. 05 NULL PIC X(1) VALUE';'. 05 FILE-NAM PIC x(9) VALUE'ACCTPAY;'. . . . PROCEDURE DIVISION. . . . CALL "IFBREC" USING RETCODE, NULL, FILE-NAM.

The COBOL example below is for the current file in the group.

WORKING-STORAGE SECTION. 01 CALL-ARGS. 05 RETCODE PIC 9(5) COMP SYNC. 05 NULL PIC X(1) VALUE';'. 05 FILE-NAM PIC x(9) VALUE'$CURFILE;'. . . . PROCEDURE DIVISION. . . . CALL "IFBREC" USING RETCODE, NULL, FILE-NAM.