Appendix B

Using DLLs With Tango

Programmer Reference for Extending the Functionality of Tango Using DLLs

This appendix provides information on creating Dynamic Link Libraries (DLLs) for use with the External action when executing Tango application files on the Windows platform. This information is provided for those programmers who want to extend the functionality of Tango Server through the use of DLLs.

[back to top]

TExtParamBlock

Tango passes each function the following parameter block:

struct TExtParamBlock{
DWORD ThreadId;
DWORD CurrRow;
DWORD CurrColumn;
VOID *UserData;
VOID *Reserved;
};

Tango uses this "extension parameter block" to communicate the current state to the DLL. The DLL uses it to track user data between invocations of the DLL. The members of the parameter block are:

• DWORD ThreadId;

The ID of the calling thread allocated by Tango. The value is set by Tango; it may not be changed by the DLL.

• DWORD CurrRow;

The row number currently processed by Tango. This value is incremented by Tango as it iterates through each row of the result set.

• DWORD CurrColumn;

The column number currently processed by Tango. This value is incremented by Tango as it iterates through each column of a particular row of the result set.

• VOID *UserData;

Contains any user defined data. If the DLL requires some memory on a per query basis, use the UserData member to keep a reference to the memory block. UserData is usually assigned at the time of ExtSrcConnect call. It must be freed in the ExtSrcDisconnect function.

• VOID *Reserved;

Reserved for future use by Tango. Do not reference or set this member.

[back to top]

DLL Functions

DLL writers must implement five functions in their DLL. A sixth function, used to process errors, is optional. Tango calls these functions to process specific events.

The prototypes for these functions are defined in the ExtSrc.h file, included with Tango.

These DLL functions are:

• extern "C" _export int ExtSrcConnect(TExtParamBlock *param_block);

This function is called when the external data source is connected, usually the first time the External action that references the DLL is executed. The UserData member of the TExtParamBlock structure should be initialized at this point.

This function must return one of the following values:

EXT_SRC_SUCCESS (if connection is successful)

EXT_SRC_ERROR (otherwise)

• extern "C" _export int ExtSrcDisconnect(TExtParamBlock *param_block);

This function is called when the external data source is disconnected, usually when the Tango Service is stopped. This function provides the last opportunity to deallocate any memory referenced by the UserData member of the parameter block.

This function must return one of the following values:

EXT_SRC_SUCCESS (if disconnection is successful)

EXT_SRC_ERROR (otherwise)

• extern "C" _export int ExtSrcExecuteQuery(TExtParamBlock *param_block, char *p1, char *p2, char *p3);

The ExtSrcExecuteQuery function is called once for each time the External action is executed by Tango Server. This function either returns an error code or the number of columns in the result set arising from the execution of the DLL. The number of columns is used by the Tango Server to control when the ExtSrcGetNextColumn function is called.

For more information, see "Configuring a DLL Call".

The declaration of this function depends on the number of parameters you intend to pass to the DLL. After the param_block parameter you need to include a char * parameter for each parameter defined in the External action window in Tango Editor. For example, the prototype shown above is for a DLL that has three parameters defined for it in the External action.

This function must return one of the following values:

EXT_SRC_ERROR (in case of error)

result set quantity (zero or greater number identifying the number of columns in the result set)

• extern "C" _export int ExtSrcFetchNextRow(TExtParamBlock *param_block);

This function is called by Tango Server once for each row of the result set created by the ExtSrcExecuteQuery function. The result of this function determines the number of times it is called: Tango Server continues to call ExtSrcFetchNextRow until the function returns EXT_SRC_NODATA or EXT_SRC_ERROR.

This function does not return data to Tango Server. It should be used by the DLL to load or prepare the data for retrieval. After calling this function, the ExtSrcGetNextColumn function is called to retrieve the data from each column. ExtSrcGetNextColumn is called once for each column in the result set; the number of columns is determined by the result of the ExtSrcExecuteQuery function.

This function must return one of the following values:

EXT_SRC_SUCCESS (if the row is retrieved successfully)

EXT_SRC_NODATA (if there are no rows remaining to return)

EXT_SRC_ERROR (if an error occurs)

• extern "C" _export int ExtSrcGetNextColumn(TExtParamBlock *param_block, UCHAR *buffer, DWORD blen, DWORD *actlen);

This function is called by Tango Server once for each column of the result set for each row fetched by the ExtSrcFetchNextRow function.The number of columns is determined by the result of the ExtSrcExecuteQuery function.

This function has the following parameters:

TExtParamBlock *param_block (pointer to the external action parameter block)

UCHAR *buffer (pointer to a 32K buffer allocated by Tango)

DWORD blen (size of the buffer allocated by Tango (currently set to 32K))

DWORD *actlen (actual size of the data written by the DLL to the buffer)

This function must return one of the following values:

EXT_SRC_SUCCESS (if the column's data is retrieved successfully)

EXT_SRC_ERROR (if an error occurs)

• extern "C" _export int ExtSrcErrorCode(TExtParamBlock *param_block);

This is an optional function. If implemented, Tango calls ExtSrcErrorCode whenever one of the other DLL functions returns EXT_SRC_ERROR to Tango.