R:BASE 11 Help

(UDF ('exe-name','parameter-list'))

(UDF ('-exe-name','parameter-list'))

(UDF ('+exe-name','parameter-list'))

(UDF ('@dll-name','parameter-list'))

 

The logic behind using User Defined Functions or adding custom functionality to R:BASE is currently supported with plugins. Please refer to the PLUGIN command

 

You can use a user-defined function (UDF) anywhere you can use a function in R:BASE:

 

•Forms

•Reports

•Entry/exit procedures

•Applications

•Commands

 

The arguments for a UDF are as follows:

 

  @, +, -, or nothing

If you do not specify a plus or minus, the function is hidden when it runs; this setting is the default. A plus (+) runs the function in a normalized window. A minus (-) runs the function as a minimized icon. The at sign (@) is used to indicate that the UDF being called is a DLL. This only applies to Windows and is not available to the DOS version of R:BASE.

 

  exe-name,dll-name

Specifies the name of the UDF (the name of the executable file into which you have compiled and linked your program). Under Windows this can be a Windows program. When using DLL's you MUST include the .DLL extension or the DLL may not be executed.

 

parameter-list

Specifies a text string. Multiple parameters must be separated by spaces, as shown:

 

SET VAR v1=(UDF('random','25 345'))

 

UDFs function as follows:

 

•R:BASE passes command line arguments to the UDF executable file.

•The UDF executable file completes its calculations and passes the data and the ERRORLEVEL to R:BASE.

 

This file can be found in the same directory as the main R:BASE executable.

 

When used with executables the parameter-list, from the UDF syntax, acts exactly as if you typed it at the a command prompt. Remember to account for the length of the executable name as well as the memory address (eight characters) plus the spaces between the .EXE name, the parameter list, and the address name. The parameter list can be space delimited with EXE UDF's.

 

You can write a UDF executable file in any language that allows writing to far pointers, such as Microsoft C. UDF executable files require protected mode libraries. You can return only 1,500 bytes of text data to R:BASE; that is, when you copy your results to either the address passed in or the shared-memory segment, you must not write more than 1,499 characters plus the NULL terminator (/0). If you write more than 1,500 total characters to the address you will corrupt the R:BASE variables and R:BASE might "hang."

 

If you forget the NULL terminator (/0) you will probably get high-order ASCII characters in your text variable. To pass back multiple values, delimit them with commas and then use other R:BASE functions to pull out the values. R:BASE stops looking at the returned text when it first encounters a NULL (/0). If your UDF executable file hangs, It is very likely that R:BASE will as well.

 

The size of a UDF is limited by the amount of available memory. Keep your executable files as small as possible. You will have to experiment to determine the maximum possible memory in a given situation. You can have different amounts of available memory at different times in an R:BASE session. Because you had an amount of memory available at one point in an R:BASE session does not mean that you will have the same amount of memory available in your next R:BASE session.

 

If your UDF fails to write to the memory given to it, then the UDF function in R:BASE sets the variable to NULL (-0-). You could use this in your UDF executable file to show whether the UDF failed. UDFs treat error variables the same as R:BASE does; therefore, you can have your application tell you if the UDF was successful or not by using the R:BASE error variable and the compiler's function that allows the return of error variables, such as Microsoft C exit( ) function to return the ERRORLEVEL. R:BASE places the ERRORLEVEL value in the R:BASE error variable.

 

Error Level

If your UDF fails to write to the memory given to it, then the UDF function in R:BASE sets the variable to NULL (-0-). You could use this in your own UDF executable file to show whether the UDF failed.

 

UDFs treat error variables the same as R:BASE does; therefore, you can have your application tell you if the UDF was successful or not by using the R:BASE error variable and the compiler's function that allows the return of error variables, such as Microsoft C exit( ) function to return the ERRORLEVEL. R:BASE places the ERRORLEVEL value in the R:BASE error variable.

 

Memory Issues

The size of a UDF is limited by the amount of available memory. Keep your executable files as small as possible. Depending on where the UDF is run and how much memory R:BASE has available to it at that moment, you could possibly run an executable file as large as 50K. You will have to experiment to determine the maximum possible memory in a given situation.

 

You can have different amounts of available memory at different times in an R:BASE session. Because you had an amount of memory available at one point in an R:BASE session does not mean that you will have the same amount of memory available in your next R:BASE session.

 

Returning Multiple Values

A UDF can return up to 1,500 characters. You can write a UDF that returns multiple values; then, you can write a command file that interprets coded strings and tells your application what was returned. For example, you could set up the following coded strings:

 

 

The UDF returns the information below to R:BASE with values for the coded strings 100 and 200 in comma-delimited format:

 

100,1.23456,200,2.34567

 

The command file would interpret that 1.23456 is the cube root of the input number, and 2.34567 is the standard deviation of the input number.