Writing to a Data Source

In this section:

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

These commands are described in detail in Command Reference.

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


Top of page

x
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 whether the command was successful. A data source command might not be successful if you attempt to insert a record that already exists; if you attempt to update, delete, or read a record that does not exist; or if the command is 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 shown in bold:

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

Top of page

x
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 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:

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

To determine whether an entire stack was successfully written to the data source, test FocError immediately following the data source command. If FocError is not 0, you can determine which row caused the problem by testing FocErrorRow; you can then reprocess that 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 rolls back all of the write command's 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, Maintain updates the records matching the first 29 rows and ignores rows 30 and higher.


Information Builders