Chapter 5 C Routines Reference

JagResultsPassthrough

Description

Forward results from an ODBC or Client-Library remote database command to the client.

Syntax

#include <jagpublic.h>

JagResultsPassthrough(
                  JAGPOINTER     conlib, 
                  JAGPOINTER     conlib_ptr,
                  JagPthruType   pthruType)

Parameters

conlib

One of the following strings:

"ODBC" to indicate that conlib_ptr is the address of an ODBC HSTMT control structure.
"CTLIB" to indicate that conlib_ptr is the address of a Client-Library CS_COMMAND control structure.

conlib_pointer

The address of the control structure used to access result rows for the connectivity library that you are using.

When using Client-Library, set conlib_ptr to the address of a CS_COMMAND structure. The CS_COMMAND structure must be in a state that allows ct_results to be called without error.

When using ODBC, set conlib_ptr to the address of an HSTMT control structure. The HSTMT must be in a state that allows SQLFetch to be called without error.

pthruType

One of the following symbolic constants to indicate how results are to be processed:

pthruType value	To indicate
JAG_PTHRU_ALL_RESULTS	All results from the current command will be retrieved and sent to the client.
JAG_PTHRU_CURRENT_RESULTS	Only rows from the current result set will be returned.

Return Values

Return value	To indicate
JAG_SUCCEED	Successfully sent results.
JAG_NO_MORE_RESULTS	Applies only when using Client-Library and the JAG_PTHRU_CURRENT_RESULTS option for pthruType. Indicates that all results have been retrieved from the CS_COMMAND structure.
JAG_FAIL	Failure

Check the server's log file for more information when JagSendMessage fails.

Usage

JagResultsPassthru forwards results from an ODBC or Client-Library remote database command to the client.

All results from a query can be forwarded with one call using the JAG_PTHRU_ALL_RESULTS option for the pthruType parameter. To forward single result sets, use the JAG_PTHRU_ALL_RESULTS option.

When using the JAG_PTHRU_ALL_RESULTS option with Client-Library, any result type other than row results (CS_ROW_RESULTS) causes JagResultsPassthrough to fail.

When forwarding single result sets, you must ensure that you retrieve or cancel all results. The sections below describe the loop algorithms for forwarding individual result sets.

Forwarding individual result sets with Client-Library

When using the JAG_PTHRU_CURRENT_RESULTS option with Client-Library, call JagResultsPassthrough in place of calling ct_results. JagResultsPassthrough returns JAG_NO_MORE_RESULTS when CS_COMMAND structure. The code fragment below illustrates how JagResultsPassthrough can be called in a loop:

JagStatus   jagRet;
CS_RETCODE  retcode;
CS_CHAR     *sqlCmd = "select * from titles select * from authors"
CS_COMMAND      *cmd;

// Deleted the code which did CT-Lib
// initialization, connected to the SQL Server,
// and allocated the CS_COMMAND structure.

retcode = ct_command(cmd, CS_LANG_CMD, sqlCmd,
                     CS_NULLTERM, CS_UNUSED);
if (retcode != CS_SUCCEED)
{
    // handle failure
}
retcode = ct_send(cmd);
if (retcode != CS_SUCCEED)
{
    // handle failure
}
while ((jagRet = JagResultsPassthrough("CTLIB", cmd, 
        JAG_PTHRU_CURRENT_RESULTS)) == JAG_SUCCEED)
{
    // No code needed here. JagResultsPassthru 
    // did all the work
      ;
}
if (jagRet != JAG_NO_MORE_RESULTS)
{
    // handle failure
}

Forwarding individual result sets with ODBC

When using the JAG_PTHRU_CURRENT_RESULTS option with ODBC, call JagResultsPassthrough before calling SQLMoreResults, instead of the usual SQLFetch row processing. The code fragment below illustrates how JagResultsPassthrough and SQLMoreResults can be called in a loop to forward all result sets to the client.

RETCODE     odbcRet;
CS_CHAR     *sqlCmd =
        "select * from titles select * from authors"
HSTMT       hstmt;

// Deleted the code which did ODBC initialization,
// connected to the SQL Server, and allocated
// the HSTMT.

odbcRet = SQLExecDirect(hstmt, (SQLCHAR *)sqlCmd, SQL_NTS);
if (odbcRet != SQL_SUCCESS)
{
    // handle failure
}
do
{
    jagRet = JagResultsPassthrough("ODBC", &hstmt, 
                    JAG_PTHRU_CURRENT_RESULTS);
    if (jagRet != JAG_SUCCEED)
    {
        // handle failure
    }
} while (SQLMoreResults(hstmt) == SQL_SUCCESS);
if (odbcRet != SQL_NO_DATA_FOUND)
{
    // handle failure
}