ct_bind

CS_RETCODE ct_bind (command, item_num, datafmt,
                     buffer, copied, indicator);
CS_COMMAND    *command;
CS_LONG       item_num;
CS_DATAFMT    *datafmt;
CS_BYTE       *buffer;
CS_INT        *copied;
CS_SMALLINT   *indicator;

command

(I) Handle for this connection. This is the handle defined in the ct_cmd_alloc call for this connection. The command handle corresponds to the TDPROC handle in the Open ServerConnect Gateway-Library.

item_num

(I) Ordinal number of the result column, return parameter, or return status value that is to be bound.

When binding a result column, item_num is the column number. For example, the first column in the select list of a SQL select statement is column number 1, the second is column number 2, and so forth.

When binding a return parameter, item_num is the ordinal rank of the return parameter. The first parameter returned by a procedure or parameter is number 1. Adaptive Server Enterprise stored procedure return parameters are returned in the order originally specified in the create procedure statement for the stored procedure. This is not necessarily the same order as specified in the RPC that invoked the stored procedure or transaction.

In determining what number to assign to item_num, do not count non-return parameters. For example, if the second parameter in a stored procedure is the only return parameter, its item_num is 1.

When binding a stored procedure return status, item_num must be 1. There is only one column and one row in a return status result set.

To clear all bindings, assign item_num a value of CS_UNUSED with datafmt, buffer, copied, and indicator as CS_NULL.

DATAFMT

(I) A structure that contains a description of the destination variable(s). This structure is also used by ct_describe, ct_param, and cs_convert and is explained in Chapter 2, “Gateway-Library Concepts”, under “DATAFMT structure”.

Table 3-2 lists the fields in the DATAFMT structure, indicates whether they are used by ct_bind, and contains general information about each field. ct_bind ignores datafmt fields that it does not use.

WARNING! You must initialize the entire DATAFMT structure to zeroes. Failure to do so causes addressing exceptions.

Table 3-2 lists the fields in the DATAFMT structure for ct_bind.

Table 3-2: Fields in the DATAFMT structure for ct_bind

Field	When used	Value represents
name	Not used (CS_FMT_UNUSED).	Not applicable.
namelen	Not used (CS_FMT_UNUSED).	Not applicable.
datatype	When binding all types of results.	The datatype of the destination variable (buffer). All datatypes listed under “DATAFMT structure” are valid. ct_bind supports a wide range of datatype conversions, so datatype can be different from the datatype returned by the server. For instance, by specifying a datatype of CS_FLOAT, you can bind a CS_MONEY or CS_MONEY4 value to a float-type program variable. The appropriate data conversion happens automatically. A return status always has a datatype of CS_INT.
format	When binding results to character or binary destination variables. In all other cases, this field is unused (CS_FMT_UNUSED).	The destination format of character or binary data. For character-type destinations only: CS_FMT_PADBLANK—pads to the full length of the variable with blanks. For character or binary type destination variables: CS_FMT_PADNULL—pads to the full length of the variable with nulls.
maxlength	When binding all types of results to non-fixed-length types. maxlength is ignored when binding to fixed-length datatypes.	The length of the destination variable, in bytes. If buffer has more than one element (that is, it is an array), maxlength is the length of one element. When binding to character or binary destinations, maxlength must describe the total length of the destination variable, including any space required for special terminating bytes, with this exception: when binding to a VARYCHAR-type destination such as DB2’s VARCHAR, maxlength does not include the length of the “LL” length specification. To clear bind values, assign maxlength a value of 0. If the length specified in maxlengthis too small to hold a result data item, then, at fetch time, ct_fetch discards the result item that is too large, fetches any remaining items in the row, and returns CS_ROW_FAIL. If this occurs, the contents of buffer are undefined. When binding Sybase-numerical/decimal to char, use ct_describe to determine precision. maxlength should be precision + 2 in this case. When binding to packed-decimal, ct_bind calculates maxlength as (precision/2) + 1.
scale	Only when converting column results or return parameters to or from an Open ServerConnect packed decimal (CS_PACKED370), Sybase-decimal, and Sybase-numeric datatypes.	The number of digits to the right of the decimal point. If the source value is the same datatype as the destination value, set scaleto CS_SRC_VALUE to indicate that the destination variable should pick up the value for scale from the source data. scale must be less than or equal to precision and cannot be greater than 31. If the actual scale is greater than the scale specified in scale but not greater than 31, ct_bind truncates the results and issues a warning. If the actual scale is greater than 31, the ct_bind call fails. When binding sybase-numeric/decimal to char or packed-decimal use ct_describe to determine precision and scale.
precision	Only when binding column results or return parameters to an Open ServerConnect packed decimal (CS_PACKED370), Sybase-decimal, and Sybase-numeric datatypes.	The total number of decimal digits in the destination variable. If the source data is the same datatype as the destination variable, setting precision to CS_SRC_VALUE instructs the destination variable to pick up its value for precision from the source data. If the precision of the value fetched exceeds the precision of the destination variable, ct_bind returns a warning message. precision must be greater than or equal to scale and cannot be less than 1 or greater than 31.
status	Not used (CS_FMT_UNUSED).	Not applicable.
count	When binding all types of results. Only regular row result sets ever contain multiple rows. Other types of results (for example, return parameters, status) are treated like a single row of results.	The number of result rows to be copied to program variables per ct_fetch call. If count is larger than the number of available rows, only the available rows are copied. count must have the same value for all columns in a result set: If count is 0 or 1, 1 row is fetched; If count is greater than 1, it represents the number of rows that are fetched. In this case, buffer must be an array. Only regular row result sets can contain multiple rows. Other types of results (such as return parameters and status) are treated like a single row of results.
usertype	Not used (CS_FMT_UNUSED).	Not applicable.
locale	Not used (CS_FMT_UNUSED).	Reserved for future use.

