Apollo supports UDFs (User-Defined Functions) which allows you to extend the xBase expression. This is useful for creating user-defined functions in index expressions.
UDFs must reside in a standard Windows DLL (Dynamic Link Library), and the new xBase functions must be defined in a special text file that Apollo looks for whenever one of its RDEs (Replaceable Database Engines) is loaded.
Sample text file that supports the UDF DLL:
[udf01]
DLLName=sdeudf.dll
DLLFuncName=MonthName
xBaseFuncName=CMONTH
ReturnType=STRING
Param1Type=NUMERIC
The new xBase extensions may be used in your Apollo application wherever xBase functions are supported (e.g., index expressions, queries, filters, conditions, TApolloTable.Eval* methods, etc.).
See the source code for a sample DLL that supports the functions shown below is included with Apollo in the ..\UDF subdirectory. DLLs may be written in any Windows language.
Calling conventions and data types as described below must be respected.
SDEUDF definition file
You may define up to 64 UDFs (User Defined Functions) for each RDE file type. Each function must reside in a DLL (not necessarily the same DLL). Apollo will pass parameters to your function as POINTERS (passing parameters by value is prohibited). You must return a pointer to a value.
This file must reside in the Windows home directory - NOT the system directory. This is because these files are basically .INI file formats and internal INI file-related API functions are used to read the data. A Windows requirement for INI files is that they reside in the Windows root directory.
The file name is tied to the RDE (Replaceable Database Engine) type. These must be named as follows:
• SDECDX.UDF - FoxPro format
• SDENTX.UDF - Clipper format
• SDENSX.UDF - HiPer-SIx format
When the RDE is first loaded, a search is made for the appropriate UDF file in the Windows home directory. Any valid function definitions are added to the Apollo xBase function table.
SECTION NAMES [udfxx]
Section names in this file must be in the form [udfxx] where xx is a number between "01" and "64" (note the leading "0" for sections [udf01] through [udf09]). Multiple UDF definitions must be labeled with consecutive section numbers. The first [udfxx] that does not exist or the first empty [udfxx] section DLLName parameter will stop the parse engine.
DLLName - The name of the DLL that contains the UDF. If it is not in the search path, you must qualify it by specifying the complete path to the file.
DLLFuncName - The name of the function in your DLL. This does not have to be the same as the name you use in an xBase expression. Our example SDEUDF.DLL has an exported function called "MonthName" and we will access it in xBase expressions passed to Apollo as CMONTH.
DLLFuncName is case sensitive. It must be passed exactly as it is declared in your DLL.
xBaseFuncName - The name for the function that will be used in xBase expressions. The maximum length of an xBase function name is 8 characters. This name is NOT case sensitive. The function name must begin with a letter and may contain A..Z, a..z, 0..9, and an underscore (_). No special characters except for the underscore are allowed. You must also ensure that the first four characters of your xBaseFuncName are UNIQUE. They may not match Apollo defined xBase functions nor may they match any other UDF name. Apollo does NOT test for duplicate function names. The first definition in the xBase table will be used.
ReturnType and ParamxType - Valid types for ReturnType and Input ParamxTypes are:
• NUMERIC - passed as a number
• JULIAN - passed as a number
• DATESTRING - passed as a quoted string conforming to date mask setting
• STRING - passed as a quoted string
• LOGICAL - passed as a number (0 = False, 1 = True)
NUMERIC and JULIAN types will be passed to your function as double *. If your return value is NUMERIC or JULIAN you must pass it back to Apollo as a double *.
Every UDF must have a ReturnType. If the return type is LOGICAL, pass a pointer to an integer containing your TRUE or FALSE value back to SDE.
Input parameters are optional. The maximum number of input parameters is three. If any input ParamType item is unused, leave it blank as in the example below.
[udf01]
DLLName=sdeudf.dll
DLLFuncName=MonthName
xBaseFuncName=CMONTH
ReturnType=STRING
Param1Type=NUMERIC
Param2Type=
Param3Type=
Using our example UDF, the following Apollo instruction would return "November" if the month portion of datefield was 11.
sMonth = ApTbl.EvalString('CMONTH(month(datefield))')
See the sample UDF code in the in the ..\VCL\UDF subdirectory (TESTUDF.DPR) for the complete example function source and more tips on constructing your own functions.