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
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.
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.
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.
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 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.
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.
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 ↓ 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 (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).
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
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".
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.
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.
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.
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.
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.
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.
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.