Specifies the name of the list that should be searched by this command.
The default value of *FIRST specifies that the first list declared in the RDML program by a DEF_LIST (define list) command is the list to be used. This list must have the TYPE(*WORKING) parameter to be valid.
If a list name is used then the list name must be declared elsewhere in the RDML program by a DEF_LIST (define list) command and must have the TYPE(*WORKING) parameter.
Refer to Specifying Conditions and Expressions.
If no WHERE parameter is specified then the first entry in the list will always be returned by the LOC_ENTRY command.
Optionally specify the name of a field that is to be set by the LOC_ENTRY command to contain the entry number of the entry located.
If no entry is found in the list that satisfies the condition the field's value is not changed by the LOC_ENTRY command.
*NONE, which is the default value indicates that no field is to contain the located list entry number. If a field is nominated, it must be of type numeric and have been defined previously in the LANSA data dictionary or elsewhere in the function.
As each entry is added to a list by the ADD_ENTRY command it is assigned a number that identifies it. List entries are numbered from 1 (first entry number) to 9999 (maximum possible last entry number) sequentially.
By knowing a list entry number it is possible to directly retrieve an individual list entry (see the GET_ENTRY command for more details).
Specifies the name of a field that is to receive the "return code" that results from the LOC_ENTRY command.
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 and be defined in the LANSA data dictionary or elsewhere in the function. Even if a user field is nominated the special field #IO$STS is still updated.
The LOC_ENTRY command only returns 2 possible status codes. These are "OK" (an entry was located) or "NR" (no entry was located).
Specifies whether or not the located list entry should be returned from the list into the RDML program.
*YES, which is the default value, indicates that the located list entry should be returned into the RDML program.
*NO indicates that there is no need to return the list entry into the RDML program. This option is typically used when a list is being used for validation purposes. In such cases, it is the fact that the entry is in (or not in) the list that matters, not its location or content.
The command:
LOC_ENTRY IN_LIST(#COUNTRIES) WHERE('#CNTRY = AUST')
is functionally identical to the commands:
LOC_ENTRY IN_LIST(#COUNTRIES) WHERE('#CNTRY = AUST') RET_NUMBER(#NUMBER) RET_ENTRY(*NO)
IF_STATUS IS(*OKAY)
GET_ENTRY NUMBER(#NUMBER) FROM_LIST(#COUNTRIES)
ENDIF
