THE ORGANISER SCIENCE PACK

The Psion Organiser and the plug-in Program Packs and Datapaks form a sophisticated pocket computer system containing digital electronic components. They have been designed for ease of use, but to ensure that you make me most or their capabilities we suggest that you read this booklet, in conjunction with your basic Organiser handbook.

To avoid any possible damage, your organiser, Program Packs and Datapaks should not be exposed to extremes of temperature or humidity. Do not subject them to hard knocks or excessive force, nor immerse in liquids or use volatile fluids when cleaning the case.

If within 12 months or purchase this Program Pack
can be shown to be faulty, Psion will (at the option
of the purchaser) refund the purchase price or
replace the Program Pack. All other liability arising
from any error, defect or failure or the Program
Pack is excluded, including incidental or
consequential damage or loss.

This does not affect your statutory consumer
rights.

(C) PSION PROCESSORS LTD 1984

DESIGN REGISTRATION APPLICATIONS

NOS. 1019736 AND 1019737

PATENT APPLICATION NO. 8412628

- INTRODUCTION

Introduction; RUN; CAT; PROG; COPY; example - SCIENCE AND MATHS FUNCTIONS

List of extra mathematical functions and utilities; using functions. - SCIENTIFIC CONSTANTS

List of scientific constants; cgs and SI units; using constants. - CONVERSION OF UNITS

cgs, SI and imperial units - SCIENTIFIC FORMULAE

Available formulae; evaluation In 'RUN' or 'CALC'. - POLYNOMIAL EQUATIONS

Quadratic and higher order polynomial equations; real and complex roots - LINE-FITTING

LINE program — least squares fit - INTEGRATION

INTEGR program — area under a curve. - POPL — PROGRAMMING

Introduction; writing a program; programming activities; PROG, EDIT, INSRT, QUIT, EXIT, SAVE, ERASE. - VARIABLES, INPUT, OUTPUT

Variables; IN statement; OUT statement. - GOTO — LABELS, BRANCHING

Branching: GOTO statement; line labels - CONDITIONS — IF STATEMENT

Conditional statements: IF then GOTO; AND, OR, NOT. - LOOPING AND ITERATION

Forming loops with IF and GOTO. - GLOBALS AND ARRAYS

Local and Global variables; Arrays with STORE and RECALL. - CALLING PROCEDURES

How to use procedures within procedures; passing parameters. - ERROR MESSAGES
- TROUBLESHOOTING
- WARRANTY

INTRODUCTION

In the box containing this manual you will find a program pack for the Organiser. The external physical construction is identical to that of a datapak and it plugs into your Organiser in exactly the same way. Remove the datapak or dummy pak from one of the solid-state drives of your Organiser by pulling on the knurled outside of the pak. Now insert the Science Program Pack in the empty slot in the normal way.

The Science pack is a substantial software system which turns the Organiser into a powerful tool for scientific analysis. It contains a series of widely applicable science constants, a range of unit conversion functions, and a selection of programs or 'procedures' designed for application to common scientific problems such as Bohr energy levels, plasma frequency, the period of an LC circuit, or fitting a line to experimental data. It also contains a comprehensive list of mathematical functions which are automatically added to the calculator and may also be used in programs.

However, most importantly it has been designed as a potent means of customizing the Organiser to your own specific needs and requirements. This is achieved by the provision of a simple and easy-to- use programming language in which you may write your own programs or procedures, save them permanently on your datapaks, and reuse them whenever you need them for commonly occurring problems that you deal with in your work or at home. The Organiser is a complete pocket computer, and the programming language POPL allows you to apply it to your specific problems.

Once the program pack has been inserted into one
of the solid-slate drives of the Organiser, the range
of available activities is automatically extended.
Switch on the Organiser and press the
**MODE/HOME** key. In the basic Organiser, without
a program pack, the normal activities available
would be 'ENTER', 'CALC', 'OFF'. With the program
pack inserted, you will find additional activities
have been provided —— press **MODE/HOME**
repeatedly to view them. These additional
activities are 'PROG', 'CAT', COPY' and 'RUN', and
they perform the following functions.

To run a program or procedure, select 'RUN', type
its name and press **EXECUTE**. The procedure or
program must either be one provided in the
program pack or one that you have stored in the
datapak currently fitted.

'CAT' is used to list or find procedures from the
program pack or from the currently-fitted datapak.
It operates on procedure names in exactly the
same way as 'FIND' operates on records made
with the **SAVE** key.

Input a search clue in 'CAT' and press **EXECUTE**
and the Organiser will retrieve all program or
procedure names which include the search clue.
For a list of every program and procedure name
simply leave out the search clue and press
**EXECUTE** repeatedly — the Organiser will list the
programs and procedures from the program pack
first and then any in an attached datapak.
(Incidentally, some of the procedures you find this
way are specifically for use within others and
cannot be run independently.) When a procedure
has been found by executing 'CAT', the Organiser
will retain that procedure or program in temporary
storage so that you may go on to use it directly in
'RUN', or 'CALC'.

'PROG' is the Organiser activity for writing, editing, and saving your own procedures or programs. 'PROG' itself contains a menu of activities. These and the use of 'PROG' are described in detail in Chapter 9 and need not concern us now.

'COPY' is a utility which allows you to copy the
entire contents (All), or the records (Records), or
the procedures (Procedures) of one datapak to
another. 'COPY' always copies from the datapak in
drive 1 (the one nearest the display window) to the
datapak in drive 2. When **EXECUTE** is pressed in
this activity, the organiser instructs you to insert
the datapaks. Remove the program pack and slot
the datapak from which you wish to copy into drive
1 and an empty or newly-formatted datapak into
drive 2 (You don't need to switch off first, but if you
do, 'COPY' will still be available when you switch
on again.) Next, press **EXECUTE**: the 'COPY'
utility will ask you whether you wish to copy the
entire contents (All), or records of information
(Records) or procedures (Procedures) only. Press
A, R, or P. The Organiser will now copy from the
datapak in drive 1 to the datapak in drive 2
according to your instructions, and leaving out all
erased records or procedures.

