mlm-command DisplayFile Tokens Guide

This is a more-or-less complete listing of all available bracketed tokens for use in mlm-command display files.The level of completeness claimed is only "more or less" because environment variables may change from platform to platform. In particular, until testing has been done on Web servers other than Apache, it's impossible to be sure what environment variables will be passed to CGI scripts under normal circumstances.

Additionally, there are a few variables (environment and otherwise) which are fairly boring, and useless to bother using. These have been omitted for brevity.

However, if you find a token listed for use here, you can rely on it being available for use in your display files.

Environment Variables

Many environment variables are passed to CGI scripts by Apache (and similar NCSA-based Web servers) by default. Of primary interest, and greatest use for display files, are the following. By convention, these environment variables are always named in ALL_CAPS, using the underscore for internal words separation. By contrast, the mlm-command internal variables (listed below) are named in MixedCase.

DOCUMENT_ROOT The path on the server leading to the root directory for Web documents. Common values are:
  • /home/httpd/html
  • /usr/local/apache/htdocs
  • /var/www/htdocs
Of course, you may find other values in place on your system.
HTTP_HOST The hostname that the user's browser thinks it's connecting to. This will usually be the same as SERVER_NAME (below), but may occasionally differ, especially when there are weird things going on with DNS. You'll normally want to use SERVER_NAME if you want a fairly canonical value.
HTTP_REFERER The URL of the form that called mlm-command. This is useful for sending people back where they came from in error messages, and for referring to the page the user was just at. To provide a hyperlink to the referring page, use: <A HREF="[HTTP_REFERER]">your link text</a>.
HTTP_USER_AGENT The identification string sent by the user's browser to identify what it is. This generally includes the company, brand name, version, and any patchlevels, and often includes operating system information as well. You probably don't want to echo this entire string back to the user, but you are at least able to. Also, note that browsers sometimes lie about what kind they are.
QUERY_STRING

The string sent by the browser as part of the URL in an HTTP GET request. mlm-command users are encouraged to write their forms using the POST method instead of GET (and all examples of the HTML <FORM> tag in the Command Reference use POST), but mlm-command will accept GET input. In that case, the QUERY_STRING will look something like this, only probably much longer:

EmailAddress=foo%40bar.com&ListAddress=list%40baz.net

You'll note that this is quite ugly. This is why GET requests and the GET method are discouraged for use with mlm-command. If POST is used instead, QUERY_STRING will be empty.

REMOTE_ADDR The IP address of the user's computer, in dotted-quad decimal notation (for example, 64.81.50.197).
SERVER_ADDR The IP address of the Web server mlm-command's running on, also in dotted-quad notation.
SERVER_ADMIN The email address of the server administrator -- usually "webmaster@SERVER_NAME", sometimes with the "www." removed.
SERVER_NAME The hostname of the Web server that mlm-command's running on. This value can also be gotten from the ThisHost token, described below.

mlm-command Internal Variables

The following variables are internal to mlm-command alone. While some are actually used by mlm-command to perform various operations, others are provided specifically to make writing display files easier.

Please note that all variables passed to mlm-command by the calling form (EmailAddress, ListAddress, Action, and so forth) are available as expansion tokens. They are listed here for completeness as you scan the list, but no explanation is given; they are simply described as "Value passed from calling form."

ThisHost Equivalent to the SERVER_NAME environment variable; the actual fully-qualified domain name (FQDN) of the server running mlm-command.
ThisDomain The second-level domain containing ThisHost, stripped of any leading hostname. In other words, if your hostname (FQDN) is random.host.name.domain.tld, your domain is simply domain.tld. This can be useful if you want to refer, by name, to your entire domain rather than a single specific host.
ListAddress Value passed from calling form.
ListName Only the local-part of ListAddress (i.e., the part before the @ sign).
ListHost The FQDN of the server on which the list (specified in ListAddress) is hosted. (I.e., just the part after the @ sign.) If ForceLocalList is zero, it may be expected that this may differ from ThisHost at least occasionally. (If ForceLocalList is non-zero, mlm-command will return a "non-local-list" error if the value of ThisDomain cannot be found within ListHost.)
ListDomain The second-level domain of the server that hosts the mailing list specified in ListAddress.
ReferringPage Equal to HTTP_REFERER; provided as a convenience.
ReferringHost The FQDN of the server on which ReferringPage (or HTTP_REFERER) resides. If ForceLocalReferrer is zero, it may be expected that this may differ from ThisHost at least occasionally. (If ForceLocalReferrer is non-zero, mlm-command will return a "non-local-referrer" error if the value of ThisDomain cannot be found within ReferringHost.)
ReferringDomain The second-level domain containing ReferringHost (and ReferringPage).
EmailAddress Value passed from calling form.
Action Value passed from calling form. (This value will be all lower-case by the time it is interpolated into your DisplayFile.)
ActionDescription Value which will be interpolated based on the value of Action, as described in the mlm-command Command Reference.
ListManager Value passed from calling form. (This value will be all lower-case by the time it is interpolated into your DisplayFile.)
ListMgrName A version of ListManager with the first letter uppercased, for more "proper" display.
RealName Value passed from calling form.
ReturnURL Value passed from calling form.
DisplayFile Value passed from calling form. By the time it is interpolated into your DisplayFile, it will have had DOCUMENT_ROOT prepended to it, and the error code appended to it. It will therefore be the full pathname of the file currently being displayed!
DisplayPath DisplayFile, truncated until it represents a directory. If DisplayFile is a directory, then DisplayPath will be equal to it; however, if DisplayFile represents a file-glob on the server, DisplayPath will be directory containing those files. Either way, DisplayPath can be used in IMG SRC values to allow images to display properly in your DisplayFiles; see the "corporate" files included with the standard mlm-command distribution for examples.
FullError This value will only be set if an error page is being displayed. In that case, it will be the actual error message returned when things went wrong. This can be useful for debugging conditions like err-mail and err-other.

Home  |  Command Reference  |  Sysadmin Docs  |  User Installation