AX2338

How Save Type 1 works

This topic explains how save-to-database processes are triggered and executed, to help file designers configure save blocks correctly.

Order of save block processing

When a save-to-database is executed in a file, Axiom Software identifies the save blocks in the file and then triggers them for processing. By default, multiple save blocks are triggered and run concurrently, unless Axiom Software encounters a potential dependency that automatically causes processing to wait. "Save blocks" refers to Save2DB tags for Save Type 1, and SaveStructure2DB tags for Save Type 4—both save types are handled using the same process.

Save blocks are identified and triggered for execution in the following order:

  • Each sheet is processed in the order they are listed on the Control Sheet.

  • Within a sheet, Axiom searches for save blocks by row from left to right, starting at the first row and then moving down. If Save2DB tags are numbered, then the save blocks are processed in numeric order, otherwise they are processed in the order found.

When Axiom Software identifies a save block to be processed, it triggers a background task to handle the save instead of waiting for the save to finish. It then immediately moves on to identify and trigger the next save block, so that multiple saves are run concurrently. In order to automatically handle dependent save-to-database processes, the following exceptions apply:

  • Reference tables: If the destination table for the save block is a reference table, Axiom Software triggers the background task for the save but then waits for all current tasks to complete before moving on to the next save block. This behavior is intended to handle cases where records are saved to a reference table, and then a subsequent save references the new or updated records.

  • Save Type 4: If the save block is SaveStructure2DB (Save Type 4) instead of Save2DB (Save Type 1), Axiom Software triggers the background task for the save but then waits for all current tasks to complete before moving on to the next save block. This behavior is intended to handle cases where subsequent save blocks depend on the changes made using Save Type 4.

  • Axiom query: If the save block triggers an Axiom query to be run before the save-to-database occurs, Axiom Software waits for all current tasks to complete before continuing. Once all tasks are complete, Axiom Software runs the specified Axiom query and then triggers the background task for the save. This behavior is intended to handle the case where the Axiom query is returning records that may be impacted by a previous save block.

  • Same data table: If the destination table for a save block is the same destination data table as a previous save block, Axiom Software triggers the background task for the save but does not start processing it until the task for the previous save block to the table has been completed. This behavior is intended to prevent database errors that could result if both save blocks attempted to add or update the same records at the same time.

If a particular save block encounters an error, processing stops for that block and no new save blocks are triggered for processing. However, any other save blocks that are already in process will finish processing.

If necessary, it is possible to disable the default parallel save behavior, and instead process all save blocks sequentially. In this case, save blocks are still identified in the same order, but they are processed one by one, with no overlap. If an error occurs in the current save block, all save processing stops. To disable the default parallel save behavior:

  • Per File: To disable the parallel save behavior for a particular file, set Enable Parallel Save Data to Off on the Control Sheet.

  • System-Wide: To disable the parallel save behavior for an entire system, set the system configuration setting ParallelSaveEnabled to FALSE. Generally speaking, you should only do this if instructed by Axiom Support. For information on how to modify the system configuration settings, see System configuration settings.

NOTE: The parallel save behavior only applies when a user executes a save from within a file, to improve performance when communicating between the client and the application server. When a file is processed server-side using Scheduler and a save-to-database occurs, all saves are executed sequentially.

How Save Type 1 updates data in the database

This section describes the basic update behavior for Save Type 1. Advanced options may be used to adjust this behavior as needed.

Each Axiom file has a unique document ID. The first time a save-to-database is performed for a file, Axiom Software generates a zero tag based on the document ID. For each record of data saved to the destination table, this tag is placed in the SaveTagDocID column. The SaveTagDocID column must be manually created in the destination table—it is not system-generated.

When subsequent data saves are performed for that file, Axiom Software does the following:

  1. Compares the records to be saved from the source sheet to the existing records in the destination table that are flagged with the matching zero tag in the SaveTagDocID column. If a record exists in the table but not in the sheet data, then the following columns are zeroed for that record:

  2. Saves the sheet data to the database. For each record that was updated or inserted, the save tag is placed in the SaveTagDocID field.
  3. Deletes records that are flagged to be deleted.

The zero process is intended to ensure that no old data is retained in the database from prior saves. In certain cases you may want to disable the zero process (so that no zeroing occurs on save), or modify it to use custom zero tags (so that each save process is tracked independently).

If multiple rows of data in the sheet share the same combination of key codes, then by default all non-key and non-validated fields in those rows are aggregated when saved to the database. This default behavior only applies when saving to data tables (aggregation never occurs when saving to reference tables), and can be disabled if desired by using a parameter in the Save2db tag.

Updating a record using multiple save processes

The default zero behavior described in the previous section assumes that data for each unique table record is saved from one save process in one file only. If you save data to a record from multiple files (or multiple save processes in the same file), then each subsequent save process will overwrite the zero tag from the prior process. To enable saving to the same records from multiple save processes, you must define a custom zero tag and custom zero column for each additional save process that has the same target records (advanced settings ZeroTag Value and Custom ZeroTag Column).

For example, you may have a plan file for Dept 200, which saves data to Acct 10000. And you may have a report allocation "utility" which also saves data back to Dept 200 / Acct 10000. If both of these files use the default zero behavior, then when the allocation utility is run, its zero tag will overwrite the zero tag from the plan file. However, if both save processes use a different custom zero tag and column, then one process will not overwrite the zero tag for the other process.

Custom zero tag settings can be defined per sheet (in the Control Sheet) or per save process (in the Save2DB tag). For more information, see Using zero tags with Save Type 1.

See also