# A first program

## Contents

- Overview
- Creating a new module

- Inside the Program editor

- An example procedure to type in

- Type in and edit the procedure
- What the keywords do when the program runs

- Translating and running

- What happens when you translate a module?
- Running after translating

## Overview

This tutorial describes how to create a very small initial program using the standard EPOC Program editor. All the example does is print some text to the screen, but following the tutorial will introduce you to some of the basics of OPL.

## Creating a new module

The words 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: Click the ‘New File’ button (or select ‘Create New File’ from the ‘File’ menu).

Select ‘Program’ from the `Program` selector. 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 256 characters long (including their folder names), like other EPOC file names. The names may include any characters except `\`, `/` and `:`, and any trailing spaces or dots (.) will be stripped automatically.

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 upon which the machine acts. You type these statements, in order, between `PROC :` and `ENDP`. When you come to run the program, the statements are executed one by one. When the last statement in the procedure has been completed 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 application, except that text you type does not word-wrap; you should press Enter at the end of each statement.

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

## An example procedure to type in

Section Contents

- Type in and edit the procedure
- What the keywords do when the program runs

The next few pages work with this example procedure:

        PROC test:
              PRINT "This is my OPL program"
              PAUSE 80
              CLS
              PRINT "Press a key to finish"
              GET
        ENDP

This short procedure is 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 the screen is cleared and then `Press a key to finish` is displayed. 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 for you to do this (before the colon). You can choose any name you like within the following restrictions:

Procedure names may have up to 32 characters. The alphabetic and numeric characters are allowed and also the underscore character, `_`. The first character of any procedure name must be either an underscore or an alphabetic character.

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 the down cursor key. The text position is already indented, as if the Tab key had been pressed.
3. You can now type the statements in this procedure:
4. 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.

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 applications at any time while you are editing an OPL module.

To return to editing your program, either:

- tap on the Program icon on the Extras bar, or
- select the module’s name on the System screen, or
- use the Task List to return to the Program editor.

### 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 and running

Section Contents

- What happens when you translate a module?
- Running after translating

The translation process makes a separate version of your program in a format which the machine 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.

Select the `Translate` option from the `Tools` menu or tap the `Tran` button on the toolbar menu.

### What happens when you translate a module?

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

If the translator 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` 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 translation may be unable to complete, and will report a `No system memory` message. You’ll need to free some memory 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 machine can run.

Note: 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.

Running a module does require some free memory, so again a `No system memory` message is possible.

- 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, and the cursor will be positioned at the point where the error occurred.