Language Environment Interface Reference

The dtw_lei_t Structure

The interface function of each language environment receives a pointer to the dtw_lei_t structure. The dtw_lei_t structure has the following format:

typedef struct dtw_lei_t {              /* 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;

Fields in the dtw_lei_t structure:

function_name

The function_name field contains a pointer to a string containing the name of the function block. This can be useful to specify the FUNCTION block name in error messages displayed by the language environment.

flags

The flags field is used by Net.Data to communicate with the language environment. Specify the flags field pointer by performing an OR operation using the following constants:

• Net.Data sets DTW_STMT_EXEC to tell the dtw_execute() interface function that the exec_statement field contains the file name and parameters from an EXEC statement.
• DTW_END_ABNORMAL is set by Net.Data to tell the dtw_cleanup() interface function that an abnormal or unexpected condition has occurred and that the language environment should perform any cleanup necessary (that is, free held resources) before Net.Data ends.
• DTW_LE_FATAL_ERROR is set by a language environment interface function to tell Net.Data that a fatal error has occurred in the language environment. If this flag is set, Net.Data stops processing the Net.Data macro, calls all active language environment's dtw_cleanup() interface function with flags set to DTW_END_ABNORMAL, prints default message, and exits. The flag is checked only if a non-zero return value is returned on a language environment call.
• DTW_LE_MSG_KEEP is set by a language environment interface function to tell Net.Data that the storage pointed to by default_error_message should not be freed. If this constant is not set, Net.Data attempts to free the storage.
• DTW_LE_CONTINUE is set by the dtw_execute() interface function to tell Net.Data to call the dtw_getNextRow() interface function. Net.Data calls dtw_getNextRow() only if the flag is set and the return value from the call to the dtw_execute() interface function is zero.

exec_statement

The exec_statement field contains one of the following pointers:

• To a string containing the executable statements (after variable substitution) from the FUNCTION block
• To the file name and parameters from an EXEC statement

parm_data_array

The parm_data_array field contains a pointer to an array of dtw_parm_data_t structures. The array ends with a parm_data structure containing zeros. The dtw_parm_data_t 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. See The dtw_parm_data_t Structure for a description of the structure.

default_error_message

The default_error_message field is set by the language environment to a character string that describes an error condition. If the return value from a call to a language environment interface function is non-zero and the return value does not match the value of a message in a MESSAGE block, the default message is displayed. Otherwise, Net.Data displays the message selected from the MESSAGE block.

le_opaque_data

The le_opaque_data field is set by any of the interface functions in the language environment to pass parameters from one interface function to another. Net.Data saves the pointer and passes it to another interface function that Net.Data calls. After processing the Net.Data macro, and before returning to the caller of Net.Data, Net.Data defines the pointer to NULL. Because the field is thread-specific, language environments can store data that is thread specific. Use this field only if you have a dtw_cleanup() interface function, so that the function can free the storage associated with the le_opaque_data field.

row

The row field is set by Net.Data to a row object prior to calling a language environment's dtw_getNextRow() interface function. The dtw_getNextRow() function inserts a row of table data in the object using the Net.Data row utility interface functions. Net.Data then processes the row and calls dtw_getNextRow() until there are no more rows to process.

The reserved field is for IBM use only.