
                      Paul Jones and PJCO present...
    __  __          __    __      __                 ___       __     
   /\ \/\ \        /\ \__/\ \  __/\ \               /\_ \     /\ \    
   \ \ `\\ \     __\ \ ,_\ \ \/\ \ \ \    ___   _ __\//\ \    \_\ \   
    \ \ , ` \  /'__`\ \ \/\ \ \ \ \ \ \  / __`\/\`'__\\ \ \   /'_` \  
     \ \ \`\ \/\  __/\ \ \_\ \ \_/ \_\ \/\ \L\ \ \ \/  \_\ \_/\ \L\ \ 
v1.42 \ \_\ \_\ \____\\ \__\\ `\___x___/\ \____/\ \_\  /\____\ \___,_\
       \/_/\/_/\/____/ \/__/ '\/__//__/  \/___/  \/_/  \/____/\/__,_ /
                                                                   
                ...use STiK with HiSoft BASIC and STOS...                                                                   
            Exclusive Atari Computing version - HBASIC version.


Disclaimer
--------------------------------------------------------------------------

PJCO, Paul Jones or Atari Compuing can not be responsible for any 
damage caused to your computer, or high phone bills caused by 
developing internet clients when using NetWorld. ;-)

What is it?
--------------------------------------------------------------------------

NetWorld allows you to use STiK - the ST internet Kit - with HiSoft 
BASIC to connect to the internet!

Installation
--------------------------------------------------------------------------

1) First you need to update your libraries. To do this find your LIB 
   folder (which contains your library .BIN files), copy NETWORLD.BIN 
   there and double click on BUILDLIB.TTP. For parameters, enter 
   "NETWORLD -q" and press [return]. The program will now make a file 
   called HBASIC.LIB.
   
2) Copy the new HBASIC.LIB file to the same directory as your HBASIC 
   editor.

3) Rename NETINC1.BAS or NETINC2.BAS (depending on which major version 
   you are using) to NETWORLD.BAS into your include folder. Also copy 
   TRANSPRT.BH there too.
  
4) Whenever creating programs which use NetWorld, add the line "rem 
   $include networld.bas". This file contains the commands found in 
   the file "INCSPEC.TXT" and the library commands.

5) Program an internet client!

What can you do with NetWorld?
--------------------------------------------------------------------------

Well, the things I know you can do are a:

* Emailing program (Antmail)
* USENet (news) reader (NEWSie)
* IRC program (Internet Relay Chat - example FracIRC).
* Telnet program (Telnet)
* HTML viewer (CAB)
* FTP (MG-FTP)
* Gopher

What's this "TCP/IP" jargon about? (the Internet story)
--------------------------------------------------------------------------

TCP/IP stands for Transmission Control Protocol over Internet 
Protocol, and is the standard method of transfering data over the 
internet.

This internet protocol actually was designed for military purposes. In 
1969, the US Defense Department started work on the Advanced Research 
Projects Agency NETwork, ARPANET for short. To continue funding from 
the US, the project had to show that it had military defence purposes, 
so it renamed itself DARPANET - Defense Advanced Research Projects 
Agency NETwork.

The idea was to have a communication system which would stand any 
attack, in those days mostly from fear a nuclear war. A packet of data 
would be sent from one computer, and arrive at the destination, except 
the data wouldn't go through one central computer (which might be 
bombed in an attack), but would be split up through several nodes. If 
one access message system hasn't working, the messages could re-route 
themselves around this until all packets arrived at the destination.

This system was using the TCP/IP protocol by 1974, but it became 
standard when the University of Berkley implemented the DAPRA Internet 
software, and gave the source code to Public Domain.

The military gave up this method of communication in 1989 when it 
became common knowledge, at which the system changed it's name: the 
InterNet - the International Network.

So how do I write an internet client?
---------------------------------------------------------------------------

Well, that would be telling wouldn't it! :-) STiK clients should 
follow these main pointers:

1) Check stikinitialised. If it's equal to one (1) then STiK can be 
   used, if it's a negitive number, STiK isn't installed correctly and 
   shouldn't be used.
   
2) Find the correct host name and port, then do a TCP_connect(). This 
   should connect you to the host. If you want to write your own 
   routines using resolve() and TCP_open, then do so. Check my 
   include routines for an example for how to do this.
   
