sCal-QA-9

sCal -- Questions/Answers

sCal2.gif :-link to sCal2 ver.0.8 if avail.

Load up any of the current versions of sCal by clicking on thumbnails above, and work along with the text. [sCal2 will not be available, nor the Draft Documentation, without the full download package from the SourceForge Project Page.]

Table of Contents . . . . . If you don't see it here, try the Draft Doc or Edit->Find on your browser.

About sCal
Q: sCal? Another electronic calculator? Why should I give it a second look?
Q: Current Versions? Why so many?
Q: Online calculators?
Q: License, Price, Registration?
Q: Install / Uninstall?
Q: Why program in JavaScript?
Q: How can you do even the basic calculator functions in 20 kb?
Q: How can I tell if it will work on my system?
Q: OK, but it looks bad on my browser / operating system.
Q: I'm not a Scientist or Engineer. What good is sCal to me?
Operating sCal
Q: What's a Slide Rule?
Q: Say I'm from Mars; how does sCal work?
Q: Stopwatch Opertion?
Q: What's a JScrAp?
Q: Currency Conversions are included. How often are these updated?
Q: Other Conversions?
Programming sCal
Q: Programming Resources?
Q: How do you program JScrAps?
Q: Program Anything?
Q: How to Share JScrAps?

_ _ _ _ ^top^ _ _ _ _

Q: sCal? Another electronic calculator? Why should I give it a second look?

A: Yes, there are many computer based calculators available in all varieties. Most are simple calculators, with little more than the basic add, subtract, multiply, and divide opertions available. Many are free. Some also offer conversion factors and scientific, statistical, and/or financial functions. Fewer allow user customization and a degree of programmability. Fewer still offer work-alike versions for both the desktop and handheld machines.
If that's everything you're looking for, and if your desktop and handheld are both Windows based and you have around a half-meg of storage to spare, you probably need to be at the Calc98 download site . But...
if you're looking at only around 20-kilobites of storage, at least for starting out; or
if you have some mix of Linux, Macintosh, Palm, etc. operating systems to deal with; or
if you could use a built-in stopwatch with a virtually limitless recording lap timer; or
if you're a science / engineering student or practitioner who is looking for real, number-crunching programmability (including conditionals, looping, etc.), but can't invest the time and money to become a semi-professional programmer, or
if you want complete control over how your calculator looks and operates;
then sCal is for you. Small, free, Open-Source, portable, programmable, safe.

The author of sCal is a registered user of Calc98, and would hate to be without it. But there's some reason why he spent all the time to write sCal. Many (many) years ago, as a civil engineering student, with volumes of conversions, formulae, and procedures plus their applications and limitations to remember, there was always a need for something more than a slide rule or even a normal calculator. Time is better spent on knowing the principles, the right numbers to plug into what application, versus the actual grinding through them.

_ _ _ _ ^top^ _ _ _ _

Q: Current Versions? Why so many?

A: There are several versions of sCal in this release: ver.0.8, ver.p.8, ver.0.9, and sCal2-ver.0.8. These are all interim versions which go beyond the ordinary stable beta release. Find more detail in the Release Notes at the SourceForge Project Site and included with the download package sCal-8-9.zip. In short, work is well underway for sCal ver.1.0. Version p.8 (originally customized for the Pocket PC) to 0.9 is on the main line to this. Catagories will be handled somewhat differently and JScrAps should be totally interchangeable between the lean, fast-loading sCal and an extended X-version.
The larger scale formats of 0.8 are dead ends. They don't fit on the Pocket PC screen, especially the double-width of sCal2--which, in addition, uses a method of menu population that doesn't work in Pocket Internet Explorer 2003. Otherwise, these extra catagories provide hundreds of additional examples in mathematics, materials, physics, probability, statistics, data management, and even some simple games. And, it has 20 additional memory slots that are used very effectively for Input/Output. Programming these is not compatible with the single screen version though. That's why this release is so fat. If anyone else wishes to take up further developement along the sCal2 line, they are welcome to do so; and will have all the development work so far to start from (or discard as seen fit).
If your consideration is only operational, you should stick to sCal-ver.0.9 and sCal2-ver.0.8.

_ _ _ _ ^top^ _ _ _ _

Q: Online calculators?

A: sCal designed for off-line use. Web connections can become unreliable, and power consuming on a PPC.

_ _ _ _ ^top^ _ _ _ _

Q: License, Price, Registration?

A: None, None, None.

_ _ _ _ ^top^ _ _ _ _

