Gavin Crawford

CallOPro

Call an Ovation Pro function

CallOPro provides a simple way to call a function in an Ovation Pro applet from an external task. This allows an external task to 'control' an applet, perhaps, to wake-up the applet, or it could be used to send data to an applet by calling a function that requires the data as a parameter.

How it works

CallOPro takes the string that was passed to it on the command line and wraps it up in a main() function, as if it was a small executable scrip file in memory. It is then sent (or saved) to Ovation Pro using a Message_RAMTransmit message as 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. (Should you wish to implement this transfer method in your own task a more details description can be found below.)

Using CallOpro

Run CallOPro and pass the functions you wish to call on the command line. 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 do in an Ovation Pro script file.

How you use CallOPro depends on the type of program you are using it from.

Note: In the following examples <path> is used to represent the location of where !CallOPro resides on disc. You should note that CallOPro does not set any system variables to its location, so you should set your own to point to it in your own applet or application etc.

From single tasking program - *Run

If you are using it from a single tasking program, one that doesn't register with the Wimp, such as a simple BASIC file you should run CallOPro using the *Run star command. For example:

   OSCLI("Run <path>.!CallOPro my_applet_function();"
or
   SYS"OS_CLI","Run <path>.!CallOPro my_applet_function();"  

From an Obey file - *Run

To use CallOPro from an Obey file use *Run.

   Run <path>.!CallOPro my_applet_function();
or
   <path>.!CallOPro my_applet_function();  

From a wimp task - *WimpTask or Wimp_StartTask SWI

If you are using it from a Wimp task then you need to run CallOPro as a new task using the Wimp_StartTask SWI or the star command *WimpTask.

   SYS"Wimp_StartTask",".!CallOPro my_applet_function();"
or
   OSCLI("WimpTask .!CallOPro my_applet_function();"  

Also note, that CallOPro is not restricted to calling just one function, but make sure you 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, and type the text 'hello world' at the current caret position. OK, so it's not very useful but it shows how more than one function can be called, and how data can be passed to script functions, in this case a string. 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

If your external code runs as a task by registering with the Wimp then it's probably better to handle the whole transfer protocol yourself. But if your code runs as a single tasking program 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.


[detailed description]

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.


New version coming soon