7.35.1 DELETE Parameters

AUTOCOMMIT

CHECK_ONLY

FROM_FILE

IO_ERROR

IO_STATUS

ISSUE_MSG

NOT_FOUND

RETURN_RRN

WHERE

VAL_ERROR

WITH_KEY

WITH_RRN

WITH_UPDID

Refer to Specifying File Names in I/O Commands.

Refer to Specifying Conditions and Expressions and Specifying WHERE Parameter in I/O Commands.

Refer to Specifying File Key Lists in I/O Commands.

For details of how using this parameter can affect automatic "cross update" checking, refer to the Delete Comments/Warnings section.

Specifies the name of a field that is to receive the "return code" that results from the I/O operation.

If the default value of *STATUS is used the return code is placed into a special field called #IO$STS which can be referenced in the RDML program just like any other field.

If a user field is nominated to receive the return code it must be alphanumeric with a length of 2. Even if a user field is nominated the special field #IO$STS is still updated.

For values, refer to I/O Return Codes.

Specifies what action is to be taken if an I/O error occurs when the command is executed.

An I/O error is considered to be a "fatal" error. Some examples are file not found, file is damaged, file cannot be allocated. These types of errors stop the function from performing any processing at all with the file involved.

If the default value of *ABORT is used the function will abort with error message(s) that indicate the nature of the I/O error.

*NEXT indicates that control should be passed to the next command. The purpose of *NEXT is to permit you to handle error messages in the RDML, and then ABORT, rather than use the default ABORT. (It is possible for processing to continue for LANSA for i and Visual LANSA, but this is NOT a recommended way to use LANSA.)

ER returned from a database operation is a fatal error and LANSA does not expect processing to continue. The IO Module is reset and further IO will be as if no previous IO on that file had occurred. Thus you must not make any presumptions as to the state of the file. For example, the last record read will not be set. A special case of an IO_ERROR is when a trigger function is coded to return ER in TRIG_RETC. The above description applies to this case as well.
Therefore, LANSA recommends that you do NOT use a return code of ER from a trigger function to cause anything but an ABORT or EXIT to occur before any further IO is performed.

*RETURN specifies that in a program mainline control is to be returned to the caller and in a subroutine control is to be returned to the caller routine or the program mainline.

If none of the previous values are used you must nominate a valid command label to which control should be passed.

Specifies the action to be taken if a validation error was detected by the command.

A validation error occurs when information that is to be added, updated or deleted from the file does not pass the FILE or DICTIONARY level validation checks associated with fields in the file.

If the default value *LASTDIS is used control will be passed back to the last display screen used. The field(s) that failed the associated validation checks will be displayed in reverse image and the cursor positioned to the first field in error on the screen.

*NEXT indicates that control should be passed to the next command.

*RETURN indicates that control should be returned to the invoking routine (identical to executing a RETURN command).

If none of the previous values are used you must nominate a valid command label to which control should be passed.

Specifies what is to happen if no record is found in the file that has a key matching the key nominated in the WITH_KEY parameter.

*NEXT indicates that control should be passed to the next command.

*RETURN indicates that control should be returned to the invoking routine (identical to executing a RETURN command).

If none of the previous values are used you must nominate a valid command label to which control should be passed.

Specifies whether a "not found" message is to be automatically issued or not.

The default value is *NO which indicates that no message should be issued.

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 deleted. The WITH_RRN parameter cannot be used if the WITH_KEY or WHERE parameters are used.

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

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.

Refer also to:

• 7.35.2 DELETE Comments / Warnings for details of how using this parameter can affect automatic "cross 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 deleted should be returned. The value returned in this field is not usable when the DELETE command is deleting multiple records from the file.

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

For further information refer also to Load Other File in the Visual LANSA Developers Guide.

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.

*NO, which is the default value, indicates that the I/O operation should be performed in the normal manner.

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

To use commitment control specify COMMIT and/or ROLLBACK commands in your application.

Generally only COMMIT commands are required.

For the implications of using commitment control on the IBM i, refer to Commitment Control in the LANSA for i User 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 deleted.

Only valid if WITH_KEY, WITH_RRN, or WHERE 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 DELETE command must be clearly understood. When a DELETE is issued, there is an automatic "crossed update" checking if no WITH_KEY and no WITH_RRN are specified, or an explicit "crossed update" checking if WITH_UPDID is specified, or effectively no "crossed update" checking if WITH_KEY or WITH_RRN are specified without WITH_UPDID.

  Note that a false "crossed update" error will occur if an 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
     ...
     DELETE (no WITH_KEY and no WITH_RRN)

  Since the DELETE command has no WITH_KEY or WITH_RRN parameter, it is indicating 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 DELETEd.

  Note: This may take some time.

  This is a correct and valid use of the automatic "crossed update" checking facility. If the row is changed by another job/user between the FETCH and the DELETE, the DELETE will generate a "crossed update error" (which must be handled 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")

     DELETE 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 DELETEd, but in this case, it may not be occurring in the same "job"

  Note: This may take some time.

  This is a correct and valid use of the explicit "crossed update" checking facility, as long as the WITH_KEY, for both FETCH and DELETE, acts on the same row. If that row is changed by another job/user between the FETCH and the DELETE, the DELETE will generate a "crossed update error" (which must be handled like any other type of validation error).

• No crossed update checks

  Consider this flow of commands:

     FETCH WITH_KEY( ) or WITH_RRN( )
     DISPLAY
     ...
     DELETE WITH_KEY( ) or WITH_RRN( ) (but no WITH_UPDID)

  Since the DELETE 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 deleted.

  This is a frequent coding mistake to expect an automatic "crossed update" checking. The WITH_KEY or WITH_RRN values on the DELETE command must 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 DELETE.

  In this situation, the "crossed update window" is in the interval between the time the row is (re)read by the DELETE command and then deleted by the DELETE command. This interval is very short, thus the "crossed update" check is effectively disabled.

  This is not considered a valid and correct use of the DELETE command in an interactive scenario because it effectively disables the automatic "crossed update" check.

• No KEY

  When a DELETE command has no WITH_KEY, WHERE, or WITH_RRN parameters specified, the last row read from the table will be deleted. These are equivalent operations:

     DELETE FROM_FILE(ORDHDR) WITH_KEY(#ORDNUM

  is functionally equivalent to:

     FETCH FROM_FILE(ORDHDR) WITH_KEY(#ORDNUM)
     DELETE FROM_FILE(ORDHDR)

  and: 

     DELETE FROM_FILE(ORDLIN) WITH_KEY(#ORDNUM)

  Is functionally equivalent to:

     SELECT FROM_FILE(ORDLIN) WITH_KEY(#ORDNUM)
     DELETE FROM_FILE(ORDLIN)
     ENDSELECT

  Note that the last 2 examples delete all order lines for the order. This is an example of multiple rows deleting or "set at a time" deleting.

  Note DELETE WITH_KEY or WHERE must not be used within a select loop for the same table or view in a subroutine called from within the select loop.