To demonstrate how simple it is to use the
Organiser's Science program pack, we shall find,
run and list a procedure. With the program pack in
drive 1, press **ON/CLEAR** and use the
**MODE/HOME** key to select 'CAT'. Now type in the
letters BOH and press **EXECUTE**. The Organiser
will automatically find the procedure called BOHR
and the name will be displayed.

The BOHR procedure is one of the scientific procedures on the program pack and evaluates the Bohr energy levels of an atom given the atomic number and the principal quantum number of the level concerned.

Press the **MODE/HOME** key until the activity
changes to 'RUN'. The program name 'BOH' will
still be shown to the right of the 'RUN:' indicator.
Press **EXECUTE** to run the program.

The Organiser will now prompt you for the atomic
number of the atom concerned. Enter a number
and press **EXECUTE**. The Organiser will now ask
you for the principal quantum number. Enter the
number of the level concerned (the display
automatically comes to rest when you start typing)
and press **EXECUTE**. The Organiser will evaluate
the Bohr energy of that level and display the result
in Joules. If you are only interested in that
particular energy level of the atom, press
**ON/CLEAR** to return to 'RUN'. If you wish to find
other Bohr energy levels for the same atomic
number, press any other key except << or >> then
enter another quantum number in response to the
prompt, and press **EXECUTE**. Entering a negative
quantum number ends the procedure and makes it
return the previous result tor this run or a zero
result if no positive quantum number has yet been
entered.

Alter you have run this procedure as described
above, you may wish to read how it is written in the
Organisers own programming language — POPL.
Press the **MODE/HOME** key until 'PROG' is
displayed. Now type **BOHR** and press **EXECUTE**.
The activity indicator changes to 'EDlT:', and the
first line of the procedure appears to its right.
Press the **FIND** key, and you will see the next line
of the procedure. This effect is the second function
of the **FIND** key, (only applicable in 'PROG') and is
indicated by the blue arrow below the key. Keep
pressing the **↓** key to see each line of the
procedure in turn. Do not worry at this stage about
the meaning of each of the lines. They are
described in detail in chapters 9-15. When you
wish to leave 'PROG', press the **MODE/HOME** key
until either of the indicators 'QUlT' or 'EXIT'
appears, and press **EXECUTE**.

We have seen how to find programs or procedures, how to recall them and run them, and we have peeked into the language itself. The power of the Organiser has been hugely advanced through the Science program pack. The chapters below describe all the scientific procedures supplied in your program pack and describe how to write, and save for repeated use, your own procedures. The program pack has also, however, enhanced the power of the calculator activity 'CALC', by a wide range of mathematical functions. These and their use are described in Chapter 2.

SCIENCE AND MATHS FUNCTIONS

When the Science pack is attached to the Organiser through one of the solid-state drives, a comprehensive range of mathematical functions automatically becomes available in CALC. Any of these functions may be used in everyday calculations simply by typing its name with a numerical argument or arguments (i.e. the number or numbers on which it is to operate) They may also be used with numbers or variables in programs (see Chapters 9-15). They are listed below under the abbreviated names which the Organiser recognizes. The number of arguments, or parameters, each one requires is shown below in parentheses.

**
Note that all angles are measured in radians
except for the purposes of the conversion
functions DEG and RAD.
**

LOG | (1) | Log to the base ten of the given number. Input must be greater than zero. |

ALOG | (1) | Antilog. The result at raising ten to the given power. |

LN | (1) | Log to the base e where e = 2.7183 corrected to four decimal places. Input must be greater than zero. |

EXP | (1) | Exponential value. Raises e to the given power. |

SQRT | (1) | Square root. No negative values accepted. |

SIN | (1) | Sine of an angle |

COS | (1) | Cosine of an angle |

TAN | (1) | Tangent of an angle. Organiser registers an error if the angle yields an infinite tangent, e.g. PI/2 radians (90 degrees), 3PI/2 rads, 5PI/2 rads, etc. |

ASN | (1) | Arcsine. The angle whose sine, which must lie between -1 and 1, is given. |

ACS | (1) | Arc cosine. The angle whose cosine, which must lie between -1 and 1, is given. |

ATN | (1) | Arctangent. The angle whose tangent is given. |

ABS | (1) | Absolute value. Converts a negative number to a positive one. e.g. ABS(-5)=5. |

INT | (1) | Integer value. Rounds down to whole number. e.g. INT(1.8451)=1 |

DEG | (1) | converts radians to degrees. |

RAD | (1) | Converts degrees to radians. |

MOD | (2) | Modulo. Calculates the remainder after dividing the first parameter by the second. e.g. MOD(20,8) is translated into 20-8*INT(20/8) which works out as 4, so that MOD(20,8)=4. The second parameter must not be equal to zero. |

SINH | (1) | Hyperbolic Sine. e.g. SINH(5) returns the result of (EXP(5)-EXP(-5))/2. |

COSH | (1) | Hyperbolic Cosine. e.g. COSH(5) returns the result of (EXP(5)+EXP(-5))/2. |

TANH | (1) | Hyperbolic Tangent. e.g. TANH(5) returns the result at SINH(5)/COSH(5). |

MIN | (1 to 42) | Minimum. Finds the smallest of the values given. |

MAX | (1 to 42) | Maximum. Finds the greatest of the values given. |

FAC | (1) | Factorial e.g. FAC(5) is 5*4*3*2*1, so that FAC(5)=120. Input must lie between zero and 69. |

SGN | (1) | Sign. Looks at the sign at the given number. Its result is +1 if the number is positive, -1 if it is negative, and zero if it is zero. |

ROUND | (1) | Rounds input to nearest integer, (0.5 is rounded up) |

MEAN | (1 to 42) | Calculates the mean of the input values. |

STDEV | (1 to 42) | Standard Deviation (n-1 basis) of the input values. |

PI | Needs no parameters. Produces the value of the Constant pi. which is 3.1416 (corrected), to be used in calculation like any other number. | |

** | (0) | Simply type two multiplication signs together to call this operation. Raises the number to its left to the power given by the number to its right. e.g. 3**2 = 9. |

RND | (2) | Random number generator. Returns a random number in the range bounded by the two inputs, inclusive or the greater but excluding the lesser. For instance, RND(5,20) may produce any number from 6 to 20 inclusive. These random numbers are random in terms of distribution, but actually depend on a mathematical formula. |