Q: Install / Uninstall?

A: Just transfer the file where you want it. Delete it if you no longer want it. The default Browser is registered to read HTML files. If you paste sCal in the "Program" directory/folder, or make it a Favorite / Bookmark with the browser, it may be easier to call up. It depends on your style.

_ _ _ _ ^top^ _ _ _ _

Q: Why program in JavaScript?

A: A good question. JavaScript is hardly anybody's favorite programming language. Nonetheless it has several things going for it:
• Its an interpreted scripting language. For some applications, notably huge, complex ones, a compiled program has clear speed advantages and, once compiled, is dificult to tamper with. sCal is no such application. It works as a calculator, with short opertions to a quick answer. Any speed difference is simply not noticeable. And sCal is designed to be tampered with--only its called user customization. The malicious hazards of this are minimal. (Code that doesn't do exactly what you want it to, is another story. Always retain a good copy before you start mesing around.) JavaScript does not allow most of the low-level operations that C/C++ and Java provide. Except for cookies, you cannot even write directly to the hard drive with JavaScript. Furthermore, you can see and read ALL the code. You can't get more "Open Source" than that.

Open source code has its own virtues, and disciples. As you're picking this up from Sourceforge.net, you are well within the Open Source camp. You can follow any of a number of links to find out more. Many programs are available in Open Source that perform as well as, and in some applications, better than alternatives with proprietary code. Sometimes not. Sometimes there are no alternatives. sCal is one of those programs that would not be as effective in terms of flexibility if it were not Open Source.

  • No runtime library; no compile step; no compiler to learn: switches to set, files to include,... You can write JavaScript and HTML with just about any common text editor; save it with an '.htm' extension, and then run it. You don't need anything more as long as you already have a properly installed, modern web browser (so it knows what to do with a file with an '.htm' extension, and is not so senile that it can't interpret JavaScript). That's probably the browser you're using to read this now.
  • Easy Modification While running sCal in most browsers, you can click View->Source Code, and the code will come up in a text file. (With some browsers you will need to start from the File menu to get there.) Make any changes you want. If you then save the file with the same name, you can re-activate the sCal window and click View->Refresh. Any changes you made will be expressed IMMEDIATELY. If you start out in any decent HTML editor, you can switch back and forth between the Program and the Editor without losing your place or using a Save step.
  • JavaScript has the eval(x) function. Therein, x is a string. A string could be any bunch of ordered characters: 'Hello, World.' or 'qwertyuiop' or, for sCal to work properly, a valid JavaScript statement or statements. It works like an interpreter inside the interpreter, evaluating the string sent to it.
  • Besides eval(x), JavaScript has a reasonably full complement of other functions, and/or properties and methods, in the object oriented jargon. Math, time, arrays, conditional branching, looping, and more--all with a syntax similar to C/C++ and Java, though a great deal simpler in implementation.
  • Together with HTML, JavaScript is designed to work the same across any browser and operating system in a common environment: the World Wide Web.
  •
  •

_ _ _ _ ^top^ _ _ _ _

Q: How can you do even the basic calculator functions in 20 kb?

A: The key to sCal's small size is the browser and the eval(x) function doing the heavy lifting. A complete parser does not have to be built into the program. sCal only needs to supply a skeleton of variables and functions (the sCal-eton) to support it, and a form (the calculator face) to give the Input/Output features.

_ _ _ _ ^top^ _ _ _ _

Q: How can I tell if it will work on my system?

A: Use the Links at top of this page, or the web page. sCal2 will not appear, however, unles you've downloaded the full package, sCal-8-9.zip located about halfway down the SourceForge Project Page.

_ _ _ _ ^top^ _ _ _ _

Q: OK, but it looks bad on my browser / operating system.

A: sCal has been sucessfully tested on Windows systems (98, NT, 2000, XP, and Mobile 2003) using Internet Explorer (IE)(versions 5 & 6); Netscape (ver.6) / Mozilla (ver.1); Opera (ver.7); and Pocket Internet Explorer (PIE) for Windows CE. Due to lack of availability, other common systems: Macintosh, Linux, Palm, etc. have not been checked.

