Access to CopiaFacts Variables
You may of course pass variables to your DLL by including for example @varname in the string you assign to the DLL_PARM variable as shown in the examples above. However the COPIAFACTS DLL call interface also allows direct setting and retrieving of variable values by making a callback from your DLL. Using the callback functions is the most efficient way of getting and setting variable values.
To use this feature, you must provide an entry point named FFDLLinit in your DLL. If CopiaFacts finds this entry point, it will call it to pass you two procedural arguments which are the addresses of functions you can call to get and set variables from your DLL. The C prototypes are as follows:
typedef void (*FFCB_GV)(int,char const*,char*,int); /* getvar */
typedef void (*FFCB_SV)(int,char const*,char const*); /* setvar */
typedef int (*FFCB_DI)(int,FFCB_GV,FFCB_SV); /* dll init */
The three parameters for the FFDLLinit entry point are as follows:
•The number of 'lines' in the node
•The procedure address for the 'get variable' call
•The procedure address for the 'set variable' call
When this entry point has been provided and called, there will be a small difference in the arguments passed to all of your other entry points in the DLL. The first argument to each of your entry points is then the line reference, not the line number. The line reference is an integer ranging from 0 to one less than the number of lines in the node. The line number is the unique line number across all your nodes, with base 1. You must pass the same line reference back to the callback functions if you wish to retrieve or set variables from inside your DLL. Passing any other value as the first argument to the callback functions will cause incorrect and possibly catastrophic results. If for some reason you need the actual line number you can retrieve it from the LNUM variable as shown below.
To retrieve the value of a system or user variable, call the callback function with the line reference, the name of the variable, the address of a buffer to receive the value, and the length of the buffer in characters. This always needs to include the terminating null character of a string value, and we recommend making the buffer larger than the maximum size you expect. An example of the use of the callback to retrieve a variable is as follows:
To set the value of a variable, call the callback function with the line reference, the name of the variable, and a string value. An example of the use of the callback to set a variable is as follows:
After your DLL returns control to COPIAFACTS you can access this variable in the normal way as @MYTOTAL in your infobox logic. You can delete a variable (as opposed to setting it to an empty value) by passing a null pointer as the third argument to this function. Note that the @ character is not normally used in these function calls.
The variable names and values will by default be UTF8-encoded. To use parameters with system default encoding, or with Unicode (UTF-18) encoding, see the topic on Alternate Parameter Encoding.