A DATAFMT structure is used to describe data values and program variables. For example:
CTBBIND requires a DATAFMT structure describing a destination variable.
CTBDESCRIBE returns a DATAFMT structure describing a result data item.
CTBPARAM requires a DATAFMT structure describing an input parameter.
CSBCONVERT requires a DATAFMT structure describing source and destination data.
Most functions use only a subset of the fields in a DATAFMT structure. For example, CTBBIND does not use the FMT_NAME, FMT_STATUS, and FMT_UTYPE fields, and CTBDESCRIBE does not use the FMT_FORMAT field. For information on which DATAFMT fields a function uses, see Table 2-3 in this chapter, or the description of the relevant function in the next chapter.
A DATAFMT structure is defined as follows:
DCL 01 DATAFMT, 05 FMT_NAME CHAR(132), 05 FMT_NAMELEN FIXED BIN(31), 05 FMT_TYPE FIXED BIN(31), 05 FMT_FORMAT FIXED BIN(31), 05 FMT_MAXLEN FIXED BIN(31), 05 FMT_SCALE FIXED BIN(31), 05 FMT_PRECIS FIXED BIN(31), 05 FMT_STATUS FIXED BIN(31), 05 FMT_COUNT FIXED BIN(31), 05 FMT_UTYPE FIXED BIN(31), 05 FMT_LOCALE FIXED BIN(31);
Table 2-3 describes the fields in the DATAFMT structure.
Field |
Contents |
Used by |
|---|---|---|
FMT_NAME |
The name of the data item. |
CTBDESCRIBE CTBPARAM |
FMT_NAMELEN |
The length of FMT_NAME. |
CTBDESCRIBE CTBPARAM |
FMT_TYPE |
The datatype of the data. See the specific call to find which data this refers to. |
CSBCONVERT CTBBIND CTBDESCRIBE CTBPARAM |
FMT_FORMAT |
The format of the data, represented by symbolic values. |
CTBBIND |
FMT_MAXLEN |
The maximum length of the data. |
CSBCONVERT CTBBIND CTBDESCRIBE CTBPARAM |
FMT_SCALE |
The number of digits in the decimal part of a number. This field is used with packed decimal, numeric and Sybase-decimal. |
CSBCONVERT CTBBIND |
FMT_PRECIS |
The total number of digits in a number. This field is used with packed decimal, numeric and Sybase-decimal. |
CSBCONVERT CTBBIND |
FMT_STATUS |
Status values. |
CTBDESCRIBE CTBPARAM |
FMT_COUNT |
The number of items. |
CTBBIND CTBDESCRIBE |
FMT_UTYPE |
The user-defined datatype (UDT) of retrieved data. The UDT is assigned by the server. |
CTBDESCRIBE CTBPARAM |
FMT_LOCALE |
Reserved for future use. |
CSBCONVERT CTBBIND CTBDESCRIBE CTBPARAM |
FMT_NAME is the name of the data item. This can be a column, a parameter, or a return status name.
FMT_NAMELEN is the length, in bytes, of FMT_NAME. Assign FMT_NAMELEN a value of 0 if the data item is unnamed.
FMT_TYPE is the datatype of the data. This is one of the Client-Library datatypes listed under “Datatypes”.
Return status values have a datatype of CS_INT.
FMT_FORMAT is the destination format of fixed-length character or binary data. FMT_FORMAT is one of the following values listed in Table 2-4.
Value |
Meaning |
Datatype |
|---|---|---|
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. |
FMT_MAXLEN 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 FMT_MAXLEN for each function that uses it.
Function |
Length defined |
|---|---|
CSBCONVERT |
The length of the source variable and the length of the destination variable. |
CTBBIND |
The length of the variable to which the data is bound. |
CTBDESCRIBE |
The maximum possible length of the column or parameter being described. |
CTBPARAM |
The maximum length of return parameter data. |
FMT_SCALE is the number of decimal places in the value being converted. FMT_SCALE is used with CTBBIND, CSBCONVERT, and CTBPARAM when converting to or from decimal datatypes CS_PACKED370, numeric, and Sybase-decimal.
Legal values for FMT_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 FMT_SCALE to CS_SRC_VALUE. FMT_SCALE must be less than or equal to FMT_PRECIS.
FMT_PRECIS is the precision of the value being converted. FMT_PRECIS is used only with CTBBIND, CSBCONVERT, and CTBPARAM when converting to or from decimal datatypes CS_PACKED370, numeric, and Sybase-decimal. Legal values for FMT_PRECIS are from 1 to 31. To indicate that destination data should use the same precision as the source data, set FMT_PRECIS to CS_SRC_VALUE. The value of FMT_PRECIS must be greater than or equal to FMT_SCALE.
FMT_STATUS is one or more of the following symbolic values (added together) listed in Table 2-6.
Value |
Meaning |
For this function |
|---|---|---|
CS_CANBENULL |
The column can contain nulls. |
CTBDESCRIBE |
CS_NODATA |
No data is associated with the result data item. |
CTBDESCRIBE |
CS_INPUTVALUE |
The parameter is a non-return RPC parameter (input parameter). |
CTBPARAM |
CS_RETURN |
The parameter is an RPC return parameter. |
CTBPARAM |
FMT_COUNT is the number of rows to copy to program variables per CTBFETCH call.
FMT_UTYPE is the user-defined datatype, if any, of data returned by the server.
FMT_UTYPE is used only
for datatypes defined at the server, not for datatypes defined by Open ClientConnect.
For example, Adaptive Server-defined datatypes or datatypes defined
with TDSETUDT in Open ServerConnect.
FMT_LOCALE is reserved for future use. It must be set to zero.
