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 descriptions of the CTBBIND and CTBDESCRIBE functions located in the sections CTBBIND and CTBDESCRIBE in Chapter 3, “Functions.”
A DATAFMT structure is defined as follows:
01 DATAFMT 05 FMT-NAME PIC X(132). 05 FMT-NAMELEN PIC S9(9) COMP SYNC. 05 FMT-TYPE PIC S9(9) COMP SYNC. 05 FMT-FORMAT PIC S9(9) COMP SYNC. 05 FMT-MAXLEN PIC S9(9) COMP SYNC. 05 FMT-SCALE PIC S9(9) COMP SYNC. 05 FMT-PRECIS PIC S9(9) COMP SYNC. 05 FMT-STATUS PIC S9(9) COMP SYNC. 05 FMT-COUNT PIC S9(9) COMP SYNC. 05 FMT-UTYPE PIC S9(9) COMP SYNC. 05 FMT-LOCALE PIC S9(9) COMP SYNC.
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 |
FM-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 can have 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 LOW-VALUES 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, these would include 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.
