Writing to a Data Source

In this section:

Writing to a data source is the heart of transaction processing applications. Maintain Data provides the following commands to write to a data source:

These commands are described in detail in Command Reference in the App Studio Maintain Data Language Reference manual.

Maintain Data requires that data sources to which it writes have unique keys.

Evaluating the Success of a Simple Data Source Command

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:

Example: Evaluating the Success of an UPDATE Command

The following function updates the VideoTrk data source for new video rentals. If the UPDATE command is unsuccessful, the application invokes a function that displays a message to the user. The line that evaluates the success of the command is highlighted below:

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

Evaluating the Success of a Stack-based Write Command

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:

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.

Example: Evaluating a Stack-based Update Command

The NewSalaries stack has 45 rows. The following command updates the Employee data source for all the rows in NewSalaries:

FOR ALL UPDATE Curr_Sal FROM NewSalaries;

If there is no data source record that matches the thirtieth row of NewSalaries, Maintain Data updates the data source records matching the first 29 rows and ignores records that match rows 30 and higher.