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: fieldname fieldname(n) fieldname(*) fieldname(%variable) fieldname(+n) fieldname(+%variable) where: fieldname updates the first occurrence of the named field. Note that this is equivalent to fieldname(1). If the field does not occur in the current record, IFSTOR 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, IFSTOR adds it. fieldname(*) adds the named field to the current record. If the field already exists in the current record, IFSTOR 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, IFSTOR 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 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.