I don't know if anyone makes a browser for the Palm Operating System that can interpret JavaScript 1.3 (Netscape) or JScript 5.0 (Microsoft's version) or ECMA Script 262 (European Computer Manufacturer's Assoc.). These are approximately equivalent and not even the latest and greatest implementations. (Windows Mobile 2003 claims JScript 5.5 compatibility.) In any case, Palm models with the 160x160 pixel screen would have a hardware problem with sCal. A 320x320 screen should work fine since the Pocket PC screen is 240x320. Color or gray-scale should make no difference.

The WEB is the common denominator, and sCal just uses HTML, JavaScript (see above comment) and some CSS (Cascading Style Sheet) information. These are not foreign languages to any modern browser.
Nonetheless, there is a continual problem with the layout display of sCal's Screen. Macintosh and (I believe) Linux use pixels to dimension "TextArea" and "text" boxes. These are the input boxes for the global x-variable (line 257+/- of the source code for sCal-09.htm and dimensioned 'rows=4' 'cols=21') and m-memory (line 270+/- with 'size=8'). Some experimentation with these values may coax the display into looking as designed. Other areas may need tweaking, too. A lot of effort went into incorporating CSS into versions 0.8 (both sCal and sCal, by two different methods) with little to show for it.
sCal-09 uses its browser check to set an extra space in Netscape/Mozilla button widths, but the layout is otherwise unadulterated. It ends up with variable button widths on desktop displays, but shows nicely on the Pocket PC (at least the ViewSonic PPC V36, set for medium text size). Version 1.0 hopes to take care of some of this. Any feedback to a SourceForge Forum will be appreciated.

_ _ _ _ ^top^ _ _ _ _

Q: I'm not a Scientist or Engineer. What good is sCal to me?

A: sCal is a good general calculator for its size, even if you stay with the bottom 2/3 of the face: the main x-display, memory functions and keypad. But, it should be comforting to know that if you're making a car purchase with the dealer supplying the financing arrangements through a bank, you can always check the payments vs. the quoted interest rate. The dealer may have snuck in a few points for himself as a service fee. Its legal. But its nice to know if you're shopping around.
Beyond that, one could imagine other uses:
Teaching Introductory Programming- Writing a JScrAp to run within sCal shows real results immediately, rather than using a big, intimidating SDK to make some pretty GUI screen that does nothing useful. And one is teaching JavaScript, a useful language itself, which further has syntax similar to C/C++ and Java. Yes, the loose typing can lead to bad habits, but the most recent versions of JScript support typed variables. Headers and switches and include files can be left for more advanced courses. (Actually, when basic BASIC was the typical starting language, one went directly into writing code. The output was text to a console type environment. sCal bears some similarity to that.)
Programming- In some situations it can be easier to test a complex stand-alone algorithm in sCal. Its interpreted code doesn't require a compile step; and the core logic of a function can be written and tested before thrusting it into the main program. Any problems are reduced to interactions with the other functions. Also, for certain types of functions, sCal is a reasonable ready reference. For the Math. methods (functions) especially, almost all of them are represented in Set2. All you need to do is select one and click the [js] button to have a reminder of how to code it.
Websites and Equipment/Service Supply- A Webmaster or Commercial Supplier (often the same) wishes to impart some sort of knowledge to his visitor or potential customer. A cooking site could, for example, provide its visitors with a copy of sCal (purged of the Civil Hydraulics routines and replaced with one's own) set up to convert teaspoons to ounces or recipes for 2 to recipes for 10. An artifical sweenter manufacturer might show how x-grams of his product replaces y-cups of sugar.
Professional/Technical Papers- For those that appear on the Web, JScrAps are highly portable. They can be inserted in a copy of sCal (substituting for the Civil Hydraulics and other not-genrally-useful stuff), and still is not a big load on a server (the average ad is huge by comparison) and provide the operating environment.

_ _ _ _ ^top^ _ _ _ _

Q: What's a Slide Rule?

A: A 'slip stick'. OK, its a device involving sliding scales as a method for adding/subtracting logarithms (therefore, multiplying/dividing numbers). It requires no batteries, supplemental displays, what have you now.
The A and B scales do this in a straightforward manor. The C and D scales have a single log cycle, and thus also become square root scales with respect to the A and B scales. The D1 scale is reciprocal of D. The K scale does cubes & cube roots.
The L scale is base10 logarithms--the only place on the slide rule where the graduations are evenly divided.
S and T scales are trigonometric: sine and tangent--or rather the logarithms of them. REMEMBER this: (the slide rule will NOT help you with decimal places)

• the sine and tangent of 0° is 0.0000. (This is the ratio of the side opposite to the angle to the hypotenuse and the adjacent sides, respectively.)
• sin(1°)=0.0175=tan(0°)
• sin(10°)~0.175 [-0.77% (0.1736)]; tan(10°)~0.175 [+0.76% (0.1763)] {Note that sine and tangent are very close together and nearly linear (within 1%) for angles less than 10°)
• sin(30°)=0.5=cos(60°). The cosine function is the sine(90°-angle). The tan(30°)=0.577. You don't need to memorize that; but you do need to know that tan(x°)=sin(x°)/cos(x°).
• sin(45°)=0.707=cos(45°) The tangent of 45° = 1.0000. The reciprocal of the sine (0R cosine) of 45° is 1.414 (which is also the square root of 2). Its the ratio of the diagonal of a square to its side.
• sin(60°)=0.866=cos(30°) =sqRt(3)/2 (This can be worked out from half of an equilateral triangle and the Pythagorean Theorm.)
• sin(90°)=1.000=cos(0°) The tangent of 90° = infinity.
So you look at the scales and see what gives you the known values.

Natural logs? Ln scale and maybe LL1, LL2, etc. (Hey, the Electrical Engineering students carried those big wide slide rules. You throw in a factor or 2.3 on common logs and its the same, only more error.)
There's more, but you get the idea. [Even if you don't have to use a slide rule, you should know some of this anyway. You may have to use a strange calculator some day. Its not always obvious if its giving trig functions in those pesky (for us Civil/Surveyor types) radians until you see what it gives for sin(30).]
People used these things, or a thick book of logarithms, or lots of paper and time with manual calculations (if they didn't need to take anything to a non-integer power and were game to doing an infinite series to get the logs), or a chugging, very expensive, desktop mechanical calculator. (I started out in a design shop with 7 other engineers, waiting for a turn at our only such machine.)
sCal is easy!

_ _ _ _ ^top^ _ _ _ _

Q: Say I'm from Mars; how does sCal work?

A: As every good Martian knows, calculators work differently. The very simplest ones tend to calculate answers as the data is entered. Algebraic ordered ones do multiplication and division before addition and subtraction, and wait for a function to be completed. Contrary types use Reverse (Polish) Notation. We won't go into that. sCal tends to the Algebraic style. Section 1.2 of the Draft Documentation covers this in some detail. There are a few points to highlight.
An Expression is built in the x-display. The typical calculator gives values (depending on its orientation) at interim steps. sCal only gives the final result (which may be interim to a larger calculation) when the [=] button is clicked.
Expressions can be entered from the built-in keypad or entered/edited from the desktop keyboard or hand-held pop-up keyboard. In the former instance, numbers are always appended to the end of the expression. In the latter, numbers are entered or deleted from the cursor position in the x-display. If, the cursor is in the x-display, the keyboard [Enter] will also do [=]. However, in the case of a Pocket PC, the code for the [Enter] key is unknown. (The extra [=] button to the right of the x-display overcomes this, and also gives an [=] when the keypad is buried beneath the pop-up keyboard.)
Expressions are also evaluated when some functions are clicked: eg: [1/x] does the reciprocal of the entire x-display after it is evaluated. It doesn't just do it on the last term. [x>m] does this too. The [^] evaluates the entire x-value to the left of it and takes it to the evaluation of the expression to the right of it. Thus only one [^] us allowed per expression.
The user can control the order of processing. The position of individual elements of an expression, parentheses, using the [=] and the memory keys keeps real-time calculations in sequence. JScrAps, code written in JavaScript, either directly from the keyboard or called from the menus or even pasted in from a separate text file, are parsed by the JavaScript eval(x) function.

_ _ _ _ ^top^ _ _ _ _

Q: Stopwatch Opertion?

A: The Draft Documentation gives some more detailed information, but the basics are:
After selecting the *}Timer - Stopwatch-{, [do] starts it. [js] brings up the source code, in which changing the C=/*CountDn.Sec*/ 0 from 0 to, say, 30 then clicking [=] will make it a 30-second countdown timer.
Memory buttons act like [Stop], [Lap], [Pause / Restart], and [Clear] though the names will not change on the button caps until version 1.0 is coded. In countdown timer mode, results from these buttons will be unexpected. Its best to let the timer run its course.
Default setting is 1/10 second. This is a compromise. Desktop operation will easily and accurately handle 1/100 second, but the Pocket PC (at least the ViewSonic V36) will only display the second value. The variable sC_t=100 can be changed to 10 in the source code for 10/1000 second (or edited in the JScrAp during initiation, tho its not 'permanent' that way).

_ _ _ _ ^top^ _ _ _ _

Q: What's a JScrAp?

A: A JScrAp is a JavaScript Application. (As of the end of 2003, Google drew a blank on the term JScrAp. So I'm assuming I can use it. It's pronounced 'J-scrap', meaning in addition, that its not a complete code, just a 'scrap'. It lacks all the up-front and back-end jargon, and the input/output (I/O) procedures in between. It consists only of:
a Call Name: a brief description that appears in the drop-down 'select' menu;
a Call Type: an optional } or { that is stuck on either side of the name, (and sometimes both ends if there's a default value which can be changed). It just tells the user whether the usual operation of the Code is invoked with the left [js] button (if data needs to be input in the Code) or the right [do] button (meaning the code is prepared to go ahead with its work operating on what is already in the x-display (by {x) or m-memory by {m) or perhaps elsewhere.
the Code which may be quite simple, for example(s):
Math.PI a constant, 3.14159.... that goes in the x-display. [do] it. Its the default of the top set. (Note in sCal version 0.9 or sCal2, there is and additional [o] or [1/x] button. This does the opposite, or reciprocal, of the [do].) If you click the [js] button, you'll see the code.
x*25.4 the conversion factor for inches to millimeters. Clear the x-display and enter 1. [do] it. The 1 is replaced by 25.4, i.e. 1 in. = 25.4 mm. Multiply this by 2. [o] or [1/x] that. OK, 50.8 mm = 2 in.
9*x/5+32 is the conversion of Celsius temperature to Fahrenheit. Whatever is in the x-display is x. [do] this with 0 or 100 (degrees C and find that the F equivalent of water freezing and boiling is 32 or 212. Note that there is also a F -> C conversion. Whether there is a [o] or [1/x] button, it does not give the opposite. F does not = 1/C because of the 32 constant. No warning is issued. Later versions might issue one, but the user is expected to know--i.e. be familiar with the JScrAp Code, shown by the [js] button.
I=/*int.%/prd*/ ;N=/*#.periods*/ ;P=/*Principl$*/ ;/*=repay/period @m eg: 9%APR (=0.75%/mo.) for 36mo, repay $10000 @ $318/mo.*/ i=I/100; y=Math.pow(1+i,N); m=Mr(P*i*y/(y-1),2)+'/prd.'; xRedo=1 OK--quite a leap here. This JScrAp is the second in the 'FINANCE' catagory. (The first is trivial, and only an example of simplicity.) Its Call: *}Cap.Recov: re-Pay clues us in by the *} on the left side that it's invoked by the [js] button. It contains variables which are not assigned a value. Trying to [do] it, will just return an error of some type (browser dependent). The 3 input variables: I, N, and P are labeled, in comments, on 3 separate lines to assist you in providing the input required.
Place the cursor at the end of the comment/prompt and enter the data. It will have to be done from the keyboard (since the keypad will add only to the end of the code. On PPC's the pop-up keyboard will cover most of the keypad, anyway. Also a box may appear after the prompt. This is a line-feed symbol. The cursor must be placed between the prompt and the box or JavaScript will not be able to associate the input with the variable name. It will seem to be on the next line.)
You know you're done with all the inputs when you see the /*= set of characters. Click the [=] button to perform the calculation. After that, in this particular JScrAp, is a short example of data input/output. (Its the Coder's option how to place any assistance info, if any.) After the end of the comment, */ is the real code--a standard Capital Recovery Factor computation. JavaScript, like all programming languages, ignores comments. They are just for us people to read. We can also read the code. It is difficult for us people to remember, but not a problem for sCal.

(The proper order is the Name first, then the Code. It catalogs in the source better that way. sCal2 does this in good order, sCal doesn't because it now uses mostly HTML in the Body, and its stuck with the "Select/Option Value" order. This will change with Version 1.0 and JScrAps will become interchangeable with little or no modifications.)

_ _ _ _ ^top^ _ _ _ _

Q: Currency Conversions are included. How often are these updated?

A: As often as you want. sCal has no on-line, automatic update process, and its probably not possible to do it in JavaScript. Two currency conversion factors: USD (U.S.dollars) to Euros and to Yen, are included in sCal purely as an example. Say you're traveling abroad with a Pocket PC. You'd update the conversion rate. Unles you have a favorite source, you could Google-up some conversion rates before you left and write them up in the sCal code. (Bankrate.com or x-rates.com appear high on the list.)
You can code in any conversion combinations you'll need. And be sure to adjust the date of the rate quote for future reference. Say its the same as the 15 April, 04 rate. Then, if you're in Belgium and something costs 15 Euros, you can punch that in the x-display of sCal, select the 'us$ > €uro' JScrAp from set 1, and click on [o]. Recall that this does the opposite of [do], so you'll get '€uro > us$' or 15.94. Say also that you're pricing this for a Japanese friend. You re-select the 'us$ > ¥en' JScrAp'. Since the display is already in USD, you can click [d], and find the original 15-euro price is 1948.6 yen. Unles you have a catalog of good prices for this object programmed into sCal (which you could do), your friend would have to decide if this was a good buy.

_ _ _ _ ^top^ _ _ _ _

Q: Other Conversions?

A: Lets say you want to convert from ounces to grams. If you know that there are 16 ounces to the pound, and 1000 grams in a kilogram, its only a small number of keystrokes away, using the pound to kilogram conversion to find that there are 28.35 grams per ounce. (1{lb(us)->kg}[do]/16*1000=28.349...) Not handy though. And lumens to candlepower will leave the default list of conversions stymied. You can look up additional conversions in many references and enter them manually. But once you've gone to all that trouble, why not add them permanently to the list.
sCal, in its basic version, is intended to be very small and undemanding. If you remove the Civil Engineering Hydraulics routines and references from Set 3, (which are included as an example of sCal power applications), and most of the other comments, you'll have a fairly complete scientific calculator in under 16-kb (which is the memory block size of many storage card types). Therefore it cannot include a vast supply of anything.
sCal2 and eventually sCal-X, eXtended, are repositories of JScrAps. There are whole Catagories of Length, Area, Volume, etc. to choose from. You can copy JScrAps from one to the other, usually with only a few, and later no, modifications.

_ _ _ _ ^top^ _ _ _ _

Q: Programming Resources?

A: There are many, many references, tutorials, and examples available in print or on the Web. Any search engine can find more than anyone wants to know. The classic References and User Guides for JavaScript are downloadable from Netscape, and for JScript from Microsoft. The source code for sCal illustrates the use of a lot of JavaScript. Reading code is a good place to start--though you'll find sCal is not formatted in classic style. There's a level of user of sCal who is not interested in tinkering with the sCal-eton. (With good reason. Unles you have a pretty good understanding of what's going on, changing a few characters to facilitate some operation may disable dozens of others.) Such a user may only wish to make some rearangements and add a JScrAp or two.
For such people, sCal uses very long lines. Without word wrap, one can better see the layout of the JScrAps, without line breaks. However, the longer ones are difficult to follow, even when word wrap is turned on. JScrAps are not full programs, though; they are relatively short and self-contained. Any function call is either within the JScrAp, part of the brief sCal-eton; or part of the JavaScript Language. (Some have rightly disparaged the original Basic Language for its GoTo statements. But at least you had a line number to find where the code continued. Function calls in large programs can leave one searching through pages of code to follow what's happening in a process.)

_ _ _ _ ^top^ _ _ _ _

Q: How do you program JScrAps?

A: The standard "Hello, World" example is covered in Section 1.5 of the Draft Documentation. It is ridiculously easy. So lets go on to the FINANCE Cap.Recov. operational example covered previously. A Capital Recovery formulation could well appear in any financial text as:
if i is the interest rate per period, expressed as a decimal; and
N is the number of periods (months, years, other) the loan is to extend; and
P is the Principal amount to be loaned out (or borrowed); then:
the amount to be repaid per period =
P i(1+i)^N
(1+i)^N-1

Now, lets repeat the Code from Question 14, except we'll recognize that the semi-colons are line-breaks and put them in physically. This is how JavaScript code might be laid out in a normal program. Further, for those with programming experience, lets pretend that its a function:


   function *}Cap.Recov: re-Pay

   {

       I=/*int.%/prd*/ ;  // User input values, call input routine.

       N=/*#.periods*/ ;

       P=/*Principl$*/ ;

       /*=repay/period @m eg: 9%APR (=0.75%/mo.) for 36mo, repay $10000 @ $318/mo.*/

        i=I/100;

        y=Math.pow(1+i,N);

        m=Mr(P*i*y/(y-1),2)+'/prd.';  // Program output values routine.

        xRedo=1

      }

One hopes that its quite clear that the code above (with a substitution so (1+i)^N doesn't have to be computed twice) is mostly a translation of the standard formula. That's all there is to it. But lets go through the JScrAp line-by-line:
First, few languages would allow you to name a Function this way--spaces, extraordinary symbols. A JScrAp Call Name allows a lot of flexibility in this regard, except for length. Be careful it doesn't overrun the usual length in the Menu select box. There is no rule for number of characters. It depends on the font the browser is using.
The next 3-lines assign the input variables. The typical programmer might rather name the variables with longer, explanatory names instead of the comment/prompts. That is certainly permissable in JScrAps, and good practice in long programs with lots of variables to remember. But JScrAps are short. I, N, and P are used immediately, in the next few lines (and then discarded, almost). Also, note that the variables are not typed. JavaScript uses the appropriate type. You could enter strings, and JavaScript would be happy, until the divide by 100 line, at least.
Note that there is a comment following the // on the first line of the 'function'. In a regular program, there would have to be some routine for the user to enter these variables. With a JScrAp, the code appears in an input box, and the user simply fills in the blank. Note too that the lines of code are terminated by a semi-colon, ;. This is usual when the end of a program line is not necessarily the end of a physical line.
The 4th code line is a multi-line comment, laid out between /* and */. The critical code here is the beginning /*=. Recall in the operational section, this is the notice to the user that he is done with all input variables and its time to punch the [=] button. It also tells sCal that it can stop the temporary replacement of the ; with the line feeds that assist with input. Otherwise, the code is compressed together. The code remains conpressed in the x-display beyond the /*= so it takes less scrolling if the user is interested in seeing it all without going to the source. The rest of the comment is an example with real data--a nice touch. The programmer can provide help in an alert box also. Or not. The comment must be closed with */ in any case.
The next 3-lines do the ordinary Capital Recovery Factor calculation. Interest, usually quoted in percent is changed to a decimal, y is defined as (1+i)^N to save code--since it is repeated in both the numerator and denominator of the final calculation. Note that the final calculation is placed in the Mr() function. This function is not part of JavaScript but sCal provides it in the sCal-eton. Mr is short for Math.round however it adds a second argument, the number of decimal places you want output. 2-decimals is nice for dollar amounts. In other monetary units, which work equally well in the basic formula, may have more appropriate precision.
m is RESERVED in sCal. [x is also RESERVED. Mr(),(as we have seen) Ix(), Im(), Ox(), Om(), xEval() and a few other functions are also predefined in sCal. There are also a number of reserved words in JavaScript.] You can use these as intended. x, Ix(), and Ox() are the GLOBAL JScrAp, input and output functions. m, Im(), and Om() are the GLOBALs for memory. Thus, a normal program would have to provide some routine for output, as commented on line 7 of the above code. sCal merely sets m= the computation. This automatically puts the output in the memory box for the user to view.
The final code line sets xRedo=1. xRedo is a Flag variable in sCal. The default is zero at all times except where set in a JScrAp. It is reset to zero following processing. Ordinarily, the results of a calculation will appear in the x-display. But it is convenient for the x-values to remain to redo the calculation. In the Capital Recovery example, one may want to see how the payments would change with another interest rate, keeping the principal and number of payments the same. If xRedo=1, the user can do this by editing in a new value following the [=] calculate.
Putting the output to the memory is fine for a short answer. If there is more output, one can do [m>x] to see it all, but that would replace the JScrAp in the x-display. It can be rerun, with the [js] button, but variable assignments would be lost. Sometimes it wouldn't matter. Other times you'd like to keep them separate. (In the future, more output will be generated for the Capital Recovery function--like total amount paid, total interest, and perhaps more--as sCal2 does.) In this case, you can manually, via Set2, Memory>alert box-{ see everything in an alert box. This is the same as programming xRedo=2.
Other options are expected in the future. The important thing is to have it in m first. You can't do much out of an alert box except view it and click OK. From the memory, one can Edit->Select All->Copy->Paste to a text file, or, via Set2 again, m -> TAPE -{ which stores any number of outputs sequentially. (By version 1.0, the TAPE should be date-stamped, and saveable to a cookie which restores sCal to its last-run status. Right now, the TAPE can be placed in the x-display for complete viewing with the scroll bar, copied/pasted to a text file, or transferred to m and sent to an alert box.)
sCal is designed to be a flexible tool, employing safe, user-accessable code. This is especially important if one is using it to perform calculations for which one is professionally responsible. (You surely don't expect ME to be responsible if you use the Manning Equation for non-uniform flow, do you? I can't even guarantee that the Manning Equation came through to you without some errant typo. You can check it for yourself, if you know what its about. Should you really be using it if you don't?)
To get back to the original question, how do you program JScrAps: you follow the pattern of existing JScraps, and they are plentiful in sCal2, and expected in sCal-x. Eventually (or now--there are a lot more and better programmers out there than me) you should be able to do most of what JavaScript offers in a JScrAp.

_ _ _ _ ^top^ _ _ _ _

Q: Program Anything?

A: sCal interprets what's in the x-display. A JScrAp can be most any legitimate JavaScript code. It doesn't have to be another number-crunching engine.
The following deals with text, of the HTML variety. It was written to remove the repetitious drudgery of making the Table of Contents for this Q&A document--just the kind of work that computers are designed to reduce.

<!--    This JScrAp adds Table of Contents (ToC) to HTML doc, linking to Headings (in this case, designated by <h3>. . . .</h3> tags--or other, as user edits) while inserting links back from those headings to the ^top^ (#sCal-QA-head, here).  NOTES: (1- Cut code between ToC location thru bottom of text with Headings; (2- Paste into sCal x-display;  (3- Click [x>m];  {3a- Cannot usually paste directly to m-memory, depends on Browser, some more tolerant (IE6) than others;  (4- Call this JScrap and [do];  (5- Copy/Paste from m back to original HTML document;  {5a- this routine likely ruins any nice formatting in original HTML.-->

    <option value="/*=see comments above*/ tLink='#sCal-QA-head'; topLink='<br> _ _ _ _ <small><a href='+tLink+'>^top^</a></small> _ _ _ _<br>';  Im(); var D1=m.split('<h3>'); for(j=1;j<D1.length-1;j++) {cutPt=D1[j].indexOf('</h3>'); a=D1[j].substring(0,cutPt); b=D1[j].substring(cutPt+5); Na='#'+j; D1[0]=D1[0]+'<a href='+Na+'>'+a+'</a><br>'+NL; D1[j]=topLink+'<h3><a name='+j+'>'+a+'</a></h3>'+b} m=D1.join(NL); Om();">
    *} <h3> >  html ToC {m</option> 

  <!-- also for the sCal-x "HTML JavaScript" section: make a routine to convert old style JScrAps to new.  Won't help the ones with n[0..19] arrays, but will save a lot of time on the conversion blocks: Length, Area, Force/Mass, etc.-->

This code illustrates some essential JScrAp concepts:
The JScrAp is interpreted from the x-display. That is why the text in this example must be put in the m-memory. This is common in sCal when data is preserved for manipulation, numeric or otherwise.
JScrAps are strings. JavaScript eval(x) evaluates strings. Therefore, JScrAps are defined inside quotes. Usually sCal encloses them in the double (") variety. Then one is left only with the single quotes (') to define strings within the JScrAp. Where a lot of strings are involved, one must take extra steps. An anchor is named, as a string, in quotes; but above, it is defined as tLink, a string, and then inserted as a variable. There are other work-arounds.
The explanation of a JScrap is usually longer than the code for it, even as clipped as the explanation is. The comment may appear as a user-defined help alert (by {!) in the final version, if it can be reduced enough to fit.
JScrAps are not coding miracles. The above example of automatic link generation solves a common problem. Others have probably written different, and often better routines, which do this. Finding them, is not always easy. And once found, where do you store and catalog them. sCal-X... is designed for that.

_ _ _ _ ^top^ _ _ _ _

Q: I've just written a great JScrAp (or set of them) (or extension of the sCal-eton). I think it will be useful to others and am willing to share it as public domain or under a generous public license. What do I do now?

A: Users are encouraged to submit JScrAps or other improvements (and I can't say I have lots of pride in the documentation I've put out so far, either) to any SourceForge Project Page Forum. Please include appropriate documentation to accompany what is not self-evident or ordinarily available in texts. Those that I can verify, I may include in future releases of sCal with due credit--either as a comment in the source code or larger. Those with significant contributions will be listed as developers.
Obviously, in specialty areas, I'll be unable to judge their suitability. Don't let that stop you. Your peers can make that judgement and copy them to their personal sCal setup. Or, under the GNU GPL, as I understand it, you can distribute your copy of sCal-x with your improvements. Admittedly, I've thought little about how the sCal website could facilitate this, if it ever happpens. Right now I'm committed to putting together sCal version 1.0, and then transferring the best JScrAps, and maybe some experimental ones, from sCal2 to sCal-X.

_ _ _ _ ^top^ _ _ _ _

R.Mohaupt, mgineer1@Netscape.net, May, 2004