IJagServer interface  IObjectContext interface

Chapter 2: ActiveX C++ Interface Reference

IJagServerResults interface

Description

Provides methods to send rows to a EAServer client application.

Methods

Usage

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.

See also

Chapter 25, “Sending Result Sets,” in the EAServer Programmer’s Guide




IJagServerResults::BeginResults

Description

Begins the sequence of calls that sends a result set to the client.

Syntax

#include <JagAxWrap.h>

HRESULT IJagServerResults::BeginResults(
        short numColumns
        )

Parameters

numColumns

The number of columns in the result set to be sent.

Returns

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

See also

DescribeCol

Chapter 25, “Sending Result Sets,” in the EAServer Programmer’s Guide




IJagServerResults::BindCol

Description

Binds a program variable to a column in a result set.

Syntax

#include <JagAxWrap.h>

HRESULT IJagServerResults::BindCol(
        short item,
        VARIANTARG sourceBuf,
        long maxBuflen,
        short *indicator)

Parameters

item

The column number. The first column is 1.

sourceBuf

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.

Table 2-1: VARIANTARG settings for BindCol

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:

maxBuflen

For string or binary values, the maximum length for column values that can be sent. Ignored for other datatypes.

indicator

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 Variant buffer.

-1

Column value is null.

The indicator reference must remain valid until EndResults is called.

Returns

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.

Usage

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.


ActiveX to SQL Datatype conversion

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.

See also

DescribeCol, EndResults, SendData

Chapter 25, “Sending Result Sets,” in the EAServer Programmer’s Guide




IJagServerResults::ColAttributes

Description

Specifies additional metadata for a column to be sent in a result set.

Syntax

#include <JagAxWrap.h>

HRESULT IJagServerResults::ColAttributes(
        short item,
        BSTR descType,
        VARIANTARG descBuf
)

Parameters

item

The column number. The first column is 1.

descType

A BSTR; must be initialized to “COLUMN_MONEY”.

descBuf

A VARIANTARG structure initialized to contain a VARIANT_BOOL. A value of TRUE means that the column represents a cash value.

Returns

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.

Usage

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.

See also

DescribeCol

Chapter 25, “Sending Result Sets,” in the EAServer Programmer’s Guide




IJagServerResults::DescribeCol

Description

Describes a result-set column.

Syntax

#include <JagAxWrap.h>

HRESULT IJagServerResults::DescribeCol(
        short item,
        BSTR columnName,
        BSTR SQLDatatype,
        long columnSize,
        long precision,
        short scale,
        VARIANT_BOOL nullable
)

Parameters

item

The column number. The first column is 1.

columnName

A BSTR containing the column’s name.

SQLDatatype

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.

Table 2-2: SQL datatypes for DescribeCol

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.

columnSize

For character or binary columns, the maximum length for column values.

precision

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.

scale

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.

nullable

VARIANT_TRUE if the column may have null values.

Returns

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.

Usage

DescribeCol describes the datatype, name, and format of a result column. The ColAttributes method specifies additional metadata.

See also

BindCol, ColAttributes

Chapter 25, “Sending Result Sets,” in the EAServer Programmer’s Guide




IJagServerResults::EndResults

Description

Indicates that all rows in a result set have been sent.

Syntax

#include <JagAxWrap.h>

HRESULT IJagServerResults::EndResults(long rowCount);

Parameters

rowCount

The number of rows that were sent.

Returns

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.

See also

BeginResults

Chapter 25, “Sending Result Sets,” in the EAServer Programmer’s Guide




IJagServerResults::ResultsPassthrough

Description

Forwards results from a remote database query to the client.

Syntax

#include <JagAxWrap.h>

HRESULT IJagServerResults::ResultsPassthrough(
        BSTR conlibName,
        VARIANTARG *conlibPtr,
        BSTR pthruType,
        long *pInfo
)

Parameters

conlibName

A BSTR with one of the following values:

conlibPtr

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.

pthruType

A BSTR with one of the following values:

pInfo

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

NoInfo (0)

More results remain to be processed.

NoMoreResults (1)

All results have been processed.

Returns

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.

Usage

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.


Forwarding Individual Result Sets with Client-Library

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
}

Forwarding Individual Result Sets with ODBC

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
}

See also

Chapter 25, “Sending Result Sets,” in the EAServer Programmer’s Guide




IJagServerResults::SendData

Description

Sends one row in a result set.

Syntax

#include <JagAxWrap.h>

HRESULT IJagServerResults::SendData(void);

Returns

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.

Usage

After you have described columns with DescribeCol and bound program variables to supply column data, call SendData to send each row of data.

See also

DescribeCol, BindCol, EndResults

Chapter 25, “Sending Result Sets,” in the EAServer Programmer’s Guide





Copyright © 2005. Sybase Inc. All rights reserved. IObjectContext interface