Creating a new plugin.

This section is for advanced users only. You should know at least one programming language to create a plugin. The following explanation is based upon Delphi examples.

If you want SR to successfully import the functions from your DLL library, you should comply with the following requirements:

1) The function always receives the full name of the host program (sr.exe) via pchar (pointer to a null-terminated string). Delphi programmers should always use 'stdcall':

procedure myproc(host:pchar); stdcall;

2) Your function can receive any data from SR (vars, xvars, conditions, etc) after connecting to sr.exe:

function sr_getdata(key:pchar):pchar; stdcall; external 'sr.exe';
Example: filename:=sr_getdata('*XVR FILE FULL NAME');

Never call the function twice in a row: it uses one and the same buffer to prevent lost pointers. You should always save data to local (dll) variables before calling the function again:

Error: if sr_getdata('*XVR LIST COUNT') = sr_getdata('*XVR LIST NUMBER') then...
Correct: s:=sr_getdata('*XVR LIST NUMBER'); if string(sr_getdata('*XVR LIST COUNT')) = s then...
Also correct: if sr_getdata('*XVR LIST NUMBER')='5' then...

One function for compartibility checkings - returns the version of SR:

function sr_getver:integer; stdcall;

The version is encoded so that it can be compared with < or > operations. For example, 20300 means v2.03. For beta releases, decrease 1 from the last number and add the beta number to the last two digits. For instance, 20205 means v2.03 beta 5.

There are functions that can be used for result preview purposes:

// Get the number of files in the SR file list (integer is 32-bite signed integer type):
function sr_getfilecount:integer; stdcall;

// Get the name of the file number 'num' (0 means the first file, sr_getfilecount-1 means the last file):
function sr_getfilename(num:integer):pchar; stdcall;

// Get the number of all accessible variables (var, con, xvr, xxv):
function sr_getvarcount:integer; stdcall;

// Get the name of var number 'num' (0 - first accessible var, sr_getvarcount-1 - last accessible var):
function sr_getvarname(num:integer):pchar; stdcall;

3) Your function can return as many data strings as you need. Each peace of data is referred to with the help of a unique key:

procedure sr_setdata(data:pchar); stdcall; external 'sr.exe';
Example: sr_setdata(pchar('today='+datetostr(now)));

The 'data' data is transmitted in the following format: "key=value" where key is a unique name of the data and value is the data.

4) To get parameters values you must use the mykeys:=sr_getdata('*KEY') at the very beginning of the function, where "mykeys" is a string to store the keys.

The following function extracts the value of "keyname" from the "keys" string:

function sr_getkey(keyname,keys:pchar):pchar; stdcall; external 'sr.exe';
Example:
user writes: mewanimal=cat|barkanimal=dog|mooanimal=cow
you write: myvalue:=sr_getkey('BARKANIMAL',mykeys); /* now myvalue='dog'. */

Note: in version 2.00 you could write "myvalue:=sr_getdata('*KEY BARKANIMAL');" to do the same thing. This way is still available for backward compartibility, but use it with caution. It causes problems when you use another *XXV call from your plugin, for example, if you use "coolval:=sr_getdata('*XXV SECOND FUNCTION');". In this case the keys will be overwritten by the last function and it will cause errors in your first function. This won't happen if you use new above described rules.

5) If you write a plugin for distribution, it's preferable to create a sr_help interface to help the users understand how to use the plugin. sr_help interface contains a little help part that describes the names of functions and result keys and an auto-filling part that automatically fills out the appropriate fields in SR with the default parameters.

Your helping function is very similar to the main function but it should be called 'sr_help'. Don't forget to export it, otherwise it will not be visible for SR! The function may return the following default results (all are optional):

sr_help - the text of the help message.
sr_function - the name of the default function (case sensitive!).
sr_result - the name of the default result.
sr_parameters - default params line.

Example:

procedure sr_help(host:pchar); stdcall;
var hlp:string;
begin

hlp:='sr_help=ANIMALS DEMO PLUGIN for SR v2.06.'+#13+#10+#13+#10+
'Function name: myfunc'+#13+#10+'Result key: result'+#13+#10+'Parameters:'+#13+#10+
'MEWANIMAL - the name of a mewing animal'+#13+#10+
'BARKANIMAL - the name of a barking animal'+#13+#10+
'MOOANIMAL - the name of a bellowing animal';

sr_setdata(pchar(hlp));
sr_setdata('sr_function=myfunc');
sr_setdata('sr_result=result');
sr_setdata('sr_parameters=mewanimal=cat|barkanimal=dog|mooanimal=cow');

end;

6) One dll can contain as many functions as you need. You may make them all accessible (use export).

The examples with sources are to be found in 'external' subfolder of the program.

Suggestion: if you happen to create an interesting external program that can be useful to other users of SR, contact Acritum Software support team. Your work will become accessible for downloads from www.acritum.com. Please note that your pack should contain full sources (we cannot distribute compiled plugins that may contain harmful code).

Go to the main page.