Scrolling a table so that key values currently in buffer are in a specified position (table_set_key)¶
table_set_key() |
Scroll a table so that key values currently in buffer are in a specified position |
SYNTAX
table_set_key(table_id, topline, row)
This function can only be used with tables whose source object is a file. It scrolls the table so that the record whose key matches the current values in the source file’s default buffer is displayed in the specified row number. The default buffer has the same name as the file, and is allocated to it automatically.
The row must be an integer value in the range 1 to table_id->rows. This range represents the actual rows currently visible on the table (not the total number of table lines). See Table size.
If a record with the specified key does not exist, the record with the next highest key is scrolled to the row.
The topline argument determines the position of the vertical scroll bar. If this is not known a reasonable estimate should be provided, or the nextkey command used to count this key’s position from the start of the file.
If the table source object is a secondary index, the key values for that index must be set in the default record buffer before this function is called.
One use for this function is to restore a table to a previously saved position. To save the position of a table driven by a secondary index, it is necessary to read the record in order to supply the index’s key values - the table_get_key() function only returns the main key field values. The example below illustrates this.
The function returns OKAY (0) if the operation was successful, or ERROR (1) if the row is out of range or the table source object is not a file.
EXAMPLE
Demonstrates the use of table_set_key() to restore the saved position of a table whose source object is a secondary index:
!ofile Types "data/types" update
!record SaveTypes = Type
!temp SaveTL,,i4
+table TypesTable {
source_object = Types.Desc
...
}
table_get_key(TypesTable, 1) /* Get key for current top line */
readu Types nsr = IGNORE /* Read the record. Needed because source_object is an index */
SaveTypes = Types /* Save the current file buffer */
SaveTL = TypesTable->topline /* Save the current top line */
...
Types = SaveTypes /* Restore saved values */
table_set_key(TypesTable, SaveTL, 1) /* Restore original top row to table */
RELATED TOPICS |