LABTITLE=: 'Sockets and the Internet'
LABFOCUS=: 0

NB. =========================================================
Lab Section Introduction
For the duration of this lab it is assumed that you are connected to the Internet and have access to sockets. Once you have established a connection, sockets which are created by the socket driver can be connected to any service available on the Internet.

Load the socket utilities and cover definitions in z with:
)
load 'socket'
coinsert 'jsocket'

NB. =========================================================
Lab Section
Examples of servers which exist on the Internet are those which deliver Web pages, e-mail, and files. You contact them by addressing the particular machine on which they run, at a "well-known" port number. For example, Web servers are typically listening to port 80 for incoming requests.

For many of these servers, incoming requests are in the form of a single line, followed by carriage return and linefeed characters.
)

NB. =========================================================
Lab Section Web Server
To demonstrate we will connect to the web server running at our web site (www.jsoftware.com) and request a document.

First we will create a socket:
)
]sk=: 0 pick sdcheck sdsocket ''

NB. =========================================================
Lab Section
Next, we will find the address of our web server, and connect our socket to port 80 on that host:
)
]jsoft=: sdcheck sdgethostbyname 'www.jsoftware.com'  NB. find host
sdcheck sdconnect sk;jsoft,<80  NB. connect to port 80

NB. =========================================================
Lab Section
Now that we are connected, we send a single line using HTTP (HyperText Transfer Protocol) to request a document. The simplest form of request is the word "GET" followed by the document name.
)
sdcheck ('GET /download/testsock.txt',CR,LF) sdsend sk,0

NB. =========================================================
Lab Section
The Web server will find the document and return its contents along the same socket, which we can read now.  This is the same file you would get if you used a Web browser and went to the URL:  http://www.jsoftware.com/download/testsock.txt
)
; sdcheck sdrecv sk,1000,0

NB. =========================================================
Lab Section
Web servers are stateless, and handle a single transaction per connection. Immediately after sending the file, the Web server closes its end of the connection. We now close our end:
)
sdcheck sdclose sk

NB. =========================================================
Lab Section Simple Mail
E-mail is delivered from host to host on the Internet by mail agents opening connections on port 25 of the receiving host, and transmitting email using SMTP, i.e. Simple Mail Transfer Protocol, with the server there. This protocol is a simple dialog between the requesting program and the server, and can be used to inquire about mail addresses on the host and to deliver mail text.
)

NB. =========================================================
Lab Section
Each request by the sender is a single line terminated by a carriage return and linefeed. The response is one or more lines of text, each line preceded by a 3-digit result code. The exception is when the text of an email message is being sent to the server, in which case there is no response until the entire message has been sent.
)

NB. =========================================================
Lab Section
While this lab will not actually send an e-mail message, we will connect to a mail server in order to verify an email address.

Firstly, create a socket:
)
]sk=: 0 pick sdcheck sdsocket ''

NB. =========================================================
Lab Section
Next, we connect this socket to port 25 of the host jsoftware.com:
)
]jsoftware=: sdcheck sdgethostbyname 'jsoftware.com'
sdcheck sdconnect sk;jsoftware,<25

NB. =========================================================
Lab Section
The SMTP server immediately begins by sending us a greeting, which we will read now:
)
; sdcheck sdrecv sk,1000,0

NB. =========================================================
Lab Section
We will now begin our request dialog to verify an email address. The request is in the form  "VRFY" (verify) followed by the user name being tested. We then immediately read the socket. Because by default sockets are blocking sockets, the read will hang until the response is sent back by the server.
)
sdcheck ('VRFY sales',CR,LF) sdsend sk,0
; sdcheck sdrecv sk,1000,0

NB. =========================================================
Lab Section
In order to send mail to a user at this host, we could send a few transactions which name the sender and the recipient, and then include the text of the message.

Instead, we will simple terminate the session by sending the QUIT command:
)
sdcheck ('QUIT',CR,LF) sdsend sk,0
; sdcheck sdrecv sk,1000,0
sdclose sk

NB. =========================================================
Lab Section Summary
This lab has connected to a Web server and a server for delivering e-mail. There are other e-mail servers which permit the user to connect to his mailbox and read messagese.

Two common ones are IMAP "Interactive Mail Access Protocol" and POP3 "Post Office Protocol, version 3".
)

NB. =========================================================
Lab Section
Furthermore, connecting to the appropriate port addresses of hosts, and speaking the proper protocol, can permit access to a large variety of other services on the Internet.

For example: Usenet news groups "Net News Transfer Protocol", files, via "File Transfer Protocol", IRC "Internet Relay Chat", and Telnet terminal sessions -- some of the most popular aspects of the Internet.
)

NB. =========================================================
Lab Section
Some verbs have been included in a script to show the use of sockets to connect with services on the Internet.
)
load '~system\examples\socket\socklab.ijs'

NB. =========================================================
Lab Section
One of the verbs, fortune, retrieves a page from the www.jsoftware.com web site and extracts a random saying from the Unix "fortune" command.

To run it, advance to the next section.
)

NB. =========================================================
Lab Section
)
fortune ''

NB. =========================================================
Lab Section
This concludes this lab.  You may now disconnect your Internet session if it is no longer required.
)