RAND | (1) | Randomize. Sets the starting value for the formula which generates random numbers. This determines the series of random numbers that will result from subsequent uses at RND. For example, an input RAND(2) always results in the same series at random numbers, which is different from that resulting from say RAND(4). RAND(0) results in an arbitrary starting value for the random number generator, and will give a different series every time. |

ENG | (1) | Engineering Format. Sets format of output to a number between 1 and 999 times 10 to a power which is a multiple of three. For example, 0.56 is expressed as 560 E-3. and 56780000 as 56.78 E6. To set this format on, type in ENG(1) and press EXECUTE. To set it off type ENG(0). The current setting is active even when running procedures unless your procedure contains a statement to override it. |

FIX | (1) | Sets the number of places after the decimal point for any subsequent output. A negative input with FIX clears the last setting leaving the number of decimal places open. |

NOTE — Both ENG and FIX return their previous status as a result. | ||

GETKEY | Results in the ASCII code value of the next key pressed. Needs no parameters. |

**
Don't forget, you can add to the functions your
Organiser can carry out, by writing your own
procedures.
**

First select 'CALC' Now type the name of the
function you want to use, followed by the correct
number of parameter values enclosed in brackets
Press **EXECUTE** to calculate the result.

A parameter value can be a number or the name of a function or procedure which results in a number. When you need to enter two or more parameters you should separate each one from the next by a comma, e.g.

MIN(7,9,4,PI,2,10)

Functions can be linked by arithmetical operators, just as numbers in a basic arithmetical calculation, so that calculations such as:

COS(PI/3) * (SIN(2*PI)+ LN(2))-15/2 * COS(10)

are well within Organisers capabilities.

An outstanding feature of the program pack is that it allows you to do calculations which use the result of one function or procedure as a parameter value for another. This facility also means that calculations may consist of functions stacked within each other like a set of Chinese boxes. For instance:

DEG(ASN(4/(SQRT(9+16))))

Later, when you write your own procedures, you will be able to stack them up in the same way, combining them, if you wish, with the ready-made functions.

SCIENTIFIC CONSTANTS

The Science program pack contains a comprehensive list of the fundamental scientific constants expressed in both cgs (centimetres, grams, seconds) and SI (metres, kilograms, seconds) units. These constants are held as functions or procedures in POPL so that their values me be used automatically in calculations in 'CALC'. They may also be used by their names in your own programs or procedures. They can be listed or 'found' using the 'CAT' activity, and are documented in the programming activity 'PROG'.

The constants are available in both cgs and SI
units. Their names consist of the common
scientific abbreviation for the constant, with the
prefix C for cgs units or K for SI units. Thus for the
speed of light expressed in cgs units you would
type **CC**, and to express it in SI units, type **KC**.
Both versions of each constant are listed below.
There are no parameters.

To display the value of a constant, type its name in
'CALC' or 'RUN' and press **EXECUTE**.

cgs | SI | |
---|---|---|

CC | KC | speed of light in vacuo |

CE | KE | electron charge (electrostatic cgs units apply) |

CME | KME | electron mass |

CMP | KMP | proton mass |

CMH | KMH | mass of a hydrogen atom |

CK | KK | Boltzmann's constant |

CH | KH | Planck's constant |

CG | KG | Gravitational constant |

CMU | KMU | Permeability of free space (electromagnetic cgs units apply) |

CEPS | KEFS | Permittivity of free space (electrostatic cgs units apply) |

CS | KS | speed of sound at sea level in air at 0°C. |

CNA | KNA | Avogadro's number |

CF | KF | Faraday's constant (electrostatic cgs units apply) |

CRY | KRY | Rydberg constant |

CA | KA | Bohr radius |

CR | KR | Gas constant |

CVM | KVM | Volume of 1 mole of ideal gas at STP |

CAU | KAU | Astronomic unit |

CER | KER | Earth's radius |

CEM | KEM | Earth's mass |

CEG | KEG | acceleration due to gravity at the surface of the earth. |

CFP | KFP | ice point (0°C) in Kelvin |

CZ | KZ | Intrinsic impedance of free space (electromagnetic cgs units apply) |

CONVERSION OF UNITS

A range of functions are included in the Science pack to convert common British and American or cgs units to Standard SI units. All of these functions take one argument or parameter. The numerical argument specifies the value in non- standard units and the result of the function is expressed in SI units. The functions may be called or executed In 'CALC' or they may be used in POPL programs or procedures. They are listed below with the number at arguments in parentheses. Executing each of the functions with the argument set to 1 returns the conversion factor

INCH | (1) | returns a value in metres when the argument is given in inches. |

FOOT | (1) | returns a value in metres when the argument is given in feet. |

MILE | (1) | returns a value in metres when the argument is given in miles. |

LB | (1) | returns a value in kilograms when the argument is given in pounds. |

LBF | (1) | returns the value in newtons of an argument given in pounds weight. |

HP | (1) | returns a value in watts when the argument is given in horsepower. |

BTU | (1) | returns the value in joules of an argument given in British Thermal Units. |

CAL | (1) | returns a value in joules when the argument is given in calories. |

FAHR | (1) | returns a value in degrees Centigrade when the argument is given in degrees Fahrenheit. |

ATM | (1) | returns a value in newtons per square metre when the argument is given in atmospheres of pressure. |

ESU | (1) | returns a value in coulombs when the argument is given in electrostatic units of charge. |

EV | (1) | returns a value in joules when the argument is given in electronvolts. |

GAUSS | (1) | returns a value in tesla when the argument is given in gauss. |

SOME SCIENTIFIC FORMULAE

With the Science pack, the Organiser allows you
to customise your datapaks with formulae and
functions commonly used in your work. There is a
vast variety of scientific and engineering formulae
in many different applications. Using POPL you
can define and save your own formulae. By way of
illustration, a few examples of such formulae are
included in the Science pack as POPL procedures.
To use in particular formula simply type its name in
'CALC' or 'RUN' and press **EXECUTE**. These
procedures may also be found through 'CAT'.

The procedure prompts the user for the focal
length of the lens and for the distance of the object
from the lens. In response to each prompt, type
the appropriate number and press **EXECUTE**. The
procedure evaluates the distance of the image
from the lens. A negative value suggests a virtual
image.

