Modules for Beginners

Modules, getting started

The First Module

In the last part I explained how to set up the BASIC Assembler to produce relocatable code and used it to produce a module header with title and help strings. In this part I will extend the ideas to produce some simple modules showing how to set up help strings and star commands with parameter values.

The first example called Module1 on the CD produces a module which does nothing! Well it initialises, and finalises correctly and has a title and help strings, so it will respond to *modules and *help Module1 commands. Here is the code:

A Few Notes

Do use the ON ERROR trap line, it makes debugging much simpler. Be careful with the SYS"OS_File",10 line. It must have a legal full path for the file and there are two commas between &FFA and mcode% parameters. You should find the module file appear in your chosen disc destination.

Double click on this module file, nothing should happen, your computer should work as before. Now open the Task Window (ctrl + F12). Type Modules [ret] at the star prompt. A list of the all the modules should appear with Module1 at the bottom. This shows your module has been successfully loaded and is residing in the RMA.

Now type Help Module1 [ret] The modules help message should appear with the date you assembled it. Now type *RMkill Module1 [ret] The prompt should return. Typing Modules [ret] will now show a new list which no longer contains Module1. N.B. [ret] stands for one press of the return key.

Module2 - a more useful example

This module demonstrates how easy it is to set up a star command.
The following lines are added to module1 (the full code is in the file Mod2SRC):

The pushing and pulling of registers R0 to R11 is probably an overkill but sometimes SWI's do corrupt certain registers! All thats left to do is alter the module header so the command table pointing word is changed from zero to command%.

When this module is run you should be able to do the following in a Task Window: Type either Mod2on[ret] or Mod2off[ret] and get back the help string for the command. Mod2on[ret] will give the syntax message. (RISC OS has used this message as an error since these commands do not have any parameters).

Typing *help commands[ret], this gives a list of all the modules commands loaded. Ours should be the last one in the list.
Typing *help Mod2on[ret], this should give the help message for this command.

Module3 Using parameters

The source code for this module is called Mod3SRC on the CD. This demo module is set up to accept 3 parameters for its *commands as shown below:

*newuser "name chrs" age system$variable

Rather strange but it is only a demo! The 1st parameter must be placed in quotes and can be one word or more. The 2nd parameter is typed as an integer. The third is the name of a system variable like File$Type_FFF etc.

Once this command is executed the module stores the data and then prints the message Data Accepted. Its other * commands are as follows

*modusers (no parameters)
*userdetails "name chrs"

The first one just prints out a list of the users. The second will find the data for matching the name.

The reason I chose such strange data is it shows the method of reading and transforming parameter data into a useable forms. The command block is set up as follows:

The Information word

This word holds the following:

Byte 0: The minimum number of parameters before an error will be reported. For the first command we need all 3. For the last command we only need one.

Byte 1: The way the first 8 parameters may be read by RiscOS. Each bit is used for each parameter. If set then RiscOS will try and expand the parameter as is if it is a system variable.In our example the third parameter is a system variable e.g. <File$Type_FFF> Note the use of < > to enclose the variable.

So to read this variable before it is passed to the module we need to set bit 2. Hence the (4<<8) value.

Byte 2:The maximum number of parameters before an error will occur. Hence for the first parameter (3<<16) and for the last parameter (1<<16).

Byte 3: This is rarely used, it contains flags which determine whether a string variable is a filing system command like *ADFS etc. or a star command related to *Status or *Configure.

Hence we do not use it.The full annotated BASIC source listing is on the CD called Mod3SRC.

On entering any star command routine RISCOS sets up the following registers:

R0 points to the command tail. That is the complete string of characters that make up the parameters.

R1 contains the number of spaces in the command tail which equals the number of parameters. NOTE: Any spaces contained in quotation marks are ignored.

R12 contains the memory location of the modules private word. This value is usually the pointer to the workspace.

R13 is the usual pointer to a full descending stack.

R14 holds the return address.

I use !Zap for grabbing workspace and module from the RMA for checking. This excellent routine is very powerful, I have never used all its features. You can download it from the web.

Well that is it for this time. Just for fun(!) try and add another star command to module3 called 'deluser ' which will take the name parameter only and will delete the record from the workspace, then move all records after it up by 512 bytes.