open_data(), write_data(), write_raw_data(), close_data() Functions

These APIs provide more fine-grain control to the data() API; in other words, to the SMTP DATA operation. open_data() sends the DATA command. After that, write_data() and write_raw_data() write a portion of the e-mail message. A repeat call to write_data() and write_raw_data() appends data to the e-mail message. The close_data() call ends the e-mail message by sending the sequence <CR><LF>.<CR><LF> (a single period at the beginning of a line).

Syntax

UTL_SMTP.OPEN_DATA (

c     IN OUT NOCOPY connection) 

RETURN reply;
UTL_SMTP.OPEN_DATA (

c     IN OUT NOCOPY connection);

UTL_SMTP.WRITE_DATA (

c     IN OUT NOCOPY connection, 
data  IN OUT NOCOPY);

UTL_SMTP.WRITE_RAW_DATA (

c     IN OUT NOCOPY connection
data  IN OUT NOCOPY);

UTL_SMTP.CLOSE_DATA (

c     IN OUT NOCOPY connection) 

RETURN reply;
UTL_SMTP.CLOSE_DATA (

c     IN OUT NOCOPY connection);

Parameters

Table 82-14 open_data(), write_data(), write_raw_data(), close_data() Function Parameters

Parameter	Description
c (IN OUT NOCOPY)	The SMTP connection.
data (IN OUT NOCOPY)	The portion of the text of the message to be sent, including headers, in [RFC822] format.

Usage Notes

The calls to open_data(), write_data(), write_raw_data() and close_data() must be made in the right order. A program calls open_data() to send the DATA command to the SMTP server. After that, it can call write_data() or write_raw_data() repeatedly to send the actual data. The data is terminated by calling close_data(). After open_data() is called, the only APIs that can be called are write_data(), write_raw_data(), or close_data(). A call to other APIs will result in an INVALID_OPERATION exception being raised.

The application must ensure that the contents of the body parameter conform to the MIME(RFC822) specification. The data() routine will terminate the message with a <CR><LF>.<CR><LF> sequence (a single period at the beginning of a line), as required by RFC821. It will also translate any sequence of <CR><LF>.<CR><LF> (single period) in the body to <CR><LF>..<CR><LF> (double period). This conversion provides the transparency as described in Section 4.5.2 of RFC821.

Notice that this conversion is not bullet-proof. Consider this code fragment:

  utl_smtp.write_data(`some message.' || chr(13) || chr(10));
  utl_smtp.write_data(`.' || chr(13) || chr(10));

Since the sequence <CR><LF>.<CR><LF> is split between two calls to write_data(), the implementation of write_data() will not detect the presence of the data-terminator sequence, and therefore, will not perform the translation. It will be the responsibility of the user to handle such a situation, or it may result in premature termination of the message data.

XXX_data() should be called only after open_connection(), helo()/ ehlo(), mail(), and rcpt() have been called. The connection to the SMTP server must be open and a mail transaction must be active when this routine is called.

Note that there is no function form of write_data() because the SMTP server does not respond until the data-terminator is sent during the call to close_data().

Text (VARCHAR2) data sent using write_data() API is converted to US7ASCII before it is sent. If the text contains multibyte characters, each multibyte character in the text that cannot be converted to US7ASCII is replaced by a `?' character. If 8BITMIME extension is negotiated with the SMTP server using the EHLO() API, multibyte VARCHAR2 data can be sent by first converting the text to RAW using the UTL_RAW package, and then sending the RAW data using write_raw_data().