ELowell at 19:40, 13 July 2016

2016-07-13T19:40:13Z

← Older revision		Revision as of 19:40, 13 July 2016
Line 1:		Line 1:
	The conventions used on this page are described in [[HLI: Function ~~call list~~#Function call notation conventions\|Function call notation conventions]].		The conventions used on this page are described in [[HLI: Function summary#Function call notation conventions\|Function call notation conventions]].

	==Summary==		==Summary==

ELowell at 23:00, 11 July 2016

2016-07-11T23:00:18Z

← Older revision		Revision as of 23:00, 11 July 2016
Line 1:		Line 1:
			The conventions used on this page are described in [[HLI: Function call list#Function call notation conventions\|Function call notation conventions]].

	==Summary==		==Summary==

ELowell: Created page with " ==Summary==

Description

The IFSTOR call (STORE RECORD) creates a new record and adds it to the specified file. IFSTOR specifies the data fields that compris..."

2016-07-08T21:29:04Z

Created page with " ==Summary== <dl> <dt>Description</dt> <dd>The IFSTOR call (STORE RECORD) creates a new record and adds it to the specified file. IFSTOR specifies the data fields that compris..."

New page

==Summary==
<dl>
<dt>Description</dt>
<dd>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.</dd>
<dt>Thread type</dt>
<dd>multiple cursor IFSTRT</dd>
<dt>IFCALL function number</dt>
<dd>112</dd>
</dl>

==Syntax==
IFSTOR(RETCODE,FILE_SPEC,BUFFER,EDIT_SPEC,STOR_NAME,%VARBUF,%VARSPEC,RECNUM)

<dl>
<dt>Compile-only form</dt>
<dd>IFCALL function number: 113
IFSTRC(RETCODE,FILE_SPEC,EDIT_SPEC,STOR_NAME)</dd>
<dt>Execute-only form</dt>
<dd> IFCALL function number: 114
IFSTRE(RETCODE,BUFFER,STOR_NAME,%VARBUF,%VARSPEC,RECNUM)</dd>
</dl>

Specify the parameters in the syntax order shown above.
<table>
<tr class="head">
<th>Parameter</th>
<th>Description</th>
</tr>
<tr>
<td>RETCODE</td>
<td>[O,i,r] The Model 204 return code is the required first parameter. The code is a binary integer value.</td>
</tr>
<tr>
<td>FILE_SPEC</td>
<td>[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 [[Files, groups, and reference context#IN clause|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.
</td>
</tr>
<tr>
<td>BUFFER</td>
<td>[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.
</td>
</tr>
<tr>
<td>EDIT_SPEC</td>
<td>[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:

<var class="term">fieldname list</var> 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:
<ul>
<li>
<var class="term">fieldname</var></li>
<li>
<var class="term">fieldname</var>(<var class="term">n</var>)</li>
<li>
<var class="term">fieldname</var>(*)</li>
<li>
<var class="term">fieldname</var>(%<var class="term">variable</var>)</li>
<li>
<var class="term">fieldname</var>(+<var class="term">n</var>) </li>
<li>
<var class="term">fieldname</var>(+%<var class="term">variable</var>)</li>
</ul>

where:
<ul>
<li>
<var class="term">fieldname</var> updates the first occurrence of the named field. Note that this is equivalent to <var class="term">fieldname</var>(1). If the field does not occur in the current record, IFSTOR adds it. </li>
<li>
<var class="term">fieldname</var>(<var class="term">n</var>) updates the <var class="term">n</var>th occurrence of the named field for a multiply occurring field. If the <var class="term">n</var>th occurrence does not exist in the current record, IFSTOR adds it.</li>
<li>
<var class="term">fieldname</var>(*) adds the named field to the current record. If the field already exists in the current record, IFSTOR adds another occurrence of the field. </li>
<li>
<var class="term">fieldname</var>(%<var class="term">variable</var>) retrieves the occurrence of the field specified by the %VARBUF and %VARSPEC parameters. If the <var class="term">n</var>th occurrence does not exist in the current record, IFSTOR adds it. </li>
<li>
<var class="term">fieldname</var>(+<var class="term">n</var>) 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 <var class="term">n</var>th occurrence. </li>
<li>
<var class="term">fieldname</var> (+%<var class="term">variable</var>) inserts a new occurrence of the field into the current record. The occurrence number is retrieved from the %VARBUF and %VARSPEC parameters.</li>
</ul>
Note: If there is a current <var class="term">n</var>th (or %<var class="term">variable</var>) occurrence, make it the one after the <var class="term">n</var>th occurrence. If <var class="term">n</var> 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 <var class="term">n</var> is 0 or is not specified, treat it as though <var class="term">n</var>=1 and insert the field as the first occurrence.

<var class="term">edit formats</var> 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 [[HLI: Field formatting options for HLI calls#Using EDIT format codes for an updating call|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.
</td>
</tr>
<tr>
<td>STOR_NAME</td>
<td>[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.
</td>
</tr>
<tr>
<td>%VARBUF</td>
<td>[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 [[Using variables and values in computation|%variables]]. Specify a character string.</td>
</tr>
<tr>
<td>%VARSPEC</td>
<td>[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.</td>
</tr>
<tr>
<td>RECNUM</td>
<td>[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.</td>
</tr>
</table>

==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 [[Data maintenance#STORE RECORD statement|STORE RECORD]] statement in SOUL and replaces the single cursor [[IFBREC (HLI function)|IFBREC]] and [[IFPUT (HLI function)|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:
<table>
<tr class="head">
<th>Code</th>
<th>Error condition</th>
</tr>
<tr>
<td>10</td>
<td>Model 204 encountered invalid data values for BINARY and FLOAT numeric field for a file having FILEMODL set to NUMERIC VALIDATION.</td>
</tr>
<tr>
<td>200</td>
<td>A uniqueness violation has occurred (field level constraint).</td>
</tr>
<tr>
<td>202</td>
<td>An AT-MOST-ONE violation occurred (field level constraint).</td>
</tr>
</table>

For information about BINARY and FLOAT field values, see [[Data maintenance#Storing data in fields|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.

[[Category: HLI functions]]

IFSTOR (HLI function) - Revision history

ELowell at 19:40, 13 July 2016

ELowell at 23:00, 11 July 2016

ELowell: Created page with " ==Summary== Description The IFSTOR call (STORE RECORD) creates a new record and adds it to the specified file. IFSTOR specifies the data fields that compris..."

ELowell: Created page with " ==Summary==

Description

The IFSTOR call (STORE RECORD) creates a new record and adds it to the specified file. IFSTOR specifies the data fields that compris..."