It is assumed that the compound lens is made of
two simple lenses. When you use FOCAL, you are
asked for the focal length of the first lens. Enter a
positive (convergent lens) or negative (divergent
lens) number and press **EXECUTE**. Respond
similarly to the prompt for the second lens. The
focal length of the compound lens will be
evaluated and displayed.

LC evaluates the period in seconds of the natural
oscillations of a simple inductive and capacitative
circuit. In response to the Organiser's prompt, type
the numerical value of the inductance in henries
and press **EXECUTE**. Similarly, enter the
capacitance in farads. The answer is the period in
seconds.

This procedure evaluates the Bohr energy levels of
an atom with atomic number Z for various principal
quantum numbers n. Execute the procedure in
'RUN' or 'CALC'. Enter an integer number for the
atomic number of the atom. You will be asked
repeatedly for the principal quantum number of the
energy level concerned. Type a positive integer
and press **EXECUTE**, and the energy value will be
dl splayed. Press **ON/CLEAR** or enter a negative
number to exit from the routine.

This procedure asks you for principal quantum
numbers of the upper and lower energy levels and
the effective (screened) atomic number of the
atom. Press **EXECUTE** alter entering each
number. The resulting display is the frequency of
the line spectra in Hz.

The LARMOR procedure asks you for the strength of the magnetic field in tesla. The angular frequency in radians per second is displayed.

This formula evaluates the plasma frequency of an
ionised electron gas of density n_e, in radians per
second. You will be prompted for the electron
density in particles per cubic centimetre. Enter a
positive number and press **EXECUTE**. Remember
you can use the EE key to raise the number to the
required power of 10.

This procedure evaluates the separation of the
atoms or scattering centres in a lattice for
successive orders at diffraction, given the
wavelength of the light and the angle of the
scattered light. Enter the wavelength of the light in
Angstroms and the angle of diffraction in degrees,
pressing **EXECUTE** each time. The separation
distance for the first order diffraction is displayed
in Angstroms. Press **EXECUTE** to get the result for
the next diffraction order, and so on. Press
**ON/CLEAR** to escape.

POLYNOMIAL EQUATIONS

The Science pack contains two procedures for obtaining the roots of polynomial equations with real coefficients. They are QUAD, for the simple case of quadratic equations, and POLY for polynomials of higher degree.

Type QUAD in 'RUN' or 'CALC', and press
**EXECUTE**. The quadratic equation has the form
ax2 + bx + c = 0. You will be prompted for the
values of a, b and c. Enter the number and press
**EXECUTE** in each case. If the roots are real, the
first one will be displayed, followed by the other
when you press **EXECUTE** again. If the roots are
complex, they will be a conjugate pair of the form
p+iq and p-iq. In those cases you will see "p"
first, and must press **EXECUTE** again to see "q".
Press **EXECUTE** again to end the procedure.

POLY is a set of procedures which use the quotient
difference method to obtain the roots of
polynomials if higher degree by iteration. When
you use POLY in 'RUN' or 'CALC' you will be asked
for the degree of the polynomial. Enter a number
between 3 and 6. The Organiser will now prompt
for the coefficient of each power of x, starting with
the coefficient of the highest power. All
coefficients are assumed to be real and non-zero
Enter the value of each coefficient, pressing
**EXECUTE** after each one.

When you have entered all the coefficients, POLY
will carry out three iterations and print the
resulting approximate roots. The value of each root
will be followed by the associated error. Always
press **EXECUTE** to see the next number.

When all the values have been displayed, the
program will ask whether you wish to carry out
further iterations for greater accuracy. Enter 0 if
you are satisfied, or a number from 1 to 5 for the
number of further iterations. Press **EXECUTE**.

The roots displayed so far are real. If the error of a
particular root is not converging to zero, it implies
that the root is one of a pair of complex conjugate
roots. In that case, when you press **0** and
**EXECUTE** to end the iterations. POLY will ask
whether you want the complex roots evaluated.
Type **0** for yes or **1** to escape. and press
**EXECUTE**. If yes, POLY will now evaluate the first
complex conjugate pair. You will see the real part
first and then, when u press **EXECUTE** again,
the imaginary part. Keep pressing **EXECUTE** to
see the real and then imaginary parts of any
remaining complex conjugate roots.

The solution of polynomial equations is a sophisticated task and relies on the problem being well defined. There are many cases where solutions are ill-behaved. In these cases the iteration will result in an error or in non- convergence. Then, the properties of the particular polynomial equation should be scrutinized and the applicability of any underlying physical model should be re-examined.

LINE — For Line-fitting

In many experiments, an attempt is made to fit
empirical data to a straight line. Assuming an
independent variable x and a dependent variable y,
there will be a finite set N at data points (x_{i}, y_{i}). The
Science pack contains a program called:
LINE which finds the best straight line through
this empirical data by the method of least squares.
The principle behind this method is to minimise the
sum of the squares of the errors between the
empirical data and the 'theoretical' straight line.

The theoretical line is assumed to have the form:

y = ax + b

The coefficients a and b are determined by the formulae:

s_{0} t_{1} - s_{1} t_{0} | ||

a | = | ————— |

s_{0} s_{2} - s_{1}^{2} |

s_{2} t_{0} - s_{1} t_{1} | ||

b | = | ————— |

s_{0} s_{2} - s_{1}^{2} |

where

s_{0} = N+1

s_{1} = sum(x_{i})

s_{2} = sum(x_{i}^{2})

t_{0} = sum(y_{i})

t_{1} = sum(x_{i} y_{i})

When you RUN or CALC the LINE program, it will
ask you for the number of data points to be
entered. Enter the number of points and press
**EXECUTE**. The program will prompt for the x
coordinate of the first point. Enter the number and
press **EXECUTE**. The program will then prompt for
the corresponding y value. Enter the number and
press **EXECUTE**. Enter the x and y values for all
the points in this way. When all the points are in,
the program calculates and displays the value of
the coefficient a. Press **EXECUTE** to see the value
of the coefficient b.

INTEGR — For Integration

