DATAFMT structure

Description

Most functions use only a subset of the fields in a DATAFMT structure. For example, ct_bind does not use the name, status, and usertype fields, and ct_describe does not use the format field. For information on which DATAFMT fields a function uses, see Table 2-3 in this chapter, or reference the desired function in Chapter 3, “Functions.”

A DATAFMT structure is defined as follows:

/**********************************************************************/
                     CT_DATAFMT  used for client/server API calls
/**********************************************************************/
 typedef struct _ct_datafmt {
             CS_CHAR name[CS_MAX_NAME]; /* name of the column/parm     */
             CS_INT  namelen;           /* actual length of the name   */
             CS_INT  datatype;          /* hostvar datatype            */
             CS_INT  format;            /* Pad or \0 terminate Bin/Char*/
             CS_INT  maxlength;         /* max length the data might be*/
             CS_INT  scale;             /* NUMERIC: scale value (only) */
             CS_INT  precision;         /* NUMERIC: precision value    */
             CS_INT  status;            /* datum status (key, ret parm)*/
             CS_INT  count;             /* BIND: how many rows to bind */
             CS_INT  usertype;          /* user defined datatype (UDT) */
             CS_LOCALE *locale;         /* localization struct pointer */
                    } CS_DATAFMT;

Table 2-3 describes fields in the DATAFMT structure.

• name is the name of the data item. This can be a column, a parameter, or a return status name.

• namelen is the length, in bytes, of name. Assign namelen a value of 0 if the data item is unnamed.

• datatype is the datatype of the data. This is one of the Client-Library datatypes listed in Table 2-7.

  Return status values have a datatype of CS_INT.

• format is the destination format of fixed-length character or binary data.

• format can be one of the following values listed in Table 2-4.

  Table 2-4: Values for the DATAFMT field format

  Value	Meaning	Data type
  CS_FMT_PADBLANK	The data should be padded with blanks to the full length of the destination variable.	For fixed-length character data only.
  CS_FMT_PADNULL	The data should be padded with zeroes to the full length of the destination variable.	For binary or fixed-length character data.

• maxlength can represent various lengths, depending on which function is using the DATAFMT structure. Lengths are represented in bytes. Table 2-5 lists the meaning of maxlength for each function that uses it.

  Table 2-5: Lengths defined by the DATAFMT field maxlength

  Function	Length defined
  cs_convert	The length of the source variable and the length of the destination variable.
  ct_bind	The length of the variable to which the data is bound.
  ct_describe	The maximum possible length of the column or parameter being described.
  ct_param	The maximum length of return parameter data.

• scale is the number of decimal places in the value being converted. scale is used with ct_bind, cs_convert, and ct_param when converting to or from decimal datatypes CS_PACKED370, numeric, and Sybase-decimal.

  Legal values for scale are from 0 to 31. If the actual scale is greater than 31, the call fails. To indicate that destination data should use the same scale as the source data, set scale to CS_SRC_VALUE. scale must be less than or equal to precision.

• precision is the precision of the value being converted.

  Precision is used only with ct_bind, cs_convert, and ct_param when converting to or from decimal datatypes CS_PACKED370, numeric, and Sybase-decimal. Legal values for precision are from 1 to 31. To indicate that destination data should use the same precision as the source data, set precision to CS_SRC_VALUE. precision must be greater than or equal to scale.

• status is one or more of the following symbolic values (added together) listed in Table 2-6.

  Table 2-6: Values for the DATAFMT field status

  Value	Meaning	For this function
  CS_CANBENULL	The column can contain nulls.	ct_describe
  CS_NODATA	No data is associated with the result data item.	ct_describe
  CS_INPUTVALUE	The parameter is a non-return RPC parameter (input parameter).	ct_param
  CS_RETURN	The parameter is an RPC return parameter.	ct_param

• count is the number of rows to copy to program variables per ct_fetch call.

• usertype is the user-defined datatype, if any, of data returned by the server.

  usertype is used only for datatypes defined at the server, not for datatypes defined by Open ClientConnect, such as Adaptive Server-defined datatypes or datatypes defined with TDSETUDT in Open ServerConnect.

• locale is reserved for future use. It must be set to zero.

---

Copyright © 2007. Sybase Inc. All rights reserved.

View this document as PDF