This statement is used to access the values in a query database.
Click here for information on identifying an open database.
The key field is used to locate the desired row in the query database. There is a special form of the key field which can be used to access absolute row numbers. If the key field starts with #, it should be followed by an integer in the range of 0 through Query Database Row Count-1 which is a named variable initialized when the database was opened. If the database was opened Keyless, this is the only form which can locate an item. In order to enable the use of a symbolic key starting with a #, you can specify a space before the key. Leading and trailing spaces are removed from the key.
Example: A key field of
#\<RowNumber>
implies that you want to access a cell in the row whose zero based index is contained in the RowNumber named variable.
Cell access statements require a column specification. You can specify which column you want to access symbolically or numerically. A symbolic name must exactly match the name (case sensitive) of one of the database columns or all action processing will be terminated. When a query database is first opened the names of the columns are placed in a list in the Query Database Columns named variable. Numeric specifications are numbered left to right from zero. In the rare case that you have a column with a numeric name, simply leave a space in front of the number to force the symbolic lookup.
All text fields may contain any of the escape sequences described in Escape Sequences.
The statement is only executed once for all execution modes.
The following functions can be performed:
- Save Cell to Named Variable
- The contents of the referenced cell are saved to a named variable.
- Set Cell to Value
- The referenced cell's content is set to the specified value. Note that you cannot use this statement to modify the key column.
- Apply Cell to Tracks
- The contents of the referenced cell are applied to all tracks in the current execution mode. You cannot use this statement to apply the key field's contents. Further, only those columns associated with Yate fields in the database's defining Export Set, can be applied.
- Set Cell to Named Variable
- The referenced cell's content is set to the value of the specified named variable. This is a convenience function which avoids the need of escaping a named variable with the Set to value function.
- Save Row as List to Named Variable
- The referenced row's values are saved as a list to the specified named variable. The default list delimiter (\~) separates the list items.
- Save Row to Named Variables With Prefix
- The referenced row's values are saved as individual named variables. The prefix is optional. Each named variable is constructed as follows:
supplied prefix-column name.
or
column name- Set Row from List in Named Variable
- The referenced row's values are set from the list components in the specified named variable. The default list delimiter (\~) separates the list items. If more list components exist than there are columns, the extra components are ignored. If less components exists than there are columns, the missing values will be assumed to be the empty string. Note that the key column, if any, will not be modified, but that the column occupies a location in the list of values.
- Set Row from Named Variables With Prefix
- The referenced row's values are set from individual named variables. The prefix is optional. Each named variable is constructed as follows:
supplied prefix-column name.
or
column name
If a named variable associated with a column cannot be found, the missing value is assumed to be the empty string. Note that the key column, if any, will not be modified.- Set Column to Value
- The specified column in every row is set to the supplied value. Note that you cannot set the value of the key column. When Use previous results is selected, you must specify a named variable containing a list of keys suitable for querying the database. Typically this list will have been produced by an Issue Database Query statement. When specified, only the items identified in the list will be modified. Note that the list delimiter for the previous results list is always the \~ sequence.
- Save Column as List to Named Variable
- The data contained in the specified column of each row in the previous results or in the entire database are saved to the specified named variable. The default list delimiter (\~) separates the returned list items and is always used as the delimiter for the previous results list.
An invalid column specification is a fatal error, as is explicitly attempting to set the value of the key column.
The action test state is set as follows:
- Save
- The action test state will be set to true if the specified key was located. Otherwise it will be set to false. When set to false, the result named variable will be empty.
- Set
- The action test state will be set to true if the specified key was located. Otherwise it will be set to false. It will always be set to true for a column set.
- Apply
- The action test state will be set to true if data was applied to a track. Otherwise it will be set to false. Note that many column types cannot be applied to tracks.