@ValidateInternetAddress (Formula Language)

Validates an Internet address based on the RFC 822 or RFC 821 Address Format Syntax.

Note: This @function is new with Release 5.

Syntax

@ValidateInternetAddress( [ addressFormat ] ; address )

Parameters

[ addressFormat ]

Keyword. Specifies the formatting with which to validate an Internet address. Can be one of the following keywords:

[ADDRESS821]

Requests input address be validated based on RFC821 Address Format Syntax.

SStreitfeld@gazette.com

[ADDRESS822]

Requests input address be validated based on RFC822 Address Format Syntax.

"Streitfeld, Sara (Miami)" <SStreitfeld@gazette.com>

address

Text or text list. Input address string

Return value

Text or text list.

If validation is successful, an empty string is returned.
If validation fails, an error message string is returned to the user specific to the failure. More error message strings will be added in the future as necessary.

Possible error messages

Invalid Input Parameter

Invalid parameters to @function - @ValidateInternetAddress.

Invalid RFC821 syntax, no Phrase required.

When a phrase is present in an address requiring an RFC821 syntax.

Invalid Phrase or character found.

Phrase part of 822 address invalid.

Invalid Quoted String or mismatched quotes found.

Quoted string is invalid within the address.

Invalid comment or mismatched parenthesis found.

Embedded (comment(s)) within address is invalid.

Invalid or missing Domain.

Invalid or missing Domain part of Address.

Invalid LocalPart or character found.

Invalid LocalPart specified.

Usage

@ValidateInternetAddress is currently used in location records to validate Internet address fields as well as in mail forms. This function is most useful in field validation formulas where users are asked to input their Internet address or in computed fields where Internet addresses are inherited.

If the second parameter is a list, the function operates on each element of the list, and the return value is a list with the same number of elements.

Note: Multi-byte, or 8-bit characters, are allowed in the Phrase part of an RFC 822 format Internet address. They are not allowed anywhere else. Also, the Group syntax (that is, several Internet addresses combined into one group name, such as "Customers") is not supported in the validator.

Examples

You have designed a form asking the user to input an Internet address. The user enters a standard RFC 821 format Internet address SStreitfeld@gazette.com in the editable field User_Address.
If you enter the field validation formula
```
validateAddress := @ValidateInternetAddress([Address821]; User_Address);
@If(validateAddress != ""; @Failure(validateAddress); @Success)
```
the validation formula returns an empty string indicating a successful validation.

However if you enter
```
"Streitfeld, Sara (Miami)" <SStreitfeld@gazette.com>
```
the validation formula returns the following error message:
```
"Invalid RFC821 syntax, no Phrase required."
```

The following example returns "Invalid RFC821 syntax, no Phrase required." and "OK" in a list.

User_Address1 := {"Streitfeld, Sara (Miami)" <SStreitfeld@gazette.com>};
User_Address2 := {SStreitfeld@gazette.com};
@Replace(@ValidateInternetAddress(
[Address821]; User_Address1 : User_Address2); ""; "OK")

The following example returns "Not OK" if any of the elements in the SendTo field validate to an error message and "OK" if every element validates to an empty string.
```
@If(@ValidateInternetAddress([Address821]; SendTo) != ""; "Not OK"; "OK")
```
Note: Testing the validated list for equality to an empty string does not work because @True is returned if any element is an empty string even if others contain error messages.