Please visit the sponsor of this series, and don't forget to say where you heard of them!
Please ensure you have the latest version (1.4) of the RMREvent example program before reading through this tutorial. If you use an older version, some of the text may not make sense.
We're continuing our walk through the RMR Event example program, having
just looked through the INCLUDEs and CONST definitions. We now come to the
first real procedure, start:, and surprisingly it's only 2 lines long! Let me
explain why...
You'll remember that when we programmed our MiLo utility we ended up
with a file ending in .OPO. Essentially, an .OPO file is just a translated OPL
module waiting to be run or called. OPL programs have for years used OPL's
LOADM (LOAD Module) command to load in extra sections of program code that
weren't already included in the main application. This is usually done for
space reasons (e.g. OPL typed in directly on the S3a/3c is limited to 32
kilobytes per file and so smaller modules are LOADed and UNLOADed as
required), or (as here) because the code in the module is from a different
source to the author of the main program and loading up a given standalone
module is the easiest way to interface the two bits together.
OPO modules are normally LOADed from the main program and
used following which control is passed back to the calling procedure. All very
sensible and straightforward. Unfortunately, something as potentially
complicated as a Series 5 toolbar requires a bit more work. Firstly there's the
fact that we need the toolbar handled by EPOC itself (so that the clock and
'open files' list still work). Secondly, Toolbar.opo requires that all its
globals be declared before any within the user program (to avoid conflicts,
just in case). The solution is one of the well-known EPOC 'tricks'. Effectively
our start: procedure loads the main Psion-produced toolbar.opo and then
executes the latter's routine TBarLink:. This in turn 'chains' control back to
the first real procedure in the RMR Event code, after which everything happens
as normal.
Don't worry too much if you don't understand exactly what's happening
here, you just need to know how to code it so that it all works. That's one of
the advantages of using Alan's example application - he's done the hard work
and enabled us to start with something that already functions properly! The
only thing you need to note for now is the parameter we pass to TbarLink:, namely
the name of the first proper procedure in our program. If this doesn't match
then obviously things will come to an abrupt halt!
Once into the main program, the first thing to do is define
all the globals needed. Although you can define GLOBALs as you go
along, at the start of the relevant procedures, it's a very messy way to
proceed as it's easy to get confused as to which variable was defined where and
whether it's valid in another routine. The simplest solution is to define all
globals right at the top and that's what RMR have done here. Don't worry about
the variables used yet, we'll tackle them as we need to in the course of
running through the program.
The two CMD$ lines are very important. Any file-based application
(i.e. one in which you can do "New file", "Open file" etc) needs to be able to
detect how it was launched and respond accordingly. The CMD$ command returns
to the program all relevant information from the system screen. CMD$(2) will
always contain the full filename to be opened, i.e. the file tapped on by the
user or the name entered in the "New file" dialog. CMD$(3) will always contain
a single letter code, which is EPOC's way of communicating with the program.
Letter code "O" means "Open", "C" - "Create" and (new to OPL for EPOC/32) "R"
(for "Resume" or "Remember"?) tells your program that it's been started from
the Extras bar and that no explicit file was specified, in which case the
program should remember and use the last file opened.
After the two lines have been executed, we now effectively have in
variables DocumentName$ and SystemCommandLetter$ the file to be opened and what to do with it.
We'll use this information in the near future to open a real file.
Go to next lesson | Programming index