RES-Reach allows external programs or DLL functions to be called from a template using the SET tag.
The current release of RES-Reach allows you to call sample functions from the "R32DLL.DLL" library. The next release of RES-Reach will offer the RES-Reach software development kit which will allow you to define your own library functions.
The syntax for calling an external program (.EXE, .BAT, .CMD) is:
<SET VARIABLE="varname" PROGRAM="c:\winnt\system32\someprog.exe" VALUE="some string">
The VARIABLE element refers to a private variable into which the return value, a string, is placed by the program via standard output (stdout). If the program file is missing, or the program terminates abnormally, the error can only be detected by examining this variable. If the variable had a value before the program call, it will not have changed. If it did not have a value, it is still "unknown".
The PROGRAM element defines the name of the external program, including directory information (if required) and all command-line arguments.
The VALUE element is optional. If it exists, its contents are passed to an external program through standard input (stdin).
To determine how long RES-Reach waits for a return answer from an external program set the _RUN.WAIT runtime variable with the number of milliseconds you are willing to wait.
<SET VARIABLE="_RUN.WAIT" VALUE="5">
If the program exceeds that value, RES-Reach will attempt to terminate it: it may or may not succeed.
If you do not set the _RUN.WAIT variable, the default waiting time is 0. If _RUN.WAIT is set to 0, the external program is executed asynchronously and the return string can be ignored.
Most operating system functions can be accessed at this time as external programs; however, if you want to write your own programs for inclusion in RES-Reach templates, you will need the RES-Reach SDK due with the next release.
Example:
This example shows how the "winver.exe" operating system function can be called.
<SET VARIABLE="_RUN.WAIT" VALUE="2000">
<SET VARIABLE="PROGRAM" VALUE="">
{time} Calling WinVer with {_RUN.Wait} milliseconds maximum waiting time. <BR>
<SET VARIABLE="PROGRAM" PROGRAM="C:\\WINNT\\SYSTEM32\\Winver.EXE">
{time} Status after calling WinVer program: {ERRNO} {ERRSTRING}<BR>
<PRE>Win ver output :{PROGRAM}</PRE><BR>
The syntax for calling an function in a dynamic link library (.DLL) is:
<SET VARIABLE="varname" FUNCTION="URLENC" VALUE="some string">
The VARIABLE element refers to a private variable into which the function's return value, a string, is placed. If the function is not found in the specified libraries (see below), or the function terminates abnormally, the error can only be detected by examining this variable. If the variable had a value before the program/function call, it will not have changed. If it did not have a value, it is still "unknown".
The FUNCTION element defines the name of the function to be called. The contents of the _RUN.LIBS variable determines one or more library files to be searched to find the function:
<SET VARIABLE="_RUN.LIBS" VALUE="Publics.DLL, String.DLL">
If the _RUN.LIBS variable has not been given a value, a parsing error will be triggered.
The VALUE element is optional. If it exists, its contents are passed to the DLL function via the DLL calling mechanism.
_RUN.WAIT can be passed to a DLL function if its definition allows, it may or may not choose to respect it. Typically, if used, it is assigned the number of milliseconds the RES-Reach template is willing to wait for results.
<SET VARIABLE="_RUN.WAIT" VALUE="5">
To define your own DLL functions, you must have a copy of the RES-Reach SDK; this will be available in a few months.
The next section describes sample functions, included in this release, which you may find useful. Support for these functions is limited.