Writing to a Data Source

When you issue a command that reads or writes to a data source, you should determine if the command was successful. Reasons for a data source command not being successful include attempting to insert a record that already exists, to update a record that does not exist, to delete a record that does not exist, to read a record that does not exist, and being interrupted by a system failure.

When you issue a command that reads or writes to a data source, if the command is:

• Successful, Maintain Data automatically sets the transaction variable FocError to 0 (zero), and writes to the data source.
• Unsuccessful, Maintain Data sets FocError to a non-zero value, and does not write to the data source.

CASE UpdateCustOrder
    UPDATE ReturnDate Fee FROM RentalStack;
    IF FocError NE 0 THEN PERFORM ErrorMessage; 
ENDCASE

When you write a set of stack rows to a data source, if you specify more rows than there are matching data source records, this does not invalidate the write operation. Maintain Data attempts to write all the matching rows to the data source. For example, the following UPDATE command specifies 15 rows, but there are only 12 matching rows. All 12 are written to the data source.

FOR 15 UPDATE Curr_Sal FROM NewSalaries;

When you write a set of stack rows to a data source, if one row fails, the following happens:

• The rows preceding the failed row are written to the data source.
• The rows following the failed row are ignored.
• FocError is set to a non-zero value, signaling an error.
• FocErrorRow is set to the number of the failed row.

Data source logic errors include attempting to insert an existing record, to update a nonexistent record, and to delete a nonexistent record.

To determine if an entire stack was successfully written to the data source, test FocError immediately following the data source command. If FocError is not zero (0), you can determine which row caused the problem by testing FocErrorRow; you can then reprocess that row. If you will be passing control to a different procedure and reprocessing the row there, consider first setting the stack's FocIndex variable to the value of FocErrorRow in the current procedure, so that after you pass control the stack is already positioned at the problem row.

If you do not wish to take advantage of this flexibility, and instead prefer to invalidate all the rows of the stack if any of them are unsuccessful, you can bracket the data source command in a logical transaction that you can then roll back. Logical transactions are discussed in Transaction Processing.

Row failure when committing to a data source. If a stack-based write command is part of a logical transaction, and the write command succeeds when it is issued but fails when the application tries to commit the transaction, Maintain Data rolls back all of the write command rows, along with the rest of the transaction. For example, a write command might fail at commit time because another user has already changed one of the records to which the command is writing. Transaction processing is described in Transaction Processing.

FOR ALL UPDATE Curr_Sal FROM NewSalaries;