7.5.1 BROWSE Parameters
Specifies either the field(s) that are to be browsed from the record in the file or the name of a group that specifies the field(s) to be browsed.
Refer to Specifying File Names in I/O Commands.
Refer to Specifying Conditions and Expressions.
Refer to Specifying File Key Lists in I/O Commands.
This parameter can be used in conjunction with the WITH_KEY parameter to vary the number of key fields that are actually used to browse records at execution time.
*WITHKEY, which is the default value, specifies that the number of key fields will always match the number specified in the WITH_KEY parameter and the value will not be changed at execution time.
If the number of key fields is to be varied at execution time specify the name of a numeric field that contains the number of keys value. The field specified must be defined in this function or in the LANSA data dictionary and must be numeric.
At execution time the value contained in the NBR_KEYS field must not be less than zero or greater than the number of key fields specified in the WITH_KEY parameter.
Refer to the examples following for more information.
Specifies whether or not generic searching is required. Generic searching is different to full or partial key searching because only the non-blank or non-zero portion of the key value is used when comparing the search key with the file key.
When using generic searching on an alphanumeric field only the leftmost non-blank portion of the search field is compared with the file key (i.e: trailing blanks are ignored for comparative purposes).
When using generic searching on a numeric field only the leftmost non-zero portion of the search field is compared with the file key (i.e: trailing zeros are ignored for comparative purposes). Also, generic numeric field comparisons are done as if both the search key and the file key are positive numbers, regardless of what they actually are.
Note that these generic search rules mean that a blank alphanumeric search key or a zero (0) numeric key will match every record selected.
For example, if a file was keyed by a name field and it contained the following values:
SM
SMIT
SMITH
SMITHS
SMITHY
SMYTHE
Then the SELECT statement:
SELECT WITH_KEY('SM')
would only select the first record in the file because it is the only record that matches the full key value 'SM'.
If however, the SELECT statement was changed to:
SELECT WITH_KEY('SM') GENERIC(*YES)
then all the records in the file would be selected because only the non-blank portion of the key value specified is compared with the file key.
*NO, which is the default value, indicates that generic searching is not required.
*YES, indicates that generic searching is to be performed. When generic searching is used it is actually performed only on the last key that was supplied at execution time. Other (previous) keys specified in the WITH_KEY parameter must exactly match the values in the file. They are not generically compared with the data in the file.
For instance, imagine a name and address file that is keyed by state, post/zip code and name. The command:
SELECT WITH_KEY('NSW' 2000 'SM') NBR_KEYS(3) GENERIC(*YES)
would select all names in NSW, with postcode 2000 whose names start with SM. This is an example of generic searching on an alphanumeric field. Trailing blanks are ignored when comparing the search key with the data read from the file. Also note that only the last key ('SM') is actually generically compared with the data on the file. The other keys , 'NSW' and 2000 must exactly match data read from the file.
If, at execution time the command was dynamically modified to use 2 keys, like this:
SELECT WITH_KEY('NSW' 2000 'SM') NBR_KEYS(2) GENERIC(*YES)
then it would select all names in NSW with a post code that starts with 2. This is an example of generic searching on a numeric field where trailing zeroes (0's) are ignored.
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 will still be 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.
If the default value *ABORT is not used you must nominate a valid command label to which control should be passed if an I/O error occurs.
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 will be positioned to the first field in error on the screen.
If the default value *LASTDIS is not used you must nominate either *NEXT, indicating that control should be passed to the next command, or, 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 whether the browse is to allow record selection.
The default value is *YES which means that when the browse is displayed, the user will be able to nominate which record is to be selected. Once a record selection is made, all of the fields in the function will contain the associated values and the program will continue on to the next statement.
The only other allowable value is *NO which means that the browse will be displayed with no select column. Once the enter key or a function key is pressed, the program will continue to the next statement. The value of fields within the function will be unchanged. The I/O status will return an OK if there was at least one record in the browse or else NR if there were no records in the browse.
Indicates the action to be taken if no browse entry was selected.
The default *NEXT will pass control to the next executable command.
Otherwise nominate the label associated with a command to which control should be passed.
This option will be ignored if USE_SELECT(*NO) has been specified.
Indicates what action is to be taken if the browse command finds one and only one record matching the search criteria.
The default, *DISPLAY indicates that the record should be displayed to the user.
The only other option is to specify *SELECT which will automatically select the record. This provides a very simple means of supplying generic search lists. A partial key can be supplied, and if a single hit was found then the record would be retrieved. If more than one record was found then LANSA would prompt the user to select the desired record.
Specifies whether an "end of file" 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 in which the relative record number of the record just selected should be returned in.
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 .
Specifies the spacing between rows on the browse. The value specified must be *DESIGN or a number in the range 1 to 10. DESIGN will set a default value of 1.
Specifies the spacing between columns on the browse. The value specified must be *DESIGN or a number in the range 1 to 10. DESIGN will set a default value of 1.
Specifies whether the EXIT function key is to be enabled when the browse list is displayed at the workstation. In addition it also specifies what is to happen if the EXIT key is used.
*YES, which is the default value, indicates that the EXIT key should be enabled when the screen is displayed.
If *YES is used it is also possible to nominate a command label to which control should be passed when the EXIT key is used.
If no label is specified the default value of *EXIT is used which specifies that a complete exit from the LANSA system should be performed. In SAA/CUA partitions this is referred to as a "high" exit.
*NO indicates that the EXIT function key should not be enabled when the screen is displayed.
Specifies whether the MENU function key is to be enabled when the browse list is displayed at the workstation. In addition it also specifies what is to happen if the MENU key is used.
*YES, which is the default value, indicates that the MENU key should be enabled when the screen is displayed. If *YES is used it is also possible to nominate a command label to which control should be passed when the MENU key is used. If no label is specified the default value of *MENU is used which specifies that the process's main menu should be re-displayed.
*NO indicates that the MENU function key should not be enabled when the screen is displayed.
Specifies whether the ADD function key is to be enabled when the browse list is displayed at the workstation. In addition it also specifies what is to happen if the ADD key is used.
*NO, which is the default value, indicates that the ADD function key should not be enabled when the screen is displayed.
*YES indicates that the ADD key should be enabled when the screen is displayed. If *YES is used it is also possible to nominate a command label to which control should be passed when the ADD key is used. If no label is specified the default value of *NEXT is used which specifies that the next RDML command should be executed.
Specifies whether the CHANGE function key is to be enabled when the browse list is displayed at the workstation. In addition it also specifies what is to happen if the CHANGE key is used.
*NO, which is the default value, indicates that the CHANGE function key should not be enabled when the screen is displayed.
*YES indicates that the CHANGE key should be enabled when the screen is displayed. If *YES is used it is also possible to nominate a command label to which control should be passed when the CHANGE key is used. If no label is specified the default value of *NEXT is used which specifies that the next RDML command should be executed.
Specifies whether the DELETE function key is to be enabled when the browse list is displayed at the workstation. In addition it also specifies what is to happen if the DELETE key is used.
*NO, which is the default value, indicates that the DELETE function key should not be enabled when the screen is displayed.
*YES indicates that the DELETE key should be enabled when the screen is displayed. If *YES is used it is also possible to nominate a command label to which control should be passed when the DELETE key is used. If no label is specified the default value of *NEXT is used which specifies that the next RDML command should be executed.
Specifies up to 5 additional user function keys that will be enabled when the browse list is displayed at the workstation.
Any user function keys assigned must not conflict with function keys assigned to the standard LANSA functions of EXIT, MENU, MESSAGES, ADD, CHANGE or DELETE when they are enabled on a command (i.e: a function key cannot be assigned to more than one function).
Additional user function keys are specified in the format:
where:
|
fnc key number |
Is a normal function or function key number in the range 1 to 24. |
|
'description' |
Is a description of the function assigned to the function key. This description will be displayed on line 23 of the screen format. Maximum length is 8 characters. |
|
Label |
Is an optional label to which control should be passed if the function key is used. Special value *NEXT is assumed as a default and indicates that the next command (after this one) should receive control. |
Refer to the IF_KEY command for details of how the function key that was used can be tested in the RDML program.
As an example of use consider the following:
BROWSE ...... USER_KEYS((14 'Commit')(15 'Purge'))
IF_KEY WAS(*USERKEY1)
<< Commit logic >>
ENDIF
IF_KEY WAS(*USERKEY2)
<< Purge logic >>
ENDIF
Note that the IF_KEY command refers to the keys by symbolic names that indicate the order in which they are declared in the USER_ KEYS parameter, not the actual function key numbers assigned to them. This makes changing function key assignments easier.
Specifies whether the "next function" field should be shown on line 22 of the screen. The next function field is a facility that allows transfer between the functions in a process without the need to return to the process menu each time. Refer to The Function Control Table in the for details about "next function" processing.
*PRO, which is the default value, indicates that the "next function" field should appear only when the process to which this function belongs has a menu selection style of "FUNCTION". If the process menu selection style is "NUMBER" or "CURSOR" then the next function field should not appear.
*YES indicates that the next function field should appear regardless of what menu selection style is being used by the process to which this function belongs.
*NO indicates that the next function field should not appear regardless of what menu selection style is being used by the process to which this function belongs.
Note: The SHOW_NEXT parameter is ignored in SAA/CUA applications.