Return to the Index
<==

Creating and running programs

There are 3 stages to producing a program using OPL, the Series 3a programming language:

This chapter guides you through these stages with a simple example. If you wish to follow the example, note that each instruction for you to do something is numbered.

Note: the example programs in the first few chapters do not include full error handling. This keeps the programs short and easy to understand. But it means that when you run one of these programs and, for example, fail to type in the kind of value which the program asks for, the program may fail harmlessly stopping before it completed. As you develop your own programs, you should usually add some error handling code to them. A later chapter gives a full explanation of error handling.


Creating a new module

As well as the word program, you'll often see the word module used. The terms program and module are used almost interchangeably to describe each OPL file you say "OPL module" like you might say "Word Processor document".

Create a new module and give it a name:

1. Move to the Program icon on the System screen, and select `New file' from the `File' menu.

2. Type "test" as the name to use for this OPL module and press Enter. You will move into the Program editor.

Module names can be up to 8 characters long, like other filenames on the Series 3a. The names can include numbers, but must start with a letter.

It's always best to choose a name that describes what the module does. Then, when you've written several modules, you can still recognise which is which.

Inside the Program editor

When you first move into the Program editor you will see that "PROC :" has already been entered on the first line, and "ENDP" on the third.

"PROC" and "ENDP" are the keywords that are used to mark the start and end of a procedure. Larger modules are broken up into procedures, each of which has one specific function to perform. A simple OPL module, like the one you are going to create, consists of only one procedure.

A procedure consists of a number of statements instructions which the Series 3a acts upon. You type these statements, in order, between "PROC :" and "ENDP". When you come to run the program, the Series 3a goes through the statements one by one. When the last statement in the procedure has been acted upon and "ENDP" is reached, the procedure ends.

You can type and edit in the Program editor in much the same way as in the Word Processor, except that text you type does not word-wrap; you should press Enter at the end of each statement. Note also that the Program editor does not offer text layout features such as styles and emphases.

Note : You can use upper or lower case letters when entering OPL keywords.


An example procedure to type in

The next few pages work with this example procedure:

This procedure does nothing of any real use it is just an example of how some common OPL keywords (PRINT, PAUSE, CLS and GET) are used. (The procedure first displays "This is my OPL program" on the screen. After a few seconds this is replaced by "Press a key to finish". Then, when you press a key, the program finishes.)


Type in and edit the procedure

Before you type the statements that constitute the procedure, you must type a name for it, after the word "PROC". The flashing cursor is automatically in the correct place (before the colon) for you to do this. You can choose any name you like (with the same restrictions as when entering the filename earlier). For simple procedures which are the only procedure in a module, you might use the same filename you gave the module.

1. Type "test" . The top line should now read "PROC test:" .

2. Press " DOWN ". The cursor is already indented, as if the Tab key had been pressed.

You can now type the statements in this procedure:

3. Type "PRINT "This is my OPL program"". (Note the space after "PRINT".) Press Enter at the end of the line.

Each new line is automatically indented, so you don't need to press the Tab key each time. These indents are not obligatory, though as you'll see, they can make a procedure easier to read. However, other spacing such as the space between "PAUSE" and "80" is essential for the procedure to work properly.

4. Type the other statements in the procedure. Press Enter at the end of each line. You are now ready to translate the module and then run it.

When you are entering the statements in a procedure you can, if you want, combine adjacent lines by separating them with a space and colon. For example, the two lines:

PAUSE 80 CLS

could be combined as this one line:

PAUSE 80 :CLS

You can, of course, use the other Series 3a applications at any time while you are editing an OPL module. Use Control-Word (hold down the Control key and press the Word button) to return to the Program editor to continue editing your program.

What the keywords do when the program runs

"PRINT" takes text you enter between quote marks, and displays it on the screen. The text to be displayed, in the first statement, is "This is my OPL program".

"PAUSE" pauses the program, for a specified number of twentieths of a second. "PAUSE 80" waits for 4 seconds. ("PAUSE 20" would wait for 1 second, and so on.)

"CLS" clears the screen.

"GET" waits for you to press a key on the keyboard.


Translating a module

The translation process makes a separate version of your program in a format which the Series 3a can run.

You'd usually try to translate a module as soon as you finish typing it in, to check for any typing mistakes you've made, and then to see if the program runs as you intended.

1. Select the `Translate' option from the `Prog' menu.

Note : The `Prog' menu also has a `S3 translate' option, for translating the current program in a form which can run on a Psion Series 3 (as opposed to a Series 3a).

What happens when you translate a module?

First: the procedures in the module are checked for errors.

If the Series 3a cannot understand a procedure, because of a typing error, a message is shown, such as `Syntax error'. The cursor is positioned at the point where the error was detected, so that you can correct it. For example, you might have typed "PRONT "This is..."", or "PAUSE80" without the space.

When you think you've corrected the mistake, select `Translate' from the `Prog' menu again. If there is still a mistake, you are again taken back to where it was detected.

Note : If you've already used up almost all of the memory, the Series 3a may be unable to translate the program, and will report a `No system memory' message. You'll need to free some memory, as described in the `Troubleshooting' chapter of the User Guide, before trying again.
When `Translate' can find no more errors, the translation will succeed, producing a separate version of your module in a format which the Series 3a can run.

There may still be errors in your program at this point because there are some errors which cannot be detected until you try to run the program.

Running after translating

When your module translates successfully, the `Run program' dialog is displayed, asking whether to run the translated module. You'd usually run it straight away in order to test it.

