Defining a Sample UDF with a Descriptor Parameter

From InterBase
Jump to: navigation, search

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.

Explanation of the structure fields
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.

Explanation of dsc_type
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.

Explanation of dsc_flags
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.