table of contents
ici::doc::pod3::sdrtable(3) | ICI library functions | ici::doc::pod3::sdrtable(3) |
NAME¶
sdrtable - Simple Data Recorder table management functions
SYNOPSIS¶
#include "sdr.h" Object sdr_table_create (Sdr sdr, int rowSize, int rowCount); int sdr_table_user_data_set (Sdr sdr, Object table, Address userData); Address sdr_table_user_data (Sdr sdr, Object table); int sdr_table_dimensions (Sdr sdr, Object table, int *rowSize, int *rowCount); int sdr_table_stage (Sdr sdr, Object table); Address sdr_table_row (Sdr sdr, Object table, unsigned int rowNbr); int sdr_table_destroy (Sdr sdr, Object table);
DESCRIPTION¶
The SDR table functions manage table objects in the SDR. An SDR table comprises N rows of M bytes each, plus optionally one word of user data (which is nominally the address of some other object in the SDR's heap space). When a table is created, the number of rows in the table and the length of each row are specified; they remain fixed for the life of the table. The table functions merely maintain information about the table structure and its location in the SDR and calculate row addresses; other SDR functions such as sdr_read() and sdr_write() are used to read and write the contents of the table's rows. In particular, the format of the rows of a table is left entirely up to the user.
- Object sdr_table_create(Sdr sdr, int rowSize, int rowCount)
- Creates a "self-delimited table", comprising rowCount rows of rowSize bytes each, in the heap space of the indicated SDR. Note that the content of the table, a two-dimensional array, is a single SDR heap space object of size (rowCount x rowSize). Returns the address of the new table on success, zero on any error.
- void sdr_table_user_data_set(Sdr sdr, Object table, Address userData)
- Sets the "user data" word of table to userData. Note that userData is nominally an Address but can in fact be any value that occupies a single word. It is typically used to point to an SDR object that somehow characterizes the table as a whole, such as an SDR string containing a name.
- Address sdr_table_user_data(Sdr sdr, Object table)
- Returns the value of the "user data" word of table, or zero on any error.
- void sdr_table_dimensions(Sdr sdr, Object table, int *rowSize, int *rowCount)
- Reports on the row size and row count of the indicated table, as specified when the table was created.
- void sdr_table_stage(Sdr sdr, Object table)
- Stages table so that the array it encapsulates may be updated; see
the discussion of sdr_stage() in sdr(3). The effect of this
function is the same as:
sdr_stage(sdr, NULL, (Object) sdr_table_row(sdr, table, 0), 0)
- Address sdr_table_row(Sdr sdr, Object table, unsigned int rowNbr)
- Returns the address of the rowNbrth row of table, for use in reading or writing the content of this row; returns -1 on any error.
- void sdr_table_destroy(Sdr sdr, Object table)
- Destroys table, releasing all bytes of all rows and destroying the table structure itself. DO NOT use sdr_free() to destroy a table, as this would leave the table's content allocated yet unreferenced.
SEE ALSO¶
sdr(3), sdrlist(3), sdrstring(3)
2016-07-07 | perl v5.24.1 |