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