{S:X;X;0;0;Custom Functions from the Beginning \ù Part 1{ITR-X}by Gerald L Fitton}
{S:X;X;0;1;Keywords:{ITT-X}RProL Custom Function Introduction Parameter Sequence Fitton}
{S:X;X;0;2;If you are new to Resultz then I suggest that you read the [ReadMe] file in the Documents directory before this one. If you are new to worksheets (sometimes called spreadsheets) then I suggest that you have a look at the simpler tutorials in the Sheets series before embarking on the more advanced features of Resultz such as custom functions, names and arrays.}
{S:X;X;0;3;Introduction to \ÉRProL\æ{ITR-X}{ITR-X}This is the first tutorial article of a series which, I hope, will help you to get to grips with one of the advanced features of Resultz which first appeared in PipeDreamá4, custom functions. If you wish to use these custom functions then you need to learn the Resultz custom function programming language which, at present, doesn\æt have a name. I shall call it \ÉRProL\æ. I'm not sure of the best pronunciation but \ÉR-prol\æ seems OK to me!}
{S:X;X;0;4;One thing to clear up from the start. Custom functions can not be used to move blocks around within a document nor indeed to change the \Éshape\æ of a document in any way. However, what you can do with custom functions is to process the data which already exists within the slots of a document (or within a set of documents) in more intricate ways than can be done simply with the \Éstandard\æ functions provided. Just like any standard function such as (a1á+áa2) or the more complex lookup(a1,b1b10,c1c10), a custom function is \Écalled\æ from a slot and the \Éresult\æ of executing the function is returned to the slot from which it is called.}
{S:X;X;0;5;Calling Custom Functions{ITR-X}{ITR-X}Let's have a look at a custom function at work. Double click on the file [AddOne] and you will find that you load to the screen not only [AddOne] but a dependent document which I have called [c_AddOne] containing a simple, two line, custom function. I have deliberately limited the width of [c_AddOne] so that it will fit across a mode 12 screen.}
{S:X;X;0;6;You can use any valid filing system file name for a custom function document but, so that I can recognise which Resultz (or Fireworkz) files are \Éordinary\æ documents and which are custom function documents, I have prefixed all my custom function documents with c_ (a lower case c followed by an underline). I suggest that you follow this convention\\\; it is recommended not only by me but by Colton Software as well.}
{S:X;X;0;7;Because Resultz (like Wordz) saves the position of a Resultz document on the screen and the position of the cursor within the document, what you should find is that [AddOne] is visible and alive (a yellow top bar) with the cursor in slot [AddOne]a3. If not then position the pointer on the number in [AddOne]a3 (it should be the number 2 unless you\æve modified the file) and click the mouse select (left) button. You should see the same number in the formula line (at the top of the document just to the right of the cross and tick). Tap some other number, say 9, and then tap <Return>. If all goes well then, besides [AddOne]a3 changing to 9, the number in [AddOne]b3 will change to 10.}
{S:X;X;0;8;The custom function \Écalled\æ from [AddOne]b3 is not a spectacular custom function. The \Éresult\æ returned to the slot [AddOne]b3 is (a3á+á1), one more than the number in the slot [AddOne]a3. Change the value in [AddOne]a3 a few times and convince yourself that the value in [AddOne]b3 is always 1 more than the value in [AddOne]a3.}
{S:X;X;0;9;Now let\æs have a look at the content of slot [AddOne]b3. Place the pointer over [AddOne]b3 and click select. The formula line does not show the simple, non custom function way of adding 1 which would be (a3á+á1)\\\; instead it shows the formula used to \Écall\æ the custom function, namely [c_AddOne]one_more_than(a3). Before looking at the custom function document, [c_AddOne], let's have a look at the formula used to call the custom function in more detail.}
{S:X;X;0;10;The \Écalling\æ formula is in three parts:{ITR-X}{ITR-X}The first part - [c_AddOne] - is the name of the dependent document which contains the custom function. A custom function document such as [c_AddOne] can contain more than one custom function. Indeed, it is desirable to \Ésplitáup\æ large, exotic custom functions into a set of smaller custom functions (stored within the same \Éc_\æ document) in the same way that it is usually desirable to split up a long program written in BASIC into more easily digested PROCs and FNs.}
{S:X;X;0;11;The second part - one_more_than - is the name of the custom function within [c_AddOne]. If you look at slot a7 of the document [c_AddOne] you will see that -áone_more_thaná-, the name of the custom function, appears after the word \Éfunction\æ. Another convention which I recommend to you is that the names of custom functions should be totally in lower case (no capitals). The reason is that lower case and upper case function names are equivalent (unlike BASIC procedures) and Resultz converts upper case letters in the custom function names to lower case anyway!}
{S:X;X;0;12;The third part - (a3) - is the single piece of data which is passed to the custom function for processing. To be more accurate, [AddOne]a3 is the slotref of the data passed to [c_AddOne] for processing. The data passed to a custom function this way is called a \Éparameter\æ. A parameter is a \Ésort of\æ variable which has a \Éfixed\æ value within the custom function but can be varied outside the custom function. As we shall see in a later tutorial, it is possible to pass more than one parameter to a custom function. You can pass as many different parameters as you wish to a custom function but, if you want to pass a large amount of data, rather than use many parameters (a rather cumbersome method), it is better to pass a range of slots or an array as one single parameter.}
{S:X;X;0;13;Returning the Result{ITR-X}{ITR-X}\ÉCalling\æ the custom function - [c_AddOne]one_more_than(a3) - from slot [AddOne]b3 returns the result of the processing to the slot from which it was called, [AddOne]b3. Although the result can be returned to only a single slot this does not mean that you can return only one value from a custom function! You can return many values to one slot by returning an array to the calling slot. This array can then be expanded using set_value(range,slotref) where \Éslotref\æ contains the array (and the calling function) and where \Érange\æ is the range of slots containing the expanded array. We shall return to examples of this tactic in a later tutorial.}
{S:X;X;0;14;Programming in General{ITR-X}{ITR-X}Before we look at the custom function in [c_AddOne] in detail I am going to digress and discuss programming from a broader point of view.}
{S:X;X;0;15;Perhaps you are familiar with writing short programs in BASIC. That may help or it may not! Perhaps you write \Éwell written\æ or perhaps \Ébadly written\æ BASIC programs. Both types usually work most of the time\\\; both types sometimes fail. The difference between the two is often apparent only when you want to \Édebug\æ, modify, improve or extend the program you (or maybe someone else) has written. Those programs which I class as \Égood\æ are usually easier to \Édebug\æ if they don\æt work first time and easier for others to modify if they wish to extend or improve them. Short \Ébad\æ programs can usually be written in a much shorter time so too many programmers with no formal training pick up some bad habits when they start programming. This is particularly true if they write short \Ébad\æ programs which work. Early \Ébad\æ habits learnt that way are often the most difficult to break.}
{S:X;X;0;16;Some languages encourage \Égood\æ programming. Others permit \Ébad\æ or even \Évery bad\æ programming. I think I would put \ÉRProL\æ in the \Éfairly good\æ category!}
{S:X;X;0;17;Programming in \ÉRProL\æ{ITR-X}{ITR-X}Custom function documents such as - [c_AddOne] - contain custom functions such as -áone_more_than - which are written in the programming language I have called \ÉRProL\æ. A custom function is a set of instructions which is designed to process similar data in a similar way. No matter what the actual value of the data, the same set of instructions are followed. For example, in the case of -áone_more_thaná- the data passed to it is a parameter representing a single number such as 2 and the pair of instructions which make up -áone_more_thaná- process the number represented by the parameter by adding 1 and returning the result.}
{S:X;X;0;18;Whatever the number which is passed as a parameter to -áone_more_thaná- the \Éresult\æ returned is one more than the original number. That original number is represented within the custom function as the parameter \öparameter\ò. Custom functions are written so that they can and most often do operate on variables (symbols representing any similar piece of data) rather than sets of instructions which process data directly.}
{S:X;X;0;19;There are many ways of classifying variables\\\; one is by the way in which they retain or lose their identity when the overall program is broken down into smaller units. Using this classification a parameter is a \Ésort of\æ variable\\\; there are two more sorts called \Élocal\æ and \Églobal\æ variables which I shall introduce in another tutorial.}
{S:X;X;0;20;Within all but the simplest programming languages the manner of processing the data (best included as variables) is based on four concepts. We shall study these concepts under the headings: \öSequence\ò, \öRepetition\ò (such as \öforá-ánext\ò loops), \öDecision\ò (such as \öifá-áthen\ò statements) and \öInterrupt\ò (which will include the use of the \ÉRProL\æ commands - input - and - alert). I shall limit this tutorial to a discussion of \öSequence\ò and the use of a parameter. In later tutorials we shall discover other sorts of variables as well as the concepts of \öRepetition\ò, \öDecision\ò and \öInterrupt\ò.}
{S:X;X;0;21;Sequence{ITR-X}{ITR-X}This topic is concerned with the order in which the commands are executed. Every sequence must have a start and a finish.}
{S:X;X;0;22;In a large number of spreadsheets you must choose whether to recalculate along the rows (one at a time, starting at the top and running from left to right along each row) or down the columns (one at a time starting with the left most column and working down each column from top to bottom). In Resultz recalculation takes place in an order which is called \önatural\ò. Here is not the place to explain in detail what is meant by \önatural\ò\\\; essentially, with \önatural\ò recalculation, every slot can be regarded as part of a chain and the calculation proceeds along the chain in such a way that slots which depend on other slots are processed last no matter where they are located within the document. When a slot is changed in Resultz only those chains which are affected are recalculated.}
{S:X;X;0;23;In a Resultz custom function the default sequence is that commands are executed, one at a time, down a single column. The start is identified by the command -áfunctioná- and the end is identified by the command -áresult.}
{S:X;X;0;24;The Custom Function{ITR-X}{ITR-X}What we haven't looked at yet is the custom function itself to see how it adds one to the parameter and returns the 'result'. To do this we must bring the custom function - [c_AddOne]one_more_than - into view.}
{S:X;X;0;25;Let\æs look at the commands in detail and see how they process data.}
{S:X;X;0;26;Row 7 - function("one_more_than","parameter:number"){ITR-X}In this custom function the \ÉRProL\æ command -áfunctioná- has two arguments. The first argument is the name of the custom function, -á"one_more_than"á- note that the name is included in inverted commas. The second argument is the one and only parameter passed to the function. The name of the one parameter passed to -á[c_AddOne]á- is -áparameterá- and its \Étype\æ has been declared (after the colon) as a number. Because of this declaration, if you try to pass anything other than a number to this function then an error will be generated. You do not have to declare the type of variable if you want to pass a number sometimes and, say, a string on another occasion.}
{S:X;X;0;27;Try typing Fred (without and then with inverted commas) into [AddOne]a3 and you will find that the error message -áString not expectedá- is returned to slot [AddOne]b3. You will find the error message foreshortened in the body of the [AddOne] document. If you want to read the full error message then you must look n the Status line at the top of the document.}
{S:X;X;0;28;Row 8 - result(@parameter+1){ITR-X}The command - ...result - terminates the sequence of commands and returns a value to the slot from which it was called, [AddOne]b3. Note the sign preceding the word -áparameterá- and the inverted commas have gone. The sign \Égoes with\æ the word -áparameterá- try return(1+ parameter), it gives the same result.}
{S:X;X;0;29;Try changing return( parameter+2). You have to do this in the formula line of [c_AddOne]. Even when you have modified the custom function, the number 3 in the slot [AddOne]b3 does not change. To make that change, and indeed if you want to check whether you have introduced any \Ébugs\æ (errors in programming) in [c_AddOne] you must \Érun\æ the custom function by \Écalling\æ it again from the document [AddOne]. The simplest way of doing this is to place the cursor in slot [AddOne]b3, then move the pointer to the formula line and click on [c_AddOne]one_more_than(a3). Finally, click on the green tick to the left of the formula line\\\; when you click on the green tick the custom function will be called and the new \Éresult\æ will be returned to [AddOne]b3.}
{S:X;X;0;30;Over to you now{ITR-X}{ITR-X}As your first exercise in writing custom functions try to recreate the pair of documents, [AddOne] and [c_AddOne]. Only when you have succeeded are you ready to continue! If you have problems then reload my [c_AddOne] and study it carefully. You should type the expression -áfunction("one_more_than","parameter:number") - into a number slot and tap <Return>! In case you really get stuck I have included in this directory a file call [CustomFn] which you might like to load and then save as a custom function template.}
{S:X;X;0;31;Summary{ITR-X}{ITR-X}A custom function is a sequence of commands which start with a -áfunctioná- command and end with a -áresultá- command. Once there is a custom function within a document then the whole document is a custom function document. Custom function documents behave differently from \Éordinary\æ documents \ù but they do not have a different file type!}
{S:X;X;0;32;The next tutorial{ITR-X}{ITR-X}The next tutorial of this series is in the Custom02 directory.}
