Script Execution Points

Tcl mail merge scripts can be processed at different times during the message send process. There are currently three different states at which Tcl tags can be executed:

1. Before the message send starts;

2. During the message send;

3. After the message send is completed or goes into retry mode.

The states at which scripts are executed are determined by the presence of special tags at the beginning of each script. These tags can be thought of as procedures, but are actually removed before any scripts are executed. For consistency, they obey the syntax of a procedure.

Message-Level Scripts

When a message is sent, data that applies to the entire message and that doesn't change for each recipient is loaded once. There may also be scripts that need to be processed or certain table fields that need to be retrieved only once for the entire message. These are referred to as "message-level scripts" or "message-level data" since they apply to the entire message.

Message-level scripts are indicated by the inclusion of the keywords init or before that immediately follow the Tcl tag delimiters. For example:

%% init ; ... some message-level Tcl code ... %%

or

%% before ; ... some message-level Tcl code ... %%

Both of these tag types will be processed once for the entire message before the recipients are mail-merged. At this stage in the send, no recipient-level data is accessible and any attempts to execute recipient-level procedures or merge recipient-level columns will result in an error.

They will be processed again at the beginning of processing any retries of the message.

The only difference between init tags and before tags is that init tags always return an empty string and before tags function as normal merge scripts. In Tcl, whatever the last string to be manipulated was is the return string of the script. For example:

%% before ; set variable "some value"%%

will return "some value" as if we had done:

%% before ; set variable "some value" ; return $variable%%

For this reason, the init tag was created. Any message-level initialization that does not require a string to be returned should be done in init tags. This will help guard against the inadvertent merging of data. before tags should be used for mail-merging text that only needs to be set once for the entire message.

Recipient-Level Scripts

Scripts that may return different results for each user are referred to as "recipient-level scripts" and a recipient's data is referred to as "recipient-level" data. This data is generally data from the members table but could be any data that is available via a join from the members table to any other accessible table. This join is done by sending to a subset where the join criteria has been defined as part of the subset. A "recipient-level" script requires no special tags. For example:

%% set variable [merge EmailAddr_] ; return $variable %%

Send-Completion Scripts

When the current message send is completed or goes into retry mode, scripts defined as "after" scripts are executed. These scripts never have any impact on the content of the message because the message has already been sent by the time that these are executed.

Recipient-level scripts do not require any special keywords. In general, recipient-level scripts should only be used for scripts or merging fields that could change from recipient to recipient. Recipient-level scripts can execute message-level Tcl procedures or use message-level data. The reverse is not true.

Scripts to be run when the message is completed should be run in scripts using the tag "after". For example:

%% after ; sql tag execute "insert into results ..." %%