The program INTEGR determines the integral
under a curve defined by a set of points. The curve
has the form y=f(x) and the area bounded by y=0,
x=x_l, x=x_h, and y=f(x) is determined. Run the
program by typing INTEGR and pressing
**EXECUTE** in 'RUN' or 'CALC'. The program will
prompt for the lowest x value x_l. and the highest x
value x_h, respectively. Enter each value and press
**EXECUTE**. You will then be asked for the number
of points on the curve. Up to twenty points are
allowed. Enter the number of points, and press
**EXECUTE** — the points on the curve are assumed
to be equally spaced, with a point at each end.
Next you will be prompted for each of the
corresponding y values in turn. Press **EXECUTE**
alter typing each value. When you have typed the
last y value and pressed **EXECUTE** the integral
will be evaluate and displayed.

Note that a y value can be a number or any valid function of x which returns a number, including procedures you have written yourself using POPL.

Examples: **10; 20*(SIN(SQRT(X))); 3*(X+2);
PROC(X)**, where PROC is a procedure which accepts
one parameter, such as **=SIN(P1)+PI**2**. (see
chapters 9 to 15 for details about writing procedures).

POPL — Programming Your Organiser

Programming your Organiser is as simple as all of the other Organiser operations, and yet enables you to perform sophisticated and complex tasks tailored exactly to your requirements. This is achieved with the Psion Organiser Programming Language (POPL) — a unique language which takes full advantage of the Organiser's ability to make things simple.

As with all Organiser operations. the line is still
the base unit of information, but with POPL you
can string together lines of instructions as a
sequence of steps for the Organiser to follow. A
complete series of steps is defined as a
**procedure**, and is given a unique name so that
you can save, recall, calculate, run and edit it.
Procedures are the building blocks in Organiser's
modular programming language, and they can be
combined, cross-referenced and generally used in
a flexible manner to produce a sophisticated
program.

Even the most complex and ambitious task can be split down into a series of manageable elements using this approach.

First, decide exactly what you want your procedure to accomplish. Then examine the task in detail to establish what steps are necessary to complete it. If it is very complicated, break it down into manageable sections, and tackle each one separately. Each section can then be a procedure in its own right with a unique name.

As a first step in writing a procedure it is often useful to split the task into three parts; data you need to feed in; how it is to be processed; and data you want to get out. It is then easier to think clearly and logically about the detail of the procedure.

When you are deciding on the steps which will
make up the procedure, remember that computers
rely entirely on our instructions, which they
follow in the order of occurrence. The Organiser is
designed to point out many possible mistakes. but
it cannot supply instructions which you omit, or
decide that although you have written one thing
you really mean another! So, always be sure to
include, * in strictly logical sequence*, every
action involved in performing the task, not
forgetting to make provision for the Organiser to
read in any necessary information. Whenever you
write an instruction, consider what must be done
before it can be obeyed, and check that previous
instructions make the necessary provisions.

The programming activities on the Organiser are
grouped in the activity 'PROG', so the first step is
to select 'PROG', using the **MODE/HOME** key.
This tells Organiser that you want to write a new
program or procedure or access an existing one
in order to edit, save or erase it. Now press
**EXECUTE** to show you are serious, Organiser will
briefly display the message "ENTER PROG
NAME" and then revert to the 'PROG:' indicator
and wait. Type in any procedure name, e.g.
TEMPCONV1 and press **EXECUTE**. Note that
procedure names must begin with a letter and
contain between 2 and 16 characters. The name
may contain numbers but spaces and
mathematical operators are not allowed in
procedure names.

If it is a new procedure, Organiser displays "NEW PROCEDURE" briefly, then selects 'EDIT' and gives you a new line ready for the first step in your procedure. If you have typed the name of an existing procedure its first line will be displayed ready or you to edit it. In both cases, the activity indicator 'EDIT:' is displayed. 'EDIT' is the activity you will use for writing and editing procedures, and it is always the first one presented within 'PROG'.

Now you can use the **MODE/HOME** key to select
any of the following range of activities concerned
with programming and the manipulation of
procedures. These are:

'EDIT' | for writing and editing procedures. The
SAVE and FIND keys take on new
identities as ↑ and ↓ respectively,
allowing you to step up and down
through the lines of a procedure. The
chevron keys, << and >> will still scroll
the display horizontally so that you can
read and edit a long line.
When you have typed a step of your
procedure, press |

'INSRT' | To insert a line above an existing one,
bring the existing line into the display
and select 'INSRT'. Enter your line of
information and press ↓ to move down
to the next line. You are now back in
'EDIT'. 'INSRT' only allows you to insert
one line at a time. |

'QUlT' | discards your current edition (like
ON/CLEAR but acting on a whole
procedure) and selects 'ENTER'. |

'EXIT' | takes you out of 'PROG' and carries your procedure into 'RUN' where you can try it out without delay. The procedure is retained in temporary storage until you replace it with another one or switch off. |

'SAVE' | copies the edited procedure into permanent storage on a datapak for future reference |

'ERASE' | erases (ie makes inaccessible) the procedure from the datapak. A copy of the procedure is retained in temporary storage, and the procedure name is carried into 'EDIT' in case you wish to edit and perhaps save it under the old name. |

Like most Organiser activities, 'EXIT', 'QUIT',
'SAVE' and 'ERASE' do not take effect until you
press **EXECUTE**.

Within the current line, typing and editing information are exactly as they were with the basic Organiser, but when you are writing or editing a procedure, all the lines you type go into temporary storage, ready for immediate access.

Anything in temporary storage is lost when you switch the Organiser off. When you write or edit another procedure, the last one is automatically discarded from temporary storage (This temporary storage is simply a development of the way in which the current line was retained in your basic use of the organiser. As well as the current line and the current procedure, it has space for procedures and data called and created during calculations involving the program pack.)

Note that the maximum length of any one line in a procedure is 100 characters. The maximum length of any one procedure is 200 bytes — approximately 200 characters — but a program can consist of as many procedures as you like, and procedures can be nested or stacked within each other. In this way you can write a program several thousands of bytes (characters) long and store it on a datapak.

Before you leave 'PROG', you may wish to copy
your current procedure into a datapak. To do this,
press **MODE/HOME** to select 'SAVE1:' or 'SAVE2:'
depending on which drive contains your datapak.
The procedure name is displayed with the 'SAVE:'
indicator for confirmation. If the datapak already
contains a procedure with that name. Organiser
briefly displays the message "NAME IN USE"
before the activity indicator appears. Before you
can save the current procedure, you must change
its name or erase the existing procedure from the
datapak. (For instance if you have edited a
procedure called GALS you might store the new
version under the name 'GALS2'.)

