Interfacing with Email
This release of PicLan-IP supports a programming interface allowing you
to format and send internet email messages using SMTP (Simple Mail Transfer
Protocol). SMTP is the standard internet protocol for sending email.
This documentation is designed for PicLan-IP build 2.0.0(129)
In order to use email functions, you will need to have the following
elements in place:
Your Pick host must have PicLan-IP installed and running.
You must have a supervisor process and at least one thread process running.
You must have at least one DNS configured and accessible.
You must have PicLan-IP SMTP send-mail functions enabled in your PicLan-IP
How Mail is Sent
Internet email can be sent in one of two ways:
If your ISP has an email server, you can send email to that
server and it will forward it to the destination address.
The advantage of using your ISP's email server is that it will take care
of email retries without your system needing to worry about it. The advantage
of sending the mail directly is that you do not rely on your ISP's mail
server. To understand the importance of this decision, a quick discussion
of internet mail routing is appropriate here:
You can send the email directly to the destination address (or to one
of the destinations backup relays).
Internet Email Routing and Retries
When email is sent over the internet, it may or may not be directly sent
to the recipient's mail server. Part of the Domain Name Server's function
is to support a system of mail forwarding information called Mail eXchange
(MX) records. These pieces of data tell mail users and mail servers how
to deliver an email message to a particular destination. Simple destination
may have a single MX entry that is just the machine name of the mail server
at the destination. More complicated examples may have several systems
listed, any of which can accept inbound internet email, or backup system
that can store and forward the message if the primary mail server is down
When email is sent over the internet, there is no expectation that the
mail can be sent instantaniously. In fact, the standard requires that a
mail server try to deliver a message for five days before giving up on
it. If you setup your Pick system to directly send mail to a destination
mailbox and not use your ISP's mail server, then your Pick system has the
responsibility of trying to send a message for five days. If the Pick host
is a production system that is always running, this is probably fine. If
the Pick host is a part-time host, then using your ISP's mail server is
better because it becomes another system's responsibility to retry failed
The email database files in PicLan-IP include cross-reference files that
are mainained using high-performance BTREE indexes. These indexes
are nearly impossible to manually query or maintain, so you must be sure
to use the doucmented interfaces whenever updating any of the mail database
Email Subroutine Documentation
Sending an Email Message
The process of sending a message is a multi-step process:
First the message must be formatted correctly so that it looks like an
internet email message and then this message must be transmitted to the
Formatting an Email Message
The process of formatting an email message involves building the header
fields that the message requires followed by including the message body.
In general, email message can have three general levels of complexity:
The first version of the PicLan-IP email support only include support for
simple messages. Support for encoding and multi-part MIME (Multimedia Internet
Mail Extensions) messages will be included in a future build.
Simple Messages - the message body contains printable text only
Encoded Messages - the message body contains encoded text (perhaps binary
Multi-part Messages - the message body contains multiple parts, some of
which may be encoded.
You have two choices in formatting a message. Your application program
can build the message itself as a text string using attribute marks to
delimit lines, or you can use a helper subroutine within PicLan-IP to add
internet header fields onto you message body.
If you use the helper function, you application will call the subroutine:
This subroutine will take the contents of PARMS and CONTENTS and return
MSG, FR.ADDR, TO.ADDR, and R.ERR. The PARMS and CONTENTS parameters are
designed to support multi-part and encoded messages, even though these
functions are not working in the build.
The PARMS paramter is a dynamic array that you build prior to calling PLM.BUILD.MSG.
This dynamic array has the following format:
The email address that the message is from in "sloppy" internet format.
This allows you to include descriptive narative with the email address
such as "Doug Dumitru" email@example.com or Doug Dumitru <firstname.lastname@example.org>
The email address(es) that you wish the message to be delivered to. You
can specify multiple addresses seperated by commas. Again these addresses
are in "sloppy" internet format.
Carbon Copy (CC) address(es) that you wish the message to be copied to.
You can specify multiple addresses seperated by commas. Again, these address
are in "sloppy" internet format.
Blind Carbon Copy (BCC) address(es) that you wish the message to be copied
to. Internet email messages do not include a header field for BCC addresses,
so an original recipient will not know that you also sent the message to
Reply to address. If included this "sloppy" internet format address will
be included in a "Reply-To:" header. A reply to header is where email clients
will send replys (unless the user overrides this address).
To: string. If included, this string will be included in the "To:" header.
If not included, then the to address list will be included in the "To:"
header field. This field is usually used for mailing lists where you do
not wish to list all of the recipients of the message in the header.
CC: string. If included, this string will be included in the "CC:" header.
If not included, then the CC address list will be included in the "CC:"
If you included text in attributes 21 or greater, then this text will be
appended to the message header without interpretation. This allows you
to add customized header fields. If you specify a header field in attributes
21 or greater that is one of the standard header fields that PLM.BUILD.MSG
usually creates, then you user-supplied header field will take precidence.
CONTENTS Array Parameter
The CONTENTS parameter is a dimensioned array with 100 elements. The reason
this field is supplied as a dimensioned array is to support multi-part
messages. With this build of PicLan-IP, you should set all elements of
this array to null except the first element.
The PARMS variable and CONTENTS array are the only two values that you
need to specify when calling PLM.BUILD.MSG. The following paramters are
returned from the subroutine call and are used in subsequent calls to actually
sent the email:
A string that indicates where the message body is stored. Possible values
INLINE - The message starts on attribute 11 of the CONTENTS parameter.
FILE acct filename item-id - The message is stored in the Pick data file
DSG dsgname path - The message is stored accessible over a PicLan DOS Services
The encoding of the message with character set. Supported values are:
How the message is to be stored in the mail message. Supported values are:
7bit - used for text
base64 - used for binary data or any other data that contains character
over ascii values from 128 to 255
The actual text content of the message if INLINE is specified.
This parameter will contain the text contents of the message including
the message header and body.
This is the internet address that the message is from with extraneous words
These are the addresses where the message will be sent with extraneous
words removed. The TO.ADDR entries include To:, CC:, and BCC: addresses.
Multiple addresses are stored as multiple attributes within this parameter.
This field should normally be set to null upon return from PLM.BUILD.MSG.
If this field is non-null, it indicates that and error was encountered
in building the email message and that the message cannot be sent.
Sending the Message
After the message has been formatted, either manually or using the PLM.BUILD.MSG
subroutine, you need to schedule the message to be transmitted. The term
"schedule" is used here because the mail message may or may not be sent
immediately. To schedule a message for transmission, you call the subroutine:
The FR.ADDR, TO.ADDR, and MSG fields are the results of the PLM.BUILD.MSG
The ID is a string returned that identifies the message so that you
can subsequently check on it's status.
The R.ERR is a string returned that indicates any error condition that
prevents the message from being scheduled. Even if the error string is
null, the message will not necessarily be delivered if it has invalid addresses
or if network connections or mail hosts are down.
Sending a Batch of Messages
If you are building a large quantity of messages to send, the PLM.BUILD.MSG
and PLM.SEND functions are not ideal. First, they are not really
optimized for performance, and second, because they are very "black-box"
in nature, they have to run a lot of internal initialization code on every
call. If you are sending a large number of messages you may wish
to use an alternate interface.
This TCP command will take an input data file along with an active select
list and generate one email message for each item in the specified data
file. The format of these items is:
002 TO.ADDR (multi-valued if multiple addresses are specified)
Checking the Status of a
This function is not currently implemented.
© Copyright 1996-1998 Modular Software
Corporation.All rights Reserved.