A DDO save is normally a two-step process. First you send Request_Validate to the DDO to make sure that your data is ready for the save. If your data is valid, you then send Request_Save to the DDO to perform the save.
In some cases, you will use objects such as data-entry object (DEOs) to handle the entire save for you. In other cases, you will need to write custom code to perform the save. In all cases, the save process itself is the same.
Get Request_Validate of hoDD to bErr
Before a Request_Save is sent to a DDO, the Request_Validate message should be sent to validate that all data is valid for a save. When performing saves with a DEO or using a Web Browser object’s high level save, this message is sent for you. If you are performing saves manually within a Batch Process or Web Object, you will need to send this message yourself.
Request_Validate sends validation messages to all DDO Field’s that will participate in the upcoming save. If the validation of any field fails, an error is reported and the save will not proceed.
Function SaveCustomer returns Boolean
Boolean bErr
Get Request_Validate of oCustomer_DD to bErr
If Not bErr Begin
Send Request_Save of oCustomer_DD
Move (Err) to bErr
End
Function_Return bErr
End_Function
It is important that you understand when and how this process occurs.
Before a save, every single field in every single DDO that will participate in the save will be validated.
This is a pre-save validation.
Your database is not locked at this point.
If any validation function returns a non-zero value, the Request_Validate will fail and return a non-zero value.
An error message will usually be generated when a field validation fails.
If DEOs are attached to the DDO, the DDO will attempt to give the focus to the DEO that contains the invalid field data.
This field validation is a different process than the actual DDO save validation (Validate_Save), which occurs much later in the save process.
Send Request_Save of hoDD
When the save operation is performed by a DDO, it saves records into its main table as well as the tables in its parent DDOs. This allows updates in total fields in related tables to be performed as each record in the main table is created or edited. This action can also cause the creation of new records in any of the tables. Any record buffer that was not pointing to an already-existing record will have a new record created.
Function SaveCustomer returns Boolean
Boolean bErr
Get Request_Validate of oCustomer_DD to bErr
If Not bErr Begin
Send Request_Save of oCustomer_DD
Move (Err) to bErr
End
Function_Return bErr
End_Function
The Request_Save message is responsible for saving new or existing records. When Request_Save is sent to a DDO, it will:
Verify that the DDO structure is valid for the save operation.
Begin Transaction – From this point on tables are locked (if the database uses table locking) or records are locked as they are found (if the database uses record locking).
Re-find all original records. Send Backout to all tables with existing records.
If any parent records are switched (i.e., you selected a different parent), save the original records (with backed out data) and re-find the new records.
Move all changed data from the DDO-Field buffers to the table file-buffers.
Send Creating to all DDOs with new records.
Send Update to all participating DDOs.
Get Validate_Save of all participating DDOs. If any Validate_Save fails, cancel the operation.
If all DDOs validate, attach, and save all records by sending Attach_Main_File and Save_Main_File to every table.
End Transaction – either commit changes or roll back changes. Unlock tables.
If save was successful, send Refresh all participating DEOs.
If an error occurs anywhere within a save, the transaction is rolled back, the database is unlocked and the error is reported.
Most often the error will occur within the Validate_Save event and will be a “handled” error (i.e., an error purposefully created by the programmer). This must be a real DataFlex error generated using the UserError message or the Error command. The generation of an error is what triggers a transaction rollback. The reporting of the error will be properly deferred until the transaction is rolled back and your database is unlocked.
Although Validate_Save is the event specifically created to allow you to perform one last validation, you may stop a transaction within any of the save events (Creating, Update, Backout, Attach_Main_File, Save_Main_File). If you generate an error, the transaction will be rolled back.
Unless otherwise noted, the messages listed are sent to all the objects in a data-server structure that will participate in a particular operation. Validate_Save, for example, gets called during a save operation. A save involves the DDO that actually started the save (received the Request_Save message) and all the DDOs that it updates (saves propagate up). During a save, Validate_Save is sent to every one of these objects. When you think of DDO behaviors, try to think in terms of the behaviors of Data Dictionary structures and not single DDOs.
When a message is propagated through a Data Dictionary structure, the order in which messages are sent will vary. In some cases, a message will be sent to the parent-most (server) DDO and propagate down to the child DDOs (clients). The Save_Main_File message propagates in this manner. Other messages will start with the child and propagate up to the parents. The update messages propagate in this manner. Usually all you need to know is that the message will get sent to the right DDOs in the right order based on the function of the message.