THE ORGANISER FINANCE 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.

Whilst all care has been taken in devising and producing this Program Pack, neither Psion Limited nor Psion Processors can accept any liability whatsoever with respect to the use or application of the Program and Programming Language supplied in this Program Pack or of the results of calculations utilising the facilities of this Program Pack.

(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. - COMPOUND INTEREST

Introduction; MORTGAGE, PAYMENTS, VALUE, CAPITAL, and DURATION programs. - CASHFLOW PROGRAMS — NPV, IRR

Net Present Value and Internal Rate or Return programs. - DEPRECIATION

Straight line depreciation DEPSL program; reducing balance depreciation DEPRB program. - BONDS AND EQUITIES

Redemption yield of a semi-annual bond, BOND program; investment analysis, EQUITYPE program. - 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 drives of your Organiser by pulling with your finger on the knurled outside of the pak. Now insert the Finance Program Pack in the empty slot in the normal way.

The Finance pack is a substantial software system which turns the Organiser into a powerful tool for business, financial, accounting and investment needs. It contains a series of programs or 'procedures' especially designed to solve common financial problems such as cash flow, depreciation of compound interest. It also contains a comprehensive list of mathematical functions which are automatically added to the calculator and which 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 switch into 'RUN', 'PROG'
or 'CALC'.

'PROG' is the Organiser activity for writing, editing, and saving your own procedures or programs that you have written. 'PROG' itself contains a menu of activities. These and the use of 'PROG' are described in detail in Chapter 7 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 remove
the program pack. Once you have done this you
must place the datapak from which you wish to
copy into drive 1 and an empty or newly-formatted
datapak in drive 2. When you have done this 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
MORTGAGE and you will see the program name in
the display.

The MORTGAGE procedure is one of the financial
programs in the program pack and evaluates the
monthly repayments on a conventional repayment
mortgage. Press the **MODE/HOME** key until the
activity changes to 'RUN'. The program name
'MORTGAGE' 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 amount
of the loan concerned. Enter a number and press
**EXECUTE**. The Organiser will now ask you for the
interest rate which it is to apply. Enter the
percentage interest rate and press **EXECUTE**. You
will now be asked for the duration of the loan in
years. Enter a number and press **EXECUTE**.
Finally you will be asked whether the loan is from a
building society or bank. Enter 0 or 1 and press
**EXECUTE**. The Organiser will evaluate the
monthly repayments and print out the result on the
screen. This could apply, for example, to mortgage
repayments on a £25,000 loan, spread over 20
years and payable monthly throughout the duration
of the loan.

Alter you have run this procedure in the manner
described above, you may wish to read how the
program is written in the Organiser's own
programming language — POPL. Press the
**MODE/HOME** key until 'PROG' is displayed. Now
press **EXECUTE**. The activity indicator will change
to 'EDlT:', and the procedure name 'MORTGAGE' will
be shown to its right. Press the **FIND** key, and you
will see the next line of the procedure. This 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 7-13.

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 large range of mathematical functions. These and their use are described in Chapter 2.

SCIENCE AND MATHS FUNCTIONS

When the Finance 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 7-13). 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.

COMPOUND INTEREST

The next four chapters describe a series of programs already written and available for immediate use from the Finance pack. They are written in the Organiser's own programming language and are executed or RUN through the 'RUN' activity. (They may also be run or evaluated like library functions through the 'CALC' activity).

To execute them press the **MODE/HOME** key until
the 'RUN' indicator is shown and enter the full
name of the program. Then press the EXECUTE
key. The programs may also be found more simply
through the 'CAT' activity (see chapter 1).

In this chapter a series of programs to evaluate compound interest problems are described. The simplest of these is the evaluation of a monthly mortgage repayment.

This program will prompt the user for the initial
capital size of the mortgage, the interest rate to be
applied, and the duration of the mortgage in years.
in response to each prompt displayed by the
Organiser you should enter the appropriate
number and press the **EXECUTE** key. Do not enter
a non-numerical character. The program now
prompts you as to whether the mortgage is from a
building society or from a bank or other institution.
Enter 0 for a building society and 1 otherwise. The
program will then evaluate the monthly repayment
amount and show the amount on the screen.

At the end of the duration of the mortgage, the program assumes that all capital and interest has been paid. The distinction between building societies and other loan institutions arises from the different treatment of compound interest by the building societies. The latter charge the full interest on the principal at the beginning of the year throughout the year and only reduce the principal at the end of each year. The total interest and repayment for the year are simply divided by 12 to give the monthly mortgage. Other financial institutions usually reduce the principal on a monthly basis.

This and the following three programs are more general programs than the special case of mortgage repayment, and apply to the general compound interest problem which governs many financial transactions, decisions or evaluations.

The compound interest problem is defined as:

V = CAPITAL FLOW AT START OF PERIOD

C = CAPITAL FLOW AT END OF PERIOD

P = AMOUNT OF PAYMENTS AT REGULAR INTERVALS DURING PERIOD

Y = DURATION OF PERIOD IN YEARS

I = INTEREST RATE AS A PERCENTAGE

N = NUMBER OF PAYMENTS PER YEAR

K = 0 OR 1 FOR PAYMENTS AT END OR BEGINNING OF PAYMENT INTERVALS

let i = I/(100*N) then solutions are found for the equation:

I, N and Y must be positive numbers. For different problems C, V and P may be positive or negative. The sign convention used is that cash in (whether capital or payment) is positive while cash out is negative.

