************************************* * * * DB/C Newsletter * * June 1995 * * * ************************************* Editor's Notes It finally happened! On May 31, we made the first test version of DB/C 9 available to early testers. If you weren't notified and would like to participate, please send an email message to 'dbc@swc.com' requesting to be included in the DB/C 9 early tester program. One of the more important new features in DB/C 9 is the ability to write programs to send and receive messages on any TCP/IP network (including the biggest TCP/IP network - the Internet). This month's article provides a tutorial on how to do this programming. don.wills@swc.com How To Program TCP/IP in DB/C 9 DB/C 9 gives the programmer direct access to the two most important Internet protocols, TCP and UDP, and to the DNS service. This article is a tutorial for how to write programs that use TCP, UDP and DNS. For complete details about programming each of these protocols, refer to the communications chapter of the DB/C 9 Developer Guide. We will use two sample programs to show the details of programming TCP using DB/C. These programs are FTP.PRG and WEB.PRG. The FTP program is an FTP client program. The WEB program is a WWW server program. Both programs are complete enough to be used in production, although both are missing some slightly used features of their respective higher level protocols. These sample programs are available in the /pub/misc/tcpip directory at ftp.swc.com. These are the relevant files: FTP.PRG (main program) WEB.PRG (main program) FTP.TXT (include file) WEB.TXT (include file) README.FTP (readme file) README.WEB (readme file) The readme files provide more detailed descriptions of the programs than are provided by this article. In this article, we will make reference to Requests For Comments (RFCs) and Internet Drafts. These are documents that describe Internet standards. They are available in many places, including the following ftp sites: nic.ddn.mil ftp.nisc.sri.com nisc.jrnc.net nnsc.nsf.net TCP communications takes place between two endpoints (also referred to as sockets). Endpoints are uniquely determined by their IP address and port number. An IP address is unique to the machine the endpoint is on, and is specified in one of the following ways: 199.3.63.33 atlas.swc.com These addresses are actually the same. The first is the four byte address used by the IP protocol. The second is in domain name format. The purpose of a Domain Name Server (DNS) is to convert an address in its DNS form into its four byte IP address. The port number element of an endpoint is a value from 1 to 65,536. Thus for any given machine, there are 65,536 unique endpoints. In practice, most operating systems allow a much smaller number of endpoints to be active at any one time. Port numbers are broken down into ranges that are available for different kinds of services. Ports 1 to 1023 are the "well known port numbers". For example, port 23 is the telnet port. This means that telnet server software listens for telnet clients on port 23. The list of standard port numbers can be found in many places including RFC1700 (Assigned Numbers) and the file /etc/services on most UNIX systems. Port numbers 1024-5000 are the "ephemeral port numbers". These port numbers are assigned to applications that request use of an endpoint without specifying a port number. This behavior is typical of a client application. These endpoints tend to exist for a limited time, hence the name ephemeral. Port numbers above 5000 are available to server applications by specific request. Server programs must use endpoints with predetermined addresses so that clients know where and how to connect with servers. The DB/C comopen statement is used to open a TCP connection. There are two ways to open a TCP connection, one as the client and the other as the server. The first is like this: cfile comfile comopen cfile, "TCPCLIENT " Just as with other types of communications operations, a comfile variable used as the anchor for a session or connection. The and parameters are the IP address and port number of the server to which the connection will be made. The IP address can either be in nnn.nnn.nnn.nnn or domain name format. For example, the following two statements will open connections to the DB/C FTP server: comopen cfile, "TCPCLIENT 199.3.63.33 21" comopen cfile, "TCPCLIENT ftp.swc.com 21" The endpoint on the client end of the connection will have the IP address of the client machine, and an ephemeral port number that the operating system assigns to it. You can use the comctl statement to retrieve the IP address of an endpoint, like this: ctl char 50 cfile comfile comopen cfile, "TCPCLIENT 199.3.63.33 21" move "GETLOCALADDR" to ctl comctl cfile, ctl The local address and port are moved into the variable named ctl. The way to open a TCP connection as a server is like this: cfile comfile comopen cfile, "TCPSERVER " When TCPSERVER is used in the comopen statement, an endpoint is opened waiting for incoming connections. The IP address is that of the local machine, and the port is as specified in comopen. When another application connects to this endpoint, the connection is actually be made on another port on the server computer. This insures that another comopen using the original port will continue to wait for connections on the original port. This means that after a connection is completed, comctl will return a different port number than the the port number specified in the comopen statement. Here is an example of opening multiple server connections on a port: cfile1 comfile cfile2 comfile cfile3 comfile comopen cfile1, "TCPSERVER 9999" comopen cfile2, "TCPSERVER 9999" comopen cfile3, "TCPSERVER 9999" Messages are actually transmitted using the send and recv statements. In the case of both TCPCLIENT and TCPSERVER, send and recv will each only be satisfied after the connections are actually made. Success on comopen means only that the socket was successfully opened. The syntax of the send and recv statements is as follows: send cfile, time; list recv cfile, time; list The time-out value is specified by time. It is specified in seconds. A value of zero means an immediate time-out. A negative value means no time-out. TCP is a stream based protocol. A send will be in a completed state when the requested list has been sent or a timeout or error occurs. The recv statement is slightly different. The comtst statement will show a completed recv as soon as any amount of data is available. This means that any use of message boundaries must be provided for by the application. UDP is a connectionless, message based protocol. Here how to open an endpoint for UDP communications: cfile comfile comopen cfile, "UDP " This comopen statement opens an endpoint with the IP address of the local machine and the port number specified by . The comctl statement returns this information in the same way as it does for TCP. A recv or send on a UDP endpoint results in a whole message being sent or received. In order to specify the destination for sending a message, the comctl statement is used. Here is an example: cfile comfile ctl char 50 msg init "hello" time init "-1" comopen cfile, "UDP 11005" move "SETSENDADDR=199.3.63.33 10005" comctl cfile, ctl send cfile, time; msg comwait cfile comtst cfile if (equal and not eos) display "success" else display "error" endif This code segment will cause UDP messages to be sent from local port 11005 to port 10005 on the machine at 199.3.63.33. After a UDP message has been received, the comctl statement can be used to find out where it came from. In the following example, if the recv is successful, the IP address and port of the program that sent the message will be placed in the variable ctl: cfile comfile ctl char 50 msg char 5 time init "-1" comopen cfile, "UDP 10005" recv cfile, time; msg comwait cfile comtst cfile if (less and not over) display "success" move "GETRECVADDR" to ctl comctl cfile, ctl else display "error" endif FTP (File Transfer Protocol) is a protocol that runs on top of TCP to allow for the transfer of files between computers. The DB/C program FTP.PRG uses this protocol. The full specification of the FTP protocol is given in RFC959 and RFC1123. FTP.PRG complies with these standards. To connect to an FTP server, a client program connects to port 21. The connection that is established acts as the control connection for the session. FTP commands are passed to the server over this connection. All FTP commands end with a carriage return followed by a linefeed. For example, the following command requests a directory listing from the server: LIST The server responds to each FTP command with one or more three digit reply codes followed by text descriptions of the action taken, or any error in the request. Many FTP commands require a second connection, the data connection, to be established. For example, this connection is the one that is used for the actual file transfer in response to the GET or PUT commands. The core of the FTP.PRG program is a loop that takes commands at a keyin statement and calls routines to handle them. For example, if you enter the `help' command, a list of commands is provided. If you enter `help open', a description of the `open' command will be provided. The WEB.PRG program implements the HTTP protocol used by World Wide Web (WWW) clients and servers. If you compile WEB.PRG with the -e=_DISPLAY parameter, the WEB.DBC program will display messages as it receives them. Otherwise, the WEB.DBC program runs silently. We have also provided some sample files to be used with WEB.DBC. They are index.html, pic1.gif, and pic2.gif (you can find them in the same directory as WEB.PRG). If you start WEB.DBC with these files in your DBC_FILEPATH, a client WWW browser (such as Netscape) will be able to connect to WEB.DBC server. To connect, specify the address http:// to the WWW browser, where is the address of the machine running WEB.DBC. The WEB.DBC program acts as a server using the HTTP 1.0 protocol. Like FTP, this protocol runs on top of TCP. HTTP 1.0 is described in an Internet Draft called "Hypertext Transfer Protocol". This draft standard is usually named 'draft-ietf-iiir-http-00.txt' or 'draft-ietf-iiir-http-00.ps'. WEB.DBC is not fully compliant with HTTP 1.0, but it is designed to allow the necessary pieces to be added. The HTTP protocol is a stateless four step protocol: 1. Client makes connection to server on port 80. 2. Client sends request. 3. Server sends response. 4. Connection is closed. The WEB.PRG program also uses the object-oriented features of DB/C 9. The January 1995 DB/C Newsletter (found at ftp.swc.com in /pub/news) can serve as a good reference. Some minor changes have been made to the object-oriented features of DB/C 9 since that newsletter was published, but none of them apply to WEB.PRG. The WEB.PRG program makes nine objects from the 'channel' class. It then enters a loop where it waits for send and recv statements to complete. When a recv statement completes, the request is processed. One or more send statements are executed to satisfy the request. We hope these programs are helpful in getting you started writing DB/C programs for the Internet. DB/C Class Schedule The next DB/C class is scheduled for June 12-15, 1995. The class is held in the Oak Brook, Illinois office of Subject, Wills and Company. For more information, contact Judi Tamkevic via email at dbc@swc.com or via telephone at (708) 572-0240.