820-UPDATE-<FileName>

Name

820-UPDATE-<FileName>

Description

820-UPDATE-<FileName> directly updates a single existing record in a file. It combines the actions of the 840-MODIFY-<Index> and 820-STORE-<FileName> routines into a single call. Use this routine when you already know that a record exists, such as when you have already inquired on or modified a record in a previous call.

Using the API in a Program

The performance advantage derived from this reduction in the number of calls brings with it a pair of requirements.

You must enter a value in all DB fields before performing the routine, because this routine can update the key fields in the index, just as the 840-MODIFY-<Index> routine does.

You must populate all record fields, unlike the 840-MODIFY-<Index> routine. This requirement must be enforced because the 820-UPDATE-<FileName> routine replaces the entire existing record with the contents of all the record fields, even if one or more of them are empty.

Input Values

Field Description

<Index>

 You must specify the database index name that you want to create a record in.
Record retrieval variables (also known as DB fields) You must populate the index key fields used to locate the record before using this call.

Return Values

Field Description

<FileName>-SW

The Modify routines set the <FileName>-SW switch to indicate the outcome of the read. This routine sets the logical value <FileName>-NOTFOUND or <FileName>-FOUND based on the outcome of the read process.

Programming Example

The following example shows the same process as the previous example for the 840-MODIFY-<Index> routine, but using the 820-UPDATE-<FileName> call to alter a record. The record has already been retrieved using a Find call.

*      Update an individual record to reflect a change.
*
       PERFORM 910-AUDIT-BEGIN.

       MOVE CT01F1-CTF-NAME        TO DB-NAME.
       MOVE CT01F1-CTF-COMPANY     TO DB-COMPANY.

       PERFORM 500-MOVE-DATA
       THRU    500-END.

       PERFORM 820-UPDATE-CTFILENAME.

       PERFORM 920-AUDIT-END.

This example shows the same change being made as in the previous example for the 840-MODIFY-<Index> call. The major differences are that you only use a single call, and you populate the DB fields and record fields before calling the 820-UPDATE-<Index> routine.

In this case, you must be certain that the 500-MOVE-DATA fills all of the record fields. If it does not, any unfilled record fields cause the 820-UPDATE-<FileName> call to overwrite the corresponding file fields with the initialization values.