Note that when you save a procedure, it is stored
in a different way from that selected with the
**SAVE** key, so that it is invisible for the purposes of
'FIND'. Thus your personal records are not
cluttered with procedures and related data. A
procedure can only be accessed by entering its
name in 'CALC', 'PROG', 'CAT' or 'RUN'.

'PROG' is especially for programming activities, so when you have finished working on a procedure you must leave 'PROG' in order to progress to something else. Your current work is retained in temporary storage unless you discard it using 'QUIT', If you want to use your procedure straight away, you should 'EXIT' so that 'RUN' is automatically selected. Both 'QUIT' and 'EXIT' bring the current procedure name into the display with the activity indicator, so that you can change the name if you wish, or select another activity within 'PROG'.

When you leave 'PROG' the current procedure name is retained and displayed next time you select 'PROG' (unless you used 'QUIT', when the name is totally discarded).

VARIABLES, INPUT, and OUTPUT

Within a program you will want to use numbers.
some of which are constants and can be written
as numbers in the program, and some of which
you will want to take different values each time
the program is run. The latter kind is called a
**variable** and is given a name consisting of a
single letter of the alphabet. Organiser reserves a
pigeon-hole in its memory for that variable, and
each time a new value is assigned to the variable
it puts the new value in the pigeon-hole. There is
more about variables in chapter 14.

This is the input statement at POPL and causes
the organiser to read a numeric value from the
keyboard, and store it under the variable name
specified. This statement can take two forms: one
which just reads and stores the number you enter,
and another which makes the Organiser display a
message and wait for you to enter a number, and
then read and store the input. Note that whenever
Organiser prompts you to enter information you
must do so and then press **EXECUTE** to make it
continue.

Examples:

IN L

makes the Organiser display a question mark and
then wait for you to type a number and press
**EXECUTE**. It then reads and stores that number
under the name L.

IN "NUMBER OF LITRES" L

makes Organiser display "NUMBER OF LITRES?" and wait for you to type a number which it then reads and stores as L. Note that the Organiser supplies the question mark for you.

This is the output statement of POPL and causes the Organiser to display the result of an operation. with or without an accompanying message. Your message text must be enclosed with quotation marks, for example:

OUT L*0.22

makes the Organiser display the result of multiplying the current value of L by 0.22.

OUT "GALS" L*0.22

makes it display the result with a caption "GALS".

OUT "HELLO MASTER"

makes it display that message of greeting.

Assignment statements tell the Organiser what it
must do with the numbers and variables on the
right hand side of the = sign to compute the new
value of the variable on the left. Once computed,
the new value of the variable replaces the existing
one in the pigeon hole. For example, **C=3*(A+B)**
tells Organiser to add together the current values
of the variables A and B, and multiply the result by
three to compute the new value of the variable C.

