Page History
7.125.1 UPDATE Parameters
|
|---|
Specifies either the field(s) that are to be updated in the file or the name of a group that specifies the field(s) to be updated.
...
*ALL, specifies that all fields from the currently active file be updated.
*ALL_REAL, specifies that all real fields from the currently active file be updated.
*ALL_VIRT, specifies that all virtual fields from the currently active file be updated.
*EXCLUDING, specifies that fields following this special value must be excluded from the field list.
*INCLUDING, specifies that fields following this special value must be included in the field list. This special value is only required after an *EXCLUDING entry has caused the field list to be in exclusion mode.
| Info |
|---|
| When all fields are updated through a logical file maintained by OTHER, all the fields from the based-on physical file are included in the field list. |
It is strongly recommended that the special values *ALL, *ALL_REAL or *ALL_VIRT in parameter FIELDS be used sparingly and only when strictly required. Updating fields which are not needed invalidates cross-reference details (shows fields which are not used in the function) and increases the Crude Entity Complexity Rating of the function pointlessly.
Portability Considerations | On IBM i, if one or more LOB fields are to be updated, and the file is not under commitment control, if an I/O error occurs, it is possible that the non-LOB fields have been updated, but one or more LOB fields have not. Refer also to Commitment Control in the LANSA Application Design Guide. |
|
|---|
Refer to Specifying File Names in I/O commands.
|
|---|
Refer to Specifying File Key Lists in I/O Commands.
Also refer to the comments/warnings section following for details of how using this parameter affects automatic "crossed update" checking.
|
|---|
Specifies the name of a field that is to receive the "return code" that results from the I/O operation.
...
Refer to I/O Command Return Codes Table for I/O operation return codes.
|
|---|
Specifies what action is to be taken if an I/O error occurs when the command is executed.
...
If none of the previous values are used you must nominate a valid command label to which control should be passed.
|
|---|
Specifies the action Specifies the action to be taken if a validation error was detected by the command.
...
If none of the previous values are used you must nominate a valid command label to which control should be passed.
| Info |
|---|
| The *LASTDIS is valid even if there is no "last display" (such as in batch functions). In this case the function will abort with the appropriate error message(s). When using *LASTDIS the "Last Display" must be at the same level as the database command (INSERT, UPDATE, DELETE, FETCH and SELECT). If they are at different levels e.g. the database command is specified in a SUBROUTINE, but the "Last Display" is a caller routine or the mainline, the function will abort with the appropriate error message(s). The same does NOT apply to the use of event routines and method routines in Visual LANSA. In these cases, control will be returned to the calling routine. The fields will display in error with messages returned to the first status bar encountered in the parent chain of forms, or if none exist, the first form with a status bar encountered in the execution stack (for example, a reusable part that inherits from PRIM_OBJT). |
|
|---|
Specifies what is to happen if no record is found in the file to be updated.
...
If none of the previous values are used you must nominate a valid command label to which control should be passed.
|
|---|
Specifies whether a "record not found" message is to be automatically issued or not.
...
The only other allowable value is *YES which indicates that a message should be automatically issued. The message will appear on line 22/24 of the next screen format presented to the user or on the job log of a batch job.
|
|---|
Specifies the name of a field that contains the relative record number (for relative record file processing) of the record which is to be updated.
...
Any field nominated in this parameter must be defined within the function or the LANSA data dictionary and must be numeric.
| Note |
|---|
| Note: Using the WITH_RRN parameter to FETCH, DELETE or UPDATE records is faster than any other form of database access. |
The actual database file being accessed is always the physical file, regardless of whether or not the file nominated in the command is a logical file. Thus logical file select/omit criteria are not used when accessing a logical file via the WITH_RRN parameter.
...
7.125.2 UPDATE Comments / Warnings for details of how using this parameter affects automatic "crossed update" checking.
Load Other File in the Visual LANSA Developers Guide.
|
|---|
Specifies the name of a field in which the relative record number of the record just updated should be returned. The value returned in this field is not usable when the UPDATE command is updating multiple records in the file.
...
For further information refer also to Load Other File in the Visual LANSA Developers Guide.
|
|---|
Indicates whether Indicates whether the I/O operation should actually be performed or only "simulated" to check whether all file and data dictionary level validation checks can be satisfied when it is actually performed.
...
*YES indicates that the I/O operation should be simulated to verify that all file and data dictionary level checks can be satisfied. The database file involved is not changed in any way when this option is used.
|
|---|
This parameter was made redundant in LANSA release 4.0 at program change level E5.
...
For the implications of using commitment control on the IBM i, refer to Commitment Control in the LANSA for I User Guide.
Portability Considerations | If using Visual LANSA, refer to Commitment Control in the LANSA Application Design Guide. |
|
|---|
Specifies the name of a field that contains the update id column to be compared with the update id column of the row to be updated.
...
Only valid in RDMLX code.
| Warning |
|---|
Warnings:
|
Note Note: This may take some time. This is a correct and valid use of the automatic "crossed update" checking facility. If the row was changed by another job/user between the FETCH and the UPDATE, then the UPDATE will generate a "crossed update error" (which should be handled just like any other type of validation error).
Explicit crossed update checks
Consider this flow of commands:
Interaction 1
FETCH RET_UPDID( ) WITH_KEY( ) or WITH_RRN( )
Interaction 2 (same "job" or different "job")
UPDATE WITH_UPDID( ) WITH_KEY( ) or WITH_RRN( )
In this situation, the "crossed update window" is in the interval between the time the row was FETCHed and the time it was UPDATEd, but in this case, it may not be occurring in the same "job".
Again, this could be very long if the user went and had a cup of coffee in between interactions.
This is a correct and valid use of the explicit "crossed update" checking facility, as long as the WITH_KEY for both, FETCH and UPDATE, act on the same row. If that row was changed by another job/user between the FETCH and the UPDATE, then the UPDATE will generate a "crossed update error" (which should be handled just like any other type of validation error).
No crossed update checks
Consider this flow of commands:
FETCH WITH_KEY( ) or WITH_RRN( )
DISPLAY
...
UPDATE WITH_KEY( ) or WITH_RRN( ) (but no WITH_UPDID)Since the UPDATE command has a WITH_KEY or WITH_RRN parameter but no WITH_UPDID parameter, it indicates that a specific row (or group of rows) should be read and updated.
It is a frequent coding mistake to expect automatic "crossed update" checking. Everyone knows that the WITH_KEY or WITH_RRN values on the UPDATE command should be the same as those on the FETCH command. However, the RDML compiler cannot be sure that the values have not been changed since the FETCH command was executed, so it is forced to (re)read the row before attempting the UPDATE.
In this situation, the "crossed update window" is in the interval between the time the row is (re)read by the UPDATE command and then updated by the UPDATE command. This interval is very short, and thus the "crossed update" check is effectively disabled.
This is not considered to be a valid and correct use of the UPDATE command in an interactive scenario like this because it effectively disables the automatic "crossed update" check.
No KEY
Where an UPDATE command has no WITH_KEY or WITH_RRN parameters specified, the last row read from the table will be updated. These are equivalent operations:
CHANGE FIELD(#DATDUE) TO(*DATE)
UPDATE FIELDS(#DATDUE) IN_FILE(ORDHDR) WITH_KEY(#ORDNUMis functionally equivalent to:
FETCH FIELDS(#DATDUE) FROM_FILE(ORDHDR) WITH_KEY(#ORDNUM)
CHANGE FIELD(#DATDUE) TO(*DATE)
UPDATE FIELDS(#DATDUE) IN_FILE(ORDHDR)and:
CHANGE FIELD(#QUANTITY) TO100)
UPDATE FIELDS(#QUANTITY) IN_FILE(ORDLIN) WITH_KEY(#ORDNUMIs functionally equivalent to:
SELECT FIELDS(#QUANTITY) FROM_FILE(ORDLIN) WITH_KEY(#ORDNUM)
CHANGE FIELD(#QUANTITY) TO100)
UPDATE FIELDS(#QUANTITY) IN_FILE(ORDLIN)
ENDSELECTNote that the last 2 examples change the #QUANTITY field name of all order lines for the order to 100. This is an example of multiple row updating or "set at a time" updating.
Note UPDATE WITH_KEY must not be used within a select loop for the same table or view or in a subroutine called from within the select loop.