Table source object

source_object = field_id | file_id | [file_id.]index_id | record_id | func_id

The object that provides the source for the values in the table. This clause is mandatory. Unless the source object is a function, it also serves as the default display object, defining the table columns.

The valid object types are:

field_id

An array field. This forms a single-column table. The total number of lines listed is the field’s dimension, or the current value of the max_line = clause, whichever is the lesser. The line number of each value in the table is that of the corresponding array subscript.

file_id

A Sculptor keyed file. The total number of lines listed is the number of records in the file, which can change dynamically. The max_line = clause is not used when the source object is a file. Sculptor reads the file and maintains the display automatically. To update the table use the display command:

display table_id

The advantage of using a file as the source object is that the file can be any size, and that Sculptor will efficiently determine the records to be displayed for any position of the vertical scroll bar. It is only possible to do this accurately if the file’s index is packed and balanced. After building the file, run the kfri program to rebuild and pack the index, as follows:

kfri -p filename

A file which is frequently updated is not very suitable for use as a table source object. In this case, a better approach is to take a snapshot of the file by building a temporary index, and to use a function as the source object. It is also not recommended that a file be used as the source object if the program is intended to run over the Internet. It is better to minimise file access by reading the record data into arrays and using batch file read mode.

A record_id may be assigned as the display object. Each file record is then assigned to the display object before display. The fields required should be given the same name in the display object as they have in the file. Only those fields which have a corresponding name in the display object are included in the table, with each selected field forming a column. Thus a subset of the fields in the file may be selected for inclusion in the table.

If there is no display object, all the fields in the file form the table columns.

The following functions are available for use with file-driven tables only:

table_first_selected_key()

Get key values of first selected record

table_get_key()

Copy key values from a table to the source file buffer

table_is_selected_key()

Test if record in file record buffer is currently selected

table_next_selected_key()

Get key values of next selected record

table_set_key()

Scroll table to display record in file buffer in a specified row

table_set_selected_key()

Select/deselect the record in the file buffer

Note

An ODBC/SQL database file cannot be used as a table source object.

[file_id.]index_id

A Sculptor keyed file secondary index. The file_id need not be specified if the index_id is unique within the program. Other details are the same as for a main file.

record_id

If the record buffer has a file_id clause, it works exactly as if it were a file_id (see above).

Otherwise the record has its own field list and all the fields which are to be displayed should be subscripted (before Sculptor version 6.2.0). A value must be assigned to max_line, or no lines will display. The line number of each value in the table is that of the corresponding array subscript, and the table is populated automatically.

Since Sculptor version 6.2.0 with the record array feature there is no need to define a record of field arrays and is possible to just define a more logical record array, e.g:

!record srcObj[20] {
    fldCol1,,a10
    fldCol2,,a10
}
...
+table ... {
    source_object = srcObj
}
...

A different record_id may be assigned as the display object. Each line of values is then assigned to the display object before display. The fields required should be given the same name in the display object as they have in the record structure.

Only those fields which have a corresponding name in the display object are included in the table, with each selected field forming a column. Sculptor maintains the display automatically.

If there is no display object, all the fields in the record form the table columns.

func_id

When a function is defined as the source object, the contents of the lines of the table are determined by calls to this function. If the table is defined as being initially created (+table table_id), the function is called before any other program code is executed. The function is called as follows:

func_id(EV_SUPPLY_VALUE, table_id, line, display_object)

The line defines the line in the table which is to be filled. The function must either assign the required values to the display object and return OKAY, or, if the line number exceeds the maximum number of lines to be listed, must return ERROR. The maximum number of lines is determined by the max_line = clause, which must be defined.

The function is called automatically to supply the initial values whenever the table is created, once for each row to be initially displayed. Further calls to the function are generated whenever the user scrolls up or down the table. These may include requests to resupply values that have been previously provided. The program must assign the required values for the line to the fields in the display object.

NOTES

  • If an editable table has a display object that differs from the source object, is may be appropriate to assign the edit mode flag EM_SYNC_SOURCE to the table. This causes the source object to be updated when a cell loses focus. If this flag is not set, only the display object is updated.

  • If a table is declared with +table, and the source object is a file or function, the file is read or the function called before any other program code is executed, which means that +windows other than the table’s parent window may not yet have been created. If this is not desired, use -table and create the table in the main code.

EXAMPLE

In this example the line number argument is used to read a temporary file which provides the key for the main file. The fields required from this file have been given identically named fields in the display object, so the standard record assignment “DisplayObj = MainFile” is all the assignment required.

!function SourceObj(EventCode, Table, Line, DisplayObj) {
     if EventCode != EV_SUPPLY_VALUE then return

     findu TempFile key = Line nsr = NO_SUCH_LINE
     readu MainFile key = tmp.Key nsr = NO_SUCH_LINE
     DisplayObj = MainFile
     return OKAY

NO_SUCH_LINE:
     return ERROR
}

RELATED TOPICS

Tables