Note : Running a module does require some free memory, so again a `No system memory' message is possible.
1. Press `Y' to run the module; the screen is cleared, and the module runs.

When the module has finished running, you return to the Program editor, with the cursor where it was before.

If an error occurs while the module is running, you will return to editing the module, with the cursor at the point where the error occurred.


File management

New OPL modules

You can create new OPL modules in the same way as new Word Processor documents. Use the `New file' option in the Program editor, or move to the Program icon in the System screen and use its `New File' option.

Your module names are listed below the Program icon. The word `Program' is shown below the icon if there are no modules at all.

The names under the RunOpl icon are those modules which have been translated successfully.

To re-edit an existing OPL program, use the `Open file' option in the Program editor, or move to the Program icon in the System screen and select the filename from the list.

Copying modules

Use the `Copy file' option in the System screen to copy modules (or translated modules). See the User Guide for full details. You can also use the `Save as' option in the Program editor itself, to make new copies of an OPL module.

Deleting modules

You can delete an OPL module (or a translated version) as you would any other file go to the System screen, move the highlight onto the file and use the `Delete file' option.

Note : If you delete all of your translated modules, the RunOpl icon will remain on the System screen, with the word `RunOpl' beneath it.

`File or device in use'

If you see a `File or device in use' error message when deleting or copying an OPL module, the file is open it is currently being edited in the Program editor. Exit the file, eg with the Delete key in the System screen, then try again.

If it's the translated file you're trying to delete or copy, `File or device in use' means that the translated file is currently running. Stop the running program by pressing Control-Calc (to go to the running program) then Psion-Esc (to stop it), and then you can try again.


More about running modules

Running from the Program editor

You can run a module at any time from within the Program editor, by selecting `Run' from the `Prog' menu. This runs the translated version of your program; if you've made changes to the module and haven't translated it again, you must translate the module again, or the changes have no effect.

`Run' displays a dialog, letting you select the name of any translated module which you want to run.

Running modules from the System screen

The names of any successfully translated programs automatically appear under a new icon in the System screen. The icon is just the word "OPL" in a speech bubble, and is called the `RunOpl' icon. It appears at the right-hand end of the list of icons (past the Program icon), and is usually off the right-hand edge of the screen. Just move the highlight onto the name of the translated program you want to run, and press Enter.

Like the Program editor, RunOpl is assigned a keypress - you can press Control-Calc (hold down Control and press the Calc button) as the short-cut to move to the RunOpl icon, whatever you're doing. (If there is a running program, this instead moves directly to it.)

When an OPL module has been successfully translated and run, you will usually run it from the System screen. While you're still editing and testing, however, it's quicker to run it from inside the Program editor. This also positions the cursor for you, if errors occur.

Stopping a program while it's running

To stop a running program, press Psion-Esc. (If you've gone away from the running program it will still be running, and you must first return to it perhaps by pressing Control-Calc and/or selecting it from under the RunOpl icon in the System screen before pressing Psion-Esc.)

To pause a running program, press Control-S. It will be paused as soon as it next tries to display something on the screen. Press any other key to let the program resume running.

Displaying a status window

A temporary status window is always available while an OPL program is running. Press Psion-Menu to see it. As you'll see, there are keywords for displaying a status window yourself.

Looking at a running program

If you translate and run a module from the Program editor, the Control-Word keypress will still return to the Program editor, even if the translated program has not finished running. A `Busy' message is shown you can move the cursor around the program as normal, but you can't edit it.

To return to the running version, select it from beneath the RunOpl icon in the System screen. It will be in bold, at the top of the list, to show that it is currently running. Alternatively, press Control-Calc.

Running more than one module

If a module is running, and you select a second one from the System screen, the first one is not replaced both modules run together, and will be in bold on the file list. Control-Shift-Calc swaps between them.


Menu options while editing

While you're typing in the procedure, all the options on the `Edit' menu such as `Copy text' and `Insert text' are available and can be used as in the Word Processor. Refer to the chapter on the Word Processor in the User Guide for more information.

The menus available are the same as in the Word Processor, except that the `Word' menu has been replaced by the `Prog' menu. The `Prog' menu has options for translating and running the current program. It also has a `Show error' option, to re-display an error which prevented successful translation, and an `Indentation' option, for setting the tab width and to turn auto-indentation on and off in the Program editor.

Unlike the Word Processor, the Program editor only ever uses one template for creating new files, called `default'. When you use the `New file' option, the `Use template' line is therefore unavailable; the new file is created using the `default' template automatically. If you wish to change the `default' template, you can use the `Save as template' option to replace it with the current file. Do not try to swap templates between the Word Processor and the Program editor.

`Set preferences' allows you to choose between bold/normal and mono/proportional text. It also has options for showing tabs, spaces, paragraph ends, soft hyphens and forced line breaks.

There is no `Password' option.

The DIAMOND (diamond) key

The DIAMOND key allows you to switch between a `Normal' and an `Outline' view of your OPL module. The `Outline' view lists only the names of each procedure, for quick navigation around the module.


SUMMARY

Move to the Program icon in the System screen and select the `New file' option.

Type in your procedure.

Select `Translate' from the `Prog' menu.

When a module translates correctly you are given the option to run it. You can run it again at any time, either with `Run' in the `Prog' menu, or directly from the RunOpl icon in the System screen.


<== Return to the Index