Within an assignment statement you can use any
of the standard mathematical operators, **+ - * /**,
or ****** (which raises the preceding number to the
power of the following number). In addition you
may use any of the mathematical functions and
procedures provided on the Science Pack or ones
that you have written yourself, thus building up an
algebraic equation.

In many cases an assignment statement is indistinguishable from an algebraic equation However while, for instance. A=A+1 is unacceptable as an algebraic equation, it is a valid assignment statement, which tells the Organiser to add one to the current value of the variable A to compute the new value.

With the IN and OUT statements. variables and assignments, it is possible to write a whole procedure:

__GALS__
IN "LITRES" L
G=L*0.22
OUT "GALLONS" G

When RUNning this program or executing it in
'CALC', you would be asked for the numbers of
litres with the prompt "LITRES?" and the answer
would be displayed as **GALLONS=answer**

In fact this program could have been made
shorter. A different assignment statement,
**= L*0.22** would have caused the Organiser to
finish the procedure at that line and still return the
same answer but with the procedure name as the
caption.

__GALS__
IN "LITRES" L
=L*0.22

would return **GALS=answer**

GOTO—Branching and Labels

So far the Organiser has dealt with each line of a program in strict sequence, step by step. However in programming one often wants to redirect the Organiser to different parts of the program, to jump from one section to another. To do this you need to be able to identify the line you wish to jump to.

Labels are used as a means of identifying a
particular line in a program and are placed at the
beginning of the line. They can have any number
of characters, but must start with a letter and be
followed by a colon. For example the label 'HERE'
could he used like this **HERE:IN "COST" C**. For
reasons that will become apparent later, the
identifiers P1, P2, P3, P4, and P5 are reserved for
a special use and cannot be used as labels.

This statement tells the Organiser to jump to a particular line in the program, ignoring the lines in between. GOTO must be used with a label as a reference for the line to be jumped to.

For example:

GOTO HERE THERE:IN "PRICE" P HERE:IN "COST" C

Organiser will jump to me line labelled 'HERE'. without asking for the input 'PRICE'. Thus to branch from one part of the program to another one simply identifies the destination with a label and uses the GOTO command to make the Organiser jump to that branch. Another GOTO elsewhere in the procedure would refer to the label "THERE".

CONDITIONS—the IF statement

It is often desirable to have a statement in a
program that effectively says "If something is true
Then GOTO a particular part of the program". This
is achieved in POPL with the **IF** statement, which
doesn't require you to type the "then". For
example:

IF V=10 GOTO HERE

which means that if the variable V has a value of
10 then the condition is **true** and the GOTO
instruction is followed. If the condition had been
**false** (ie V was not equal to 10) then the Organiser
would have ignored the GOTO instruction and
proceeded directly to the next line in the program.

This conditional statement can be used with the
Equals condition (=), with Less Than (<), Greater
Than (>) and Not Equal To (<>). All these
symbols are marked In blue on the keyboard and
(in common with the other blue symbols below
character keys) are accessed by pressing **SHIFT**
first.

The Less Than and Greater Than conditions can be combined with the equality condition to produce the conditions Less Than Or Equal To (<=) and Greater Than Or Equal To (>=). For example:

IF V>=5 GOTO HERE

means that if V has a value of 5 or more then the Organiser will GOTO the line labelled 'HERE' and continue executing the program from that point.

Before moving on to consider the use of logical
operators **AND**, **OR** and **NOT** we should first
explain a special case of the equality condition.
Where an IF statement uses a name without an
associated condition and says, for example: **IF V
GOTO**, then if V has a value of zero the condition
will be interpreted as false, and if V has a value
other than zero it will be interpreted as true and
the GOTO statement followed. This feature is very
useful since it is often important to follow different
actions depending on whether or not a variable
has a value of zero.

The IF statement can be extended to obey multiple conditions using the AND, OR and NOT operator, which are concerned with true and false relationships.

**AND** is used to combine two conditions that must
both be met for the result to be true. For example
the statement A=5 AND B<4 is false if either A
is not equal to 5 or B is not less than 4.

**OR** is used to combine two condition so that if
either or both are met then the result of the
statement is true. For example the statement A=5
OR b<5 is true if either A is equal to 5 or if B is
less than 4.

**NOT** is used to make a true result false and a
false result true. For example NOT C=3 will return
a result of true if the expression C=3 is false (ie.
C is not equal to 3).

These three logical operators can be combined in
just the same way as the mathematical operators
*** / + -** and ******. Similarly they have an order of
preference of evaluation — the NOT operator is
evaluated first, and then the AND and OR
operators have equal precedence and are
evaluated in the order they appear on the line
from left to right. For example:

IF A=3 AND NOT B=4 OR C<7 GOTO HERE

would be calculated in this order: firstly the NOT B=4 to give a result which we can call 'result 1'; then the expression A=3 AND 'result 1' would be evaluated to give a 'result2'; finally the expression 'result 2' OR C<7 would be evaluated to give a result of true of false for the IF condition.

LOOPING and ITERATION

Within a program it is often very important to be able to repeat a series of instructions several times. This may be because you wish to carry out a particular evaluation several times, or because you need to increment a variable repeatedly and perform a calculation on it, or because you need an iterative solution to an expression.

With POPL this is a very simple task using the GOTO and IF statements. For example, a simple procedure to calculate the factorial of a number is shown below (note that in this program pack we have actually given you a function which performs this operation, so perhaps you might like to test this procedure against the function!)

__FACT__
IN "NUMBER" N
C=0
F=1
LOOP:C=C+1
F=F*C
IF C<N GOTO LOOP
OUT "FACTORIAL IS "F

In this procedure the loop is used to increment the counter C. The factorial is evaluated recursively by multiplying the variable F by each successive value of C. When C=N the loop is ended (The definition of Factorial N is N*(N-1)*(N-2)*...1 ).

There are many uses of loops in the programs supplied with this program pack, so for further examples just examine these programs using the 'EDIT' activity.

GLOBALS and ARRAYS — STORE, RECALL

So far we have only said that variables must have
a name consisting of a single character, thus
giving a maximum of twenty-six variables. In fact
these variables are said to be **local** to the
procedure in which they occur. That is, you can
use the same variable name again in a different
procedure without it affecting the variable in the
original procedure.

However, it is often desirable to have some
variables which are **global**, that is, variables that
are accessible to every procedure — so that if
you alter the value of, say, A then any other
procedure using A will read the altered value.

This is achieved In POPL with the STORE and RECALL functions, also providing a convenient method of storing a series at repetitive inputs or results. STORE is a function that has two arguments — an index number and the value you wish to store. For example, STORE(1,5.6) will put the number 5.6 in temporary storage at a location with an index number of 1. The value stored is then accessible from all procedures, it is a global reference. To retrieve the number use the RECALL function, which has just one argument, the index number. For example A=RECALL(1) will make the variable A equal to the number stored in index position 1.

The index number can be any whole number between 1 and 20 inclusive, thus there is capacity to STORE twenty values in this way.

STORE and RECALL can be used very conveniently when you wish to handle a series of numbers, such as inputs or calculation results. For example, examine the following three procedures which deal with data input, manipulation and output separately:

__INPUT__
IN "No. OF VALUES (LESS THAN 10)" N
I=0
LOOP:I=I+1
OUT "VALUE" I
IN "VALUE IS" V
STORE(I,V)
IF I<N GOTO LOOP

__CALCULATION__
IN "NO. OF CALCS (LESS THAN 10)" N
I=0
LOOP:I=I+1
A=RECALL(I)
R=A/2
STORE(I+10,R)
IF I<N GOTO LOOP

__OUTPUT__
IN "HOW MANY RESULTS" N
I=0
LOOP:I=I+1
A=RECALL(I)
OUT "FOR INPUT" A
B=RECALL(I+10)
OUT "RESULT IS" B
IF I<N GOTO LOOP

These procedures could be combined in one program called EXAMPLE

__EXAMPLE__
INPUT
CALCULATION
OUTPUT

This program would execute each of the procedures in turn.

CALLING PROCEDURES

As we have said earlier the basic building block of programs written in POPL is the procedure, and procedures can be nested or stacked within each other. The process of using one procedure within another is named 'calling a procedure'. Thus the program 'WAGES' might call the procedure 'DAYS' to calculate the number of days between two dates as part of a calculation of the wages of a seasonal, temporary employee. The actual mechanics of calling a procedure are very simple — where the procedure is required just quote its name, either on a line of its own or as part of an expression. For example:

__WAGES__
IN "DAILY WAGE" W
A=DAYS
P=A*W
OUT "PAY IS £" P

In this example 'DAYS' is a procedure. Before we can talk any more about calling procedures we need to discuss parameters.

Although the term parameters may be unfamiliar
to you, you are in fact accustomed to using them.
For example, the operator **+** takes two
parameters, that is two numbers on which to
operate (note that these parameters can be
mathematical expressions themselves, just so
long as they return a numerical result for the + to
operate on). Another example is the SIN function
provided by this program pack —— you are asked
to use the function by putting in brackets the
number whose sin you want eg SIN(1.3). In the
same way, a procedure can be made to operate
on parameters to be written in brackets after the
procedure name.

Parameters are particularly useful when you want
to **pass** a number or result of a calculation from
one procedure to be used as the input in another
procedure. In one way they can be considered as
a substitute for variables, but the value of a
parameter does not change within a procedure.
Using parameters gives you the freedom to write
a procedure that can be used in other procedures
without having to coordinate the two procedures
to reference the same STORE index.

POPL allows you to pass five numbers, parameters, from one procedure to another without having to use STORE and RECALL. Instead write the procedure using parameter names P1, P2, P3, P4, and P5 for the values you wish to be read from the parent procedure. For example imagine a general purpose procedure called 'GROSS' which converts a wholesale price to a retail price including VAT and allows for a discount to the retailer. You want to be able to include this procedure in several different programs. The procedure requires two parameters, the wholesale price and the discount rate, to be passed to it.

__GROSS__
=1.15*P1/(1-P2/100))

This procedure could be called from within a program which calculates the retail price lot different products, the relevant part of which may look like:

IN "WHOLESALE PRICE" W IN "DISCOUNT RATE" D R=GROSS(W,D) OUT "RETAIL PRICE IS £" R

This will call the procedure GROSS and pass the values or W and D to the procedure as P1 and P2. This example is in fact a rather trivial one which could have been achieved without passing parameters, however, it illustrates the principles. A more sophisticated example which uses parameters in an iterative loop, calling the procedure itself again and again in the loop, is shown below. In fact this example is another procedure to calculate the factorial of a number (similar to the one we used to demonstrate loops)

__FACT__
IF P1>0 GOTO LABEL
A=1
GOTO RET
LABEL:A=FACT(P1-1)*P1
RET:=A

We could RUN or CALC this procedure to calculate the Factorial of 6 by executing FACT(6), but if we just executed FACT it would assume that P1 should take a value of 0, and in this case would give the result FACT(0)=1. This type of procedure relies on being passed the input data it requires in the form of PROCEDURE NAME(P1, P2,P3,P4,P5). This differs from other procedures we have met where the input data is requested through INput statements. When calling procedures from procedures the passing parameters method is most commonly used, however it is possible to write a procedure which will accept passed parameters if they are given. but will prompt for input it they are not given.

This ability to prepare a procedure to receive numbers at the same time as it is called is essential for combining several procedures in one calculation. For instance the procedure:

__EGG__
=15

may be combined with

__CHIPS__
=30

and

__DOUBLE__
=2*(P1)

so that the calculation

DOUBLE(EGG+CHIPS)

becomes possible. 'DOUBLE' takes one parameter, written as P1 in the procedure, and to get the number it calls and runs 'EGG', then it calls and runs 'CHIPS' and adds the two results together. Thus the final result here would be 2*45.

ERROR MESSAGES

The Organiser is able to detect many programming
errors before you try to RUN your program, and
brings them to your attention for you to take
remedial action. When it finds an error, the
Organiser displays a message describing the
nature of the error. Simply press the **ON/CLEAR**
key to clear the message and the offending line
will be displayed, with the cursor marking the
actual error. Correct the problem and continue.

Those errors which need a little more explanation than is possible in a sixteen character error message are detailed below:

**"ILLEGAL NAME"** — This message will come up
for three seconds to indicate that an inadmissible
procedure name has been used. All procedure
names must start with a letter and consist only of
letters and digits. The names P1, P2, P3, P4 and P5
are reserved as parameter names.

**"NAME IN USE"** — This message will come up for
three seconds if you try to SAVE a program or
procedure under a name which already exists on
the Program Pack or Datapak. Either edit the name
or ERASE the old program or procedure.

**"LABEL NOT FOUND"** — This means that the
Organiser was unable to find the label referred to
in a GOTO statement. Press **ON/CLEAR** to clear
the message and get back to the line in which the
GOTO occurs.

**"DATAPAK FULL"** — means that the datapak to
which you were trying to SAVE is full. Press
**ON/CLEAR** and insert a different datapak which
has sufficient space remaining.

**"PROGRAM NOT FOUND"** — means that you
have tried to RUN, CALC, CAT, PROG or call a
program or procedure that does not exist on either
the program pack or the datapak fitted. Clear the
message with **ON/CLEAR** and either correct the
name or replace the datapak with the one that
contains the program and try again.

**"PROGRAM TOO LONG"** — means that a
program or procedure has exceeded the limit of
200 bytes (approximately 200 characters). Clear
the message with **ON/CLEAR** and reduce the
length of the program concerned. This is in fact
quite simple to do by splitting the program or
procedure into smaller procedures, each less than
200 bytes long, or by making the program more
efficient (consider reducing the length of any
output text).

**"OUT OF MEMORY"** — means that the
combination of the program and variables held in
temporary storage has exhausted the amount of
temporary storage available on the Organiser.
Clear the message with **ON/CLEAR** and edit your
programs and data to occupy less space. Apart
from making your program more efficient you can
save memory by calling fewer procedures from
within procedures because each one takes up a
small overhead of space.

TROUBLESHOOTING

If nothing appears to be happening when you expect otherwise, this could be because:

1. The Organiser is waiting for you to respond to an
input request (the cursor is flashing) — type a
number and press **EXECUTE**.

2. The Organiser has displayed an output and is
waiting for you to press **EXECUTE** to continue
with the next step of a program.

3. The Organiser is performing a calculation or
program — you must wait for the calculation to
be completed. Pressing **ON/CLEAR** will abort
the calculation. If you wish to chart the progress
of a program or procedure, insert output
statements at various points.

4. The Organiser has completed a calculation or program and is ready for fresh instructions.

5. The Organiser is stuck in an infinite loop — this
will not occur for any of the programs supplied
on the program pack! Abort with the
**ON/CLEAR** key and edit your program.

WARRANTY

Your Psion Organiser Program Pack carries a one year warranty against mechanical or electrical failure other than in the case of misuse or damage arising from negligence. There are no user- serviceable parts within your Program Pack, and any attempt to dismantle or repair your Program Pack other than by an Appointed Psion Service Agent will invalidate this warranty.

Should you experience any problems consult both this and your basic Organiser manual with particular reference to the troubleshooting section. If you find no solution to your problem send your Program Pack in suitably protective packaging to:

Service Dept.

Psion Processors Ltd.

22 Dorset Square

LONDON NW1 6QG

We can accept no responsibility for goods damaged in transit to us. This warranty does not affect your statutory rights.