DLL EmailCmd(Handle,Operation,Data)

DLL access Operations Example

Declaration: int EmailCmd (int, int, char*)

Parameters: integer Handle : the unique integer identifier

         integer Operation: the command to perform

         string Data: the information to use in the command.

Returns: integer Error Code

This function performs the real work of the DLL. All the commands go through this function. Every call to this function, regardless of the operation, takes the three parameters, and returns an integer error code.

The first parameter to EmailCmd, "Handle", is an value proposed by the script calling the DLL. When you use the EmailCmd with the val_NewEmail operator, the handle is accepted to identify the new (DLL-based) email object.

To identify itself among the other user sessions that might be creating email messages, the DLL uses a unique handle to identify each DLL-based email object. If you are interfacing directly with the DLL. you must keep track of the Handle in your program, and you must ensure that no one else will try to use that handle. That is why the IntraBuilder netInfo.sessionID is well suited to this. The restriction is that each user session is only allowed to have a single email (DLL) object active at any time. Because of this, it is important to dispose of the objects, using the FreeEmail command.

The second parameter, "Operation", is an integer that indicates what is to be done when the function call is performed. The legal values are described in the file DLLdefines100.js, and under the Operations topic.

The last parameter to the EmailCmd, the Data string, carries whatever data is necessary to complete the operation. It may be message text, a header line, or an email recipient, depending on the operation.

The EmailCmd function always returns an integer value. A zero indicates the command was successful, while negative numbers indicate a problem occurred. Only in the val_NewEmail operation will this value be greater than zero. Refer to the Error Code information for more. You can get American English descriptions of any returned error message with the GetErrorString function.

Using the DLL directly is very nearly the same as with the Email Class ; there is little difference in the types and uses of the calls made directly to the DLL.

Initially, you should obtain a handle identifier and use the val_NewEmail operation. Once you have completed your use of the email object, use the val_FreeEmail operator to dispose of the object in the DLL.

After you've successfully created the email object, you can set the various email message information using the other operators. To set the SMTP mail server address, use the val_SetMailServer operator. Set the email message sender with the val_SetFrom operator. You can set a different address for replies with the val_SetReplyTo operator.

Many of the standard email header lines are supported directly with operators. For those operators that take addresses where mail is to be sent, you can give plain-text names and multiple names using the described email address syntax . For the normal recipients (To), the Carbon Copy (CC) recipients, and the Blind Carbon Copy (BCC) recipients, there is an operator to clear the list, and another to add one or more recipients. The operators are:

         To: val_ClearRecipients val_AddRecipient

         CC: val_ClearCC val_AddCC

         BCC: val_ClearBCC val_AddBCC

You can also use non-standard header lines with the val_ClearOtherHeaders and val_AddOtherHeader operators.

To set the subject of the email message, use the val_SetSubject operator. Although the SMTP server will add the date/time header line if it finds none, you can also supply a date/time string using the val_SetDate operator.

To clear the text of the message, use the val_ClearMessage operator. To add text into the message, use the val_AddMessageLine operator. You can add one line or a long string of text using that operator. If you want to use a signature file, or the message text is located in a file, use the val_SetMessageFile operator.

Depending on your network's email traffic, you may want to increase the number of attempts made to send an email message, using the val_SetMaxAttempts operator. When you're ready to transmit the message, use the val_SendMessage operator. Once you're done, use the val_FreeEmail operator to release the object inside the DLL.

If you have any changes you'd like to see made, please feel free to let me know, and I'll consider them for a future release. See the Support section for information.