The Absolute Beginners Guide to OPL

P102 - OPL/16 - Looping the loop

---

These tutorials use the 16-bit version of RMR Software's excellent "RMREvent" example program, disecting it bit by bit to show you how and why it works. Make sure you've got the latest version, v1.00.

We commented last time that most of RMREvent's working life is spent going round and round the loop:

DO
  Run:
UNTIL 0

Obviously, the condition "0" (i.e. zero) is never going to equal one, true, or anything else worth evaluating, so the DO loop just carries on forever. Effectively RMREvent is saying "Run forever, handling each event as it happens". Typical events might be a user pressing a key or the system saying "Shut down now".

Let's look further at the Run: procedure:

Notice that this too is basically just one big loop. There are many ways to arrange 'event loops' and RMR's standard technique is to have the main one nested 'inside' a higher level loop. This is done so that when things go wrong (i.e. the ONERR statement is needed) things can be handled (through the GoError: procedure) and control returned to Run:'s loop via the top level one.

Each time through the loop, GETEVENT Event%() is called. Event%(10) is an array of integers defined right at the start of the main code which is destined to receive detailed information on all events detected within the running program. GETEVENT works a bit like the simple GET command in that it hangs around until there's something there (i.e. it doesn't just carry on returning zero or similar). It's also very battery-efficient, waiting with almost no battery drain at all. Contrast this with the more clumsy technique, often used by beginners, of looping round very fast, testing KEY to see which keys have been pressed.

The code within the loop is really just a list of tests of possible values that GETEVENT can return. The first few are hopefully obvious (look ahead to the appropriate procedures to see exactly what happens when each is detected):

• Check whether SIBO has sent in the special "Moved to foreground" event code, i.e. the user has selected a running instance of RMREvent from the system screen or switched to it via a hot-key or task switcher utility.
• Check whether SIBO has sent in the special "Moved to background" event code, i.e. the user has pressed "System" or another button bar icon etc.
• Check whether SIBO has sent in the special "Power on" event code, i.e. the Series 3 has been turned on. This event code is a very popular thing to check in password-oriented or novelty applications. Note that (before you ask!) there's no equivalent "Power off" event.
• Check whether SIBO either wants RMREvent to either close down or switch to a different user file.

It's the section at the end of the loop which is most interesting. Event%(1) and Event%(2) get set by GETEVENT to the keycode and the 'modifier' used. Both these two need a note of explanation:

• The keycode returned represents information on both the exact key pressed and the modifier (Control, Psion, Shift etc.) used. Note that although keycodes for most common characters are just their ASCII codes, those for special keys (e.g. the cursor keys) are not obvious and you're strongly advised to make yourself up a little 10 line program to detect key events and then print them on screen - a very handy way to find out a key's keycode when there's no manual around.
• The modifier is calculated here as Mod%=Event%(2) AND 255, a strange looking line. The AND is a logical function and can be thought of as taking the first number as a series of binary ones and zeros and then writing the second beneath it. For each digit position, unless both lines contain 'one', the result of the logical 'and' is zero. In plain english, this type of operation is called a 'mask', as it masks off all except binary digits which are stored in specific areas of the binary number. In even plainer english, this line of code simply strips off any information that's irrelevant.
  e.g.
  0011001000001010 AND
  0000000011111111 (255) equals
  0000000000001010 , which in this case tells us that Psion and Shift were pressed down during the key event. See the OPL manuals for details on the binary codes for each modifier.

Once a value for Mod% has been obtained (i.e. we know which of Control, Shift, Psion were held down during the last keypress), procedure Modify: simply sets up integer 'flags' (Control%, Shift% etc) for our convenience when considering what to do with the keypress.

Finally, the keycode itself is investigated in detail, in procedure Key:

As you can see, this section of code is nothing more than a very long list of IF...ELSEIF...ENDIF conditions. When a match is found, the program knows what to do etc. This is where you'd put the calls to your custom procedures that make up the guts of your specific program, e.g. calculate:, display:, printout: etc. or whatever your program is supposed to do.

See you next week, when we'll be looking further at hot-keys and their coexistence with a well-designed menu.