MCFMailUtil Class Methods

In this section we discuss the MCFMailUtil class methods. The methods are described in alphabetical order.

Syntax

DecodeText(TextToDecode, &DecodedText)

Description

Use the DecodeText method to decode text. If you only want to decode a word, use the DecodeWord property.

The text is decoded based on the values used with the EncodeText method.

The decoded text is placed in the &DecodedText parameter.

This method returns true if successful. If the return value is false, the following MCFMailUtil properties are set accordingly:

  • ErrorDescription

  • ErrorDetails

  • ErrorMsgParamsCount

  • MessageNumber

  • MessageSetNumber

In addition you can use the GetErrorMsgParam method to return each of the substitution strings used to format the error message.

Parameters

Field or Control

Definition
TextToDecode

Specify the text that is to be decoded, as a string.
&DecodedText

Specify a string variable, used to hold the decoded text.

Returns

A Boolean value: true if successful, false otherwise.

Syntax

DecodeWord(WordToDecode, &DecodedWord)

Description

Use the DecodeWord method to decode a word. If you want to decode a string, use the DecodeText method instead.

The word is decoded based on the values used with the EncodeWord method.

The decoded word is placed in the &DecodedWord parameter.

This method returns true if successful. If the return value is false, the following MCFMailUtil properties are set accordingly:

  • ErrorDescription

  • ErrorDetails

  • ErrorMsgParamsCount

  • MessageNumber

  • MessageSetNumber

In addition you can use the GetErrorMsgParam method to return each of the substitution strings used to format the error message.

Parameters

Field or Control

Definition
WordToDecode

Specify the word that is to be decoded, as a string.
&DecodedWord

Specify a string variable, used to hold the decoded word.

Returns

A Boolean value: true if successful, false otherwise.

Syntax

EncodeText(TextToEncode, charset, EncodingStyle, &EncodedText)

Description

Use the EncodeText method to encode text. If you only want to encode a single word, use the EncodeWord method instead.

The encoded text is placed in the &EncodedText parameter.

This method returns true if successful. If the return value is false, the following MCFMailUtil properties are set accordingly:

  • ErrorDescription

  • ErrorDetails

  • ErrorMsgParamsCount

  • MessageNumber

  • MessageSetNumber

In addition you can use the GetErrorMsgParam method to return each of the substitution strings used to format the error message.

Using Encoding Styles

You can specify either “B” or “Q” for the EncodingStyle parameter, indicating either Base64 or “Quoted-Printable” content-transfer-encoding, respectively.

Oracle recommends using the “Q” encoding when most of the characters to be encoded are in the ASCII character set; otherwise, you should use the “B” encoding. However, a mail reader that claims to recognize encoded text must be able to accept either encoding for any character set that it supports.

Both Base64 and “Quoted-Printable” content-transfer-encoding are defined by RCF 1521. See RCF 1521: Base64 Content-Transfer-Encoding and Quoted-Printable Content-Transfer-Encoding.

Parameters

Field or Control

Definition
TextToEncode

Specify the text that is to be encoded, as a string.
charset

Specify the character set to be used for encoding the text, as a string.

See Character Sets Across the Tiers of the PeopleSoft Architecture.
EncodingStyle

Specify the encoding style. Valid values are:

  • B — for Base64 encoding.

  • Q — for "Quoted-Printable" content- transfer-encoding.
&EncodedText

Specify a string variable used to hold the encoded text.

Returns

A Boolean value: true if successful, false otherwise.

Syntax

EncodeWord(WordToEncode, charset, EncodingStyle, &EncodedWord)

Description

Use the EncodeWord method to encode a word. If you want to encode more than a single word, use the EncodeText method.

The encoded word is placed in the &EncodedWord parameter.

This method returns true if successful. If the return value is false, the following MCFMailUtil properties are set accordingly:

  • ErrorDescription

  • ErrorDetails

  • ErrorMsgParamsCount

  • MessageNumber

  • MessageSetNumber

In addition you can use the GetErrorMsgParam method to return each of the substitution strings used to format the error message.

Using Encoding Styles

You can specify either “B” or “Q” for the EncodingStyle parameter, indicating either Base64 or “Quoted-Printable” content-transfer-encoding, respectively.

PeopleSoft recommends using the “Q” encoding when most of the characters to be encoded are in the ASCII character set; otherwise, you should use the “B” encoding. However, a mail reader that claims to recognize encoded text must be able to accept either encoding for any character set that it supports.

Both Base64 and “Quoted-Printable” content-transfer-encoding are defined by RCF 1521. See RCF 1521: Base64 Content-Transfer-Encoding and Quoted-Printable Content-Transfer-Encoding.

Parameters

Field or Control

Definition
WordToEncode

Specify the word that is to be encoded, as a string.
charset

Specify the character set to be used for encoding the word, as a string.

See Character Sets Across the Tiers of the PeopleSoft Architecture.
EncodingStyle

Specify the encoding style. Valid values are:

  • B — for Base64 encoding.

  • Q — for "Quoted-Printable" content- transfer-encoding.
