MTermRX external tasks

Considerations for operation

INTRODUCTION:

But fear not, there is a reason for this.

The MTermRX terminal window in implemented by redirecting the VDU output into the terminal sprite. Then when your external task is executed, it does anything necessary to the terminal sprite to provide "enhancements". However, when your task is executed, MTermRX and therefore the terminal sprite get paged out. All RiscOS applications believe that they start at &8000 in memory and are the only task running...

The way around this was seem as simply dumping the sprite to disc, and expecting you to load it and deal with it. The biggest con with this system is the sheer complication of the loading and redirecting code. The pros, however, outweight the cons because you can how manipulate the sprite in any way you see fit... Even as weird as doing a binary sort on it!

Provided with MTermRX are C and BASIC sources to programs that will basically load the terminal sprite, do something to it (like plot a bunch of random lines) and save the sprite for MTermRX to reload.
Simple and relatively pointless, but it does illustrate the code required. Just paste the code segments into your own application, and go from there.

You should not assume anything about the spritefile, other than the presence of a sprite called "angelachase", with the following specifications:

• MODE 12 (16 colour 1:2 ratio)
• NAME "angelachase"
• WIDTH 640 pixels
• HEIGHT 194 pixels
• PALETTE Yes, but it is ignored - Wimp palette used
• MASK No
• SIZE 62252 bytes

MTerm does have partial support for a MODE 20 (hi-res) terminal window. However, as the MTermRX text routines cannot yet handle this, you are unlikely to meet the MODE 20 sprites.
It is, however, a good idea to support them...to future-proof your external task. So below is the dimensions of the MODE 20 sprite:

• MODE 20 (16 colour 1:1 ratio)
• NAME "angelachase"
• WIDTH 640 pixels
• HEIGHT 388 pixels
• PALETTE Yes, but it is ignored - Wimp palette used
• MASK No
• SIZE 124332 bytes

1. Find out the size of the sprite file.
2. Dimension enough memory to load it.
3. Set that memory up as a sprite area.
4. Load the sprite file into the sprite area.
5. Examine the statistics of the "angelachase" sprite.

  This is an example of the Rbiorhythm task:

WHAT REALLY HAPPENS?

Briefly, what happens is:

• MTermRX receives a "SYS_ENQ" message to run your task.
• MTermRX saves the sprite to "<MTermRX$Dir>.Tasks.Screen".
• MTermRX redirects VDU output to VDU.
• MTermRX calls your task (and gets paged out).
  • Your task, now running, sets up a sprite area and loads "...Screen".
  • Your task redirects VDU output to sprite "angelachase".
  • Your task draws into the sprite.
  • Your task redirects VDU output to VDU.
  • Your task saves the sprite back to "...Screen".
  • Your task exits.
• MTermRX is paged back in. It reloads "...Screen".
• MTermRX redirects VDU output to sprite.
• MTermRX continues parsing script commands.

Sure, it is contrived... But on the other hand you can do any sprite operations you like, even replacing the sprite with another!

As long as the output sprite is physically IDENTICAL to the original, you can do pretty much anything.

ERK! THAT SOUNDS DIFFICULT!

A commented C example is given. The code is written with the minimum of extra libraries and should be quite easy to port to other languages as necessary.

Feel free to plagarise the code for your own purposes. It's a reasonably useless task that takes one CLI parameter and draws that value of random lines on the screen (min = 10, max = 250).

When your program is run, the entire command line passed as a SYS_ENQ parameter will be sent to run the task.

WHAT EXAMPLES ARE PROVIDED?

Rbiorhythm

Draws Richard Murray's biorhythm. A little example written in BASIC. Soon it will be expanded to offer the ability to draw YOUR biorhythm.

drawgraph

A simple graph plotting routine. Tasks settings as CLI parameters.

lines

An example of writing a simple external task. Source supplied.

IMPORTANT NEW ADDITION

The specifications have been updated so that MTermRX sets the system variable 'MTerm$SysEnq$Disable' to "No" before calling your task.
Your task should check this, and if it is set to "Yes", then your task should shut down without doing anything.
This is to allow some external software to control what (if any) tasks are allowed. The external software may implement your task within itself, or it may decide to override a newly downloaded task.
At time of writing, this method has not been fully coded - the system variable will always read "No". However this has been fixed in the next version of MTermRX.