PMDF System Manager's Guide

If the comparison of the pattern in a given 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 Table 5-2 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.

Table 5-2 Mapping Template Substitutions and Metacharacters

Substitution sequence	Section	Substitutes
$ n	5.3.2.1	nth wildcarded field as counted from left to right starting from 0
$#...#	5.3.2.6	Sequence number substitution.
$]...[	5.3.2.7	LDAP search URL lookup; substitute in result.
${...}	5.3.2.8	General database substitution.
$|...|	5.3.2.9	Apply specified mapping table to supplied string.
$[...]	5.3.2.10	Invoke site-supplied routine; substitute in result.
Metacharacter	Section	Description
$C	5.3.2.3	Continue the mapping process starting with the next table entry; use the output string of this entry as the new input string for the mapping process.
$E	5.3.2.3	End the mapping process now; use the output string from this entry as the final result of the mapping process.
$L	5.3.2.3	Continue the mapping process starting with the next table entry; use the output string of this entry as the new input string; after all entries in the table are exhausted make one additional pass starting with the first table entry. A subsequent match can override this condition with a $C, $E, or $R metacharacter.
$R	5.3.2.3	Continue the mapping process starting with the first entry of the the mapping table; use the output string of this entry as the new input string for the mapping process.
$? x?	5.3.2.5	Mapping entry succeeds x percent of the time.
$\	5.3.2.2	Force subsequent text to lowercase.
$^	5.3.2.2	Force subsequent text to uppercase.
$_	5.3.2.2	Leave subsequent text in its original case.
$: x	5.3.2.4	Match only if the specified flag is set.
$; x	5.3.2.4	Match only if the specified flag is clear.

5.3.2.1 Wildcard Field Substitutions, $n

PSI$%*::* $1@$0.psi.example.com

would match the input string PSI%A::B and produce the resultant output string b@a.psi.example.com. The input string PSI%1234::USER would also match producing USER@1234.psi.example.com 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.

5.3.2.2 Controlling Text Case, $\, $^, $_

5.3.2.3 Processing Control, $C, $L, $R, $E

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

5.3.2.4 Check for Special Flags

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 $C metacharacter to the left of the flag check and use the $E flag to the right of the flag check.

5.3.2.5 Entry Randomly Succeeds or Fails, $?x?

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'd like to slow it down; if you're using the multithreaded TCP SMTP channel, you can use a PORT_ACCESS mapping table in the following way. Suppose you'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 PORT_ACCESS mapping table uses $?25? to cause the entry with the $Y (accept the connection) to succeed only 25 percent of the time; the other 75 percent of the time, when this entry fails, the initial $C on that entry causes PMDF to continue the mapping from the next entry, which causes the connection attempt to be rejected with a temporary SMTP error (in this example, 452 4.4.0) and the text message "Try again later".

PORT_ACCESS TCP|*|25|123.45.6.78|* $C$?25?$Y TCP|*|25|123.45.6.78|* $N452$ 4.4.0$ Try$ again$ later

Or to similarly reject many, but not all, POP3 and IMAP connection attempts from a system with IP address 123.45.6.78:

PORT_ACCESS ! POP3 connections TCP|*|110|123.45.6.78|* $C$?25?$Y TCP|*|110|123.45.6.78|* $N-ERR$ Try$ again$ later ! IMAP connections TCP|*|143|123.45.6.78|* $C$?25?$Y TCP|*|143|123.45.6.78|* $N*$ BYE$ Try$ again$ later

See Section 23.2.1 for details on the PORT_ACCESS mapping table.

Another example would be to randomly issue 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 4.5.9 to 80 percent of the messages that busybee@some.where attempts to send to your local channel users. Then a SEND_ACCESS mapping table could be used, e.g.,

SEND_ACCESS tcp_*|busybee@some.where|l|* $C$?20?$Y tcp_*|busybee@some.where|l|* $N$X4.5.9|Try$ again$ later

5.3.2.6 Sequence Number Substitutions, $#...#

Permitted syntax is any one of:

$#seq-file-spec|radix|width#

or

$#seq-file-spec|radix#

or

$#seq-file-spec#

where the optional seq-file-spec argument is a full file specification for an (already existing) PMDF sequence file, and where the optional radix and width arguments specify the radix (base) in which to output the sequence value, and the number of digits to output, respectively. The seq-file-spec argument can be omitted, in which case PMDF 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'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.

As noted above, when specifying an explicit PMDF sequence file in a mapping, that file must already exist. To create a PMDF sequence file, on OpenVMS use the command

$ CREATE/FDL=PMDF_COM:sequence_number.fdl seq-file-spec

or on UNIX use the command

% touch seq-file-spec

or

% cat >seq-file-spec

or on NT use the command

C:\> copy nul seq-file-spec

A sequence number file accessed via a mapping table must be world readable in order to operate properly. You must also have a PMDF user account in order to use such sequence number files.
On OpenVMS, if you did not create a PMDF user account PMDF_USER during your PMDF installation, you should use the PMDF_COM:create_pmdf_user_account.com procedure to create it.

5.3.2.7 LDAP Query URL Substitutions, $]...[

ldap:///dn[?attributes[?scope?filter]]

where the square bracket characters [ and ] shown above indicate optional portions of the URL. The dn is required and is a distinguished name specifying the search base. The optional attributes, scope, and filter portions of the URL further refine what information to return. That is, attributes specifies the attribute or attributes to be returned from LDAP directory entries matching this LDAP query. The scope can be any of base (the default), one, or sub. filter describes the characteristics of matching entries.

Certain LDAP URL substitution sequences are available for use within the LDAP query URL; see Table 3-1 for a full list.

5.3.2.8 General Database Substitutions, ${...}

If a general database exists, it should be world readable to ensure that it operates properly.

Note that when wanting to use processing control metacharacters such as $C, $R, or $L 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.

5.3.2.9 Mapping Table Substitutions, $|...|

Note that when wanting to use processing control metacharacters such as $C, $R, or $L 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.

5.3.2.10 Site-supplied Routine Substitutions, $[...]

Note that when wanting to use processing control metacharacters such as $C, $R, or $L 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 PMDF's mapping process to be extended in all sorts of complex ways. For example, in a PORT_ACCESS or SEND_ACCESS 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.
On OpenVMS systems, since LIB$FIND_IMAGE_SYMBOL is used to dynamically load the site-supplied image image, then image must be a logical name pointing to the actual shareable image. Moreover, as this mechanism will be invoked by PMDF in a variety of contexts, the logical must be an executive mode logical, any logicals it references must also be executive mode logicals, and the image itself must be world readable and installed as a known image.

On UNIX systems, the site-supplied shared library image image should be world readable.