ListManager Tcl Commands

General Tcl Commands

The following Tcl commands can be used in either message or recipient-level Tcl scripts:

sql

The sql Tcl command allows an administrator to execute an SQL statement and obtain the results. For security reasons, the administrator must login first using the login command. The sqlcommand can be used to execute an SQL statement that returns a single result set or no results. That result set can have multiple columns and rows. SQL statements that return multiple result sets are not currently supported. The syntax for the SQL command is:

%%sql (tag) (function) (function arguments)%%

The first argument to the sql command is a tag that is used to identify the query when executing a statement and retrieving results. It allows multiple queries to be distinguished within a message.

It is important to note that queries that are done within a message-level Tcl script are in a different scope than those in a recipient-level script. Therefore, the tags that are used to identify them are also in different scopes. A tag used in a message-level script is distinct from the same tag used in a recipient-level script. A tag can be any string.

A message-level script is executed only once for the message and a recipient-level script is executed for each recipient. The results of SQL queries executed in each of these scopes are stored separately and cannot be accessed from a different scope. In other words, recipient-level scripts cannot access the results of queries performed in a message-level script. The reverse is also true. Since the results of message-level queries might be required at the recipient level, they can be stored in variables and accessed for recipients without any command call overhead.

The second argument to the sql command is the name of the function that is executed. These functions and their arguments are:

• sql (tag) execute (sql statement): This function executes the specified SQL statement.
• sql (tag) numrows: This function returns the number of rows that were retrieved.
• sql (tag) numcolumns: This function returns the number of columns that were retrieved.
• sql (tag) columnname (column index): This function returns the name of the column at the specified index. The index must be between 1 and N where N is the number of columns retrieved.
• sql (tag) data (column index) (row index): This function returns the data that corresponds to the specified column and row indices. The row index must be between 1 and M where M is the number of rows retrieved. If the row index argument is omitted, it defaults to 1. If both the column index and row index are omitted, they both default to 1.

Here is an example to return all of the names and email addresses on the current list in the form:

Name = Full Name, Email = email@address

%%!
init ;
errormode debug ;
login youradmin@email.addr yourpassword ;
%%
%%!
sql listmembers execute "SELECT FullName_, EmailAddr_ FROM members_ WHERE List_='[list.name]'" ;
set numrows [sql listmembers numrows] ;
set results "" ;
for { set row 1 } { $row <= $numrows } { incr row } {
set Name [sql listmembers data 1 $row] ;
set EmailAddr [sql listmembers data 2 $row] ;
append results "Name = $Name, Email = $EmailAddr\n" ;
} ;
return $results ;

 

sendmessagelm

This command is a simple method of sending a message using ListManager's standard message send system. This function takes four arguments:

sendmessagelm (from) (to) (subject) (body): Due to the length of the subject and body, it may be more convenient to define these as variables to pass to this command. For example:

%% after ;
set From "me@myaddress.dom" ;
set To "me@myaddress.dom" ;
set Subject "message send has completed!" ;
set Body <
The message send for:
[merge inmail_.HdrSubject_]
is complete.> ;
sendmessagelm $From $To $Subject $Body
%%

 

process_merge_tags: The process_merge_tags TclMerge command is useful anytime you want to merge content from another source and have the merge tags evaluated. This command is very useful for HTML mailings. This command is used in mailings, but can apply to other documents, such as hello and goodbye documents as well. The process_merge_tags TclMerge command evaluates any %%-delimited merge tags in the argument passed to it and return the results. Doing so is useful in cases where you want to perform a mail merge on text that is retrieved from the database or via http.

Note that these tags are evaluated as straight Tcl and therefore any Aurea List Manager Tcl language extensions does not work in these tags.

For example, the "init" and "before" modifiers are not evaluated properly and line unwrapping is not done. Additionally, any special merge tags that are not handled as normal Tcl procedures such as %%MemberID_%% results in errors. You must use the %%merge MemberID_%% convention for all merged data fields.

Example:

