NS BASIC Tech Note                                September 12, 1996

34. BASIC Internet Enabler (BIT)
-------------------------------------------------------------------

NS BASIC makes a very handy tool for accessing the internet. With it, you 
can create custom mail, news and web applications. By loading the BASIC 
iNet Tool (BIT) onto your system, you add a set of easy to use functions 
to NS BASIC that let you cruise the net from your Newt.

Table of Contents
-----------------
1. Prerequisites    2
2. General Comments    2
3. How to use the BASIC Internet Tool (BIT)    3
4. News    4
5. WWW    5
6. Getting Mail    6
7. Sending Mail    7
8. Testing Stuff out using Telnet    8
Appendix A: List of standard internet port numbers    9
Appendix B: Program Listing   10


Quotes from Beta Testers:

"I think BIT is a very good way to get access to all the possibilities and 
informations of the internet. The handling is very easy. Everybody with a 
little knowledge of Internet-protocols could do his own Newsreader, 
Emailreader, etc...  Great...;))))"

"BIT looks like a very fun tool. A superb addition to a more and more 
professional product."

1. Prerequisites
----------------
1. Newton MessagePad 130. (A Newton 120 2.0 probably has insufficient 
memory for this).
2. The Newton Internet Enabler (NIE) must be installed. (Available from 
http://devworld.apple.com/dev/newton/tools/nie.html
3. A modem
4. An account with an Internet Service Provider (ISP)
5. Internet Setup must have been performed
6. NS BASIC 3.0 or newer, installed on the Internal store.
7. Basic iNet Tool (BIT) must also be installed on the Internal store.

2. General Comments
----------------
The NS BASIC internet interface is designed to be very easy to use. In 
this document, we give some of the basics on accessing different internet 
services.
A good resource on how the internet works in general is located at 
http://www.freesoft.org/Connected. You might want to look at this to get 
information on more advanced uses of the internet services.

The BASIC iNet Tool is an add on piece of software which NS BASIC uses to 
access the Newton Internet Enabler. Small (less that 15K), it greatly 
simplifies the code needed in the NS BASIC program.


3. How to use the BASIC Internet Tool (BIT)
-------------------------------------------

To initialize BIT, put the following statement into your program:

BIT:=getroot().|bit:nsbasic|

You can now access the additional variables provided by BIT by referring 
to the in your program as BIT.. To call a function, use the 
expression U.BIT:().

BIT runs as a background task. You can ask it to do something, and leave 
it to run while you do other processing. Note that if you do so, you will 
take cycles away from BIT and it will take longer for it to work. Running 
BIT as a background task allows you to do a bit of housekeeping in NS 
BASIC and to set up a WAIT loop that can time out if BIT takes too long to 
reply.

Here are important variables and functions in BIT:

mConnect() 

This function establishes the connection. Before it can be called, the 
variables BIT.fConfigAddr and BIT.fConfigRPort must be set. If the phone 
connection has not been made, this function will also establish it, using 
the defaults in Internet Setup.

Send(text)

This function sends the text and clears u.fReceiveBuffer.

CancelRequest(nil)

This function allows you to cancel an outstanding request.

Receive(text)

This function returns a copy of current contents of BIT.fReceiveBuffer and 
clears it.

Cleanup()

This function releases the connection and frees up the memory used by the 
connection.

Rev()

This function returns the current rev of BIT.

The following variables are used by BIT:

fEndPointState    var   0 if idle, 1 if connected.
fReceiveBuffer    var   string data received from net. Max size is 8000.
fConfigAddr       var   string net address to access
fConfigRPort      var   integer port number to access. See Appendix A.
fstatus           var   the current status
4. News
----------------
To connect with news, use address "nntp.netcruiser" and port 119. (The 
address will be different with your service provider; the port will be 
standard. See Appendix A for a complete list of ports). For complete 
documentation on how to talk to a news server, see 
http://freesoft.mesa.net/Connected/RFC/977/

You'll get an initial welcome message back:

"200 tor-nn1.netcom.ca InterNetNews NNRP server INN 1.4unoff4 05-Mar-96 
ready (posting ok)."

Tell it what newsgroup you want:

group alt.food.wine

You'll get back :

211 206 16868 17075 alt.food.wine

This means there are 206 articles, numbered from 16868 to 17075.

To read the headers of some of the articles, send

xover 17000-17005

You'll get back:

"17070	Re: Old Liebfraumich...	"Roger L. Lustig" 	
Wed, 31 Jul 1996 22:51:21 -0400	<32001BA9.367© ix.netcom.com>	
<4tnroe$m9m© mcmail.CIS.McMaster.CA>	1092	14"
"17071	Re: Wine de Constantia, info needed	"Roger L. Lustig" 
	Wed, 31 Jul 1996 22:54:37 -0400	
<32001C6D.76ED© ix.netcom.com>	
	1590	31"
"17072	Napa Crush Begins	"Brian Boulden" 	1 Aug 
1996 04:50:45 GMT	<01bb7f64$195b6da0$a677ae8c© boulden.community.net>		1523	
22"
"17073	Re: Alsace	zincats© aol.com (ZinCats)	1 Aug 1996 01:00:41 -0400	
<4tpdlp$m8i© newsbf02.news.aol.com>	<31FD65C5.4774© widomaker.com>	992	8"
"17074	Re: Oregon Bound - Need Help	zincats© aol.com (ZinCats)	1 Aug 1996 
01:14:38 -0400	<4tpefu$mog© newsbf02.news.aol.com>	
<31FAFB21.2052© execpc.com>	793	5"
"17075	RE: Old Liebfraumich...	chris.anderson© dinosaur.com	Wed, 31 Jul 96 
23:06:55 -0700	<9607312306.0WH1U00© dinosaur.com>	
<4tnroe$m9m© mcmail.CIS.McMaster.CA>	1317	18"

To read a single article, send

article 17000

Ariticles may be any number of lines long, terminated by a final line that 
consists of ., or "\u000D000A\u.\u000D000A\u" in NS BASIC.

See the sample code in Appendix B for an example of accessing a news group.

5. WWW
----------------
To connect with a web server, use address "www.nsbasic.com" and port 80. 
(The address will be different depending on the web server you wish to 
access; the port will be standard. See Appendix A for a complete list of 
ports).

To get a web page,

GET http://www.nsbasic.com/

The data will come back and the connection will be closed. Note that while 
News lines end with CR/LF, web information that returns may end in just 
LF. At the end of receiving a page of data, the server closes the 
connection, so to see if the page is complete, wait for the connection to 
be terminated.

Web sites also have local programs that get run, using something called 
cgi. For example, to check a stock price, connect to location www.dbc.com 
and do the following command:

GET /cgibin/htx.exe/squote?TICKER=DOCSF

One NS BASIC quirk to look out for: the "//" that often appears as part of 
a URL confuses the NS BASIC scanner, which also takes // to mean the 
beginning of a comment on a statement line. To get around this, you may 
need to enter the URL as "GET http:/" & "/www.nsbasic.com/.

See the sample code in Appendix B for an example of accessing a web page.

6. Getting Mail
----------------

The program most commonly used to read news on a server is called POP3. 
Documentation for this can be found at http://www.imc.org/rfc1939.

To connect with a POP3 server, use address "netcom.ca" and port 110. (The 
address will be different depending on the web server you wish to access; 
the port will be standard. See Appendix A for a complete list of ports).

Here's a sample of the underlying dialogue that takes place. In your NS 
BASIC program, you'll duplicate this dialog. Lines entered by the user 
start with U:

U: telnet netcom.ca 110
Trying 207.93.1.148...
Connected to netcom.ca.
Escape character is '^]'.
+OK NETCOM v0.1 at tor-srs1 starting : built on Aug  2 1996 14:00:08.
U: user ghenne
+OK Password required for ghenne.
U: PASS xxxxxx
+OK ghenne has 0 message(s) (0 octets).
U: STAT
+OK 3 1766
U: DELE 3
+OK Message 3 has been deleted.
U: LIST
+OK 2 messages (1425 octets)
1 801
2 624
.
U: DELE 2
+OK Message 2 has been deleted.
U: RETR 1
+OK 801 octets
Return-Path: 
Received: from deliverator.io.com by tor-srs1.netcom.ca 
(8.7.5/SMI-4.1/Netcom)
        id PAA17679; Tue, 27 Aug 1996 15:28:22 -0400 (EDT)
From: gh© nsbasic.com
Received: from tor-srs1.netcom.ca (tor-srs1.netcom.ca [207.93.1.148]) by 
deliverator.io.com (8.7.5/8.7.3) with ESMTP id OAA16463 for 
; Tue, 27 Aug 1996 14:24:42 -0500 (CDT)
Received: from pentagon.io.com by tor-srs1.netcom.ca (8.7.5/SMI-4.1/Netcom)
        id PAA16699; Tue, 27 Aug 1996 15:23:18 -0400 (EDT)
Date: Tue, 27 Aug 1996 15:23:18 -0400 (EDT)
Message-Id: <199608271923.PAA16699© tor-srs1.netcom.ca>

This is line 1 of my message
and line 2.

.
U: QUIT
+OK Pop server at  signing off.
Connection closed by foreign host.

See the sample code in Appendix B for an example of reading mail.
7. Sending Mail
----------------

The most common program used to send mail is SMTP. Documentation for SMTP 
can be found at http://www.freesoft.org/Connected/RFC/821/1.html

To connect with a SMTP server, use address "netcom.ca" and port 25. (The 
address will be different depending on the web server you wish to access; 
the port will be standard. See Appendix A for a complete list of ports).

Here's a sample of the underlying dialogue that takes place. In your NS 
BASIC program, you'll duplicate this dialog. Lines entered by the user 
start with U:

U: telnet netcom.ca 25
Trying 207.93.1.148...
Connected to netcom.ca.
Escape character is '^]'.
220 tor-srs1.netcom.ca ESMTP Sendmail 8.7.5/SMI-4.1/Netcom ready at Tue, 
27 Aug 1996 15:23:06 -0400 (EDT)
U: HELO io.com
250 tor-srs1.netcom.ca Hello nsbasic© pentagon.io.com [199.170.88.5], 
pleased to meet you
U: MAIL FROM: gh© nsbasic.com
250 gh© nsbasic.com... Sender ok
U: RCPT TO: gh© nsbasic.com
250 Recipient ok
U: DATA
354 Enter mail, end with "." on a line by itself
U: SUBJECT: This is some test data
U: This is line 1 of my message
U: and line 2.
U: .
250 PAA16699 Message accepted for delivery
U: QUIT
221 tor-srs1.netcom.ca closing connection
Connection closed by foreign host.

See the sample code in Appendix B for an example of sending mail.
8. Testing Stuff out using Telnet
---------------------------------

Telnet is another of the basic services provided on the net. It allows you 
to establish a low level connection with any port on a service provider. 
There are a number of Telnet implementations available for for PCs and 
Macs.

You can test most of this stuff out using Telnet and your PC or Mac. 
Connect to your service provider, and start up telnet. (Unfortunately, not 
all ISP's allow you to access Telnet: Netcom is a good example. Let them 
know how you feel!) 

Once in telnet, you can type

telnet netcom.ca 25

The first argument is the address of the service provider and the second 
is the port number you want to connect to.

Try testing the commands you want to issue manually before writing an NS 
BASIC program to perform them.

Unfortunately, it's not so easy to create a Telnet application from NS 
BASIC. Telnet relies on special escape characters for its processing, 
which can appear at any point in the transmission. This requires character 
by character processing of the incoming data, which would need to be done 
a very low level routine - the standard code provided by Apple as part of 
the Newton Internet Enabler isn't set up for this.
Appendix A: List of standard internet port numbers
--------------------------------------------------
tcpmux          1/tcp                           # TCP port multiplexer 
(RFC1078)
echo            7/tcp
echo            7/udp
discard         9/tcp           sink null
discard         9/udp           sink null
systat          11/tcp          users
daytime         13/tcp
daytime         13/udp
netstat         15/tcp
qotd            17/tcp          quote
chargen         19/tcp          ttytst source
chargen         19/udp          ttytst source
ftp             21/tcp
telnet          23/tcp
smtp            25/tcp          mail
time            37/tcp          timserver
time            37/udp          timserver
rlp             39/udp          resource        # resource location
nameserver      42/tcp          name            # IEN 116
whois           43/tcp          nicname
domain          53/tcp          nameserver      # name-domain server
domain          53/udp          nameserver
mtp             57/tcp                          # deprecated
bootps          67/udp          bootp           # bootp server
bootpc          68/udp                          # bootp client
tftp            69/udp
gopher          70/tcp
rje             77/tcp          netrjs
finger          79/tcp
link            87/tcp          ttylink
supdup          95/tcp
hostnames       101/tcp         hostname        # usually from sri-nic
tsap            102/tcp                         # part of ISODE.
pop2            109/tcp                         # old pop port
pop             110/tcp         pop3 postoffice
sunrpc          111/tcp
sunrpc          111/udp
ident           113/tcp         auth tap authentication
sftp            115/tcp
uucp-path       117/tcp
nntp            119/tcp         readnews untp   # USENET News Transfer 
Protocol
ntp             123/udp         ntpd
imap            143/tcp
snmp            161/udp                         # network time protocol
snmp-trap       162/udp
smux            199/tcp

Appendix B: Program Listing
---------------------------

0010  rem demonstrate internet access -- IN
0015  cls
0020  print "Demonstrate Internet Access"
0030  print
0040  print "A. Get a news article"
0050  print "B. Get something from a web site"
0060  print "C. Get some mail"
0061  print "D. Send some mail"
0065  print "X. Exit"
0070  print
0080  print "Input Selection-"
0090  input Sel$
0100  if sel$="A" then gosub news
0110  if sel$="B" then gosub web
0120  if sel$="C" then gosub getMail
0121  if sel$="D" then gosub sendMail
0125  if sel$="X" then goto fin
0130  GOTO 0020

1000 news: rem get news
1010  LET bit:=getroot().|bit:nsbasic|
1020  LET bit.fconfigRAddr="nntp.netcruiser"
1030  LET bit.fconfigRPort=119
1050  gosub WaitForConnect //
1055  gosub waitForInputComplete //
1070  u.bit:send("group alt.food.wine")
1110  gosub waitForOneLine //
1120  LET x=u.bit:receive()
1130  u.bit:send("article" && substr(x,8,5))
1140  gosub waitForPeriod //
1150  PRINT u.bit:receive()
1195  return

1200 web: REM
1210  LET bit:=getroot().|bit:nsbasic|
1220  LET bit.fConfigRAddr="www.nsbasic.com"
1230  LET bit.fconfigRPort=80
1240  gosub WaitForConnect //
1250  gosub waitForInputComplete //
1280  u.bit:send("GET http:/" & "/www.nsbasic.com/")
1290  gosub waitForDisconnect //
1300  print bit.fReceiveBuffer
1395  return

1400 getmail: REM
1410  LET bit:=getroot().|bit:nsbasic|
1420  LET bit.fConfigRAddr="netcom.ca"
1430  LET bit.fconfigRPort=110
1440  gosub waitForConnect //
1450  gosub waitForInputComplete //
1475  u.bit:send("USER ghenne")
1480  gosub waitForOneLine //
1495  u.bit:send("PASS xxxxxx")
1500  gosub waitForOneLine //
1510  PRINT u.bit:receive()
1535  u.bit:send("RETR 1")
1540  gosub waitForInputComplete //
1550  PRINT u.bit:receive()
1570  u.bit:send("QUIT")
1580  gosub waitForDisconnect //
1590  return

1600 sendMail: REM
1610  LET bit:=getroot().|bit:nsbasic|
1620  LET bit.fConfigRAddr="netcom.ca"
1625  LET bit.fconfigRPort=25
1630  gosub waitForConnect //
1640  gosub waitForInputComplete //
1675  u.bit:send("HELO io.com")
1680  gosub waitForOneLine //
1695  u.bit:send("MAIL FROM: gh© nsbasic.com")
1700  gosub waitForOneLine //
1715  u.bit:send("RCPT TO: ghenne© netcom.ca")
1720  gosub waitForOneLine //
1730  u.bit:send("DATA")
1735  gosub waitForOneLine //
1736  u.bit:send("SUBJECT: Test Message")
1740  u.bit:send("This is line 1")
1745  u.bit:send("This is another line")
1750  u.bit:send(".")
1755  gosub waitForOneLine //
1760  u.bit:send("QUIT")
1790  return

2000 waitForConnect: REM
2006  if bit.fendPointState=1 then return
2007  temp:=u.bit:mConnect()
2010  do while bit.fEndpointState<>1
2020    wait 1000
2030  loop
2040  return

2100 waitForInputComplete: REM
2120  do
2125    LET l=strLen(bit.fReceiveBuffer)
2130    wait 3000
2140  loop until l=strLen(bit.fReceiveBuffer)
2150  return

2200 waitForPeriod: REM
2210  LET termStr="\u000D000A\u.\u000D000A\u"
2220  do while not endsWith(bit.fReceiveBuffer,termStr)
2230    wait 1000
2240  loop
2250  return

2300 waitForOneLine: REM
2320  do while strLen(bit.fReceiveBuffer)=0
2330    wait 1000
2340  loop
2350  return

2400 waitForDisconnect: REM
2410  if bit.fEndpointState<>1 then return
2420  do while bit.fEndpointState=1
2430    wait 1000
2440  loop
2450  return

9000 fin: REM
9010  if u.bit then u.bit:cleanup()
9020  end