JagBeginResults  JagCmCacheProps

Chapter 5: C Routines Reference

JagBindCol

Description

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

Syntax

JagStatus JagBindCol(
          SQLSMALLINT  columnNumber,
          JagDataType  dataType,
          SQLSMALLINT  sourceType,
          SQLPOINTER   sourceBuf,
          SQLINTEGER   maxBuflen,
          SQLINTEGER   *buflen,
         SQLSMALLINT  *indicator)

Parameters

columnNumber

The column number to bind to. The first column is 1.

dataType

One of the following symbolic constants:

JAG_CS_TYPE

To indicate that Sybase Open Client Client-Library datatypes are being used.

JAG_ODBC_TYPE

To indicate that ODBC datatypes are being used.

sourceType

The sql.h type value that represents the C datatype of the bound variable. See the “Comments” section below for more information on datatypes.

sourceBuf

The memory address from which column values are to be read. Subsequent calls to JagSendData read values from the buffer. The sourceBuf address must remain valid until JagEndResults is called.

maxBuflen

The length, in bytes, of the sourceBuf buffer. For fixed-length types, maxBuflen is ignored.

buflen

The address of a SQLINTEGER variable that contains the length, in bytes, of the current value at the sourceBuf address. For columns with a variable-length datatype, JagSendData reads the length of the current value from *buflen. The buflen address must remain valid until JagEndResults is called.

For fixed-length types, buflen is ignored.

indicator

The address of a SQLSMALLINT variable that acts as a null-indicator for column values. JagSendData reads this variable to determine whether the column value is null. The indicator address must remain valid until JagEndResults is called. Acceptable indicator values are:

Value

To indicate

CS_GOODATA or any value greater than or equal to 0.

Not null.

CS_NULLDATA

Null value.

SQL_NULL_DATA

Null value.

SQL_NULL_DATA and CS_NULLDATA can be used interchangeably.

Returns

Return value

To indicate

JAG_SUCCEED

Success

JAG_FAIL

Failure

Check the server’s log file for more information when JagBindCol fails.

Usage

JagBindCol binds a program variable to a column in a result set. Binding associates the program variable with the result column: when JagSendData is called to send a row of data, it reads the current contents of the bound variable as the value of the column.

JagBindCol can use either ODBC or Open Client Client-Library datatypes. Set the dataType parameter to specify which set of type constants should be used.


ODBC datatypes

When the dataType parameter is JAG_ODBC_TYPE, JagBindCol interprets the columnDatatype parameter as an ODBC (sql.h) type constant. The C declaration of the bound variable must be an ODBC type that agrees with the C datatype. If necessary, JagSendData will perform conversion to the SQL datatype that was specified by JagDescribeCol. “C-to-SQL datatype conversions” describes supported conversions between SQL datatypes and C datatypes.

Table 5-1 lists the ODBC C datatypes:

Table 5-1: ODBC C datatypes for JagBindCol

ODBC C type constant

ODBC type definition

Equivalent C declaration

SQL_C_CHAR
UCHAR *
unsigned char *
SQL_C_SSHORT
SWORD
short int
SQL_C_LONG
SDWORD
long int
SQL_C_SLONG
SDWORD
long int
SQL_C_ULONG
UDWORD
unsigned long int
SQL_C_FLOAT
SFLOAT
float
SQL_C_DOUBLE
SDOUBLE
double
SQL_C_BIT
UCHAR
unsigned char
SQL_C_STINYINT
SCHAR
signed char
SQL_C_UTINYINT
UCHAR
unsigned char
SQL_C_BINARY
UCHAR *
unsigned char *
SQL_C_DATE
DATE_STRUCT
struct {
  SQLSMALLINT year;
  SQLUINTEGER month;
  SQLUINTEGER day;
} DATE_STRUCT;
SQL_C_TIME
TIME_STRUCT
struct {
  SQLUSMALLINT hour; 
  SQLUSMALLINT minute; 
  SQLUSMALLINT second; 
} TIME_STRUCT;
SQL_C_TIMESTAMP
TIMESTAMP_STRUCT
struct { 
  SWORD  year;
  UWORD  month;
  UWORD  day
  UWORD  hour;
  UWORD  minute;
  UWORD  second;
  UDWORD fraction;
}

fraction represents billionths of a second (1/1000000000)


C-to-SQL datatype conversions

If the C datatype indicated by source type does not map directly to the column’s SQL datatype (specified when JagDescribeCol was called), JagSendData will attempt to convert the value before sending it. The figure below shows which conversions are supported. An X indicates a supported conversion.


Client-Library datatypes

When the dataType parameter is JAG_CS_TYPE, JagBindCol interprets the sourceDatatype parameter as an Open Client Client-Library/C type constant. See your Client-Library documentation for descriptions of the Open Client datatypes. JagBindCol accepts any type constant that can be used with ct_bind except for CS_TEXT_TYPE and CS_IMAGE_TYPE. These types can be mapped to CS_LONGCHAR_TYPE and CS_LONGBINARY_TYPE, respectively.

See also

JagBeginResults, JagDescribeCol, JagSendData

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





Copyright © 2005. Sybase Inc. All rights reserved. JagCmCacheProps