AIM Keyword Lists
AIM has a special facility for defining information sources that act essentially as single field databases. This facility is useful for situations where you want to present operators with a bounded list ofdata but do not want to define a formal database. See the table Statement Argument Sources for details on how keyword lists are used in a statement definition. These "keyword" lists can be accessed by the sequence editor or by menu pages. See the description of Keyword in Accessing a Database, AIM Variable, V+ Variable, for details on adding keyword lists to menu pages.
Routines in the AIM Base Package contains the description of the following routines that implement the keyword facility:
Create a new keyword list
Add a keyword to an existing list
Returns information about a keyword list.
Get a value from a keyword list (similar to the "db.get.*" routines for accessing database values)
Searches a keyword list for a value
ai.key.find.num ($key[], value, lower, upper, $str, index)( )
Sort a keyword list
Creating a Keyword List
Keyword lists are created in a string array. Each keyword has an associated data value. Keyword lists may be constructed using any 1 or 2-dimensional global string array. The string array $ai.arg[,] has special meaning to the sequence editor (see the next section).
The number and string menu items allow you to display keyword lists. In the field, ai.ctl[ ], or V+ variable that is associated with the keyword, the index of the item selected will be stored. Lists may be displayed as either a single keyword or as a scrolling window showing possible keywords.
The following code will define a "size" keyword list:
CALL ai.key.new($size[]) ; Add the elements to the keyword list CALL ai.key.add($size[], "Small", 36) CALL ai.key.add($size[], "Medium", 44) CALL ai.key.add($size[], "Large", 52)If you used the size keyword list on a numeric menu page item that stored its value in the V+ variable "size_select" and the user selected "Medium", "size_select" would receive the value 2. The following call will return the values "Medium" in $str and 44 in data:
CALL ai.key.get($size[], size_select, $str, data)Keyword Lists and the Sequence Editor
The special global string $ai.arg[,] array contains keyword lists which may be accessed by statement routines in addition to the menu pages. At link time, the value associated with a keyword is packed into the statement argument array. The string array $ai.arg[,]is defined in TEXT.OVR/V2. The value of the left-hand index of the $ai.arg[,] array may be used as an argument type in sequence statement definitions. The negative of the left-hand index is used as the argument type. For example, the following code from ai.system.mes( ) in TEXT.OVR/OV2 creates statement argument type -19:
; Define the statement argument place holder CALL ai.key.add($ai.arg[ai.arg.st.arg,], "--component--", -19) ; Create a new keyword list for "component" (type -19) CALL ai.key.new($ai.arg[19,]) ; Add the elements to the keyword list CALL ai.key.add($ai.arg[19,], "none", 0) CALL ai.key.add($ai.arg[19,], "X", 1) CALL ai.key.add($ai.arg[19,], "Y", 2) CALL ai.key.add($ai.arg[19,], "Z", 3)These statements define a keyword list in the string array $ai.arg[19,] with the following elements:
If the negative of the left-hand index for $ai.arg[,] is specified as the argument type in a statement definition, then the keyword list string values are used as values for the statement argument. The linker packs the keyword numeric value corresponding to the keyword string into the args[ ] array which is passed to the statement execution array.
The elements in $ai.arg[ai.arg.st.arg,] have a special meaning to the sequence editor. These elements define the default strings for statement arguments using keyword lists. The numeric value associated with each of these default strings is the negative of the left-hand index into $ai.arg[,] for the possible keyword values for that argument. For example, a partial list of $ai.arg[1,] is:
This list is used on the statement definition page to select the Argument Type. Selecting "--component--" writes a value of -19 into the argument type field of the statement definition. The sequence editor then uses $ai.arg[19,] as the keyword list to select values for argument "component".
Keyword Lists and the Menu Driver
To use a keyword for a single item numeric fields; specify "keyword" as the format, in the List: data box, specify the name of the string array (without the "$"), and in the Idx: data box, specify the left-hand index of the string array.
For example, using the above example, enter "ai.arg" for List: and "19" for Idx:. If X is selected, the data item will have a value of 2 and the string "Y" will be displayed. If the data does not match any keyword value, "?" is displayed. For input, you must enter one of the keyword strings and the corresponding numeric value is stored as the numeric data.
The low/high limits on the format page refer to index values. If these limits are specified, keywords with indices outside these limits are ignored. For example, if you specify limits as 2 and 3, then only strings X and Y will be considered.
To use a keyword list for a numeric item, specify the keyword list format and a scrolling window will be displayed showing all the keywords within the low/high limits range. When you click on a keyword, the corresponding value is stored as the numeric data. The scrolling line corresponding to the numeric value is highlighted.
For string fields, the setup is identical to numeric items except the numeric value is ignored and the actual keyword is stored.