16. NS BASIC Tech Note

How to Handle Items in the In Box -- February 14,1996
------------------------------------------------------
Requirements: NS BASIC 3.x and Newton OS 2.0.

It's easy to link up the In Box's Put Away feature with NS BASIC. You can 
have
items in the In Box automatically picked up by NS BASIC programs and be
processed.

This feature can be used for a variety of applications. You could take the
incoming data and update it into your files. You could also have your 
Newton
automatically reply to incoming messages: see the Tech note entitled "How 
to
send email from NS BASIC" for more information.

Incoming messages could come from a variety of sources. They could be sent 
as
ordinary mail messages through the Internet, or by a specialized email 
package
such as enRoute, from Net Strategy Software.


Setting up
-----------
You first have to tell the InBox which messages should be sent to NS BASIC,
and then tell NS BASIC what to do with these messages. Here's some sample
code:

0010 rem register with In Box
0110 regInBoxApp('|basic:nsbasic|,"NSBASIC")
0100 rem set up a putaway function
0110 function putaway(x) :chain("PUTAWAY",x)
0120 LET getroot().|basic:nsbasic|.putaway:=putaway

Line 20 lets the In Box know what to do. The regInBoxApp() function takes 
two
arguments: the first is the symbolic name of the NS BASIC application. The
second is a string that is checked against the beginning of the Title of 
the
incoming message. If they match, the message is sent to NS BASIC when the 
Put
Away button is tapped.

Line 110 sets up the function to handle messages which are to be put away. 
It
uses the same mechanism as other applications which call NS BASIC: the 
CHAIN
function. The first argument is the name of the NS BASIC program to run, 
and
the second is the message itself that got passed from the In Box. The 
format
of the message is a frame, similar in format to the one that get 
constructed
in outgoing messages: see the Tech note entitled "How to send email from NS
BASIC" for more information.

Line 120 is the trick that makes this all work. We add the putaway 
function we
created into the NS BASIC application itself. It will stay there until the
Newton is reset - in which case, you'll need to run this program again. 
Later
revisions of NS BASIC may very well have this function built in, so the
putaway function will stick around.

To make the above example a bit more sophisticated, you could have the 
putaway
function you define in line 110 use the second word of the Title as the 
name
of the program to CHAIN to.

Processing items
----------------

In the above example, line 110 set PUTAWAY as the name of the BASIC 
program to
be run. Here it is:

0010 rem PUTAWAY
0020 print chainParam

The message being sent is in the variable chainParam: it's a complete frame
with lots of information. Slots you're likely to be interested in include:
chainParam.title
chainParam.text
chainParam.body
You can treat this data just like any NS BASIC variable: print it, alter 
it or
write it to a file.


For more information, see the Newton Programmer's Guide: Communications,
available on
http://devworld.apple.com/dev/newton/techinfo.html
Chapters 2 and 3 deal with transport
communications.