&EncodedWord

Specify a string variable, used to hold the encoded word.

Returns

A Boolean value: true if successful, false otherwise.

Syntax

GetErrorMsgParam(&index)

Description

Use this method to return each of the substitution strings used in the error message.

Parameters

Field or Control

Definition
&index

Specifies which substitution string to return from the array of substitution parameters.

Returns

A string containing the substitution parameter.

Example

Local PT_MCF_MAIL:MCFMailUtil &emailutil = create PT_MCF_MAIL:MCFMailUtil();
For &index = 1 To &emailutil.ErrorMsgParamsCount
   Local String &trace  = "Param" | &index | ": '" | &emailutil.GetErrorMsgParam(&index) | "'";
End-For;

Syntax

IsDomainNameValid(domainname)

Description

Use this method to check whether a domain name is valid. The isDomainNameValid method queries your DNS server to check whether the domain name is listed in an "MX", or mailbox exchange, record. Please note that not all domains are properly listed by DNS servers.

Note: The number of retries for domain validation is set by the SMTPDNSTimeoutRetries parameter in psappsrv.cfg. The default number of retries is 1.

This method returns true if successful. If the return value is false, the following MCFMailUtil properties are set accordingly:

  • ErrorDescription

  • ErrorDetails

  • ErrorMsgParamsCount

  • MessageNumber

  • MessageSetNumber

In addition you can use the GetErrorMsgParam method to return each of the substitution strings used to format the error message.

Parameters

Field or Control

Definition
domainname

Specifies the domain name to be validated, as a string.

Returns

A Boolean value: true if the domain name is valid, false otherwise.

Example

Local PT_MCF_MAIL:MCFMailUtil &emailutil = create PT_MCF_MAIL:MCFMailUtil();
&result = &emailutil.IsDomainNameValid("oracle.com");

Syntax

IsEmailServerAvailable(server, port, user, password)

Description

Use the IsEmailServerAvailable method to check if the email server specified with the SMTP settings in the application server configuration file is available.

This method returns true if successful. If the return value is false, the following MCFMailUtil properties are set accordingly:

  • ErrorDescription

  • ErrorDetails

  • ErrorMsgParamsCount

  • MessageNumber

  • MessageSetNumber

In addition you can use the GetErrorMsgParam method to return each of the substitution strings used to format the error message.

Parameters

Field or Control

Definition
server

Specify the name of the mail server handling the specified user account, as a string.
port

Specify the port of the mail server handling the specified user account, as an integer.
user

Specify the user name on the mail server, such as “support” or “john_doe”, as a string.
password

Specify the password associated with the specified user name, as a string.

Returns

A Boolean value: true if the server is available, false otherwise.

Syntax

ParseRichTextHtml(richtext)

Description

Use this method to split rich text content with images into an array of MCFBodyPart objects. Typically, this method is used with rich text produced by the rich text editor on a long edit box.

The first element in the array is the text of the email message. The remaining elements in the array represent each image in the message. The images are added as inline parts of the email, rather than as attachments, preserving the original formatting of the HTML content.

Prior to sending the email, the images are stored in a temporary directory. The default directory is PS_SERVDIR/images. Use the MCFMailUtil class imagesLocation property to specify a different directory location. Images in this temporary directory must be deleted manually after sending the email; these image files are not deleted automatically.

Parameters

Field or Control

Definition
richtext

Rich text with images that needs to be parsed.

Returns

An array of MCFBodyPart objects.

Example

See the example on creating an email from rich text editor output later in this topic.

Syntax

ValidateAddress(addresslist)

In which addresslist is a list of email addresses in the form:

email_address1 [{,|;} email_address2] ...

Description

Use the ValidateAddress method to validate a comma- or semicolon-separated list of email addresses. This method checks the syntax of the email address. It does not verify the domain name or the validity of the user name.

This method returns true if successful. If the return value is false, the following MCFMailUtil properties are set accordingly:

  • badaddresses

  • ErrorDescription

  • ErrorDetails

  • ErrorMsgParamsCount

  • MessageNumber

  • MessageSetNumber

In addition you can use the GetErrorMsgParam method to return each of the substitution strings used to format the error message.

Parameters

Field or Control

Definition
addresslist

Specify the email address (or addresses) you want to verify as a comma- or semicolon-separated list.

Returns

A Boolean value: true if the specified email addresses are valid, false otherwise. When ValidateAddress returns false, the badaddresses property will contain an array of all invalid addresses.

Example

import PT_MCF_MAIL:*;

Local PT_MCF_MAIL:MCFMailUtil &emailutil = create PT_MCF_MAIL:MCFMailUtil();
Local boolean &result = &emailutil.ValidateAddress(&email.Recipients);
Local array of string &bAddresses = &emailutil.badaddresses;

If (&result = False) Then
   If (&bAddresses <> Null) Then
      &i = 0;
      While &bAddresses.Next(&i)
         Warning ("Bad email address in input = " | &bAddresses [&i]);
      End-While;
   End-If;
End-If;