Net.Data uses two structures to communicate with a language environment: dtw_lei and dtw_parm_data.
The interface routine of each language environment receives a pointer to the dtw_lei structure:
typedef struct dtw_lei { /* Lang. Env. Interface */
char *function_name; /* Function block name */
int flags; /* Lang. Env. Interface flags */
char *exec_statement; /* Lang. Env. statement(s) */
dtw_parm_data_t *parm_data_array; /* Parameter array */
char *default_error_message; /* Default message */
void *le_opaque_data; /* Lang. Env. specific data */
void *row; /* For row-at-a-time processing*/
char reserved[64]; /* Reserved */
} dtw_lei_t;
The dtw_lei_t fields are discussed later. The function_name field contains a pointer to a string containing the name of the function block. This may be useful in error messages displayed by the language environment.
The flags field is used by Net.Data to communicate with the language environment. The flags field is set by performing an OR operation using the following constants:
The exec_statement field contains a pointer to a string containing the executable statements (after variable substitution) from the FUNCTION block, or the file name and parameters from an EXEC statement.
The parm_data_array field contains a pointer to an array of dtw_parm_data structures. The array is ended with a parm_data structure containing zeros. The dtw_parm_data structure is used by Net.Data to pass variables and the associated value to a language environment and to retrieve any changes to the variable value that may be made by the language environment. More information on this structure can be found in the following section.
The default_error_message field can be set by the language environment to a character string describing an error condition. If, upon return from a call to a language environment interface function, the return value of the function call is non-zero and the return value does not match the value of a message in a message block, then the default message is displayed. Otherwise, the message selected from the message block is displayed.
The le_opaque_data field can be set by any of a language_environment's interface routines. Net.Data saves the pointer and passes it to an interface routine of a language environment that it calls. After processing the Web macro, and before returning to the caller of Net.Data, the pointer is set to NULL. The field is thread-specific, so language environments can store data that is thread specific. Use this field only if you have a dtw_cleanup() routine, so that the routine can free the storage associated with the le_opaque_data field.
The row field is set by Net.Data to a row object prior to calling a language_environment's dtw_getNextRow() function. The dtw_getNextRow() routine inserts a row of table data in the object using the Net.Data row utility routines. Net.Data then processes the row, and calls dtw_getNextRow() until there are no more rows to process.
The reserved field is reserved for IBM use.
The dtw_parm_data structure is used by Net.Data to pass parameters to a language environment. Parameters are obtained from 3 sources:
Explicit parameters are passed first, followed by parameters specified in the ENVIRONMENT statement, then the return variable.
The dtw_parm_data structure has the following format:
typedef struct dtw_parm_data { /* Parameter data */
int parm_descriptor; /* Parameter descriptor */
char *parm_name; /* Parameter name */
char *parm_value; /* Parameter value */
void *res1; /* Reserved */
void *res2; /* Reserved */
} dtw_parm_data_t;
The parm_descriptor field describes the type and use of the parameter. Net.Data sets the field by performing an OR operation using the following constants:
Net.Data always sets the parm_descriptor field to DTW_IN, DTW_OUT, or DTW_INOUT and is logically ORed with DTW_STRING and DTW_TABLE.
The parm_name field is a pointer to a string that contains the name of the parameter. This pointer is set to null by Net.Data if the parameter is a literal string.
The parm_value field is a pointer to an object that contains the value of the parameter. This pointer is set to null by Net.Data if the parameter is a variable that is not already defined.
The res1 and res2 fields are reserved fields.
Both parm_name and parm_value pointers point to an object allocated from the Net.Data runtime heap. If a parm_name or parm_value is replaced with another string, the original string must be freed and replaced with a pointer to a character string allocated from the Net.Data heap. Use dtw_malloc() and dtw_free() to do this.