3) Always check for errors and data. If there's an error, report it to 
   the user (otherwise the person might get tired of waiting and start 
   taking it out on his Atari hardware). If nothing happens for a 
   while, try doing a cnkick().
   
4) ALWAYS atempt to close the port. I've found (through experience) 
   that if a port is not closed and you log off, STiK always reports 
   "Close all connections", which nearly always crashes the machine 
   if you click on 'yes'!
   
5) The STiK command reference says to use ser_disable() and 
   ser_enable() when attempting to use the DMA or serial port. To make 
   sure of the correct use of this command, everytime you want to 
   write/read something to disk, disable the port:

   c=cnbyte_count (cn)
   ser_disable dummy()
   PRINT #1,"Hello there! STiK with HBASIC with NetWorld!"
   PRINT #1,"Number of bytes waiting: "+STR$(c)
   ser_enable dummy()

The TRANSPRT.BH file...
---------------------------------------------------------------------------

The TRANSPRT.BH file contains constants for several STiK error codes 
and wait status'. This file will automatically be added if you include 
the NETWORLD.BAS file. A typical file should start:

	rem $include networld.bas

If you want to release your code, or make it more readable, and if 
referencing to error codes by numbers, try using the consts instead. 
If there is a value below E_NORMAL (which is actally 0) then there is 
an error.

An example please...?!
---------------------------------------------------------------------------

Included are two, yes TWO examples, one is called EXAMPLE.BAS (is 
your imagination running riot again Paul? - Ed) which will display 
certain information about the STiK transport layer, the NetWorld 
version and all the internal STiK errors - so don't worry - you're not 
doing anything wrong!

The second example is called TELNET.BAS - because that's what it is - 
a telnet example. I throught a Telnet example would be the best 
example because it shows you how to use the important commands for 
connecting, checking for data, getting it and sending back a response. 

Believe it or not, you can send email, read/send news, FTP, HTML and 
Gopher with this little example! You first type in a host and port, 
and it connects to it, and waits for you to send data. It's a little 
slow, but after all, it is only an example :-)

At the desktop enable STiK and connect to your internet server, then 
run TELNET.PRG

An example to send a mail:
   Connect to your email server (in my case this is 
   mail.zetnet.co.uk), and use port 25.

   You should receive something like:

220 irwell.zetnet.co.uk ESMTP Sendmail 8.8.5/8.8.5; Sun, 3 Aug 1997 17:56:21 +0100

   Type in "HELO localhost". Press [return]
   
250 irwell.zetnet.co.uk Hello man-084.dialup.zetnet.co.uk [194.247.41.104], pleased to meet you

   Type in "MAIL FROM: <your email address here> RET=FULL". Insert 
   your email address where needed. For this, I need to type in "MAIL 
   FROM: <paulat.jones@zetnet.co.uk> RET=FULL". Press [return]
   
250 <paulat.jones@zetnet.co.uk>... Sender ok

   Type in "RCPT TO: <paulat.jones@zetnet.co.uk>". This will send an 
   email to me, you can simply change the email address there for any 
   if needed. Press [return]
   
250 <paulat.jones@zetnet.co.uk>... Recipient ok

   Type in "DATA". Press [return]
   
354 Enter mail, end with "." on a line by itself

   Type in (pressing [return] for each line):
   
   Subject: Hello Paul!
   From: your name <your email address>
   To: <paulat.jones@zetnet.co.uk>
   Reply-To: <your email address>
   X-mailer: Paul's Telnet example
   X-comment: Isn't it brill!!!!
   
   (then press [return] twice after pressing [return] for the 
   X-comment message)
   
   Hello Paul,
   
   This is so good... I'm going to write an internet client RIGHT now!
   
   .

   (the above is a single full stop at the start of a line with 
   nothing else).
   
250 RAA30039 Message accepted for delivery

   Type in "QUIT".
   
221 irwell.zetnet.co.uk closing connection


Well done, you've just your own email! Simple eh!? The first three 
numbers of the incoming text are an error code - as you can see here, 
this is what the numbers should be... and now you should begin to 
realise that this is how an emailer tells if the mail was sent 
correctly or not...

