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