The Absolute Beginners Guide to OPL

P101 - OPL/16 - Setting up

---

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.

Last time, I explored the APP...ENDA section at the top of RMREvent, showing its role in presenting the program to the Series 3 system screen. Let's now look further into the program itself. A block of seven lines of GLOBAL statements at the start sets up the variables that are needed throughout. Note that although it's possible to declare GLOBAL variables at the top of any procedure in a program, things are significantly easier to understand (and thus to sort out problems at a later stage) if the declarations are done right at the start of the main procedure. There's not a lot to say about the variable names used here, as they're all sensibly named within OPL/16's constraint of allowing only 8 characters for each.

Moving on, the lines:

File$=CMD$(2)
Cmnd$=CMD$(3)

will probably look unfamiliar to you. The first duty of a professional SIBO program after it has been launched is to find out from the operating system which document file (if any) has been requested by the user and what he or she wants done with it. The special 'command letter' that gets passed through here to an OPL/16 program will either be "C" (for "Create") or "O" (for "Open"), depending on how the user activated RMREvent. For example, the user might have done Psion-N underneath the program's icon, in which case "C" would get passed through. And of course File$ will contain the full path and file name of the requested RMREvent document.

Program$ is obvious, but Path$ needs a word of explanation. By the time you finish your masterpiece, you'll have a collection of graphics, sound, resource and help files, all of which are needed at some point by the main program. The Psion convention is to stick all of them in an \APP\RMREVENT\ directory (replace with your own program name, of course), where they'll be neatly out of the way. Rather than explicitly write out this directory name dozens of times throughout the program, it's a good idea to use a variable like Path$ instead.

Similarly for Version$ and Date$, which are far better set to variables than changed ad-hoc within the code.

The rest of the main procedure looks disturbingly brief. The key, as you'll guess, is the DO...UNTIL loop, which sits there processing keystrokes and events until the program is one day closed down. We'll look at this loop in the next tutorial. In the meantime, note the Init: procedure. There are usually so many things to do at the start of an application (setting up variables, loading in graphics, reading configuration files etc) that it's tidier to keep them all in one place. Search ahead and let's see what RMREvent does in its Init: procedure:

• The section starting Foregnd% is a special group of variables, set up to help the readability of the OPL code in the main program. Rather than use the rather obscure number codes ($401 etc) needed by OPL/16's event handling routines, RMR have decided to give them sensible names. Well, as sensible as is possible within 8 characters, anyway - thus ForeGnd% stands for 'Application has been brought back into the Foreground'. After using these english-named variables for a while, you'll appreciate the difference such a simple touch can make.

• Width% and Height% are set up as variables so that RMREvent doesn't have to rely on gWIDTH and gHEIGHT giving the right answers later on in the program. You see, these two 'g' ('Graphics') commands report on the dimensions of the current 'drawable', whatever that might be, icon, bitmap or screen window. And so to avoid possible errors, the main screen size is noted as early as possible in the program's execution.
• The section starting D$ is difficult to follow, as PARSE$ commands usually are. Even after 5 years of OPL programming, I still find myself inserting lines like GIPRINT D$ :PAUSE 30 just so that I can see what on earth is going on. In this case, the first D$ line composes a full 'path' (network device, disk name, directory and filename) based on the document file passed in by the system screen. This is usually done as a check, so that the program can be absolutely sure of the characters it can expect to find in the text string. The second line uses the character position information in off%() [returned by PARSE$] to strip off the filename, leaving just the disk name and directory in D$. Don't worry too much about all this - PARSE$ and off%() are both in the OPL manual and once you've done it once you'll end up cutting and pasting the same code into everything you write without ever giving it a second thought.
• Having established the directory where the system screen would like RMREvent to create its document, it's a good idea to check it actually exists. The quickest way to do this is TRAP MKDIR D$. Essentially we're asking for it to be created anyway, but using TRAP to stop OPL raising an error if it's already there. Many OPL commands can be prefaced by the TRAP statement and I'd recommend a read of the manual to make a mental note of all its possible uses.
• There follows another simple variable assignment. We set up plain english names for the OPL values for True and False. For example, we could then later say something like IF EXIST(File$)=Yes%, which is a lot more readable than using "-1" after the equals sign. Note that more sophisticated languages usually have special 'logical' variables which can only take the values True or False, but we'll have to make do with plain integers in OPL/16.
• Lastly, LoadCFG: loads in the saved configuration options (preferences) for RMREvent, if any exist, and Initscn: sets up the logical screen widths, a border and the type of Series 3 'status' window required on the right hand side of the screen. We may look at these procedures in more detail later on.

See you next week, when we'll be looking at Run: and the vitally important concept of the 'event loop'.