In some instances when ITP accesses an Entry, it shows a Key Selection screen. ITP shows a Key Selection screen for each Main Entry that contains formal parameters and is accessed with the IN keyword. ITP suppresses the Key Selection screen for Main Entries that are accessed with the PATH keyword. ITP also suppresses the Key Selection screen if the parameters are supplied through the API.
In the Key Selection dialog, the user sees a list of records from which he can choose. When the user selects a record ITP will retrieve the matching record from the Entry. The records are presented in the Key Selection screen in batches of 25 records. When the user presses More, ITP retrieves the next 25 records.
For each formal parameter, there is an input Field at the top half of the dialog. When the user enters a value in one of these Fields and presses Ok, ITP retrieves a new set of records. The values entered are used as a positioner. The formal parameters of the first record in the new set have values equal to or greater than the values entered. Beware that these values are not used as selector, but as positioner.
The Key Retrieval attribute in an Entry definition determines how the data should be retrieved for the Key Selection screen. Depending on the DID Module connection type this can be the name or full path of a program, an SQL query, a special value or something else. The first Fields of each record or row that is retrieved by the Key Retrieval method should contain the formal parameters. These Fields should be in the same order and should have the same types as the formal parameters in the Entry definition. These Fields are not shown in the Key Selection screen. The remainder of the record can be filled with arbitrary Fields. ITP shows these Fields in the Key Selection screen. These Fields should be supplied as text Fields. It is generally a good idea to repeat the formal parameters in the Fields shown in the screen. This is also the default behavior for Entries generated by ITP wizards.
Example
We want to define Key Retrieval and selection for an Entry with formal parameters key1 and key2 and Fields key1, key2 and Field3, Field4 and Field5.
A minimal Key Retrieval record should consist of key1 and key2. In this situation however the user only sees blank lines in the Key Selection screen. Therefore, he has no criteria on which to base his selection.
A more significant Key Retrieval record consists of key1, key2, (formal parameters) key1 and key2 (screen Fields). The user now sees the formal parameters in the Key Selection screen and can make a choice based on this information.
There are however many situation in which the formal parameters do not make much sense to an end-user. In such a situation the DID developer can add additional Fields to the Key Retrieval record. If for example Field3 contains some additional identifying information for an end user, we can make a Key Retrieval record containing key1, key2, key1, key2 and Field3.
The user might even be confused by the information from key1 and key2 and we only want to show Field3. In that case, we could have a Key Retrieval record containing key1, key2 and Field3.