Provides methods to send rows to a EAServer client application.
BeginResults – Begins the sequence of calls that sends a result set to the client.
BindCol – Binds a program variable to a column in a result set.
ColAttributes – Specifies additional metadata for a column to be sent in a result set.
DescribeCol – Describes a result-set column.
EndResults – Indicates that all rows in a result set have been sent.
ResultsPassthrough – Forwards results from a remote database query to the client
SendData – Sends one row in a result set.
To create an IJagServer interface pointer, use the ProgID, “EAServer.JagServerResults.1”. Call the OLE routines CLSIDfromProgID and CoCreateInstance. CoCreateInstance returns an interface pointer for a given ActiveX class ID string. CLSIDfromProgID obtains the class ID string that CoCreateInstance requires.
To use the IJagServerResults and IJagServer interfaces, you must include JagAxWrap.h. Additionally, you must include JagAxWrap_i.c in only one source file for your component DLL. JagAxWrap.h contains interface definitions for the documented interfaces. JagAxWrap_i.c declares symbols that are required by the ActiveX CoCreateInstance routine.
WARNING! You will get duplicate-symbol link errors if you include JagAxWrap_i.c in more than one source file for your component DLL.
Chapter 25, “Sending Result Sets,” in the EAServer Programmer’s Guide
Begins the sequence of calls that sends a result set to the client.
#include <JagAxWrap.h> HRESULT IJagServerResults::BeginResults( short numColumns )
The number of columns in the result set to be sent.
Return value |
To indicate |
|---|---|
S_OK |
Successful execution |
E_INVALIDARG |
numColumns was not a positive number |
E_OUTOFMEMORY |
Out of memory |
E_FAIL |
Failure. Check the server’s log file for information about the cause of failure |
Chapter 25, “Sending Result Sets,” in the EAServer Programmer’s Guide
Binds a program variable to a column in a result set.
#include <JagAxWrap.h> HRESULT IJagServerResults::BindCol( short item, VARIANTARG sourceBuf, long maxBuflen, short *indicator)
The column number. The first column is 1.
A VARIANTARG structure
that describes the C datatype of the variable that holds data values.
The table below summarizes how to set the VARIANTARG fields.
You must set the vt field to indicate the C
type for the supplied column data, then use the indicated field
to specify the address of another variable that holds column values.
Subsequent calls to SendData read values from the
variable at the indicated address; the address must remain valid
until EndResults is called.
C datatype |
vt field setting |
Field that specifies bound variable address |
|---|---|---|
SHORT * |
VT_I2 | VT_BYREF |
piVal |
LONG * |
VT_I4 | VT_BYREF |
plVal |
FLOAT * |
VT_R4 | VT_BYREF |
pfltVal |
DOUBLE * |
VT_R8 | VT_BYREF |
pdblVal |
VARIANT_BOOL * |
VT_BOOL | VT_BYREF |
pbool |
DATE * |
VT_DATE | VT_BYREF |
pdate |
SAFEARRAY * |
VT_ARRAY | VT_UI1 | VT_BYREF |
pparray |
BSTR * |
VT_BSTR | VT_BYREF |
pbstrVal |
Use BSTR for string values and SAFE_ARRAY for binary values. Decimal and currency values can be specified as string data (BSTR) or any other type that can be converted to a numeric fraction, such as SHORT, LONG, FLOAT or DOUBLE. “ActiveX to SQL Datatype conversion” describes the supported conversions between SQL and ActiveX datatypes.
BindCol copies the structure contents before returning, consequently:
You can use one VARIANTARG structure to set up binds for all columns in a result set, and
Changes made to the structure after BindCol returns have no effect.
For string or binary values, the maximum length for column values that can be sent. Ignored for other datatypes.
The address of a variable that acts as a null-indicator for column values. Subsequent calls to SendData read the null-indicator value to determine whether a null value should be sent to the client. Null-indicator values are as follows:
Value |
To indicate |
|---|---|
0 |
Column value is not null and must be
read from the variable indicated by the sourceBuf |
-1 |
Column value is null. |
The indicator reference must remain valid until EndResults is called.
Return value |
To indicate |
|---|---|
S_OK |
Successful execution. |
E_INVALIDARG |
At least one parameter contained an invalid value. Check the server’s log file for more information. |
E_OUTOFMEMORY |
Out of memory. |
E_FAIL |
Failure. Check the server’s log file for information about the cause of failure. |
BindCol associates a program variable with a column in a result set. When SendData is called to send a row, it reads the column value for the current row from the variable that is bound to the column.
The SQLDatatype value passed to DescribeCol determines the datatype with which column values are sent over the network. If the program variable type does not map directly to the column’s SQL datatype, SendData attempts to convert the value. The figure below shows the supported conversions between SQL datatypes and bind variable types. An X indicates a supported conversion.
DescribeCol, EndResults, SendData
Chapter 25, “Sending Result Sets,” in the EAServer Programmer’s Guide
Specifies additional metadata for a column to be sent in a result set.
#include <JagAxWrap.h> HRESULT IJagServerResults::ColAttributes( short item, BSTR descType, VARIANTARG descBuf )
The column number. The first column is 1.
A BSTR; must be initialized to “COLUMN_MONEY”.
A VARIANTARG structure initialized to contain a VARIANT_BOOL. A value of TRUE means that the column represents a cash value.
Return value |
To indicate |
|---|---|
S_OK |
Successful execution. |
E_INVALIDARG |
At least one parameter contained an invalid value. Check the server’s log file for more information. |
E_FAIL |
Failure. Check the server’s log file for information about the cause of failure. |
If a column in a result set represents a cash value, you must call ColAttributes to set the “COLUMN_MONEY” attribute to TRUE. This attribute defaults to FALSE.
Chapter 25, “Sending Result Sets,” in the EAServer Programmer’s Guide
Describes a result-set column.
#include <JagAxWrap.h> HRESULT IJagServerResults::DescribeCol( short item, BSTR columnName, BSTR SQLDatatype, long columnSize, long precision, short scale, VARIANT_BOOL nullable )
The column number. The first column is 1.
A BSTR containing the column’s name.
A BSTR containing the name of the column’s SQL datatype. This value determines the datatype of values sent to the client. Values are specified in a buffer that is bound to the column with BindCol. The following table lists the datatype strings. See BindCol for details on how to bind column values.
SQL datatype string |
Description |
|---|---|
“SQL_BIT” |
Boolean. A single bit of data. |
“SQL_TINYINT” |
A 1-byte integer. |
“SQL_SMALLINT” |
A 2-byte integer. |
“SQL_INTEGER” |
A 4-byte integer. |
“SQL_REAL” |
A 4-byte floating point number. |
“SQL_FLOAT” |
An 8-byte floating point number. |
“SQL_DOUBLE” |
Same as “SQL_FLOAT”. |
“SQL_NUMERIC” |
A fixed-point fractional decimal number. |
“SQL_DECIMAL” |
Same as “SQL_DECIMAL”. |
“SQL_CHAR” |
A string of characters. Values do not vary in length, and the specified length (columnSize) must be less than 256. |
“SQL_VARCHAR” |
A string of characters. Values may vary in length and have maximum length specified by columnSize. columnSize must be < 256. |
“SQL_LONGVARCHAR” |
A string of characters. Values may vary in length and have maximum length specified by columnSize. columnSize is constrained by available memory. |
“SQL_DATE” |
An ODBC date value. |
“SQL_TIME” |
An ODBC time value. |
“SQL_TIMESTAMP” |
An ODBC timestamp value. |
“SQL_BINARY” |
An array of bytes that does not vary in length. The specified length (columnSize) must be less than 256. |
“SQL_VARBINARY” |
An array of bytes that can vary in length. The specified maximum length (columnSize) must be less than 256. |
“SQL_LONGVARBINARY” |
An array of bytes that can vary in length. The specified maximum length (columnSize) is constrained by available memory. |
For character or binary columns, the maximum length for column values.
The precision of column values. For “SQL_NUMERIC” or “SQL_DECIMAL” columns, precision indicates the maximum number of decimal digits that a value may have. For other datatypes, precision is ignored.
The scale for column values. For “SQL_NUMERIC” or “SQL_DECIMAL” columns, scale indicates the number of decimal digits to the right of the decimal point. For other datatypes, scale is ignored.
VARIANT_TRUE if the column may have null values.
Return value |
To indicate |
|---|---|
S_OK |
Successful execution. |
E_INVALIDARG |
At least one parameter contained an invalid value. Check the server’s log file for more information. |
E_OUTOFMEMORY |
Out of memory. |
E_FAIL |
Failure. Check the server’s log file for more information. |
DescribeCol describes the datatype, name, and format of a result column. The ColAttributes method specifies additional metadata.
Chapter 25, “Sending Result Sets,” in the EAServer Programmer’s Guide
Indicates that all rows in a result set have been sent.
#include <JagAxWrap.h> HRESULT IJagServerResults::EndResults(long rowCount);
The number of rows that were sent.
Return value |
To indicate |
|---|---|
S_OK |
Successful execution. |
E_FAIL |
Failure. EndResults fails if rowCount was negative. Check the server’s log file for information about the cause of failure. |
Chapter 25, “Sending Result Sets,” in the EAServer Programmer’s Guide
Forwards results from a remote database query to the client.
#include <JagAxWrap.h> HRESULT IJagServerResults::ResultsPassthrough( BSTR conlibName, VARIANTARG *conlibPtr, BSTR pthruType, long *pInfo )
A BSTR with one of the following values:
“ODBC” to indicate that conlibPtr contains the address of an ODBC HSTMT control structure.
“CTLIB” to indicate that conlibPtr contains the address of a Client-Library CS_COMMAND control structure.
A VARIANTARG structure containing the ODBC HSTMT or Client-Library CS_COMMAND control structure. Set the VARIANTARG vt field to VT_BYREF and the byref field to the address of the control structure.
When using ODBC, the HSTMT must be in a state that allows SQLFetch to be called without error.
When using Client-Library, the CS_COMMAND structure must be in a state that allows ct_results to be called without error.
A BSTR with one of the following values:
“CURRENT_RESULTS” to indicate that only the current result set should be forwarded to the client. When using this option, you must ensure that all result sets are processed. You can call ResultsPassthrough in a loop (see examples in “Comments” below). You can also retrieve or cancel subsequent result sets by directly calling ODBC or Client-Library routines.
“ALL_RESULTS” to indicate that all result sets should be forwarded to the client.
Pass as NULL if using ODBC or if using the “ALL_RESULTS” option to forward all results with one call.
When forwarding individual Client-Library result sets, pass the address of long variable as pInfo. ResultsPassthrough sets the pInfo variable to specify whether all results have been retrieved from the CS_COMMAND structure, as follows:
*pInfo value |
To indicate |
|---|---|
|
More results remain to be processed. |
|
All results have been processed. |
Return value |
To indicate |
|---|---|
S_OK |
Successful execution. |
E_INVALIDARG |
At least one parameter contained an invalid value. Check the server’s log file for more information. |
E_FAIL |
Failure. Check the server’s log file for information about the cause of failure. |
ResultsPassthrough forwards ODBC or Client-Library result sets to the client.
All results from a query can be forwarded with one call using the “ALL_RESULTS” option for the pthruType parameter. To forward single result sets, use the “CURRENT_RESULTS” option.
When using the JAG_PTHRU_ALL_RESULTS option with Client-Library, any result type other than row results (CS_ROW_RESULTS) causes ResultsPassthrough 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.
When using the “CURRENT_RESULTS” option with Client-Library, call ResultsPassthrough in place of calling ct_results. You must pass the address of a LONG as the pInfo variable. If this variable is 1 when ResultsPassthrough returns, no more results are available from the CS_COMMAND structure. The code fragment below illustrates how ResultsPassthrough can be called in a loop:
HRESULT hr;
CS_RETCODE retcode;
CS_CHAR *sqlCmd =
"select * from titles select * from authors"
CS_COMMAND *cmd;
VARIANT theVariant;
long info;
IJagServerResults *pResApis;
// Deleted code which retreived the pointer to the
// JagServerResults interface.
// Also, 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
}
theVariant.vt = VT_BYREF;
theVariant.byref = cmd;
while ((hr = pResApis->ResultsPassthrough("CTLIB", theVariant,
"CURRENT_RESULTS", &info)) == S_OK)
{
if (info == NoMoreResults)
{
break;
}
}
if (hr != S_OK)
{
// handle failure
}
When using the “CURRENT_RESULTS” option with ODBC, call ResultsPassthrough before calling SQLMoreResults, instead of the usual SQLFetch row processing. The code fragment below illustrates how ResultsPassthrough and SQLMoreResults can be called in a loop to forward all result sets to the client.
HRESULT hr;
RETCODE odbcRet;
CS_CHAR *sqlCmd =
"select * from titles select * from authors"
HSTMT hstmt;
VARIANT theVariant;
long info;
IJagServerResults *pResApis;
// Deleted code which retreived the pointer to the
// JagServerResults interface.
// Also, 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
}
theVariant.vt = VT_BYREF;
theVariant.byref = &hstmt;
do
{
hr = pResApis->ResultsPassthrough("ODBC", theVariant,
"CURRENT_RESULTS", &info);
if (hr != S_OK)
{
// handle failure
}
} while (SQLMoreResults == SQL_SUCCESS);
if (odbcRet != SQL_NO_DATA_FOUND)
{
// handle failure
}
Chapter 25, “Sending Result Sets,” in the EAServer Programmer’s Guide
Sends one row in a result set.
#include <JagAxWrap.h> HRESULT IJagServerResults::SendData(void);
Return value |
To indicate |
|---|---|
S_OK |
Successful execution. |
E_INVALIDARG |
At least one parameter contained an invalid value. Check the server’s log file for more information. |
E_FAIL |
Failure. Check the server’s log file for information about the cause of failure. |
After you have described columns with DescribeCol and bound program variables to supply column data, call SendData to send each row of data.
DescribeCol, BindCol, EndResults
Chapter 25, “Sending Result Sets,” in the EAServer Programmer’s Guide
| Copyright © 2005. Sybase Inc. All rights reserved. |
|
|
