store
Initiate validation and storage of all occurrences marked as modified. It activates the appropriate validation triggers as required, followed by the write and delete triggers.
store{/complete | /truncate}
store/e{/complete | /truncate} {Entity}
Example: store/e/complete "DEPT"
Qualifiers
| Qualifier | Description |
|---|---|
| /e | Stores the modified occurrences starting with Entity. All child component entities of the stored entity are also stored. |
| /complete | Builds any incomplete hitlists by issuing
the appropriate DBMS calls, prior to starting the actual store process. This allows the user to
continue working through the hitlists after the function has been processed. store/complete may affect performance when operating on extensive sets of data. |
| /truncate | Truncates all hitlists (both inner and outer) after the store statement has been executed. This is the default behavior. |
Parameters
|
Parameter |
Data Type |
Description |
|---|---|---|
|
Entity |
String |
Entity to be stored. If omitted, the current entity ($entname) is stored. |
Return Values
| Value | Meaning |
|---|---|
| 1 | No data was stored because no
modifications were made to the data since the last retrieve or
store statement. Or, no entities are painted on the component. |
| 0 | Data successfully stored. |
| <0 | An error occurred. $procerror contains the exact error. |
| -1 | Constraint violation. Restricted link violation. |
| -3 | Exceptional I/O error (hardware or software). |
| -4 | Open request for table or file failed. The table or file is not painted, or it does not exist. |
| -5 | Update request for nonupdatable occurrence. |
| -6 | Exceptional I/O error on write request; for example, lack of disk space, no write permission, or violation of a database constraint. Check the message frame for details. |
| -7 | Duplicate key. |
| -9 | An attempt to open a DBMS failed because the maximum number of DBMS logons has already been reached. |
| -10 | Occurrence has been modified or removed since it was retrieved; the occurrence should be reloaded. |
| -11 | Occurrence already locked. |
| -15 | Uniface network error. |
| -16 | Network error: unknown. |
|
Value |
Error constant | Meaning |
|---|---|---|
| -2 through -12 | <UIOSERR_*> | Errors during database I/O. |
| -16 through -30 | <UNETERR_*> |
Errors during network I/O. |
| -35 | <UGENERR_4GL_SAYS_ERROR> | A trigger returned a negative value in $status. |
| -301 |
<UVALERR_CONSTRAINT> |
Violation of restricted delete constraint. |
| -1102 | <UPROCERR_ENTITY> | The entity name provided is not a valid name or the entity is not painted on the component. |
Use
Allowed in all component types, except self-contained Reports.
Description
The store statement updates the database with data of all modified occurrences. It initiates implicit validation, including both declarative checks (data type, syntax, and ValRep) and procedural checks (in validation triggers) for all modified, but non-validated data in the component.
The store statement begins by performing any validation that is still outstanding. An implicit validate statement is performed, affecting each occurrence that needs validation (except those that will be deleted): declarative checks are performed and the validate and validateKey triggers are activated as necessary. If any validation action fails, the appropriate error trigger is activated; no data is stored.
If validation completes successfully, store then builds a profile from the modifications made to the occurrences in the component. This profile of modified occurrences is created with the aid of the $occdbmod function. The write, writeUp, delete, or deleteUp trigger for each modified occurrence is activated.
Finally, if the message level for the application is greater than 0, the store statement clears the message frame as it completes. (When the message level is 0, the message frame is never cleared.) The message level can be set with the /pri switch or defined in the application definitions.
After a store statement has been executed, Uniface truncates all hitlists. Uniface then treats the occurrence of the outermost entity as if it has been retrieved from the database. The user cannot modify the primary key. Use the release statement to allow the user to modify the primary key field or fields. Remember that store locks database occurrences; these occurrences remain locked until a commit or rollback is performed.
Note: If the release statement is used, any fields subsequently modified in ProcScript with the /init switch will not set the modification status. The database will not be updated if the store statement is then issued. $status will be set to 1.
Up Entities
If Entity is an Up entity, the writeUp and deleteUp triggers are activated instead of the write and delete triggers. If the occurrences in the Up entity should be written and deleted as well as read, include a write and delete statement in these triggers.
Caution: Writing and deleting Up entities can have serious effects on the integrity of the database.
Locking Behavior
After you retrieve an occurrence from the database, modify it, and store it successfully, if you then modify the occurrence a second time without retrieving it again, Uniface always applies cautious locking, overriding the user-defined locking method.
Validation Status
As each step in the validation process is completed, the corresponding validation status function ($fieldvalidation, $keyvalidation, $occvalidation, and $instancevalidation) is reset to indicate that validation has been successful and is not required again (unless further modifications are made). This ensures that validation will not be needlessly repeated.
Modification Status
The modification status functions for all the occurrences in the component are reset only after the store operation has completed successfully. If the store operation did not succeed, no modification status functions are changed. This allows you to retry a store if a DBMS error occurred, once the reason for that error is eliminated. Uniface applies optimistic locking upon retrying the store.
Using store
The following example uses the store statement in the detail trigger to navigate to the last occurrence in the hitlist:
trigger detail retrieve setocc "DEPT", 4 store/e/complete "DEPT" commit macro "^LAST_OCC" end; detail
In the following example the hitlist is reduced and the last occurrence is ‘4’:
trigger detail retrieve setocc "DEPT", 4 store/e "DEPT" commit macro "^LAST_OCC" end; detail
