Net.Data Language Environment Guide

Language Environment Utility Functions

The Net.Data utility functions fall into 4 categories:

memory management
configuration variable management
table manipulation
row manipulation.

The memory management functions are used to allocate storage to be owned by Net.Data, and to free storage that was allocated by Net.Data using Net.Data's runtime library. The following example illustrates the need for these interfaces. Suppose that Net.Data is written using compiler A, with its corresponding runtime library. A programmer writes a new language environment, but uses compiler B, which has a different runtime library. The language environment cannot free storage allocated by Net.Data, and Net.Data cannot free storage allocated by the language environment because of potential incompatibilities between the two runtime libraries.

Table 2. Memory Management Utility Functions

dtw_malloc() Allocate storage from Net.Data's runtime heap using Net.Data's runtime library.
dtw_free() Free storage allocated from Net.Data's runtime heap using Net.Data's runtime library.
dtw_strdup() Allocate storage from Net.Data's runtime heap and copy the specified string into the allocated storage using Net.Data's runtime library.

The management functions for the configuration variables let language environments access configuration information stored in the Net.Data initialization file. These functions let all language environments share the Net.Data initialization file and use information in it for configuring language environments.

Table 3. Configuration Utility Functions

dtw_getvar() Retrieve the value of a configuration variable from the Net.Data initialization file.
dtw_setvar() Set the value of a configuration variable in the Net.Data initialization file.

The table functions are used to manipulate any Net.Data macro table variables passed to the language environment.

Table 4. Table Utility Functions

dtw_table_New() Create a table object.
dtw_table_Delete() Delete a table object.
dtw_table_SetCols() Set the width of a table and allocate storage for the column headers.
dtw_table_GetV() Retrieve a table row/column value.
dtw_table_SetV() Set a table row/column value.
dtw_table_GetN() Retrieve a table column heading.
dtw_table_SetN() Set a table column heading.
dtw_table_Rows() Get the current number of rows in a table.
dtw_table_Cols() Get the current number of columns in a table.
dtw_table_MaxRows() Get the maximum allowable number of rows in a table.
dtw_table_QueryColnoNj() Get the column number of a column heading.
dtw_table_AppendRow() Add one or more rows to the end of a table.
dtw_table_InsertRow() Insert one or more rows in a table.
dtw_table_DeleteRow() Delete one or more rows from a table.
dtw_table_InsertCol() Insert one or more columns in a table.
dtw_table_DeleteCol() Delete one or more columns from a table.

The row functions manipulate the row object that is passed to a language environment's dtw_getNextRow() function when processing rows sequentially

Table 5. Row Utility Functions

dtw_row_SetCols() Set the width of a row.
dtw_row_SetV() Set a row/column value.

dtw_free()

Usage

Frees storage allocated from Net.Data's runtime heap using Net.Data's runtime library. 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);

dtw_getvar()

Usage

Retrieves the value of a configuration variable specified by var_name from the Net.Data initialization file.

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");

dtw_malloc()

Usage

This function returns a pointer to storage allocated from Net.Data's runtime heap using Net.Data's runtime library. The storage is nbytes long. If the requested storage cannot be returned, a NULL pointer is returned.

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);

dtw_row_SetCols()

Usage

This function sets the width of the row and allocates storage for the column headers. The dtw_row_SetCols() function can be used 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);

dtw_row_SetV()

Usage

This function sets a field value. The value that is assigned should be a pointer to a character string allocated using dtw_malloc() or dtw_strdup(), or NULL to delete a field value.

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);

dtw_setvar()

Usage

This function changes the value of a configuration variable specified by var_name in the Net.Data initialization file. The new value of the variable is set to the value specified by new_value.

Format

void dtw_setvar(char *var_name, char *new_value)

Parameters

var_name The name of the configuration variable to modify.
new_value The new value to which var_name is set.

Examples

char *myVariableValue = "new variable value";
 
dtw_setvar("MY_VARIABLE", myVariableValue);

dtw_strdup()

Usage

This function allocates storage from Net.Data's runtime heap and copies the string specified by string into the allocated storage using Net.Data's runtime library. If the requested storage cannot be returned, a NULL pointer is returned.

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);

dtw_table_AppendRow()

Usage

This function adds one or more rows to the end of the table. The field values of the new rows must be set using dtw_table_SetV() after they are added.

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);

dtw_table_Cols()

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);

dtw_table_Delete()

Usage

Deletes all of the column headings and field values, then deletes 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);

dtw_table_DeleteCol()

Usage

This function deletes one or more columns beginning at the column specified in start_col. To delete all of the rows and columns of a table, use 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);

dtw_table_DeleteRow()

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);

dtw_table_GetN()

Usage

Retrieves a column heading. Delete the returned string only by assigning NULL to the column heading with dtw_tableSetN.

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);

dtw_table_GetV()

Usage

Retrieves a field value from a table. You can delete the returned string only by assigning NULL to the field value with dtw_tableSetV.

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 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);

