IFSTOR (HLI function)
The conventions used on this page are described in Function call notation conventions.
Summary
- Description
- The IFSTOR call (STORE RECORD) creates a new record and adds it to the specified file. IFSTOR specifies the data fields that comprise the new record. Note that, for a saved compilation, IFSTOR allocates a cursor that points to the stored record.
- Thread type
- multiple cursor IFSTRT
- IFCALL function number
- 112
Syntax
IFSTOR(RETCODE,FILE_SPEC,BUFFER,EDIT_SPEC,STOR_NAME,%VARBUF,%VARSPEC,RECNUM)
- Compile-only form
- IFCALL function number: 113
IFSTRC(RETCODE,FILE_SPEC,EDIT_SPEC,STOR_NAME)
- Execute-only form
- IFCALL function number: 114
IFSTRE(RETCODE,BUFFER,STOR_NAME,%VARBUF,%VARSPEC,RECNUM)
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. |
| FILE_SPEC | [I,c,r] The file specification is a required input parameter that identifies the Model 204 file that will be updated to contain the new record. Specify the file as a character string using a standard Model 204 IN clause.
If a group is specified, the member clause may be used to specify a particular file within the group. Note that if a group name is specified in the IN clause and the member name is not coded, the group update file is specified by default. |
| BUFFER | [I,c,r] The buffer location is a required input parameter that specifies the address of the user's data area. Specify a character string variable.
The buffer supplies the data, the actual values, for the fields that are defined by the EDIT_SPEC parameter. |
| EDIT_SPEC | [I,c,r] The edit specification is a required input parameter that defines the fields that are to be added to form the new record. The EDIT_SPEC describes the format of the data that is read at the buffer location (see BUFFER).
Note: If the file is a sorted or hash key file and the key is required, the first field name in the EDIT_SPEC must be the key field. 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:
where:
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 IFSTOR. Note: See HLI: Field formatting options for HLI calls for a description of LIST, DATA, and EDIT formatting. |
| STOR_NAME | [I,s,o] The name of the IFSTOR 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: Model 204 allocates a cursor as part of the saved IFSTOR compilation. The cursor points to the stored record. You can reference this cursor using the STOR_NAME in an IFUPDT call to add additional fields to the record. |
| %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, which are defined by the %VARSPEC parameter to be assigned to %variables. Specify a character string. |
| %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. Specify a character string that follows LIST, DATA, or EDIT syntax. %VARSPEC is a required input parameter if %VARBUF is specified. |
| RECNUM | [O,i,o] Record number is an optional output parameter that returns the Model 204 internal record number. The number is displayed as an integer. |
Usage notes
Use the IFSTOR call to create and store a record. IFSTOR optionally opens a cursor to the new record, which allows it to be operated on by subsequent single record functions such as the IFUPDT call.
When FOPT=X'10' and the date/time stamp feature is installed, the IFSTOR function is not supported for DTS files.
The IFSTOR call is the equivalent of the STORE RECORD statement in SOUL and replaces the single cursor IFBREC and IFPUT sequence in the multiple cursor environment.
Completion return code (RETCODE)
If the IFSTOR call is unsuccessful, Model 204 returns an error code for either of the following error 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 has 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). . . . O1 CALL-ARGS. 05 RETCODE PIC 9(5) COMP SYNC. 05 FILESPEC PIC X(13) VALUE "IN FILE EMPS;". 05 EDITSPEC PIC X(28) VALUE "EDIT (SSN,NAME) (A(9),A(30));". . . . PROCEDURE DIVISION. . . . CALL "IFSTOR" USING RETCODE, FILESPEC, WORK-REC, EDITSPEC.