This section describes each of the utility functions, their format, usage, and parameters, as well as providing a simple example.
Usage
Frees storage that was allocated from Net.Data's run-time heap using dtw_malloc(). The buffer points to the allocated storage to free.
Format
void dtw_free(void *buffer)
Parameters
| buffer | A pointer to the allocated storage to free. |
Examples
char *myBuf; long nbytes = 8192; myBuf = (char *)dtw_malloc(nbytes); dtw_free((void *)myBuf);
Usage
Retrieves the value of a configuration variable specified by var_name from the Net.Data initialization file. Net.Data owns the memory returned by dtw_getvar(); do not modify or free it.
Format
char *dtw_getvar(char *var_name)
Parameters
| var_name | The name of the configuration variable to retrieve. |
Examples
char *myBindFile;
myBindFile = dtw_getvar("BIND_FILE");
Usage
Returns a pointer to storage that was allocated from Net.Data's run-time heap using dtw_malloc(). The storage is nbytes long. If Net.Data cannot return the requested storage, it returns a NULL pointer.
Format
void *dtw_malloc(long nbytes)
Parameters
| nbytes | The number of bytes to allocate. |
Examples
char *myBuf; long nbytes = 8192; myBuf = (char *)dtw_malloc(nbytes);
Usage
Assigns the width of the row and allocates storage for the column headings. You can use the dtw_row_SetCols() utility function once for each row.
Format
int dtw_row_SetCols(void *row, int cols)
Parameters
| row | A pointer to a newly created row which has not yet allocated any columns. |
| cols | The initial number of columns to allocate in the new row. |
Examples
void *myRow; rc = dtw_row_SetCols(myRow, 5);
Usage
Assigns a table value. The caller of the dtw_row_SetV() utility function retains ownership of the memory pointed to by src. To delete the current table value, assign the value to NULL.
Format
int dtw_row_SetV(void *row, char *src, int col)
Parameters
| row | A pointer to the row to modify. |
| src | A character string containing the new value to set. |
| col | The column number of the value to set. |
Examples
void *myTable; char *myFieldValue = "newValue"; rc = dtw_row_SetV(myRow, myFieldValue, 3);
Usage
Allocates storage from Net.Data's run-time heap and copies the string specified by string into the allocated storage using dtw_malloc(). If Net.Data cannot return the requested storage, it returns a NULL pointer.
Format
char *dtw_strdup(char *string)
Parameters
| string | A pointer to the string value to copy into the storage allocated. |
Examples
char *myString = "This string will be duplicated."; char *myDupString; myDupString = dtw_strdup(myString);
Usage
Adds one or more rows to the end of the table. Assign the table values of the new rows with the dtw_table_SetV() utility after rows are appended to the table.
Format
int dtw_table_AppendRow(void *table, int rows)
Parameters
| table | A pointer to the table to be appended to. |
| rows | The number of rows to append. |
Examples
void *myTable; rc = dtw_table_AppendRow(myTable, 10);
Usage
Returns the current number of columns in the table.
Format
int dtw_table_Cols(void *table)
Parameters
| table | A pointer to the table whose current number of columns is returned. |
Examples
void *myTable; int currentColumns; currentColumns = dtw_table_Cols(myTable);
Usage
Deletes all of the column headings, table values, and the table object.
Format
int dtw_table_Delete(void *table)
Parameters
| table | A pointer to the table to delete. |
Examples
void *myTable; rc = dtw_table_Delete(myTable);
Usage
Deletes one or more columns beginning at the column specified in start_col. To delete all of the rows and columns of a table, substitute the utility function dtw_table_Cols() for the cols parameter.
dtw_table_DeleteCol(table, 1, dtw_table_Cols());
Format
int dtw_table_DeleteCol(void *table, int start_col, int cols)
Parameters
| table | A pointer to the table to modify. |
| start_col | The column number of the first column to delete. |
| rows | The number of columns to delete. |
Examples
void *myTable; rc = dtw_table_DeleteCol(myTable, 1, 10);
Usage
Deletes one or more rows beginning at the row specified in start_row.
Format
int dtw_table_DeleteRow(void *table, int start_row, int rows)
Parameters
| table | A pointer to the table to modify. |
| start_row | The row number of the first row to delete. |
| rows | The number of rows to delete. |
Examples
void *myTable; rc = dtw_table_DeleteRow(myTable, 3, 10);
Usage
Retrieves a column heading. Net.Data owns the memory pointed to by dest; do not modify or free it.
Format
int dtw_table_GetN(void *table, char **dest, int col)
Parameters
| table | A pointer to the table from which a column heading is retrieved. |
| dest | A pointer to the character string to contain the column heading. |
| col | The column number of the column heading. |
Examples
void *myTable; char *myColumnHeading; rc = dtw_table_GetN(myTable, &myColumnHeading, 5);
Usage
Retrieves a value from a table. Net.Data owns the memory pointed to by dest; do not modify or free it.
Format
int dtw_table_GetV(void *table, char **dest, int row, int col)
Parameters
| table | A pointer to the table from which a value is retrieved. |
| dest | A pointer to the character string that is to contain the value. |
| row | The row number of the value to retrieve. |
| col | The column number of the value to retrieve. |
Examples
void *myTable; char *myTableValue; rc = dtw_table_GetV(myTable, &myTableValue, 3, 5);
Usage
Inserts one or more columns after the specified column.
Format
int dtw_table_InsertCol(void *table, int after_col, int cols)
Parameters
| table | A pointer to the table to modify. |
| after_col | The number of the column after which the new columns are to be inserted. To insert columns at the beginning of the table, specify 0. |
| cols | The number of columns to insert. |
Examples
void *myTable; rc = dtw_table_InsertCol(myTable, 3, 10);
Usage
Inserts one or more rows after the specified row.
Format
int dtw_table_InsertRow(void *table, int after_row, int rows)
Parameters
| table | A pointer to the table to modify. |
| after_row | The number of the row after which the new rows are inserted. To insert rows at the beginning of the table, specify 0. |
| rows | The number of rows to insert. |
Examples
void *myTable; rc = dtw_table_InsertRow(myTable, 3, 10);
Usage
Returns the maximum number of rows allowed for the Net.Data table as defined by the dtw_table_New() utility function's parameter, row_lim.
Format
int dtw_table_MaxRows(void *table)
Parameters
| table | A pointer to the table from which the maximum number of rows is returned. |
Examples
void *myTable; int maximumRows; maximumRows = dtw_table_MaxRows(myTable);
Usage
Creates a Net.Data table object and initializes all column headings and field values to NULL. The caller specifies the initial number of rows and columns, and the maximum number of rows. If the initial number of rows and columns is 0, you must use the dtw_table_SetCols() function to specify the number of fields in a row before any table function calls.
Format
int dtw_table_New(void **table, int rows, int cols, int row_lim)
Parameters
| table | The name of the new table. |
| rows | The initial number of rows to allocate in the new table. |
| cols | The initial number of columns to allocate in the new table. |
| row_lim | The maximum number of rows this table can contain. |
Examples
void *myTable; rc = dtw_table_New(&myTable, 20, 5, 100);
Usage
Returns the column number associated with a column heading.
Format
int dtw_table_QueryColnoNj(void *table, char *name)
Parameters
| table | A pointer to the table to query. |
| name | A character string specifying the column heading for which the column number is returned. If the column heading does not exist in the table, 0 is returned. |
Examples
void *myTable; int columnNumber; columnNumber = dtw_table_QueryColnoNj(myTable, "column 1");
Usage
Returns the current number of rows in the table.
Format
int dtw_table_Rows(void *table)
Parameters
| table | A pointer to the table whose current number of rows is returned. |
Examples
void *myTable;
int currentRows;
currentRows = dtw_table_Rows(myTable);
Usage
Sets the number of columns of the table and allocates storage for the column headings. Specify the column headings when the table is created; otherwise, you must specify them by calling this utility function before using any other table functions. You can only use the dtw_table_SetCols() utility function once for a table. Afterwards, use the dtw_table_DeleteCol() or dtw_table_InsertCol() utility functions.
Format
int dtw_table_SetCols(void *table, int cols)
Parameters
| table | A pointer to a new table that has no columns or rows allocated. |
| cols | The initial number of columns to allocate in the new table. |
Examples
void *myTable; rc = dtw_table_SetCols(myTable, 5);
Usage
Assigns a name to a column heading. The caller of the dtw_table_SetN() utility function retains ownership of the memory pointed to by the src parameter. To delete the column heading, assign the column heading value to NULL.
Format
int dtw_table_SetN(void *table, char *src, int col)
Parameters
| table | A pointer to the table whose column heading is assigned. |
| src | A character string being assigned to the new column heading. |
| col | The number of the column. |
Examples
void *myTable; char *myColumnHeading = "newColumnHeading"; rc = dtw_table_SetN(myTable, myColumnHeading, 5);
Usage
Assigns a value in a table. The caller of the dtw_table_SetV() utility function retains ownership of the memory pointed to by the src parameter. To delete the table value, assign the value to NULL.
Format
int dtw_table_SetV(void *table, char *src, int row, int col)
Parameters
| table | A pointer to the table whose value is being assigned. |
| src | A character string assigned to the new value. |
| row | The row number of the new value. |
| col | The column number of the new value. |
Examples
void *myTable; char *myTableValue = "newValue"; rc = dtw_table_SetV(myTable, myTableValue, 3, 5);