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.