dtw_table_InsertCol()

Usage

This function 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 inserted. To insert columns at the beginning of the table, specify a 0.
cols The number of columns to insert.

Examples

void *myTable;
 
rc = dtw_table_InsertCol(myTable, 3, 10);

dtw_table_InsertRow()

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 for this parameter.
rows The number of rows to insert.

Examples

void *myTable;
 
rc = dtw_table_InsertRow(myTable, 3, 10);

dtw_table_MaxRows()

Usage

Returns the maximum number of rows allowed in the table.

Format

int dtw_table_MaxRows(void *table)

Parameters

table A pointer to the table whose maximum number of rows is returned.

Examples

void *myTable;
int maximumRows;
 
maximumRows = dtw_table_MaxRows(myTable);

dtw_table_New()

Usage

This function creates a table object and initializes all of the 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 are 0, the dtw_table_SetCols() function must set 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 A pointer to the table to create.
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 allocate.

Examples

void *myTable;
 
rc = dtw_table_New(&myTable, 20, 5, 100);

dtw_table_QueryColnoNj()

Usage

Returns the column number of the 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");

dtw_table_Rows()

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);

dtw_table_SetCols()

Usage

Sets the number of columns of the table and allocates storage for the column headers. Specify the column headings when the table is created or else it must be specified by calling this function before using any other table functions. The dtw_table_SetCols() function can be used only once for a table. Afterwards, use the dtw_table_DeleteCol() or dtw_table_InsertCol() 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);

dtw_table_SetN()

Usage

Sets a column heading. Assign a value that is a pointer to a character string allocated using dtw_malloc() or dtw_strdup(), or NULL to delete a column heading.

Format

int dtw_table_SetN(void *table, char *src, int col)

Parameters

table A pointer to the table whose column heading is set.
src A character string containing the new column heading to set.
col The column number of the column heading to set.

Examples

void *myTable;
char *myColumnHeading = "newColumnHeading";
 
rc = dtw_table_SetN(myTable, myColumnHeading, 5);

dtw_table_SetV()

Usage

Sets a field value. The assigned value is a pointer to a character string allocated using dtw_malloc() or dtw_strdup(), or NULL to delete a field value.

Format

int dtw_table_SetV(void *table, char *src, int row, int col)

Parameters

table A pointer to the table whose value is set.
name A character string containing 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);

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]

dtw_malloc()	Allocate storage from Net.Data's runtime heap using Net.Data's runtime library.
dtw_free()	Free storage allocated from Net.Data's runtime heap using Net.Data's runtime library.
dtw_strdup()	Allocate storage from Net.Data's runtime heap and copy the specified string into the allocated storage using Net.Data's runtime library.

dtw_getvar()	Retrieve the value of a configuration variable from the Net.Data initialization file.
dtw_setvar()	Set the value of a configuration variable in the Net.Data initialization file.

dtw_table_New()	Create a table object.
dtw_table_Delete()	Delete a table object.
dtw_table_SetCols()	Set the width of a table and allocate storage for the column headers.
dtw_table_GetV()	Retrieve a table row/column value.
dtw_table_SetV()	Set a table row/column value.
dtw_table_GetN()	Retrieve a table column heading.
dtw_table_SetN()	Set a table column heading.
dtw_table_Rows()	Get the current number of rows in a table.
dtw_table_Cols()	Get the current number of columns in a table.
dtw_table_MaxRows()	Get the maximum allowable number of rows in a table.
dtw_table_QueryColnoNj()	Get the column number of a column heading.
dtw_table_AppendRow()	Add one or more rows to the end of a table.
dtw_table_InsertRow()	Insert one or more rows in a table.
dtw_table_DeleteRow()	Delete one or more rows from a table.
dtw_table_InsertCol()	Insert one or more columns in a table.
dtw_table_DeleteCol()	Delete one or more columns from a table.

dtw_row_SetCols()	Set the width of a row.
dtw_row_SetV()	Set a row/column value.

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.

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.

var_name	The name of the configuration variable to modify.
new_value	The new value to which var_name is set.

table	A pointer to the table to be appended to.
rows	The number of rows to append.

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.

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.

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.

table	A pointer to the table from which a value is retrieved.
dest	A pointer to the character string to contain the value.
row	The row number of the value to retrieve.
col	The column number of the value to retrieve.

table	A pointer to the table to modify.
after_col	The number of the column after which the new columns are inserted. To insert columns at the beginning of the table, specify a 0.
cols	The number of columns to insert.

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 for this parameter.
rows	The number of rows to insert.

table	A pointer to the table to create.
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 allocate.

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.

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.

table	A pointer to the table whose column heading is set.
src	A character string containing the new column heading to set.
col	The column number of the column heading to set.

table	A pointer to the table whose value is set.
name	A character string containing the new value.
row	The row number of the new value.
col	The column number of the new value.