%%process_merge_tags [httpget http://myserver/newsletter.html]%%

Message Level Commands

The following commands are valid only in message-level or send-completion scripts:

• login

In order to use certain Tcl commands, the administrator must first log in. This is to prevent someone from sending a message containing malicious SQL or other hazardous code pretending to be an administrator by using the administrator's email address, a practice known as "spoofing".

The "login" command is called with the administrator's email address and password. The syntax for this command is:

%% init ; login (email address) (password) %%

Since this command requires a database query to determine if this address and password are those of an administrator, it should only be used in message-level scripts -- Tcl scripts that begin with "%%init ;" or "%%before ;". Otherwise, the query is done for each recipient, and it slows down the send.

 

• redirect

For testing purposes, it is advantageous to be able to preview what each recipient sees when their message is mail-merged. The redirect command allows the administrator to redirect all messages to a specified email address.

The syntax for this command is: %% init ; redirect (email address) %%

 

• errormode

Since Tcl can be a tricky language to program, debugging message sends are required or desirable. This is to endure that the Tcl in the message executes properly. The sender should turn on error handling so that if there is an error, the message send stops and the sender is notified. The following error modes are supported: notify, abort, replace, debug, and normal.

The most helpful use of this command is the notify mode:

%% init ; errormode notify user@domain.ext %%

When this mode is set, any Tcl errors causes the message send to stop and an email that details the error description and the tag in which it occurred is sent to the specified email address.

The abort error mode simply causes the message send to stop but no notification is sent. The error text can be found in the transaction log for the message. The syntax for this mode is:

%% init ; errormode abort %%

The replace error mode causes the tag in which the error occurred to be replaced with the specified text. The syntax for this mode is:

%% init ; errormode replace "replacement text" %%

The debug error mode replaces the tag with the error string. This string indicates what the error was and the text of the script.

The normal error mode replaces the tag with an empty string. This is equivalent to calling "errormode replace" with an empty string. This is the default behavior.

 

• mailtest

This command takes no arguments and returns an empty string, tells ListManager to put this message into mailtest mode. This means that the send proceeds as normal and go through the standard SMTP transaction but resets before the message data is sent to the server. Any messages sent in this mode does not reach the recipients. This should only be used for testing mail-merge and send speeds. Since messages sent this mode are otherwise indistinguishable from a standard send, handling of transient or permanent failures for bad or intermittent email addresses still applies.

Recipient Level Commands

 

• recipindex

This command takes no arguments and returns a number that indicates the relative index of the current recipient during the current send. It is based on the range 1 to N where N is the total number of recipients to which the message is being sent. The ordering is based on the retrieval order from the database but isn't guaranteed to be in this order.

 

• numrecips

This command takes no arguments and returns the number of total recipients that are being sent to. This number represents N in the range of results returned by the "recipindex" command.

 

• skip

Sometimes the sender of a message may not want to send to certain recipients that are usually a part of a normal send. For example, if the sender was testing a message with the redirect command but they were sending to a list with 100,000 messages, they would receive 100,000 copies of the message. Or, the sender might want to do mail-merge for the entire send and verify that there were no errors before doing the actual send.

Using the skip command, which takes no arguments and returns an empty string, the sender could send to every 1000th recipient and skip the rest using the following Tcl mail-merge tag:

%% if { [recipindex] % 1000 != 0 } { skip } %%

This means that if the index of this recipient as retrieved by the recipindex command is not evenly divisible by 1000 then it is skipped.

The sender could skip every recipient by simply adding the tag "%%skip%%" to the end of the message.

When the "skip" command is executed, further processing of the current message is stopped so if you are testing the message to make sure that all the scripts are executed properly, call this command at the end of the message. Otherwise, call it at the beginning.

• abort

This command terminates the sending of the current message. If the error mode was currently set to notify, then the notification is sent. Otherwise, the error mode is set to abort and an error is generated causing the message send to stop. abort can be called with a text string argument which is passed on as the error text. For example:

%%abort "Terminating this message send."%%

memberstable, emailaddrcolumn, and memberidcolumn

The name of the members table and the column names of the email address and member ID are all configurable by the server administrator. These commands return these names. When writing custom Tcl commands for library code, use these commands in place of members_, EmailAddr_, and MemberID_

 

• memberidchar

Each member in the Aurea List Manager database has a unique ID and for each ID, there is a special code character which is a single letter. The ID and code character are used in many places for the validation of confirmations and unsubscribes. The code character makes it harder to accidentally unsubscribe someone else by typing in the wrong ID. The memberidchar command returns the member ID and the code character as a string that can be used in your scripts. For example:

To unsubscribe, click here:
http://www.yourdomain.dom/u?id=%%memberidchar%%&c=F

 

• emailunsub

The member unsubscribe address is fundamental to the operation of a mailing list and our failsafe unsubscribe feature makes it convenient and simple for a member to unsubscribe. The emailunsub command returns an unsubscribe address specific to the current member. This command is equivalent to the legacy subst tag version: $subst('email.unsub') which is also supported via the Tcl command subst email.unsub.

Legacy Subst Commands

ListManager has always had some mail-merge capability using special subst tags of the form $subst('argument'). All of these commands are supported in the new mail-merge functionality. Prior to 6.0h, the form of the tag was subst (argument), which conflicted with the Tcl subst command. For 6.0h and higher, the form of the new tags is:

 

• lmsubst (argument)

where (argument) is the same argument that was passed to the original $subst version.