The program will (after a closure) attempt to go to the beginning 
asking for another hostname, if you don't want one, just press 
[return] and it will now quit. If it doesn't go back for about 10 
seconds, press [esc] to escape. If you want to do anything else, go 
back into the program.

You can of course test the above by sending a message to yourself! 
With this method, which is how the internet clients actually 
send/receive data, you can do anything.

An example to receive an email:
   Connect to your mail server on port 110.

+OK UCB Pop server (version 1.01/Zet) at zetnet.co.uk starting.

   Type in "USER", press space and then type in the part of your email 
   address which comes before the @ symbol and then press [return]. In 
   my case, I would type in "USER paulat.jones".
   
+OK Password required for paulat.jones.

   Type in "PASS", then space, your email password and then press 
   [return]
   
+OK paulat.jones has 6 message(s) (11807 octets).

   I have six message which total 11807 bytes. I can now download a 
   message. If you haven't got any messages, try sending one to 
   yourself!
   
   To get a message, type in "RETR", then a space, then the message 
   number, then a [return]. For example, if I wanted to download 
   message 1, I would type in "RETR 1".

+OK 1038 octets

   The size will be different for every mail of course, then the 
   server will send your message. Oh look, a message from Joe! 

Received: from tom.compulink.co.uk (tom.compulink.co.uk [194.153.0.51])
	by irwell.zetnet.co.uk (8.8.5/8.8.5) with ESMTP id MAA15169
	for <paulat.jones@zetnet.co.uk>; Wed, 6 Aug 1997 12:20:15 +0100
Received: (from root@localhost) by tom.compulink.co.uk (8.8.4/8.6.9) id MAA15599 for paulat.jones@zetnet.co.uk; Wed, 6 Aug 1997 12:20:27 +0100 (BST)
Date: Wed, 6 Aug 97 12:18 BST-1
From: jconnor@cix.compulink.co.uk (Joe Connor)
Subject: Re: Testing 1,2,3...
To: paulat.jones@zetnet.co.uk
Reply-To: jconnor@cix.compulink.co.uk
Message-Id: <memo.148977@cix.compulink.co.uk>
X-Mailer: Cixread v3.5 

In-Reply-To: <199708052007.VAA23593@irwell.zetnet.co.uk>


Hi Paul,

>This message is being typed in by me with the example program. Does it 
>work? Please reply to let you confirm you want the latest copy. Loads 
>of extra things in now... in fact, I'm quite impressed with it myself 
>:-)

Coming through loud and clear! Well done!
Please do send me the latest version...

Regards

Joe


.

   All message finish with a full stop on a single line BTW. If you 
   now want to delete any messages, type in "DELE" followed by space, 
   then the message number, followed by [return].

+OK message 1 deleted

   Now, to quit, type in "QUIT" followed by [return]! 

+OK Pop server at zetnet.co.uk signing off.

     
For other stuff, try your news server on port 119. A good place to 
start is to connect onto the server and as the command type "HELP".

You can quit when having a telnet session by pressing [esc]. The 
telnet program also creates a "TELNET.LOG" file which is appened all 
the time and contains all the server/user interaction, so don't worry, 
your telnet session is recorded!

For more information on what you need to send/receive, try searching 
for "RFC" in Yahoo (http://yahoo.com).

Legal beagle
---------------------------------------------------------------------------

NetWorld is freeware, which means that no money should be payed for 
using this software. Any internet clients which use this extension may 
do so, without any money being payed to the author of NetWorld. 
However, I suggest you mention that the client is made with NetWorld, 
as it will give me some reason to carry on developing it. As this 
extension is an Atari Computing exclusive, THIS DISTRIBUTION MAY NOT 
BE UPLOADED OR COPIED ANYWHERE.

Please feel free to give me ANY comments about the library as I would 
like to know what improvements/adjustments could be made. I would also 
find it interesting if anyone asked me for more include library 
routines.

This extension is programmed in 68000 machine code with Devpac 3. It 
took about 2 and a half hours to program. This version is 1.42.

Contact
---------------------------------------------------------------------------

I (Paul Jones) am contactable from my email address 
"paulat.jones@zetnet.co.uk" or from the Atari Computing office. I also 
have a homepage at "http://www.users.zetnet.co.uk/pjones/home.htm".