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.
An expandable group expression is allowed in this parameter. Refer to Field Groups and Expandable Groups for more details. The following special values can be used:
Note: 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.
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.
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.
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 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.
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.
*NEXT indicates that control should be passed to the next command.
*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 whether a "record 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 updated.
The WITH_RRN parameter cannot be used with the WITH_KEY parameter.
Any field nominated in this parameter must be defined within the function or the LANSA data dictionary and must be numeric.
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.
Refer also to:
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.
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.
|
Portability Considerations |
If using Visual LANSA, refer to Commitment Control in the LANSA Application Design Guide. |
