Mapping entry templates

If the comparison of the pattern in a given mapping entry fails, no action is taken; the scan proceeds to the next entry. If the comparison succeeds, the right hand side of the entry is used as a template to produce an output string. The template effectively causes the replacement of the input string with the output string that is constructed from the instructions given by the template.

Almost all characters in the template simply produce themselves in the output. The one exception is a dollar sign.

A dollar sign followed by a dollar sign, space, or tab produces a dollar sign, space, or tab in the output string. Note that all these characters must be quoted in order to be inserted into the output string.

 A dollar sign followed by a digit n calls for a substitution; a dollar sign followed by an alphabetic character is referred to as a "metacharacter". Metacharacters themselves will not appear in the output string produced by a template. See the table below for a list of the special substitution and standard processing metacharacters. Any other metacharacters are reserved for mapping-specific applications.

Note that any of the metacharacters $C, $E, $L, or $R, when present in the template of a matching pattern, will influence the mapping process, controlling 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 again iterate a mapping is not honored after the counter has exceeded 10.

 Wildcard field substitutions, $n
A dollar sign followed by a digit n is replaced with the material that matched the nth wildcard in the pattern. The wildcards are numbered starting with 0. For example, the entry PSI$%&#x2a;::&#x2a;   $1@$0.psi.network.org would match the input string PSI%A::B and produce the resultant output string b@a.psi.network.org. The input string PSI%1234::USER would also match producing USER@1234.psi.network.org as the output string. The input string PSIABC::DEF would not match the pattern in this entry and no action would be taken; i.e., no output string would result from this entry.

 Controlling text case, $\, $^, $_
