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.

Return Values

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 dataypes. 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.

The following table 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.