Zbex provides you with a special variable type called a table. A table is designed to hold records, much like a file. You may put records into a table using an index number or using string called a key. You may retrieve records from the table the same way. There is also a way to access sequentially all records and their keys. Tables must be declared using the table declaration statement. All tables msut be declared as one dimensional arrays. The size should about 50% larger than you think you need. This is because records stored and retrieve with a key use the hash addressing technique. Records stored in a table may be up to 1000 bytes long. You may retrieve a record, increase its size, and put it back in the table without worrying about writing over some other record. Memory for records in a table is allocated dynamically at run time.
Tables are useful in many applications. If you want to process records at random out of a file, the best way to do this is to read the entire file into a table. If you want to count words from a large document to determine frequency ratios, the best way to do this is to use the words as keys and store the counts as records. Any application that calls for random access either by index or by key will be well served by the use of tables.
There are three instructions that address tables: tget, tput, and treset.
There are three formats to the tget instruction:
- The first format has the table name in square brackets, followed by strings for a key and a record. This format is used for sequential reading of the table.
- The second and third formats differ only in that the second parameter inside the square brackets is a string (key) in one case and an integer expression (index) in the other. These instructions are used to retrieve records from the table by key or by index. The format for the input variable(s) is the same as for getc.
- In the third format, tget is used to retrieve a record from its index in the table. Any index between 1 and the maximum
In the first format, tget is used to sequentially read key/record pairs from the table. The purpose of this instruction is to allow the table to be read as a whole. At run time, the sequential pointer is set to the first record. It can be reset to the first record by calling the tst function. Each execution of tget will retrieve the next key/record entry in the table. An attempt to retrieve beyond the end of the table will result in a run-time error. All key/record pairs will be retrieved, including those which have null keys and null records.
In the second format, tget is used to retrieve a record from its key. The key is the second parameter inside the square brackets. If the key does not exist in the table, the null string is returned.
In the third format, tget is used to retrieve a record from its index in the table. Any index between 1 and the maximum size of the table is considered valid. If the given index has no corresponding pointer in the index table, i.e., no record has been entered with this index, the null string will be returned. An invalid index will result in a run-time error.
There are two possible formats to the tput instruction. These formats are roughly the equivalent of the tget formats two and three. tput is used to store records in a table by key or by index. The format of the output field of the tput instruction is the same as for the putc and putf instructions. You may put out either variables or ASCII test. Variables must be preceded by a tilda sign (~) and followed with a space (see the section on input and output).
In the first format, tput is used to store data in a table record using a key string as the access mechanism. If the key does not already exist in the table, it is created and the run-time size of the table is incremented. If in so doing, the run-time size exceeds 90% of the maximum size, a run-time error will result. This is because hash tables become very inefficient when their size increases beyond 90% of the allocated space. The data to be stored may include the null string. From the point of view of accessing this record by a key, this will have the effect of removing the key/record group from the table. The key/record group is still accessable using the sequential version of tget.
In the second format, tput is used to store data in a table record using an index as the access mechanism. If the index is less than one or greater than the maximum size of the table, a run-time error will result. If a key does not exist for this index, the null key will be written and the run-time size will be incremented.
The treset instruction needs only the name of the table specified in square brackets. This instruction allows a table to be reset to empty, so that it may be reused by the program. This is useful in the case where data is being collected multiple times in the same program session.