{S:X;X;0;2;Introduction{ITR-X}{ITR-X}In some applications you can generate what I am going to refer to as "a long chain of unwanted dependent documents". As the application grows the chain grows unwieldy because all the files in the chain are loaded one after the other when, perhaps, you want to work on only the most recent document.}
{S:X;X;0;3;The set_value(,) function can be used to 'unlink' the chain without destroying the (occasionally wanted) dependency. Using Named variables further simplifies many applications which use dependent documents.}
{S:X;X;0;4;For my example I've chosen a simple accounts application where each month's transactions are kept in a separate document. First I'll explain how the basic application works, then I'll go on to to demonstrate how the chain of dependent documents becomes unwieldy and, then we'll see how set_value(,) can help by 'unlinking' the chain. Finally we shall see how the use of Names for variables further simplifies the creation of new documents which have to be added to the 'unlinked' chain.}
{S:X;X;0;5;Monthly transactions{ITR-X}{ITR-X}Double click on the file [Acc_9301] to load it. You will see that it represents a set of transactions for January 1993. Position the cursor in slot [Acc_9301]D5 and you will find the formula D4+B5-C5. The value brought forward from the previous month is held in slot [Acc_9301]D4, credits are added to that amount and debits are subtracted from it (line by line) to find the current balance and, finally, the amount to be carried forward to next month's accounts.}
{S:X;X;0;6;This formula has been replicated down the column from D5 to D8 by marking D5D8 and clicking on the Fill down button (top left button of the top button bar) so that, for example, the formula in [Acc_9301]D7 is D6+B7-C7.}
{S:X;X;0;7;In the form in which I've included it on this disc, the file [Acc_9301] contains only three transactions, two credits and one debit but you can extend it quite simply. Place the caret anywhere in the last row and tap <F7> to insert a new row, make your credit or debit entry and, finally, replicate the formula in the "Balance" column through to the line marked "Carried Forward".}
{S:X;X;0;8;Usually you would Save the file at this point but, in this case, don't do that or my next exercise won't work properly!}
{S:X;X;0;9;Brought Forward{ITR-X}{ITR-X}Delete the modified file [Acc_9301] from your screen (decline to Save it by clicking on the 'No' box) and then double click on the file [Acc_9302] (the transactions for Februaryá1992). You will find that [Acc_9302] and [Acc_9301] are both loaded. The reason why [Acc_9301] is loaded is because slot [Acc_9302]D4 contains the formula [Acc_9301]D8. Provided that you have not modified my version of [Acc_9301] then this formula will bring forward the balance from Januaryá1993 into the Februaryá1993 document.}
{S:X;X;0;10;There are at least two difficulties which arise when you use this strategy of entering the slot reference of the previous "Carried Forward" file, [Acc_9301]D8, into the "Brought Forward" slot, [Acc_9302]D4, of the current month's document.}
{S:X;X;0;11;The first difficulty arises if you don't have both [Acc_9301] and [Acc_9302] loaded and you want to add to or delete rows from the earlier document. If you have [Acc_9302] loaded and add a row to [Acc_9301] then you will find that the slot reference in [Acc_9302]D4 will change to match the extended [Acc_9301]. However, it is all too easy to forget that you need both files loaded. If you don't have them both loaded when you add a row to the earlier document then, when you do load the later document, it will look for the amount to bring forward in the slot where it used to be instead of where it now is.}
{S:X;X;0;12;Yes! Before you start writing to me, I do know that a method of avoiding the 'loss' (some would say 'corruption') of slot references in this fashion is to use Names in the earlier document for the slots used by the later document. Some of the examples I have received from you use this method of 'non-local' Names - I don't recommend it. I shall explain how I use Names (and give my explanation of why 'non-local' Names are not a good idea) later in this tutorial!}
{S:X;X;0;13;The second difficulty is one about which I get much correspondence. To understand why I get so many letters on this topic I'd like you to imagine the situation in Decemberá1993. When you load [Acc_9312] then it will call up [Acc_9311], which in turn will call up [Acc_9310], and so on until either all the monthly sheets have been loaded into memory or (as has happened to some of my correspondents) you don't have any memory left to use!}
{S:X;X;0;14;Loading all these earlier files is what I mean when I refer to a "chain of unwanted dependent documents". As a document become older the likelihood of you wanting to change it is reduced so one way of 'breaking the chain' is to 'snapshot' a "Brought Forward" value with Make Constant. This method of 'unlinking' the earlier dependent documents from later ones seems to be the favourite solution adopted by the majority of my correspondents. Of course, it requires a personal judgement about the likelihood of wanting to change an earlier 'unlinked' document against the desirability of keeping it (and all earlier ones in the chain) 'alive'. I'd like to suggest to you what I believe to be a much better alternative.}
{S:X;X;0;15;Carried Forward{ITR-X}{ITR-X}You might regard the use of the formula [Acc_9301]D8 in slot [Acc_9302]D4 as a function which creates a 'backwards chain' of dependency.}
{S:X;X;0;16;Let me try to convince you that chaining backwards is not consistent with the nature of the application we're considering. The application is one in which amendments to an earlier document need to be 'chained' in the forward direction whereas additions to the most recent document have no effect on earlier documents. Chaining backwards, loading earlier documents into memory, is a waste of time and effort! What we need is a set of documents which 'chain forwards'. To put it another way, we want to 'push' the "Carry Forward" balance from the earlier document into the "Brought Forward" slot of the later document rather than drag the value from the earlier document into the "Brought Forward" slot of the later document. If we can find a way of doing this then we don't need to have the earlier documents in memory (unless they need amendment\ÿin which case we want any amendment to 'ripple forwards' through the 'chain').}
{S:X;X;0;17;This is where the function set_value(,) comes in useful. It can be used to 'push' the "Carried Forward" balance into the "Brought Forward" slot of the next document in exactly the way we want. This is the strategy I have adopted in dealing with the [Acc_94##] series.}
{S:X;X;0;18;Load the file [Acc_9403] and look at the "Brought Forward" balance in slot [Acc_9403]D4. You will find that it does not contain a formula but a value. The document [Acc_9403] contains no reference to earlier documents so it does not 'pull' on the next link in the "chain of unwanted dependent documents" uselessly dragging them into memory in the way I've described in the previous section.}
{S:X;X;0;19;So how do we know that the "Brought Forward" balance is correct? How did it get there? One way would be to use Make constant and another would be to copy the "Carry Forward" manually into the "Brought Forward" slot. Either of these methods are unsatisfactory if there is a chance that you might want to make an amendment to an earlier document. Amendments to earlier documents won't ripple through a 'snapshot' and it's too easy to make a mistake!}
{S:X;X;0;20;Load [Acc_9402] and look at slot [Acc_9402]D12. You will find the formula set_value([Acc_9403]D4,D8). It is this set_value(,) function which 'pushes' the "Carried Forward" value from [Acc_9302]D8 into the "Brought Forward" slot of the Marchá1994 document. Make an amendment to the earlier document and you will find the the amendment is 'chained' through to the later document. Try adding rows to the Februaryá1994 document and you will see that the set_value(,) formula in what was [Acc_9402]D12 adjusts to the enlarged sheet.}
{S:X;X;0;21;Now delete the earlier [Acc_9402] document from the screen. You can continue to work on the Marchá1994 document and ultimately Save it with all the additions you have just made.}
{S:X;X;0;22;To see how the 'chain' works delete both the Februaryá1994 and Marchá1994 documents from the screen and then double click on [Acc_9401] (the Januaryá1994 file). That file and all subsequent files (February and Marchá1994) will be loaded. Make an amendment to the Januaryá1994 file, Save it (not on the master disc) and then delete it from the screen.}
{S:X;X;0;23;Using the 1994 Chain of Documents{ITR-X}{ITR-X}For most of your work you will not need the earlier documents loaded\\\; probably you will need only the most recent document. Make your changes to it and then Save it.}
{S:X;X;0;24;Now and again you will need to change an earlier document either to amend a value which has been entered incorrectly or to add an item which has been forgotten. If you load that earlier document then all subsequent documents in the chain will be loaded because the set_value(,) function will drive the "Carried Forward" value into the next sheet. When you make your amendments to an early document the consequences of those changes will 'ripple through' all later documents.}
{S:X;X;0;25;When you have finished with the early document you can Save it and then delete it from the screen\\\; in fact you can work through all the chained documents in chronological order Saving the new versions and then deleting them from the screen.}
{S:X;X;0;26;If you run out of memory you can 'unlink' the chain by tricking the package into believing that a particular file can't be found. For example, if you change the name of the file [Acc_9404] to, say, [Acc_9404a] (use the RISCáOS feature Rename) and then double click on [Acc_9401] you will find that the chain is broken when [Acc_9404] can't be found. You can make your amendments to the earliest file and then go through the process of Saving the chain of files and deleting them from the screen.}
{S:X;X;0;27;Restore the renamed file to its original name and then load the file whose position in the chain is just prior to that one. The new values will ripple through the rest of the files in the chain.}
{S:X;X;0;28;Using Names{ITR-X}{ITR-X}The process of creating a new document is made easier if you use Names.}
{S:X;X;0;29;I have used Names in the [Acc_95##] series. Before we have a look at the detail, double click on [Acc_9501] and you will find that the 1995 series will load and can be used in exactly the same way as you have seen when you used the [Acc_94##] series.}
{S:X;X;0;30;Load all three files by clicking on [Acc_9501] and then have a look at the contents of slot [Acc_9502]D12. You will see that the formula, instead of set_value([Acc_9503]D4,D8) has been replaced by set_value([Acc_9503]bf,cf). Two names, bf and cf (Brought Forward & Carried Forward) are used in the formula instead. The Name cf is 'local' to the [Acc_9502] sheet whereas the Name [Acc_9503]bf is what I am calling 'non-local'.}
{S:X;X;0;31;Now let's have a look at the Names which have been defined in [Acc_9502], what I am calling 'local' Names. Place the pointer on the italic f which is just to the left of the cross and tick boxes (in the same line as the formula line) and click once. At the bottom of the pop-up menu you will find the option Names. Click on Names and you will see that within [Acc_9502] only two names have been defined, bf and cf which are both 'local'. By looking at the definitions (as if you were going to edit them) you will see that the name bf refers to D4 and the name cf refers to D8 both slots within the current sheet. There are no definitions which refer to slots in other sheets.}
{S:X;X;0;32;Now let's see how many names we have in the whole chain of three documents. Once again click on the italic f but this time run the pointer through Names. You will find that six names have been defined, two we know about (bf and cf) but the other four are names which have been defined (locally) in the other two documents.}
{S:X;X;0;33;Defining the two names bf and cf in all documents makes it easier to create the next document. Let's create [Acc_9504] using the blank file [Acc_95xx] as the template. Double click on the file [Acc_95xx] to load it, change the formula in the slot [Acc_95xx]D12 from its present value to set_value([Acc_9505]bf,cf) and then Save the file as [Acc_9504].}
{S:X;X;0;34;Next you will need to 'push' the "Carried Forward" value from the previous document, [Acc_9503] into your new [Acc_9504] file. To do this you double click on [Acc_9503] to load it - then delete it from the screen! You will find that the "Brought Forward" value in [Acc_9504] has taken the correct value 'pushed' into it from the [Acc_9503] file you loaded and then removed from the screen and memory.}
{S:X;X;0;35;A Bug{ITR-X}{ITR-X}Although the process of using set_value(,) with Names works well in PipeDream it doesn't seem to 'work' properly in Fireworkz. I don't know exactly what effect you will find but, with my machine, I found that the recalculations got into an infinite loop with the 'number of calculations still to go' increasing instead of decreasing as time went by!}
{S:X;X;0;36;As a result of this 'bug' I am unable to recommend this set_value(,) with Names in Fireworkz even though, as I said before, it is the preferred method\ÿand works well in PipeDream. Perhaps when the next version of Fireworkz is released in Octoberá1994 I'll be able to delete this paragraph from this article but, in the meantime, be careful of set_value(,) when using Names in Fireworkz.}
{S:X;X;0;37;To Summarise{ITR-X}When you have a long 'chain' of dependent documents then you should consider whether you want to 'drag' or 'push' values from one member of the 'chain' to another. I suggest that for an application such as that of this tutorial you need to 'push' rather than 'drag' slot values from one sheet to the next in the 'chain'. When you have decided that the correct strategy is to 'push' you need to use the set_value(,) function in the (often unwanted) 'dependent' document to 'push' the value (or values) you want to carry forward to the next document.}
{S:X;X;0;38;Names can be used for single slots or for ranges of slots. Generally it is better to define names in such a way that the definition is 'local'. That is to say the definition does not refer to (and thus call into memory) another document. If you define a Name in one document you can always use it in another document - we have done this in the 1995 'chain' of documents - but if you define a name in one document which refers to a slot in a different document (what I call a 'non-local' definition) then you have a 'link' that you may not want.}
{S:X;X;0;39;Don't use Names with set_value(,) in Fireworkz.}
{S:X;X;0;40;Finally{ITR-X}{ITR-X}If you have an application which you think may be simplified by the use of set_value(,) or Names but can't quite work out how to do it, then please ask me. I will be able to work on your problem and send you the solution much more easily if you provide a disc based example of what you are doing together with some note (in a [ReadMe] file) indicating exactly what you are trying to achieve.}