buffer

(I) Destination variable. A single field or an array of n elements where n is count. Each array element is of size maxlength.

buffer is the program variable to which ct_bind binds the server results. When the application calls ct_fetch to fetch the result data, it is copied into this space.

If you no longer want to store incoming data in this buffer, set maxlength to 0. This clears the binding.

copied

(O) Length of the incoming data. This can be a single field or, if buffer is an array, it can be an array of n elements where n is count. At fetch time, ct_fetch fills copied with the length(s) of the copied data.

indicator

(O) From 1 to count integer variables. At fetch time, ct_fetch uses each variable to indicate the following conditions about the fetched data:

Value	Integer value	Meaning
CS_NULLDATA	-1	There was no data to fetch. In this case, data is not copied to the destination variable.
CS_GOODDATA	0	The fetch was successful.

If buffer is an array, indicator is also an array.

ct_bind returns one of the following values listed in Table 3-3.

This code fragment demonstrates the use of ct_bind to bind returned data to program variables. It is taken from the sample program SYCTSAA6 in Appendix A, “Sample Language Application.”

	/********************************************************************/
	/*                                                                  */
	/* Subroutine to bind each data                                     */
	/*                                                                  */
	/********************************************************************/
	void   bind_columns (parm_cnt)
  
	CS_INT        parm_cnt;
	{
	CS_INT        rc;
	CS_INT        col_len;
	CS_DATAFMT    datafmt;
  
         rc= ct_describe(cmd, parm_cnt, &datafmt);
  
         if (rc != CS_SUCCEED)
         {
            strncpy (msgstr, "CT_DESCRIBE failed", msg_size);
            no_errors_sw = FALSE ;
            error_out(rc);
         }
  
  /*------------------------------------------------------------*/
  /* We need TO bind the data TO program variables. We don't    */
  /* care about the indicator variable so we'll pass NULL for   */
  /* that PARAMeter in OC_BIND().                               */
  /*------------------------------------------------------------*/
  
  /*------------------------------------------------------------*/
  /* rows per fetch                                             */
  /*------------------------------------------------------------*/
  
         switch (datafmt.datatype)
         {
  /*------------------------------------------------------------*/
  /* bind the first column, FIRSTNME defined as VARCHAR(12)     */
  /*------------------------------------------------------------*/
             case  CS_VARCHAR_TYPE:
  
                rc= ct_bind(cmd, parm_cnt, &datafmt, &col_firstnme,
                            &col_len, CS_NULL);
  
                if (rc != CS_SUCCEED)
                {
                   strncpy (msgstr, "CT_BIND CS_VARCHAR_TYPE failed",
                   msg_size);
                   no_errors_sw = FALSE ;
                   error_out(rc);
                }
                break;

	/*------------------------------------------------------------*/
	/* bind the second column, EDLEVEL defined as SMALLINT        */
	/*------------------------------------------------------------*/
             case  CS_SMALLINT_TYPE:

                rc= ct_bind(cmd, parm_cnt, &dtafmt, &col_edlevel,
                            &col_len, CS_NULL);

                if (rc != CS_SUCCEED)
                {
                   strncpy (msgstr, "CT_BIND CS_SMALLINT_TYPE failed",
                   msg_size);
                   no_errors_sw = FALSE ;
                   error_out(rc);
                }
                break;
  
             default:
                break;
  
         } /* end of switch (datatype) */
  
  }   /* end bind_columns */

Usage

• ct_bind associates (“binds”) a column, parameter, or status returned by a server to a program variable. Once a result is bound to a variable, any information returned in that column or parameter, or any status returned during a ct_fetch call is copied to that variable.

• An application must call ct_bind once for each result column or return parameter.

• ct_bind can be used to bind a result column, a return parameter, or a stored procedure status value. When binding a result column, a single call to ct_bind can bind multiple rows of the column. When binding a return status, you must bind a single variable of type integer.

• An application calls ct_bind after ct_results and before ct_fetch. ct_results tells the application whether there are any results to be bound and if so, what kind; ct_fetch retrieves the results and copies them into the bound variable.

• ct_bind binds only the current result type. ct_results indicates the current result type via its result_type argument. For example, if ct_results returns CS_STATUS_RESULT, a return status is available for binding.

• An application can call ct_res_info to determine the number of items in the current result set, and can call ct_describe to get a description of each item.

• An application can only bind a result item to a single program variable. If an application binds a result item to multiple variables, only the last binding takes effect.

• Binding for a particular type of result remains in effect until ct_results returns CS_CMD_DONE to indicate that the results of a logical command are completely processed.

• If you no longer want to store incoming data in the program variable, call ct_bind with a zero-length buffer (for example, maxlength = 0).

• An application can rebind while actively fetching rows. That is, an application can call ct_bind inside a ct_fetch loop if it needs to change the binding of a result item (This action is not recommended).

• ct_bind supports CS_NUMERIC and CS_DECIMAL datatypes.

• Use ct_describe before ct_bind with decimal datatypes to get correct precision and scale.

• Table 3-4 lists the datatype conversions performed by ct_bind.

Array Binding

• ct_describe

• ct_fetch

• ct_res_info

• ct_results

---

Copyright © 2007. Sybase Inc. All rights reserved.

View this document as PDF