A language environment must have a dtw_execute() routine. Other routines are optional. If a Net.Data macro references a language environment that does not have a dtw_execute() routine, Net.Data returns an error message and stops processing the Net.Data macro.
Language environments must be referenced in the Net.Data macro being processed to be called. The language environment routines must be called in this order:
The next sections describe these routines.
In the scope of handling a Net.Data request, Net.Data calls a language environment's dtw_initialize() function (if it is defined) only once, the first time a function block referencing that language environment is called. Subsequent references to the language environment bypass the call to the dtw_initialize() function.
This function does not affect message block processing. A positive or zero return code means that processing continues; a negative return code means that processing does not continue. If the return code is non-zero and there is a default message defined in the default_error_message field, the default message is issued; if there is no default message, Net.Data issues an error message.
The dtw_execute() language environment interface function is called whenever a Net.Data macro processes a FUNCTION block. When the dtw_execute() function completes, what happens next depends on whether the DTW_LE_CONTINUE flag in the dtw_lei structure is set by the dtw_execute() function.
If the DTW_LE_CONTINUE flag is set, Net.Data performs the following steps:
Performance is usually optimized when the dtw_execute() function does all the processing necessary to produce the input for the report block processing. For example, the SQL language environment's dtw_execute routine generates the entire table to be processed during the report block phase.
The dtw_getNextRow() language environment interface function is called when these conditions are met:
When the dtw_getNextRow() function is called, the row field in the dtw_lei structure is set to point to a row object. To manipulate the row object, the Net.Data utility routines dtw_row_SetCols() and dtw_row_SetV() should be used. It is assumed that after the first call to the dtw_getNextRow() routine the row object contains the column headings. Subsequent calls should contain the actual table data.
The dtw_getNextRow() continues to get called (unless message block processing indicates otherwise) as long as the DTW_LE_CONTINUE flag is set.
While handling a Net.Data request, Net.Data calls a language environment's dtw_cleanup() function one time, if you define it. The function is only called if Net.Data processed the Net.Data macro that references the language environment and either Net.Data processing ended or an error stopped Net.Data from processing the Net.Data macro.
Net.Data sets the flags field in the dtw_lei structure to DTW_END_ABNORMAL if the cleanup processing is abnormal. These are a few examples of abnormal conditions:
If a language environment's interface routine has set the le_opaque_data field, then it should be freed by the dtw_cleanup() routine.
This call does not affect message block processing. If the return value is non-zero and there is a default message to issue, it is issued; if there is no default message, the macro processor issues a warning message.