Language Environment Interface Functions

When you write a language environment, you must determine which interfaces to provide. Your choices depend on what you intend the language environment to do. For example, if the language environment will be accessing database data, you'll make different choices than if it is for a scripting language.

Net.Data uses four interface functions with a language environment.

  1. dtw_initialize()
  2. dtw_execute()
  3. dtw_getNextRow()
  4. dtw_cleanup()

You provide one or more of these functions. Three of these functions are optional, but every language environment must have a dtw_execute() interface function. If a Net.Data macro references a language environment that does not have a dtw_execute() interface function, Net.Data returns an error message and stops processing the Net.Data macro.

To call a language environment, reference it on the FUNCTION block of the Net.Data macro. The language environment interface functions will be called if they are defined by the language environment:

When Net.Data encounters a call to a function that uses the language environment, it uses the following steps to call the language environment:

  1. Net.Data calls dtw_initialize() if it has been defined for this language environment, and if it is the first function call for this language environment. The function performs any initialization tasks required by the language environment, such as connecting to databases, or allocating variables.
  2. Net.Data calls dtw_execute() to process the macro FUNCTION block containing statements or a command that the language environment must process.
  3. Net.Data calls dtw_getNextRow() if, upon successful return, dtw_execute() indicated that dtw_getNextRow() should be called.
  4. When the Net.Data macro processing is complete, Net.Data calls dtw_cleanup() to clean up the environment (for example, disconnecting from a database or releasing resources), if this function has been defined for the language environment, and then returns to the Web server.

The following sections describe the interface functions:

dtw_initialize()

Format:
int dtw_initialize(dtw_lei_t *);

The dtw_initialize() interface function performs any special initialization that the language environment requires, such as connecting to a database or allocating resources. This interface function is optional.

Net.Data calls a language environment's dtw_initialize() interface function only once per macro, the first time Net.Data calls a FUNCTION block for that language environment. Subsequent calls to the language environment bypass the call to the dtw_initialize() interface function.

This interface 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 a default message is defined in the default_error_message field of the dtw_lei_t structure, Net.Data issues the default message; if no default message exists, Net.Data issues an error message.

dtw_execute()

Format:
dtw_execute(dtw_lei_t *);

The dtw_execute() interface function processes FUNCTION blocks on each function call. The FUNCTION blocks can contain statements or a command that will be processed in the dtw_execute() function.

The dtw_execute() interface function is called whenever a Net.Data macro calls a function that refers to the language environment. When the dtw_execute() interface function completes, Net.Data checks the return code and the flags field of the dtw_lei_t structure. If the return code is 0, Net.Data checks to see if DTW_LE_CONTINUE is set in the flags field. If it is, then Net.Data will call the dtw_getNextRow() interface function (see dtw_getNextRow()). If the return code is not zero, Net.Data will check the global and local MESSAGE blocks to determine the next course of action. If no MESSAGE blocks exists or if Net.Data cannot find a matching return code entry in any MESSAGE block, Net.Data will continue processing if the return code is positive, or it will end macro processing if the return code is negative.

You can optimize performance by having the dtw_execute() interface function do all the processing necessary to produce the input for the report block processing. For example, your dtw_execute() interface function can generate an entire table to be processed during the report block phase

dtw_getNextRow()

Format:
int dtw_getNextRow(dtw_lei_t *);

The dtw_getNextRow() interface function retrieves input for row-at-a-time processing of Net.Data REPORT blocks. It is called as long as the DTW_LE_CONTINUE flag is set, indicating that another row of data needs to be processed for the table. This interface function is optional.

Restriction: This interface function is only called if Net.Data is running on the OS/400 or OS/390 operating systems.

Net.Data calls dtw_getNextRow() when the following conditions are met:

When the dtw_execute() function sets the DTW_LE_CONTINUE flag to on and the return code is 0, Net.Data performs the following steps:

  1. Processes the REPORT block header.
  2. Calls language environment's dtw_getNextRow() interface function to retrieve a row.
  3. Processes the message block for the return value of the dtw_getNextRow() interface function.
  4. Processes the ROW block.
  5. Determines whether dtw_getNextRow() has turned on the DTW_LE_CONTINUE flag:

When dtw_getNextRow() is called, the row field in the dtw_lei_t structure is set to point to a row object. To manipulate the row object, use the Net.Data utility functions, dtw_row_SetCols() and dtw_row_SetV(). Net.Data assumes that after the first call to the dtw_getNextRow() interface function the row object contains the column headings for the table. Subsequent calls contain the actual table data.

The dtw_getNextRow() function continues to be called as long as DTW_LE_CONTINUE is set in the flags field and the return code is 0. If the return code is not zero, Net.Data checks the global and local MESSAGE blocks to decide the next course of action. If no MESSAGE block exists, or Net.Data could not find a matching entry in any MESSAGE block, Net.Data will continue processing if the return code is positive, or it will end macro processing if the return code is negative.

dtw_cleanup()

Format:
int dtw_cleanup(dtw_lei_t *);

Use the dtw_cleanup() interface function to cleanup the language environment. Consider using this interface function if you use dtw_initialize() to allocate resources. Use this function for such tasks as disconnecting from a database or releasing resources. This interface function is optional.

While handling a Net.Data request, Net.Data calls a language environment's dtw_cleanup() interface function once when macro processing ends normally or abnormally. This interface is not called if no function calls were made for the language environment.

Net.Data sets DTW_END_ABNORMAL in the flags field of the dtw_lei_t structure if the macro is terminating abnormally. The following list shows the conditions in which Net.Data would terminate abnormally:

If a language environment's interface function sets the le_opaque_data field with a parameter to be passed between interface functions, use the dtw_cleanup() to release the resources associated with the field when processing ends.

This interface function does not affect message block processing. If the return value is non-zero, a default message is issued; if no default message exists, Net.Data issues a warning message.


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