PowerBASIC Gazette CyberEdition #19 =================================== June Fourteenth 2001 From: Bob Zale, President, PowerBASIC, Inc. There's lots of exciting news this month! PowerBASIC for just $99? You bet it's true! But more about that later... Right now, there are other important things to talk about. You know, our latest Win32 compilers, PB/CC 2 and PB/DLL 6, offer full support for TCP and UDP communications. They'll let you send an email from any program, in just a few lines of code. You can add attachments, check incoming email, even access an FTP site or download a web page. Great stuff... But how does it really work? You'll get all the inside information, right here in the PowerBASIC Gazette. We've prepared a series of articles on just these topics. The first installment, an overview, was published in a previous Gazette, and can be found at www.powerbasic.com. The second article in the series, "Sending E-mail with PB/DLL", follows below. Stay tuned right here, and you'll be a TCP/IP expert in no time at all! If you haven't yet upgraded to PB/CC 2, or PB/DLL 6, now is certainly the time to do so. Check out all of the product details at www.powerbasic.com and join in the fun! {smile} Pricing and ordering information can be found at the very end of this Gazette. Questions? Just email info@powerbasic.com We'll do our very best to help. Regards, Bob Zale, President PowerBASIC, Inc. =================================================================== =================================================================== Sending E-Mail With PB/DLL Developing Internet applications is usually at the top of most programmers' "want to do" list. Often, the first type of application they want to develop is an e-mail program. A quick search on the Internet reveals a lot of example code for e-mail clients, however, few of these examples provide any clear explanation as to how an e-mail program actually works. Well, we think it's time that we shed some light on the subject at hand. Don't you? Say HELO To SMTP SMTP, or the Simple Mail Transport Protocol, provides a way for the exchange of Internet e-mail. As suggested by its name, the SMTP protocol is actually very simple to implement because it uses plain ASCII commands. Whenever an e-mail program, or SMTP client, wishes to send e-mail, it starts out by contacting the SMTP server on port 25. Using PowerBASIC DLL 6.0 we would initiate a session with an SMTP server with the following lines of code: ERRCLEAR nTCP = FREEFILE TCP OPEN "smtp" AT $SMTPServer AS nTCP IF ERR THEN MSGBOX "SMTP server could not be reached!" TCP LINE nTCP, sBuffer$ Here, we are simply opening the SMTP service for communication, where $SMTPServer is the name of the server, or host, we wish to communicate with. This usually takes the form "mail.myserver.com". The TCP LINE statement receives the reply from the server. If the TCP OPEN is successful, then the variable sBuffer$ contains a string that begins with a three-character numeric reply code, usually followed by a verbose text description of the reply code. If the numeric reply code is 220, then the connection to the server was established successfully. Now that communications between the client and the server have been established, we need to introduce ourselves to the mail server using the HELO command. The HELO command takes one parameter, which is the fully qualified domain name of the client, as illustrated in the following example: TCP PRINT nTCP, "HELO " & "someplace.com" TCP LINE nTCP, sBuffer If the HELO command is successful, the reply code is 250. The next step is to initiate the actual transfer of the message by issuing the MAIL FROM command. This command was originally designed to tell the SMTP server the reverse-path that the message has taken from its original source up until this point. In reality though, the reverse-path is rarely an actual path. It's normally the fully qualified domain name of the original sender, as shown in the below example: TCP PRINT nTCP, "MAIL FROM: " TCP LINE nTCP, sBuffer If the MAIL FROM command is successful, the reply code is 250. Now that the mail server knows who the message is from, we need to let the server know who the message is for (the recipient). This is accomplished with the RCPT TO command: TCP PRINT nTCP, "RCPT TO: " TCP LINE nTCP, sBuffer If the RCPT TO command is successful, the reply code is 250. For messages that must be sent to multiple recipients, it's simply a matter of issuing the RCPT TO command repeatedly, and in sequence, with each command designating a final recipient. Of course, you still need to get the return code for each recipient. Now that all of the recipients have been specified, we can issue the DATA command to tell the server that we are now going to send the actual message. For example: TCP PRINT nTCP, "DATA" TCP LINE nTCP, sBuffer If the DATA command is successful, the reply code is 354. Once the server indicates that it is ready to receive the message, we can send our message line by line. But first, let's take a brief look at exactly what an Internet mail message is. Simply put, a mail message consists of lines of ASCII characters terminated with characters. The first set of lines are the message header, the remaining lines are the message body, with the header being separated from the body, by a single blank line. Let's look at some example code to illustrate sending the message header: TCP PRINT nTCP, "From: someone@someplace.com" TCP PRINT nTCP, "To: someoneelse@somewhere.com" TCP PRINT nTCP, "Subject: E-Mail With PB/DLL!" TCP PRINT nTCP, "X-Mailer: PowerBASIC E-Mail Demo" TCP PRINT nTCP, "" As demonstrated above, a header in its simplest form consists of basic information, such as who the message is from, who it is for, the subject of the message, the client program used to send the message and a single, blank line to signal the end of the message header. Once we've sent the header, we can then go ahead and send the actual message body: TCP PRINT nTCP, "This is the body of our test message." Simple as that. We just repeat the above statement for each line in the message, until the entire message has been sent. No reply code is received from the server for each of these message lines. Note that individual lines should be less than 1000 characters wide. Next, We tell the server that the message body is complete by sending a line containing a single period character followed by . Since it is possible that a message could actually contain a line with nothing but a period character, care must be taken to avoid sending this line unchanged or the message body will be truncated prematurely. You can fix this potential problem by sending two periods instead of one. TCP PRINT nTCP, "." TCP LINE nTCP, sBuffer The mail server will then reply with a code indicating whether or not the transfer was a success (code 250) or a failure (code <> 250). Now that we've sent our mail message, we need to politely terminate the session with the SMTP server by sending the QUIT command. TCP PRINT nTCP, "QUIT" TCP LINE nTCP, sBuffer Upon issuing the QUIT command, the mail server will reply with code 221, indicating success, or code 500, indicating an error. It will then close the TCP connection. And there you have it - the basics of sending Internet e-mail via the Simple Mail Transfer Protocol. Like I stated at the beginning of this article, it's all fairly simple and straightforward stuff. For further information on sending Internet e-mail you may want to take a look at RFC 2821, which describes the SMTP protocol, and RFC 2822, which describes the format of electronic mail messages: http://www.powerbasic.com/files/pub/docs/rfc/2800/ For a complete sample program that illustrate how errors are to be handled, please see SMTP.bas which is installed in the PB/DLL Samples\Tcp folder. You may also wish to look at TCP32.inc in the same folder for some ideas. ============================================================================== Order online at https://www.powerbasic.com/shop/ or just send an email with all pertinent information to sales@powerbasic.com We'll take it from there! ------------------------------------------------------------------- Most PowerBASIC products (those without printed books) can now be delivered by electronic mail. No wait for a package to arrive... No high shipping costs... For just $6 per order, no matter how many products, we'll deliver directly to your computer. If you're outside the U.S., savings might be greater. You won't pay taxes or duties to a freight company or postal service, because they aren't involved in the delivery. Check your tax code to be sure, but some countries charge no tax at all on transactions of this type. It could just be your lucky day! ==================================================================== Is your PowerBASIC Gazette Electronic Edition subscription coming to you at home or work? If you don't want to miss a single issue, why not subscribe from both email addresses? Send your subscription request to email@powerbasic.com and please include your name and all email addresses you'd like to add as well as your Zip or Postal Code. Did you know that there is also a paper edition of the PowerBASIC Gazette? That's right, you can get a newsletter with articles detailing all of the products available from PowerBASIC, Inc. Full of useful code tidbits, book reviews and more. Why not get your free subscription today? Just send your name and postal address to sales@powerbasic.com If you know someone else who would enjoy this newsletter please forward a copy to them so they can subscribe. ==================================================================== All contents Copyright (c) 2001 PowerBASIC, Inc. All Rights Reserved. PowerBASIC is a registered trademark of PowerBASIC, Inc. PB/CC, PB/DLL, and PowerTREE are trademarks of PowerBASIC, Inc. All other brand names are trademarks or registered trademarks of their respective owners. ==================================================================== PowerBASIC Gazette - Electronic Edition Volume 1 - Issue 19 PowerBASIC, Inc. (800) 780-7707 Sales 1978 Tamiami Trail S. #200 (941) 408-8700 Voice Venice, FL 34293-5006 (941) 408-8820 Fax Visit us on the World Wide Web at www.powerbasic.com Email Sales: sales@powerbasic.com This newsletter is only sent to email addresses in our subscription list. If you have received this newsletter by mistake or no longer wish to receive it, please send a simple unsubscribe request to support@powerbasic.com with your name and zip/postal code. This newsletter is best viewed with a fixed-width font. ====================================================================