CallOPro

Call an Ovation Pro function

CallOPro provides a simple way to call an Ovation Pro script language function from an external task. The function can be either one of the built-in functions or one provided by an additional applet. This allows an external task to 'control' an applet, perhaps to wake-up the applet to start an event or maybe to pass it some data by calling a function that requires that data as a parameter.

How it works

CallOPro is a small stand-alone application that takes a text string passed to it on the command line. This string takes the form of the Ovation Pro function to be called. It is wrapped it up in a main() function, as if it was a small executable Ovation Pro scrip language file in memory. It is then sent (or rather, saved) to Ovation Pro using a Message_RAMTransmit message (part of the Data transfer protocol). Ovation Pro receives this as if the script file had been dragged to its iconbar icon. Upon which the script file is executed by Ovation Pro, thereby calling the function.

Using CallOpro

How you run CallOPro depends upon the type of program/environment you are calling it from - it mainly depends on whether or not you are using it from a multitasking application. The different methods of using it are fully outlined below, but in general it is simply a matter of passing the Ovation Pro function(s) you wish to call to CallOPro like so:

CallOPro function()

CallOPro will automatically add a semicolon to the end of the string supplied if it does not already have one, but if you are calling more than one function then they should be separated by a semicolon as you would normally do when using the Ovation Pro script language, eg: CallOPro function1();function

Note: In previous releases of CallOPro (prior to version 1.03) no path variables were set up and you had to run the CallOPro program by including a full filepath to its stored location. This has now changed as I decided it would be easier to use if some system variables were preset. As long as the CallOPro application has been seen by the filer (Filer_Booted) then the system variables will become active. This also means that single version of !CallOPro could be placed alongside the Ovation Pro transloaders or even in !Boot.Resources and be readily available whenever needed.

Ways to use CallOPro

CallOPro sets some alias *command style system variables that provides a simple way to use it from different environments, as well as setting a system variable to point to it's file location to aid in running the from other programs.

Below I've listed some examples of different ways to use CallOpro depending upon where you are using it.

• Obey files

  From an Obey file you can use the alias *command CallOPro which will use *Run to invoke the application.

  eg: CallOPro function()

• TaskWindow

  Using from a TaskWindow is slightly different in that you are in a MultiTasking environment so calling another application using *Run will cause an error. In a TaskWindow you can use the other alias *command CallOProMT. This will run the CallOPro application from a Multi Tasking environment (hence the MT at the end of the command) as a separate WIMP task. eg:

  CallOProMT function()

• A Multi Tasking application

  An application that is registered with the WIMP can also use the alias command CallOProMT so that a separate WIMP task is started when the CallOPro application starts up.

  For example an application written in BBC BASIC could use either of the following:

  SYS"OS_CLI","CallOProMT function()"
OSCLI"CallOProMT function"
*CallOProMT function()
  

  If your application wanted to use the SWI Wimp_StartTask directly it could use the following:

  SYS"Wimp_StartTask","<CallOPro> function()"

  Notice here the system variable '<CallOPro>' which is a short cut to the !CallOPro path location.

• A Single Tasking BASIC file

  In the situation where you may have a simple BASIC file acting as a single tasking script file, things get a little more complicated. If you use *CallOPro (or one of the alternative OSCLI / SYS"OS_CLI" variants) then when this line is executed the CallOPro application is run, but it will replace your BASIC file in memory, so nothing else past that line will get executed. You can't use the CallOProMT multi tasking version as your BASIC script is not registered as a WIMP task so an error will occur.

  There are two ways to get around this problem. The first, is to register with the WIMP at the start of the BASIC code, then it a simple matter of using the CallOProMT variant as described above under "A Multi Tasking application"

  To do this it is a simple matter of adding the following at the start of your code:

  SYS"Wimp_Initialise",310,&4b534154,"temp",0

  then at the end of your code add the following line, which does the job of de-registering:

  SYS"Wimp_CloseDown":SYS"OS_Exit"

  The second way, which involves less work, but is more limited, is to use the *Filer_Run command to start CallOPro. *Filer_Run has the advantage that it is queued-up and will only be activated AFTER the BASIC script has completed and quit, so it doesn't suffer from replacing the original BASIC file in memory. There are however, a few disadvantages. As it is queued and run afterwards it is only suitable when the BASIC file needs to issue one CallOPro command, and when it doesn't matter when that happens. In other words, the timing of events of other actions in the code doesn't matter. The other problem with *Filer_Run is that is doesn't allow a command tail string to be passed to the application, which rather defeats what CallOPro is doing. So to get around this, if CallOPro is invoked without a command line string being passed to it, it will look to use a special system variable of <CallOPro$String>. So what that all means, is to use it with *Filer_Run you would do the following:

  *Set CallOPro$String function()
*Filer_Run <CallOPro>
  

  or using SYS calls:

  SYS"OS_CLI","Set CallOPro$String function()"
SYS"OS_CLI","Filer_Run <CallOPro>"
  

  Afterwards CallOPro will unset the system variable so it is cleared before CallOPro is run again.

Further Notes on using CallOPro

CallOPro is not restricted to calling just one function, but you must make sure to include a semicolon after each function as CallOPro can only add one to the end of the string (if the string needs one). Remember that CallOPro wraps up the string supplied to it in a main() function to produce a standard Ovation Pro script file.

For example, if you pass snaptogrid();type("hello world!") as the string, CallOPro takes the string and adds a semicolon to the end, because it does not already have one. It then wraps it up in a main() function and sends it to Ovation Pro. The script file that Ovation Pro receives is as follows:

void main(void){snaptogrid();type("hello world!");}

This would snap the selected object to the grid (if it can be), and type the text 'hello world' at the current caret position. Note that the type() function enters the string at the current caret position, so this example would only work if a document is open with the caret in a text object.

Limitations

Firstly, the Data transfer protocol message is only passed to Ovation Pro's iconbar icon, not to any open document windows. So specifying which document view receives the function call is not possible.

Secondly, the length of the string that can be passed to CallOPro is limited by the maximum allowed length of the command line. As the full path to CallOPro is also included in the command line string when it is run, the actual length left for the functions you are calling is dependent upon the length of CallOPro's pathname and which version of RISC OS is being used. If a lot of data needs to be passed to Ovation Pro then the !SendOPro utility should be used - this does a similar job but instead of passing the data in memory, it sends a file on disc to Ovation Pro.

Why use CallOPro

CallOPro is intended to be a simple 'helper' app. If your external code runs as a full task by registering with the WIMP itself then it is probably better to handle the whole transfer protocol yourself. But if you just need to add the facility to some simple code or an Obey file then using CallOPro will allow you to send data to Ovation Pro in an easy way without you having to write the transfer methods yourself.

Should you wish to implement this transfer method in your own task then this is a more detailed description of what happens.

CallOPro takes the command line string tail and adds a semicolon to the end if the string doesn't already have one. It then finds the task handle of Ovation Pro, and checks through the icons on the iconbar until it finds the one belonging to Ovation Pro. Now it has a window and icon pair to send a message to (the window is -2 for the icon bar, the icon is the one it just found on the iconbar). After wrapping up the command string in a main() function, CallOPro next sends a DataSave message to Ovation Pro's iconbar icon, to which Ovation Pro responds with a RAMFetch message. Upon receiving the RAMFetch message, CallOPro transfers the data to Ovation Pro and quits.