forces subsequent text to lowercase,   forces subsequent text to uppercase, and    causes subsequent text to retain its original case (and turns off LDAP URL quoting if it had been previously turned on via the   metacharacter.  For instance, these metacharacters may be useful when using mappings to transform addresses for which case is significant.

 Processing control, $C, $L, $R, $+1R, $E, $+1E
The,  ,  , and    metacharacters influence the mapping process, controlling whether and when the mapping process terminates. causes the mapping process to continue with the next entry, using the output string of the current entry as the new input string for the mapping process. causes the mapping process to continue with the next entry, using the output string of the current entry as the new input string for the mapping process, and, if no matching entry is found, making one additional pass through the table starting with the first table entry; a subsequent matching entry with a,  , or    metacharacter overrides this condition. causes the mapping process to continue from the first entry of the table, using the output string of the current entry as the new input string for the mapping process. causes the mapping process to terminate; the output string of this entry is the final output. is the default.

New in MS 6.3 is the  metacharacter. It acts like , except that unlike   it inhibits (stops) interpretation of the rest of the template.

New in MS 8.0.2.2, the  provides a variant of  : Rather than restarting the entire mapping from the first entry, it repeats the current entry with updated output from the current operation.

The  is useful in constructing mappings that perform multiple replacements of all occurrences of one string with another where some of the strings overlap. A single operation of this sort can be done with ; for example, replacing all percent signs with at-signs can be done with: PERCENT_TO_AT &#x2a;%&#x2a;         $R$0@$1 &#x2a;           $0$Y But when multiple replacements are involved restarting the mapping from the beginning is inefficient. And if the strings being replaced overlap restarting from the beginning won&#x27;t work because the earlier, completed operations will see the later replacements and get confused. For this to work repeating the same entry until it no longer matches is required.

For example, the following mapping performs the quoting necessary for a string being inserted into an LDAP DN: DN_QUOTE &#x2a;\&#x2a;        $+1R$0~$1 &#x2a;~&#x2a;        $+1R$0\5c$1 #&#x2a;         $C\23$0 &#x2a;"&#x2a;        $+1R$0\22$1   &#x2a;+&#x2a;         $+1R$0\2b$1   &#x2a;,&#x2a;         $+1R$0\2c$1   &#x2a;;&#x2a;         $+1R$0\3b$1   &#x2a;&#x3c;&#x2a;         $+1R$0\3c$1   &#x2a;&#x3e;&#x2a;         $+1R$0\3e$1   &#x2a;           $0$Y Note that if   was used that the inital entry would damage the later replacement operations.

Mapping table templates are scanned left to right. So to set a ,  , or   flag for entries that may "succeed" or "fail", e.g.,  general database  substitutions, or random value controlled entries,  put the  ,  , or    metacharacter to the left of the part of the entry that may succeed or fail; otherwise, if the remainder of the entry fails, the flag will not be seen.

 Check for special flags
Some mapping probes have special flags set.   causes an entry to match only if the flag   is set.   causes an entry to match only if the flag   is clear. See specific mapping table descriptions for any special flags that may apply for that table.

When the intention is that an entry should succeed and terminate if the flag check succeeds, but that the mapping process should continue if the flag check fails, then the entry should use the    metacharacter to the left of the flag check and use the     metacharacter to the right of the flag check.

 Entry randomly succeeds or fails, $?x?
A    sequence in a mapping table entry causes the entry to "succeed"   percent of the time; the rest of the time, the entry "fails" and the output of the mapping entry&#x27;s input is taken unchanged as the output. (Note that, depending upon the mapping, the effect of the entry "failing" is not necessarily the same as the entry not matching in the first place.) The argument between the &#x27;s,  , should consist of a real number specifying the success percentage.

For instance, suppose that a system with IP address 123.45.6.78 is sending your site just a little too much e-mail and you&#x27;d like to slow it down; if you&#x27;re using the MTA&#x27;s SMTP server on port 25, you can use a   mapping table  in the following way. Suppose you&#x27;d like to allow through only 25 percent of its connection attempts and temporarily reject the other 75 percent of its connection attempts. The following  mapping table uses    to cause the entry with the   (accept the connection) to succeed only 25 percent of the time; the other 75 percent of the time, when this entry fails, the initial    on that entry causes the MTA to continue the mapping from the next entry, which causes the connection attempt to be rejected with a temporary SMTP error (in this example,  ) and the text message  " ". PORT_ACCESS TCP&#x7c;&#x2a;&#x7c;25&#x7c;123.45.6.78&#x7c;&#x2a;    $C$?25?$Y TCP&#x7c;&#x2a;&#x7c;25&#x7c;123.45.6.78&#x7c;&#x2a;    $N452$ 4.4.0$ Try$ again$ later Another example would be randomly issuing a temporary failure message for a certain percentage of SMTP messages from a particular envelope From address; for instance, suppose the goal is to issue a temporary failure message with extended SMTP code  to eighty percent  of the messages that busybee@some.where attempts to send to your local channel users. Then a   mapping  table could be used, e.g., SEND_ACCESS tcp_&#x2a;&#x7c;busybee@some.where&#x7c;l&#x7c;&#x2a;   $C$?20?$Y tcp_&#x2a;&#x7c;busybee@some.where&#x7c;l&#x7c;&#x2a;   $N$X4.5.9&#x7c;Try$ again$ later

 Load average substitutions, #%...%
At the present time load average substitutions are not implemented.

 Select random entry from list, $?a,b,c...?
As of MS 8.0.2.3, a    sequence consisting of two or more comma-separated string values in a mapping table entry causes one of the string values to be selected at random and retained in the output.

 Sequence number substitutions, $#...#
A  substitution increments the value stored in an MTA sequence file and substitutes that value into the template. This can be used to generate unique, increasing strings in cases where it is desirable to have a uniquifier in the mapping table output; for instance, when using a mapping table to generate file names.

Permitted syntax is any one of: $#seq-file-spec# or $#seq-file-spec&#x7c;radix# or $#seq-file-spec&#x7c;radix&#x7c;width# or (new in MS 6.1) $#seq-file-spec&#x7c;radix&#x7c;width&#x7c;modulus# where the optional   argument is a full file specification for an (already existing) MTA sequence file, and where the optional  ,  , and   arguments specify the radix (base) in which to output the sequence value, the number of digits to output, and the modulus, respectively. The   argument may be omitted, in which case the MTA will use its own temporary sequence file (that will be created and used for the duration of this image). The default radix is 10. Radices in the range -36 to 36 are also allowed; for instance, base 36 gives values expressed with digits 0,...,9,A,...,Z. By default, the sequence value is printed in its natural width, but if the specified width calls for a greater number of digits, then the output will be padded with 0&#x27;s on the left to obtain the desired number of digits. Note that if a width is explicitly specified, then the radix must be explicitly specified also. If a modulus is specified, then the value inserted is the sequence number retrieved from the file mod the modulus; the default (and the only behavior available prior to MS 6.1) is not to perform any modulus operation.

As noted above, when specifying an explicit sequence file in a mapping, that file must already exist. To create a proper sequence file, on UNIX use the command: % touch seq-file-spec or % cat &#x3e;seq-file-spec A sequence number file accessed via a mapping table must be world readable in order to operate properly. (In particular, the  user id, as specified in the   file,is used to access the file.)

 Hash substitutions, $+n#...#
(New in 7.4-18.01.)

A  substitution,    &#x3e; 0,  computes a hash of a specified string and inserts the hash result into the mapping result. The value   selects the type of hash to compute.

Permitted syntax is any one of: $+n#string# or $+n#string&#x7c;radix# or $+n#string&#x7c;radix&#x7c;width# $+n#string&#x7c;radix&#x7c;width&#x7c;modulus# where the   argument is the string to be hashed, and where the optional  ,  , and   arguments specify the radix (base) in which to output the hash value, the number of digits to output, and the modulus, respectively. The default radix is 10. Radices in the range -36 to 36 are also allowed; for instance, base 36 gives values expressed with digits 0,...,9,A,...,Z. By default, the sequence value is printed in its natural width, but if the specified width calls for a greater number of digits, then the output will be padded with 0&#x27;s on the left to obtain the desired number of digits. Note that if a width is explicitly specified, then the radix must be explicitly specified also. If a modulus is specified, then the value inserted is the sequence number retrieved from the file mod the modulus; the default is not to perform any modulus operation on the hash value.

As noted above, the value of   selects the hash operation to perform. Currently the only supported value for   is 1, which employs the following hash function (32 bit integers are assumed): int hashvalue(char &#x2a;string, int length) {    unsigned int hash; int i, j;    unsigned int &#x2a;uptr; uptr = (unsigned int &#x2a;)string; hash = length; j = length &#x3e;&#x3e; 2; for (i = 0; i &#x3c; j; i++) {        hash ^= &#x2a;uptr++; hash = (hash &#x3c;&#x3c; 9) &#x7c; (hash &#x3e;&#x3e; 23); }    for (i = j &#x3c;&#x3c; 2; i &#x3c; length; i++) {        hash ^= string&#x5b;i&#x5d;; hash = (hash &#x3c;&#x3c; 13) &#x7c; (hash &#x3e;&#x3e; 19); }    return ((hash &#x2a; 0x71279461U) &#x3e;&#x3e; 2); }

 Character value substitutions, $&...&
(New in MS 6.2.) The MTA can generate UTF-8 strings from Unicode character values using the $&...& substitution sequence. Multiple Unicode character values may be specified, by separating them with the comma character. For instance, substitution sequence of the form: $&A0A0,20,A1A1& will produce a UTF-8 string containing the characters at position A0A0, 20, and A1A1.

 LDAP query URL substitutions, $&#x5d;...&#x5b;, $&#x5d;$&#x5d;...&#x5b;, $&#x5d;$&#x5d;$&#x5d;...&#x5b;, $=, $.
A substitution of the form   ,    , or     is handled  specially.   is interpreted as an LDAP query URL and the result of the LDAP query is substituted. The difference between the three forms is that in the case of a multi-valued result,    uses the  "first" returned value (note that the LDAP protocol leaves the order of values returned as unspecified and implementation-dependent -- thus you must not make any assumptions about which value might be returned "first"), whereas a multi-valued response is an error (the lookup is considered to have failed) for    , and (new in 8.0) the     form concatenates all the results together, separated by CRLFs.

Standard LDAP URLs as per RFC 2255 are used, with the host and port typically omitted. (In versions prior to 7.4-18.01, the host and port had to be omitted; as of version 7.4-18.01, specifying the LDAP host and port in the URL is permissable.) If the host and port are omitted, they are assumed from the values of the  and   MTA options  (or the   and   base options, if the MTA options are not set, corresponding to the legacy    parameters   and  ). That is, the LDAP URL should be specified as: ldap:///dn&#x5b;?attributes&#x5b;?scope?filter&#x5d;&#x5d; or ldap://host&#x5b;:port&#x5d;/dn&#x5b;?attributes&#x5b;?scope?filter&#x5d;&#x5d; where the square bracket characters   and   shown above indicate optional portions of the URL. The   is required and is a distinguished name specifying the search base. The optional  ,  , and   portions of the URL further refine what information to return. That is,   specifies the attribute or attributes to be returned from LDAP directory entries matching this LDAP query. The   may be any of  (the default), , or.   describes the characteristics of matching entries.

As of Messaging Server 7.2-7.02, so-called external LDAP (extldap:) URLs are also  supported. (As of the Messaging Server 7.0u4 support for explicit host and port specification directly in the LDAP URL, this functionality is somewhat redundant. But it may still be useful when a particular external directory, and perhaps one with different authentication credentials needed for access, is used.) That is, if a URL is specified as  extldap:///dn&#x5b;?attributes&#x5b;?scope?filter&#x5d;&#x5d; then an LDAP lookup will be performed against the alternate LDAP directory configured (via the LDAP external directory lookup MTA options) as the "external LDAP" directory.

Note that LDAP URLs have special character quoting (encoding) requirements. (See RFC 1738, Section 2.2, "URL Character Encoding Issues", and RFC 2254, Section 4, "String Search Filter Definition". Note that the quoting rules in RFC 1960, Section 3, "String Search Filter Definition", have been superceded by those of RFC 2254.) The  metacharacter  forces subsequent material to be properly quoted (encoded) for LDAP URL usage; that is,  any of the characters $ & +, : ; = ? will be converted to the percent character, , followed by the hexadecimal representation of their location in US-ASCII, any of the characters &#x2a; will be converted to " followed by the hexadecimal representation of their location in US-ASCII (the encoded form of the backslash character followed by the hexadecimal for the particular character), while the backslash character itself  \ will be converted to  ".

The  metacharacter  disables such LDAP quoting.

So note that when using a  LDAP URL callout, one should normally use the   and   metacharacters around and substituted material that might contain special characters, and manually encode any fixed special characters in the material in the callout, or use just the    and   metacharacters around the entire interior of the LDAP URL body, e.g., $&#x5d;ldap:///$=...$_&#x5b; The overall length of the LDAP URL (after any substitutions are performed) is limited to 252 characters in iMS 5.2, limited to 256 characters in MS 6.0 through MS 6.2, and limited to 1024 characters as of MS 6.3. Note also that the length of the original template in which such an LDAP URL appears is limited: to 252 characters in iMS 5.2 and earlier, or to 256 characters as of MS 6.0 and later; but substitutions in the template, and in particular substitutions used to construct the LDAP URL, may increase the LDAP URL length.

(New in MS 6.3.) The     sequence can be used in a mapping entry to establish a string   which will be processed as the mapping entry result in the event of a temporary LDAP lookup failure. By default temporary LDAP failures cause the current mapping entry to fail, which is is problematic in cases where different actions need to be taken depending on whether the LDAP lookup failed versus the directory server being unavailable or misconfigured. Once a failure string has been set using this construct, it will remain set until current mapping processing is completed. can be used to return to the default state where no temporary failure string is set and temporary LDAP failures cause mapping entry failure. Note that all errors other than failure to match an entry in the directory are considered to be temporary errors; in general it isn&#x27;t possible to distinguish between errors caused by incorrect LDAP URLs and errors caused by directory server configuration problems.

 LDAP domain map attribute substitutions, $}...{
(New in MS 6.1p1/MS 6.2.) A substitution of the form      is handled specially.   is looked up in the directory as a domain, with domain map processing of the   to build a proper LDAP query URL being automatically performed by the MTA. (In particular, in Schema 1 mode, the   is looked up in the DC portion of the directory; while in Schema 2 mode, the   is looked up using the  Schema 2 domain filter.) Note that this argument   truly is a domain name. If the domain   exists and has the specified  , then the attribute&#x27;s initial value is substituted into the mapping result; if either the attribute or the domain does not exist, then the mapping entry fails.

The following special syntaxes are also supported:

(New in 8.0.) A substitution of the form      is handled specially.   is looked up in the directory as a user name.

The following attributes can be specified:

(New in MS 8.0.2) A substitution of the form      is handled specially.   is treated as the name of a deployment map host.

The following queries can be specified:

 General database substitutions, ${...}
A substitution of the form    is handled specially. The   part is used as a key to access the MTA&#x27;s general database. If   is found in the database, the corresponding template from the database is substituted. If   does not match an entry in the database, the input string is used unchanged as the output string.

Depending upon the setting of the   MTA option, the general "database" is either stored and accessed as an on-disk database (the default), or as an in-memory structure constructed (during configuration compilation or MTA initialization) from an on-disk flat text file. Or new in MS 8.0, the general "database" can instead be stored in memcache; see the  MTA option. The on-disk database, if that is what is being used, is   (which formerly could be redirected via the now-deleted   MTA Tailor option), which must be generated using the   utility  from some site-supplied source text file. If an in-memory database structure is instead being used, then when the MTA configuration is compiled (or at MTA process initialization time, if a compiled configuration is not in use) the MTA reads the file  (which formerly could be redirected via the now-deleted   MTA Tailor file option),  and compiles it into an in-memory structure. Use of an in-memory "database" is normally recommended (for reasons of performance and reliability); however, do note that use of this in-memory "database" does require recompiling the configuration  to get changes to the "database" (changes to the source text file) incorporated into the compiled configuration.

Note that when wishing to use processing control  metacharacters such as ,  , or    in a mapping table entry that does a general database substitution, the processing control metacharacter should be placed to the left of the general database substitution in the mapping table template; otherwise the "failure" of a general database substitution will mean that the processing control metacharacter will not be seen.

In some cases it may be useful to test to see if a given entry exists in the general database without substituting the corresponding template value from the database entry. This can be accomplished by creating a secondary mapping of the form: GENERAL_EXISTS &#x2a;                     $E${$0}$C &#x2a;                     $Y A mapping table substitution callout, described in the following section, with the general database key as the probe, will now succeed if and only if the corresponding entry is in the database, but will not return the corresponding template from the database entry.

 Mapping table substitutions, $&#x7c;...&#x7c;
A substitution of the form        is handled specially. The MTA looks for an auxiliary mapping table named   in the mapping file, and uses   as the input (probe) to that named auxiliary mapping table. The named auxiliary mapping table must exist and must set the  flag in its output  if it is successful; if the named auxiliary mapping table does not exist or doesn&#x27;t set the   flag, then that auxiliary mapping table  substitution fails and the original mapping entry is considered to fail: the original input string will be used as the output string.

A substitution of the form     , where   is a non-zero bit-encoded value works in same way, except that one or more  -separated prefixes are added to the auxiliary mapping probe. The available prefixes are:

If multiple bits are enabled the corresponding prefixes are added in numerical order with the least significant bit on the left.

Note that prefixes required an enqueue context; they will be ignored in mapping calls where such a context is not available.

Note that when wishing to use processing control  metacharacters such as ,  , or    in a mapping table entry  that does a mapping table substitution, the processing control metacharacter should be placed to the left of the mapping table substitution in the mapping table template; otherwise the "failure" of a mapping table substitution will mean that the processing control metacharacter will not be seen.

Mapping table substitutions have similarities to both subroutine calls and nesting of regular expressions using parentheses. The following recipient rate limit example illustrates the subroutine call aspect of mapping table substitutions by using a separate mapping table to remove any subaddress from an address so that subaddresses can&#x27;t be used to avoid the limit.

A Metermaid throttle table with the following settings is used to implement a limit of 10 occurrence of a given recipient every 5 minutes: msconfig&#x3e; show metermaid.local_table:reclim role.metermaid.local_table:reclim.data_type = string role.metermaid.local_table:reclim.max_entries = 100000 role.metermaid.local_table:reclim.quota = 10 role.metermaid.local_table:reclim.quota_time = 300 role.metermaid.local_table:reclim.table_type = throttle The following mapping removes any subaddress that&#x27;s present in an address: REMOVE_SUBADDRESS "$&#x5b;a-z0-9.#$&&#x27;&#x2a;\-/=?^_`{}\~&#x5d;&#x2a;+$_&#x2a;"@&#x2a; $Y$0@$2 "$_&#x2a;+$_&#x2a;"@&#x2a;                          $Y"$0"@$2 $_&#x2a;+$_&#x2a;@&#x2a;                            $Y$0@$2 &#x2a;                                    $Y$0 And finally, the following callout rule added at the end of the  mapping implements the limit: tcp_&#x2a;&#x7c;&#x2a;&#x7c;&#x2a;&#x7c;&#x2a; $C$;R$&#x5b;IMTA_LIB:check_metermaid.so,throttle,reclim,$&#x7c;REMOVE_SUBADDRESS;$3&#x7c;&#x5d;$X4.2.3&#x7c;$NRate$ too$ high$E Note the "$;R" (new in MS 8.0) prevents this rule from being applied to enqueues from "internal" channels (process channel, reprocess channel, conversions channel, etc.).

 Expression substitutions, $`..&#x27;
In addition to basic arithmetic operations and tests listed in Operators in Order of Precedence, see Symbol table functions  for a list of additional functions available for use in expressions. Note that mapping tables operate on strings; string arguments must be converted to integers (see for instance the  function)  before performing integer arithmetic on them, and conversely any arithmetic intermediate results must be converted back to strings (see for instance the    function) before being substituted back into  mapping table entry templates.

Expression arithmetic can be used to manipulate IP addresses, which are a common component of many mapping probes. For example, the following mapping takes an IP address as input performs a general database lookup on successive subnets derived from the input address up to /8: SUBNET_LOOKUP $D&#x2a;.$D&#x2a;.$D&#x2a;.$D&#x2a;   $C${$0.$1.$2.$3/32}$Y$E $D&#x2a;.$D&#x2a;.$D&#x2a;.$D&#x2a;   $C${$0.$1.$2.$`$3&#x3e;&#x3e;1&#x3c;&#x3c;1&#x27;/31}$Y$E $D&#x2a;.$D&#x2a;.$D&#x2a;.$D&#x2a;   $C${$0.$1.$2.$`$3&#x3e;&#x3e;2&#x3c;&#x3c;2&#x27;/30}$Y$E $D&#x2a;.$D&#x2a;.$D&#x2a;.$D&#x2a;   $C${$0.$1.$2.$`$3&#x3e;&#x3e;3&#x3c;&#x3c;3&#x27;/29}$Y$E $D&#x2a;.$D&#x2a;.$D&#x2a;.$D&#x2a;   $C${$0.$1.$2.$`$3&#x3e;&#x3e;4&#x3c;&#x3c;4&#x27;/28}$Y$E $D&#x2a;.$D&#x2a;.$D&#x2a;.$D&#x2a;   $C${$0.$1.$2.$`$3&#x3e;&#x3e;5&#x3c;&#x3c;5&#x27;/27}$Y$E $D&#x2a;.$D&#x2a;.$D&#x2a;.$D&#x2a;   $C${$0.$1.$2.$`$3&#x3e;&#x3e;6&#x3c;&#x3c;6&#x27;/26}$Y$E $D&#x2a;.$D&#x2a;.$D&#x2a;.$D&#x2a;   $C${$0.$1.$2.$`$3&#x3e;&#x3e;7&#x3c;&#x3c;7&#x27;/25}$Y$E $D&#x2a;.$D&#x2a;.$D&#x2a;.$D&#x2a;   $C${$0.$1.$2/24}$Y$E $D&#x2a;.$D&#x2a;.$D&#x2a;.$D&#x2a;   $C${$0.$1.$`$2&#x3e;&#x3e;1&#x3c;&#x3c;1&#x27;/23}$Y$E $D&#x2a;.$D&#x2a;.$D&#x2a;.$D&#x2a;   $C${$0.$1.$`$2&#x3e;&#x3e;2&#x3c;&#x3c;2&#x27;/22}$Y$E $D&#x2a;.$D&#x2a;.$D&#x2a;.$D&#x2a;   $C${$0.$1.$`$2&#x3e;&#x3e;3&#x3c;&#x3c;3&#x27;/21}$Y$E $D&#x2a;.$D&#x2a;.$D&#x2a;.$D&#x2a;   $C${$0.$1.$`$2&#x3e;&#x3e;4&#x3c;&#x3c;4&#x27;/20}$Y$E $D&#x2a;.$D&#x2a;.$D&#x2a;.$D&#x2a;   $C${$0.$1.$`$2&#x3e;&#x3e;5&#x3c;&#x3c;5&#x27;/19}$Y$E $D&#x2a;.$D&#x2a;.$D&#x2a;.$D&#x2a;   $C${$0.$1.$`$2&#x3e;&#x3e;6&#x3c;&#x3c;6&#x27;/18}$Y$E $D&#x2a;.$D&#x2a;.$D&#x2a;.$D&#x2a;   $C${$0.$1.$`$2&#x3e;&#x3e;7&#x3c;&#x3c;7&#x27;/17}$Y$E $D&#x2a;.$D&#x2a;.$D&#x2a;.$D&#x2a;   $C${$0.$1/16}$Y$E $D&#x2a;.$D&#x2a;.$D&#x2a;.$D&#x2a;   $C${$0.$`$1&#x3e;&#x3e;1&#x3c;&#x3c;1&#x27;/15}$Y$E $D&#x2a;.$D&#x2a;.$D&#x2a;.$D&#x2a;   $C${$0.$`$1&#x3e;&#x3e;2&#x3c;&#x3c;2&#x27;/14}$Y$E $D&#x2a;.$D&#x2a;.$D&#x2a;.$D&#x2a;   $C${$0.$`$1&#x3e;&#x3e;3&#x3c;&#x3c;3&#x27;/13}$Y$E $D&#x2a;.$D&#x2a;.$D&#x2a;.$D&#x2a;   $C${$0.$`$1&#x3e;&#x3e;4&#x3c;&#x3c;4&#x27;/12}$Y$E $D&#x2a;.$D&#x2a;.$D&#x2a;.$D&#x2a;   $C${$0.$`$1&#x3e;&#x3e;5&#x3c;&#x3c;5&#x27;/11}$Y$E $D&#x2a;.$D&#x2a;.$D&#x2a;.$D&#x2a;   $C${$0.$`$1&#x3e;&#x3e;6&#x3c;&#x3c;6&#x27;/10}$Y$E $D&#x2a;.$D&#x2a;.$D&#x2a;.$D&#x2a;   $C${$0.$`$1&#x3e;&#x3e;7&#x3c;&#x3c;7&#x27;/9}$Y$E $D&#x2a;.$D&#x2a;.$D&#x2a;.$D&#x2a;   $C${$0/8}$Y$E

<span id='Mapping_routine_substitutions'> Mapping routine substitutions, $&#x5b;...&#x5d;
A substitution of the form         is handled specially. The   part is used to find and call an Oracle-supplied or customer-supplied routine. At run-time on UNIX, the MTA uses  and   to dynamically load and call the routine   from the shared library  . The routine   is then called as a function with the following argument list: status = routine (argument, arglength, result, reslength); The argument and result arguments are 256 byte long character string buffers in MS versions prior to 8.1.0.1. As of 8.1.0.2, the size has been increased to 1024 bytes. On UNIX systems argument and result are passed as a pointer to a character string, (e.g., in C, as char&#x2a;.) arglength and reslength are signed, 32 bit integers passed by reference. On input, argument contains the   string from the mapping table template, and arglength the length of that string. On return, the resultant string should be placed in result and its length in reslength. This resultant string will then replace the "   " in the mapping table template. The routine   should return 0 if the mapping table substitution should fail and -1 if the mapping table substitution should succeed. If the substitution fails, then normally the original input string will be used unchanged as the output string.

Note that when wishing to use processing control metacharacters such as ,  , or   in a mapping table entry  that does a site-supplied routine substitution, the processing control metacharacter should be placed to the left of the site-supplied routine substitution in the mapping table template; otherwise the "failure" of a mapping table substitution will mean that the processing control metacharacter will not be seen.

The site-supplied routine callout mechanism allows the MTA&#x27;s mapping process to be extended in all sorts of complex ways. For example, in a   or    mapping table,  a call to some type of load monitoring service could be performed and the result used to decide whether or not to accept a connection or message.

See the  callouts, the    callout, and    callout  for examples of Oracle-provided  such callout routines.

See also:
 * Mapping table format
 * Mapping operation
 * Testing mapping tables
 * ldap_domain_attr_basedn Option
 * ldap_domain_attr_canonical MTA Option
 * domain_failure MTA Option
 * ldap_host MTA Option
 * ldap_port MTA Option
 * ugldaphost Option
 * ugldapport Option
 * MTA URL types
 * LDAP external directory lookup MTA options
 * General database
 * use_text_databases MTA Option
 * Callout routines