Before you can build a language environment, you have to write it. See Appendix A. "Language Environment Template" for an example of a language environment source file. There are several programming issues to consider when writing your own language environment. A few of the more common ones are discussed in the following sections.
Use the template shown in Appendix A. "Language Environment Template" if you need to write your own language environment to access Net.Data's services.
If your language environment needs to allocate resources or initialize data, or do any processing scoped to a macro invocation, then consider providing a dtw_initialize() interface. This interface is called not more than once for each macro invocation, before the first function call to your language environment. If there are no function calls to your language environment, the dtw_initialize() interface is not called. If you provide a dtw_initialize() interface, then you may also choose to provide a dtw_cleanup() interface. This interface is also only called once for each macro invocation. It is only called if the dtw_initialize() interface was called, and is called as part of the termination of the macro invocation.
The dtw_getNextRow() interface is very specialized, and is typically only useful as part of a database language environment, or a language environment that can process data a row at a time.
Input parameters are always passed to the dtw_execute() interface as part of the dtw_lei_t structure, which is the only parameter passed to dtw_execute(). The parameters are passed in the order specified on the FUNCTION block definition in the Net.Data macro, with any implicit parameters specified in the initialization file following the explicit parameters. They are passed in the parm_data_array field of the dtw_lei_t structure, each parameter in its own dtw_parm_data_t structure. The processInputParms() routine in the program template shows one possible way of processing input parameters.
How a language environment processes a user request depends on how that request is received. There are several different ways you can communicate a request to your language environment:
This is entirely dependent on your language environment and how it processes user requests. However, once the language environment has the data it wishes to return to the Net.Data macro, it can do it by modifying the values of parameters passed in the parm_data_array field of the dtw_lei_t structure. The processOutputParms() routine in the program template shows one possible way of processing output parameters, and examples of how to set both string and table parameter values.
The success or failure of a function call can be communicated through the implicit Net.Data macro variable, RETURN_CODE. This variable is set by Net.Data after returning from a call to the dtw_execute() interface. Its value is set to the return value of the dtw_execute() call itself. This value is then used by Net.Data to process the Net.Data macro MESSAGE block, if one was specified for this function call.
If you did not specify a MESSAGE block, or did not have an entry in a specified MESSAGE block to handle the return code from dtw_execute(), Net.Data displays the contents of the default_error_message field of the dtw_lei_t structure. This field can be set by the language environment at any time in the dtw_execute() routine. The setErrorMessage() routine in the program template shows an example of how to set the default_error_message field.