The program PAYMENTS solves the equation for P,
given V, C, I and N. On RUNning the program, the
Organiser will prompt you for the capital sum at
the start, the capital sum at the end, the number of
payments per year, the interest rate to apply and
the duration in years of the transaction. Type in
numerical answers to each question and press
**EXECUTE**. Use the negative sign preceding the
number if the capital sums are cashflows out. The
amount of each payment to be made at each
interval will be evaluated and shown on the screen.
A negative sign in the result shows that the
payments are cashflows out. The parameter K is
set to zero unless the capital at the start V is zero.

This program may be used to find the payments for a mortgage, the payments for the redemption of a loan with or without a final capital payment, the payments required to accrue a given capital sum through regular savings, hire purchase payments and many others.

For the compound interest equation above, this
program evaluates present value V after the
Organiser prompts the number of payments per
year N, the duration of the transaction Y, the
percentage interest rate to be applied I, the capital
sum at the end of Y, and the amount of each
payment. Enter the appropriate number and press
**EXECUTE** in response to each query. Remember
that cash in is positive and cash out is negative.

The program may be used to estimate the value of a financial asset or liability.

This program again solves the general compound interest problem above for C, given V, P, N, I and Y. K is taken as 1 if the starting capital V = 0 and otherwise 0. The program prompts the user for all inputs.

Many applications exist for this problem including the capital accrued from regular savings, the redemption value of a loan or bond and the future value of a variety of financial assets and transactions.

Again, this is the solution of the general compound interest problem above for Y, given N, I, V, and C. For example, it will answer the question "How many years will it take to repay a loan V with fixed payments P made N times a year and an interest rate of I". RUN the program in the normal way and the Organiser will prompt for all the variables. The result in years will be shown on the screen. Remember that cash flow in is positive and cashflow out is negative. There are many cases where the problem does not have a solution (an infinite period or, worse, where the capital grows). Ensure the data is meaningful.

CASHFLOW PROGRAMS — NPV and IRR

Business and investment demand the use of
capital outflows in the hope of later cash inflows.
There are a number of criteria commonly used to
estimate the merit or worth of such an
investment. The two most common criteria are
**NET PRESENT VALUE — NPV** and **INTERNAL
RATE OF RETURN — IRR**. The Net Present Value
puts a current capital value to the discounted
cash flows, both in and out, of such an investment
where a "going" interest rate is assumed. IRR on
the other hand, answers the question "What is the
effective percentage rate of return of the
investment given that the capital value prior to the
start of investment is zero?". The Organiser
will solve each of these problems through the
programs MPV and IRR.

Enter NPV or IRR when in the 'RUN' activity and
press **EXECUTE**. These programs assume regular
periods between cash payments and the
programs prompt for the duration of each period
expressed in months. To ease input of data, the
cashflow is broken into groups where each group
has a number of payments and an amount for
each payment.

The programs will prompt for the number of such
groups. For each such group, you will be
prompted for the number of payments it
comprises, and the amount of each individual
payment within it. Enter the appropriate number
in each case and press the **EXECUTE** key.
**Remember to enter cashflows in as positive
and cashflows out as negative.**

If the program is IRR, the interest rate of return will be evaluated and the result shown on the screen expressed as a percentage. If the net cashflow is negative, no result can be evaluated.

If the program is NPV, the user will be prompted for the "going interest rate" and the discounted current capital value of the project will be evaluated. You will be asked further as to whether you would like to obtain the IRR for the entered cashflow. Enter 0 for yes or 1 for no. Further NPV calculations will be allowed for different "going interest rates".

DEPRECIATION

Depreciation may be calculated by the straight line method or by the method of reducing balance.

The straight line method of depreciation assumes a fixed depreciation charge over the lifetime of the asset. Upon RUNning DEPSL you will be prompted for the purchase cost of the asset and the scrap value of the asset at the end of its lifetime expressed in years. The percentage annual rate of depreciation will be calculated and shown. Press the EXECUTE key and the depreciation charge for each year will be shown.

This method assumes a fixed rate of depreciation but varies the charge each year according to the book value at the beginning of the year. Upon RUNning DEPRB you will be prompted for whether you wish to calculate the depreciable life of an asset for a known rate, or the rate, given a known life.

Enter 0 or 1 respectively. If you enter 0, you will be asked to enter the rate of depreciation as a percentage. The program will then evaluate and show the lifetime of the asset. If you enter 1, the program will ask for the lifetime of the asset and evaluate the depreciation rate.

After these results are shown in the display, press
**EXECUTE**. The program will show the
depreciation charge for each year and the book
value at the end of the year. Press **EXECUTE** to
continue the calculation at any stage.

BONDS AND EQUITIES

The program BOND evaluates the redemption
yield on a bond with two payments a year, given
the number of days to the next interest payment,
the coupon payment in each half year, the market
price, and the number of half years to the
redemption date. Select 'RUN', type 'BOND' and
press **EXECUTE** to start the program. The
program will prompt for each variable. Note that
the redemption period is expressed in complete
half years and does not include the time from the
current date to the next interest date. The latter
must be entered in days. The redemption yield as
a percentage will be evaluated and shown on the
screen. The program solves for the yield with
precision using iteration.

This program uses a 'Whitbeck-Kisor' model to
arrive at an estimated price to earning ration for an
equity on the UK stock market as of June 1984.
**WARNING**: this program is illustrative and is
based on a model. The program can be read in
'EDIT' and varied and saved for changing
circumstances.

The model is a simple one based on
statistical analyses showing the dependence of
equity prices on growth (G), dividend cover (C)
and fluctuations of profits (F). Execute the
program through **RUN: EQUITYPE**. The program
will prompt the user for estimates of the above
variables on a particular equity. Enter the
estimates in turn and press **EXECUTE**. The
program will then evaluate and show an expected
price to earning ratio.

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
have a maximum of 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 (i.e. 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 12.

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 (i.e. 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 (i.e..
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 e.g. 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 your 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.