VB Script Programming
Napier functionality can be greatly extended by VBScript programs which can be created on a desktop computer using an editor such as NotePad, or directly on the PocketPC using the built in VBScript editor in Napier. VBScript can be used to create new functions that can be incorporated in expressions used in Napier, and all Napier functions can be used from VBScript programs. The built in editor provides easy access to both Napier and VBScript statements and also helps with testing your code by allowing you to run your functions and showing the results and where any errors occurred. You can build VBScript functions that access the file system, display and receive user input, use standard dialogs, access the WinCE API, and use ADOCE and other ActiveX objects.
To get to the editor, tap the Tools menu entry and select Edit VBScript (see illustration above). This will start the VBScript editor with the source code currently loaded into Napier. To edit different code, first load it using the File menu, or you can create completely new code by entering it into the editor.
The largest VBScript file I’ve used is over 2000 lines, the only limit to program size is the 65,000 character limit imposed by the edit control, this is approximately 2500 lines of code. As discussed above, a file with callable Functions and Subroutines can be loaded and then the functions used in expressions and assigned to keys. All the functions that can be used in expressions in Napier itself are available to loaded VBScript programs, as are the memories and the Data Set. Keep in mind that in addition to the reserved words in VBScript, all the Napier functions are defined, so don’t try to create a global variable named min or max. All names in VBScript are case insensitive, so Min is the same as min or miN.
For a function to work in a Napier, it must return a value that can be used as a double. All variables in VBScript are variants, but inside Napier, everything is treated as a double. Similarly, if a Napier function is used as an argument to a VBScript function, it will pass in a double. There are a few functions, which take text arguments, but they are exceptional cases. You can use functions which return strings with the Eval and Run functions in the immediate execution environment, but within Napier itself, only double values can be used.
Edit Menu Functions
There are more editing commands under the Edit menu button.
Code Block Buttons
Because of the relative inconvenience of text entry on a handheld device, Napier’s editor provides many code blocks that can be easily inserted into the code and then used as is or modified. For example, to enter an if..then..else block, you can just type it in, or tap the Stmts button (in the second row of keys). This will drop down the InfoBox with a set of standard VBScript statements.
This will insert the block at the current cursor position in the Main Text Window.
Now you can add your own code by bringing up the keyboard or other input display and entering the text. As you enter text, the editor will keep the left indent the same as the previous line whenever a carriage return is entered. You can enter tab characters by using Ctrl Tab, however you can also indent and exdent text lines by using the arrow buttons down in the bottom command bar. These will work on individual lines or as many lines as are currently selected.
Run and Eval Commands Window
The Run and Eval buttons need a statement to execute. To do this, the main text window will change to another where you can input a command to execute when you tap one of these buttons. You can enter several commands on different lines and choose which you want by putting the cursor on a line, then tap the Run or Eval button.
You can also get to this screen by tapping the Cmds button. You don’t have to call a function you’ve written with Run or Eval, any VBScript single line statement can be entered and executed which can be useful if you are trying to set up a Napier environment to test with. Of course, you can also just write a function to do that, or save a Start State file with Napier set up as you want for your test.
Testing The Code
Napier’s VBScript environment supports several functions designed to help test code. The first is whenever an error occurs, the editor scrolls the source code to the line where it occurred and displays an error message. The other test related functions are designed to help display the state of the execution. These functions are all available by tapping the Msg button.
MsgBox and InputBox
These are built in VBScript functions that pause execution and put up a Message Box. The InputBox command returns a string the user enters, while the MsgBox command just displays a message and returns if the user tapped OK or Cancel. These can be used to show what is going on inside the program and, depending on the input, continue or stop.
Debug Memories - DM(1) to DM(100)
These are memories used for debugging that can hold both numeric and text values. They are intended to be used by the program to store state information which can later be examined by displaying the list of DM’s with values using the DM button. This will display the list of DMs and their values in the main text window. Running the DLoad example below with Eval of DLoad (3,5,.9), then tapping the DM button will show:
Debug output printing - VBOutput
This is the equivalent of the venerable Print statement. The ClearVBOutput command clears the text in the VBOutput buffer, then each call to VBOutputWrite appends a line to it. To see what’s in the buffer, tap the Output button. This will display the current output buffer in the main text window. Using the above described example, tapping the Output button will show:
Execution Information Messages - InfoMsg
This can be used for debugging, but is mainly intended as a way to display some information to the user as a supplement to the value returned by a function when used in a Napier expression.
InfoMsg ( text ), returns nothing – the text from this is saved inside Napier until the current execution completes, then the text from the first call to InfoMsg during that execution is displayed rather than the normal extended precision answer display. This is used if you have a function which is returning some sort of information for the user. Note that if more than one function in an expression calls InfoMsg, the first one wins, its message is displayed, the other is lost.
Execution Errors - ExecErr
This can be used for debugging, but is mainly intended as a way to report a runtime error during normal use inside Napier expressions. A common use is to report that some input was out of legal range and the function couldn’t compute an answer, e.g. log(0). If ExecErr is called, it prevents further execution of the Napier expression.
ExecErr ( text ), returns nothing – this signifies that there has been some sort of internal error in the function and that the resulting answer is invalid. Like InfoMsg, the first call to this in an execution has its text displayed, subsequent ones are lost. If ExecErr is called during an execution, the answer is not displayed, the original expression is kept, and the text from the ExecErr call displayed in the information box.
IsExecErrSet ( ), returns Boolean – If there already has been a call to ExecErr, this will return True, if not False.
Example VBScript Code
These are from the file “LorentzM.txt” which is automatically loaded into the My Documents directory when Napier is installed.
Lorentz
' Calculates relativistic time dilation
' speed - fraction of c
Function Lrnz (speed)'{A}6 -10"Lrnz""Lrnz ()""Lrnz: Lorentz eq""(frac c) = dilation" "Enter fraction of c"
If (speed >= 1) Then ' no superliminal speeds
ExecErr("If you want to go that fast," & vbCrLf & _
"you'll have to go somewhere else")' stops computation
Lrnz = 0
Exit Function ' bomb out
End if
If (speed < 0) Then ' hassle user about neg speed, but continue
InfoMsg("You're going backwards") ' just puts out message
End If
Lrnz = (1-speed^2)^.5 ' calc dilation
End Function
Dload
' Loads the data set with pairs of (1) speed – fraction of c, (2) time dilation
' startIdx – Index in the data set to start loading answer pairs
' startValue – Fraction of c to start with
Function DLoad (startIdx, count, startValue)'{A}3 -30"DLoad" "DLoad (,,)" "DLoad: Load data set""(idx, cnt, val) load data" "(start, count, value)""load data set starting at idx" "with cnt entries of val + i"
diff = 1 - startValue ' how much for each step
ClearVBOutput ' clear debug output to start
For i = 1 To count ' step through data set
DM(1) = i ' into memory
If IsExecErrSet() Then ' already in error?
rtrn = InputBox("There's been an error")' just talk to user
If rtrn <> "" Then ' reply from user?
MsgBox "You said: " & rtrn ' talk back
DLoad = 0 ' return 0
Exit Function ' exit
End If
fract = 1 - diff ^ i ' keep approaching 1
DM(2) = fract 'what fraction of c
dilation = Lrnz (fract) ' get dilation factor
DM( 3 ) = dilation
Data(startIdx + (i - 1)*2) = fract ' first of each pair is speed
Data(startIdx + (i - 1)*2 + 1) = dilation ' second is dilation factor
VBOutputWrite fract ' results to output
VBOutputWrite dilation
Next
DLoad = count ' just return something
End Function