12.5 RDML I/O Return Codes
Most LANSA database commands issue a "return code" when they have completed. This return code is always mapped into a field called #IO$STS which can be used in conditional statements like any other field. Optionally the return code can also be mapped into a user defined field. Refer to the IO_STATUS parameter of the required command for more information about how this is done.
However, the approach which should be taken in all normal commercial functions is that if there was a fatal error, allow the automatic error handler to take care of it. Either the I/O operation worked, or it didn't work (and if it didn't the messages will explain why, not the return code).
The list of all I/O return code values and their meanings are as follows:
|
Return Code |
Description / Meaning |
|
OK |
OKAY. Operation completed normally. No errors detected. |
|
ER |
FATAL ERROR. Fatal file error detected. Error is probably irrecoverable. Locate cause of problem, correct, and re-attempt the operation. See also the section in this chapter that describes locked I/O status records. |
|
VE |
VALIDATION ERROR. Insert, update or delete operation failed to satisfy a file or dictionary level validation check. |
|
NR |
NO RECORD. No record(s) could be found matching the request. |
|
EF |
END OF FILE. End of file detected during read operation. |
|
BF |
BEGINNING OF FILE. Beginning of file detected during a read backwards. |
|
EQ |
EQUAL KEY FOUND. A record with a key equal to the key specified was found in the file. |
|
NE |
NO EQUAL KEY FOUND. No record could be found with a key equal to the key specified. |
There are various ways of checking the return code after an I/O operation has been performed.
The first is to always use the IO_STATUS(*STATUS) default parameter on an I/O command. In this case the return code is mapped into a field called #IO$STS which can be referenced just like any other field. For example:
FETCH FIELDS(#ORDERHEAD) FROM_FILE(ORDHDR) WITH_KEY(#ORDER)
IF COND('#IO$STS *NE OK')
MESSAGE MSGTXT('Order not found in current order file')
ENDIF
The second is to use the IO_STATUS parameter to map the return code into a user defined field. For example:
DEFINE FIELD(#RETCODE) TYPE(*CHAR) LENGTH(2)
FETCH FIELDS(#ORDERHEAD) FROM_FILE(ORDHDR) WITH_KEY(#ORDER)
IO_STATUS(#RETCODE)
IF COND('#RETCODE *NE OK')
MESSAGE MSGTXT('Order not found in current order file')
ENDIF
The third, and probably the best, is to use the IF_STATUS command to test the last return code automatically. The example already used would become:
FETCH FIELDS(#ORDERHEAD) FROM_FILE(ORDHDR) WITH_KEY(#ORDER)
IF_STATUS IS_NOT(*OKAY)
MESSAGE MSGTXT('Order not found in current order file')
ENDIF
Refer to the IF_STATUS command for more details and examples.
Also see