Page History

7.125.1 UPDATE Parameters

AUTOCOMMIT

CHECK_ONLY

FIELDS

...

VAL_ERROR

WITH_KEY

WITH_RRN

WITH_UPDID

FIELDS

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.

...

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.

IN_FILE

Refer to Specifying File Names in I/O commands.

...

For the implications of using commitment control on the IBM i, refer to Commitment Control in the LANSA for I User Guide.

WITH_UPDID

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 if WITH_KEY or WITH_RRN are specified.

Any field nominated in this parameter must be defined within the RDML or the LANSA data dictionary and must be numeric.

Only valid where the table contains a LANSA update id column.

Only valid in RDMLX code.

Warnings:

• Crossed Update Checks

  The use of "crossed update" checks by the UPDATE command must be clearly understood. When an update is issued, it may have an automatic "crossed update" checking if neither WITH_KEY nor WITH_RRN is specified, an explicit "crossed update" checking if WITH_UPDID is specified, or effectively no crossed update checking if WITH_KEY or WITH_RRN is specified without WITH_UPDID.

  Note that a false "crossed update" error will occur if automated "crossed update" checking is attempted on IBM i with an IBM i "Other" file if the I/O is using a logical view that does not contain all field names in the table.

• Automatic crossed update checks

  Consider this flow of commands:

  FETCH WITH_KEY( ) or WITH_RRN( )

  DISPLAY

  ...

  UPDATE (no WITH_KEY and no WITH_RRN)

  Since the UPDATE command has no WITH_KEY or WITH_RRN parameter, it indicates that the last row read (by the FETCH command) should be deleted.

  In this situation, the "crossed update window" is in the interval between the time the row was FETCHed and the time it is UPDATEd.

  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(#ORDNUM

  is 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(#ORDNUM

  Is functionally equivalent to:

  SELECT FIELDS(#QUANTITY) FROM_FILE(ORDLIN) WITH_KEY(#ORDNUM)

  CHANGE FIELD(#QUANTITY) TO100)

  UPDATE FIELDS(#QUANTITY) IN_FILE(ORDLIN)

  ENDSELECT

  Note 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.