Defining a Sample UDF with a Descriptor Parameter
Go Up to Declaring a UDF to a Database
Functions are defined in C/C++ or Delphi code. In C, the developer needs to accept the descriptor parameter using the ISC_DSC structure. This structure is defined in the include file “ibase.h”.
The following example defines a DESC_ABS function in a C program file:
Example:
double IB_UDF_abs (ISC_DSC *d) { double double_var ; /* function body */ return double_var ; }
For C/C++ programs, the ISC_DSC structure is defined as follows:
Example:
/*********************************/ /* Descriptor control structure */ /*********************************/ typedef struct isc_dsc { unsigned char dsc_version; /* should be set to DSC_CURRENT_VERSION or 2 */ unsigned char dsc_dtype; /* the InterBase data type of this particular parameter */ char dsc_scale; /* scale of the parameter for numeric data types */ char dsc_precision; /* precision of the numeric data type */ unsigned short dsc_length; /* size in bytes of the parameter */ short dsc_sub_type; /* for textual data types will have information about character set and collation sequence, see DSC_GET_CHARSET and DSC_GET_COLLATE macros for more information */ unsigned short dsc_flags; /* will be set to indicate null to DSC_null or to DSC_no_subtype to indicate that the sub type is not set, this is a bit map so multiple bits might be set, use binary operations to test, see table below for explanation */ unsigned char *dsc_address; /* pointer to the actual value of the data type */ } ISC_DSC;
Some related macros follow:
#define DSC_VERSION2 2 #define DSC_CURRENT_VERSION DSC_VERSION2 #define DSC_null 1 #define DSC_no_subtype 2 #define DSC_nullable 4 #define dsc_ttype dsc_sub_type #define DSC_GET_CHARSET( dsc ) ((( dsc )->dsc_ttype ) & 0x00FF) #define DSC_GET_COLLATE( dsc ) ((( dsc )->dsc_ttype ) >> 8)
The following table describes the structure fields used in the example above.
Element Name | Type | Explanation |
---|---|---|
dsc_version |
unsigned char |
Should be set to DSC_CURRENT_VERSION or 2 |
dsc_dtype |
unsigned char |
The InterBase data type of this particular parameter |
dsc_scale |
char |
Scale of the parameter for numeric data types. Scale is the number of digits to the right of the decimal point that comprise the fractional portion of the number. The allowable range for scale is from zero to precision; in other words, scale must be less than or equal to precision. See “Working with Dynamic SQL” in the InterBase API Guide for information on handling NUMERIC and DECIMAL types. |
dsc_precision |
Char |
Precision is the total number or maximum number of digits, both significant fractional, that can appear in a column of these data types. The allowable range for precision is from 1 to a maximum of 18. See “Specifying Data Types” in the Data Definition Guide for more information. |
dsc_length |
unsigned short |
Use dsc_length to figure out how many bytes are of valid data after de-referencing the dsc_address. |
dsc_sub_type |
Short |
Use DSC_GET_CHARSET and DSC_GET_COLLATE to retrieve information about character sets and collation sequences from textual data types. Also, note that for some textual dtypes, the dsc_flags maybe set to indicate that the subtype has not been set for the dtype. |
dsc_flags |
unsigned short |
See the table at the bottom of this page for more information about dsc_flag settings |
dsc_address |
unsigned char* |
Pointer to the actual data. |
For more details on the ranges of the data types and related information, see “Specifying Data Types” in the Data Definition Guide. See also “Working with Dynamic SQL” in the API Guide.
The following table describes the dsc_types that you can use in a DECLARE EXTERNAL FUNCTION statement.
dsc_dtype | Numeric value | Explanation |
---|---|---|
dtype_text |
1 |
Associated with the text data type; use the subtype for character set and collation information. This dtype maps to the SQL data type of SQL_TEXT, and CHAR. |
dtype_string |
2 |
Indicates a null-terminated string. |
dtype_varying |
3 |
Associated with the text data type; use the subtype for character set and collation information. This dtype maps to the SQL data type SQL_VARYING and VARCHAR. |
dtype_short |
8 |
Maps to the data type SQL_SHORT. |
dtype_long |
9 |
Maps to the data type SQL_LONG. |
dtype_quad |
10 |
Maps to the data type SQL_QUAD. |
dtype_real |
11 |
Maps to SQL_FLOAT. |
dtype_double |
12 |
Maps to SQL_DOUBLE. |
dtype_d_float |
13 |
Maps to SQL_D_FLOAT |
dtype_sql_date |
14 |
Maps to SQL_TYPE_DATE. |
dtype_sql_time |
15 |
Maps to SQL_TYPE_TIME. |
dtype_timestamp |
16 |
Maps to SQL_TIMESTAMP. |
dtype_blob |
17 |
Maps to SQL_BLOB. |
dtype_array |
18 |
Maps to SQL_ARRAY. |
dtype_int64 |
19 |
Maps to SQL_INT64. |
dtype_bollean |
20 |
Maps to SQL_BOOLEAN. |
The following table describes the dsc_flags that you can use in a DECLARE EXTERNAL FUNCTION statement.
Flag Name | Numeric value | Explanation |
---|---|---|
DSC_null |
1 |
This flag indicates that data passed in the descriptor has an SQL NULL value. |
DSC_no_subtype |
2 |
Flag is set for text, cstring or varying dtypes, where the subtype is not set. Normally the subtype for these dtypes will be set to the collation and charter set values. |
DSC_nullable |
4 |
Internal use. Ignore for now. |
DSC_system |
8 |
DSC_system flags a format descriptor for system (not user) relations/tables. |