WIN32 UDF for DBMaker 5.4 version external document

1. Introduction
2. Building UDF dll file method
3. Example - from create to query UDF


1. Intorduction

UDF - User Defined Function
Now, DBMaker support users to build their own user defined functions on
WIN32 platforms. Users can follow the format of a template C source file
to write their UDF. Once a UDF is written and built into DBMaker, it
seems that DBMaker has this additional function as a new built-in
function because the usage of the UDF is exactly the same as DBMaker's
built-in function. We provide a library - dmudf.lib for users to link
with their UDF's source file together to build their udf dll file. By
the way, we also provide a template make file and a template C source
file for users to reference.

2. Method to build a UDF dll file

We provide a template.c and template make file udf60.mak (for Microsoft 
VC++ 6.0) for users to reference. 
In the following statements, we take udf60.mak for example.

In the beginning, according to udf60.mak, you have to make sure where to 
include the dmudf.lib file. After you finishing it, you have to use the 
IDE that Visual C++ provides to modify where needed changes.

Step 1. Copy udf60.mak template make file into your desired directory
        and rename it as your desired make file name. 

Step 2. Choose <File> -> <Open Workspace> to open your make file project 
        workspace.

Step 3. In the <Project Workspace>, choose <File View>, then choose
        template.c to click, then press Delete key to remove it. 
        After finishing above, choose <Insert> item in the tool bar,
        choose < Files into project> to insert your own .c file into 
        your make file of project workspace.

Step 4. In the <Build> -> <Settings>, we choose WIN32 Debug for example.
        In the Project Settings <General>, you can change output 
        directories. In the template make file, we set 60Deb as the 
        intermediate and output directories.

Step 5. In the Project Settings <Link> item, in Category item <General>
        , you can change output dll file name just directly modify in 
        <Output file name>. You also have to change the linking path of 
        dmudf.lib file we support in the <Object/Library modules> as your
        own setting working directory.

After finishing above described behavior, you can build your own dll 
make file. Using the simular same steps, you can also build WIN32 Release 
version dll file. Except the above mention settings, please keep the other
settings as original what we offer. 

Note: If you are the power user of VC ++, you can also create the dll make
file by yourself by the above steps. All you have to note is set the 
structure member alignment to be 4 bytes. ( In VC ++ 4.2 IDE project
workspace, choose C/C++ item, then in Category dialog box, choose 
<Code Generation>. You can find the structure member alignment option, 
then choose 4 bytes as result.


In the following setting, we take our template make file to explain the
method to write a collect dll.


In the template.c, please remember to include libudf.h (DBMaker provides) 
and also remember to export your functions.     
                                                               
 Example:                                                       
   __declspec(dllexport) datatype YOUR_FUNCTION( ...... )      
                                                               
 Alternatively, you can also create a def file in the     
 project workspace to export your functions.   

After finishing aboves, you can build debug/release dll file. If success,
you would get udf60.dll file.       

Note 1. If you don't want to use template.c as the C default filename
        within the make file, you have to remove template.c from the 
        make file and insert your C file into make file udf60.mak 
        project workspace (as above mentioned method).

Note 2. The function name for UDF must be UPPERCASE.


3. Example - from create to query UDF


The following, we'll give you an example to show you how to use UDF.

Example:

There is a database named DMDEMO. In the DMDEMO, there is a table t1
and the table schema is (c1 int, c2 char(10)). There are also some 
data inside t1.

dmSQL> select * from t1;

    c1          c2     
=========== ========== 
         10 1          
         20 2          
         30 3          

3 rows selected


Step 1. By the example template.c DBMaker supported, we build udf60.dll
        successfully.
Step 2. In the dmconfig.ini file, we have to add one line to DMDEMO 
        section where UDF dll file located.

        [DMDEMO]
        DB_DBDir = D:\UDFDEMO
        DB_FODIR = D:\UDFDEMO\FO
        DB_LBDIR = D:\UDF\60Deb <- you have to add this line
        ^^^^^^^^^^^^^^^^^^^^^^^
Step 3. Start database DMDEMO, then create UDF function:

[Grammer] create function UDF_DLL_NAME.UPPERCASE_FUNCTION_NAME
          (FUNCTION_DATATYPE) RETURNS FUNCTION_OUTPUT_DATATYPE;

          In the example, the UDF_DLL_NAME is udf60 ,the UPPERCASE_FUNCTION
          _NAME is INT2STR, FUNCTION_DATATYPE is int, and FUNCTION_OUTPUT
          _DATATYPE is varchar(11).

          create function udf60.INT2STR(int) RETURNS varchar(11);

Step 4. Query UDF function INT2STR results.

[Grammer] select UPPERCASE_FUNCTION_NAME(RELATED_TABLE_COLUMNNAME) from 
          RELATED_TABLE;
        
          In the example, the UPPERCASE_FUNCTION_NAME is INT2STR, 
          RELATED_TABLE_COLUMNNAME is c1 according to the schema of t1 
          and the RELATED_TABLE is t1.

          dmSQL> select INT2STR(c1) from t1;

          INT2STR(c1) 
          =========== 
          10          
          20          
          30          

          3 rows selected

Step 5. As the description as above you can try another example UDF function
        STR2INT.


        dmSQL> create function udf60.STR2INT(varchar(11)) RETURNS int;

        dmSQL> select STR2INT(c2) from t1; 

        STR2INT(c2) 
        =========== 
                  1 
                  2 
                  3 

        3 rows selected
