Processing Control ($C, $L, $R, $E)

The $C, $L, $R, and $E metacharacters control whether and when the mapping process terminates. As described in 10.3.2 Mapping Operations, the mapping process normally consists of a single pass, from top to bottom, ending at the first entry with a pattern matching the input string, with the result specified by the template of that entry. Even if the processing of a metacharacter in the template fails, the mapping process would normally terminate because the input string matched the pattern of that entry. The metacharacters $C, $L, and $R cause the mapping process to continue instead of terminate. The metacharacter $E explicitly terminates the mapping process, thus overriding a previous $C on the same line.

The metacharacters $C, $L, and $R can be used to change the input string and continue the mapping process. If the template modifies the output string and $C, $L, or $R are used, the mapping process continues with the output string of the current entry used as the input string for further operations. $C continues with the next entry. $L continues with the next entry, but if no matching entry is found before the end of the table, one more pass will be made starting again at the top of the table. $R continues from the top of the table.

Templates are processed from left to right. When the intention is that an entry should succeed and terminate the mapping process if the template succeeds, but that the mapping process should continue if the template fails, then the entry should use the $C (or $R or $L) metacharacter to the left of the part that may fail and $E to the right of that part.

For example, see the PORT_ACCESS table where the $|...| callout is used in 18.7.4 To Use DNS Lookups Including RBL Checking for SMTP Relay Blocking to check the client IP address against the INTERNAL_IP table. If the lookup succeeds, the template processing ends with $Y and the mapping process is terminated by the $E. But if the lookup fails, the template processing ends with the failure, but the $C causes the mapping process to continue. Because this template generated no output string, the original input string remains unmodified.

Because metacharacters $L and $R reiterate the mapping process, the number of iterative passes through a mapping table is limited to prevent infinite loops. A counter is incremented each time a pass is restarted with a new input string that is the same length or longer than the previous pass. If the resulting output string has a shorter length than the input string, the counter is reset to zero. A request to reiterate a mapping is ignored after the counter has exceeded 10.

Note that any of the metacharacters $C, $E, $L, or $R, when present in the template, influences the mapping process and control whether it terminates or continues. That is, it is possible to set up iterative mapping table entries, where the output of one entry becomes the input of another entry. If the template of a matching pattern does not contain any of the metacharacters $C, $E, $L, or $R, then $E (immediate termination of the mapping process) is assumed.

The number of iterative passes through a mapping table is limited to prevent infinite loops. A counter is incremented each time a pass is restarted with a pattern that is the same length or longer than the previous pass. If the string has a shorter length than previously, the counter is reset to zero. A request to reiterate a mapping is not honored after the counter has exceeded 10.