Jaap's Psion II Page

Psion Organiser Series 1:
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.

LIMITATION OF LIABILITY

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


CONTENTS

  1. INTRODUCTION
    Introduction; RUN; CAT; PROG; COPY; example
  2. SCIENCE AND MATHS FUNCTIONS
    List of extra mathematical functions and utilities; using functions.
  3. SCIENTIFIC CONSTANTS
    List of scientific constants; cgs and SI units; using constants.
  4. CONVERSION OF UNITS
    cgs, SI and imperial units
  5. SCIENTIFIC FORMULAE
    Available formulae; evaluation In 'RUN' or 'CALC'.
  6. POLYNOMIAL EQUATIONS
    Quadratic and higher order polynomial equations; real and complex roots
  7. LINE-FITTING
    LINE program — least squares fit
  8. INTEGRATION
    INTEGR program — area under a curve.
  9. POPL — PROGRAMMING
    Introduction; writing a program; programming activities; PROG, EDIT, INSRT, QUIT, EXIT, SAVE, ERASE.
  10. VARIABLES, INPUT, OUTPUT
    Variables; IN statement; OUT statement.
  11. GOTO — LABELS, BRANCHING
    Branching: GOTO statement; line labels
  12. CONDITIONS — IF STATEMENT
    Conditional statements: IF then GOTO; AND, OR, NOT.
  13. LOOPING AND ITERATION
    Forming loops with IF and GOTO.
  14. GLOBALS AND ARRAYS
    Local and Global variables; Arrays with STORE and RECALL.
  15. CALLING PROCEDURES
    How to use procedures within procedures; passing parameters.
  16. ERROR MESSAGES
  17. TROUBLESHOOTING
  18. WARRANTY

1
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.

RUN — Running a program or procedure.

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 — Cataloguing or finding procedures

'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

'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 — to copy datapak contents

'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.

Running and looking at a program

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.


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.

"UTILITIES"

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.

Using Functions

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.


3
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)
CEPSKEFSPermittivity 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)

4
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.

5
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'.

IMAGE —— position of an image from a simple lens

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.

FOCAL length of a compound lens

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 — Period of an LC circuit

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.

BOHR — energy levels of an atom

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.

SPECTRA — frequency of atomic line spectra

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.

LARMOR frequency of an electron in a magnetic field

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

PLASMA frequency

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.

BRAGG formula

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.


6
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.

QUAD

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

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.


7
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 (xi, yi). 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:

s0 t1 - s1 t0
a=—————
s0 s2 - s12

s2 t0 - s1 t1
b=—————
s0 s2 - s12

where

s0 = N+1
s1 = sum(xi)
s2 = sum(xi2)
t0 = sum(yi)
t1 = sum(xi yi)

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.


8
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).


9
POPL — Programming Your Organiser

Introduction

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.

Writing a procedure

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.

PROGRAMMING ACTIVITIES

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 to move down to a new line for the next step. The first line is now in temporary storage. Press to view or edit a previous line. When you edit a line, the new version replaces the old one in temporary storage.

 
'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).


10
VARIABLES, INPUT, and OUTPUT

Variables

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.

IN

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.

OUT

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

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.

Example

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


11
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.

GOTO

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".


12
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.

AND, OR and NOT

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.


13
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.


14
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.


15
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.

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.


16
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.


17
TROUBLESHOOTING

Nothing is Happening

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.


18
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.