Test -mapping utility

From Messaging Server Technical Reference Wiki
Jump to: navigation, search

Test an MTA mapping table.

Syntax

  imsimta test -mapping [input-string]
imsimta test -mapping Command Switches
Switch Default
-context -context
-debug -nodebug
-destination_channel=channel -nodestination_channel
-flags=list-of-characters -noflags
-image_file -image_file
-mapping_file=file-spec -mapping_file=IMTA_TABLE:mappings
-option_file=file-spec -option_file=IMTA_TABLE:option.dat
-table=table-name None
-reload -noreload
-input=file-spec -input=stdin
-originator=address -nooriginator
-output=file-spec -output=stdout
-sources -sources
-source_channel=channel -nosource_channel

Prompts

imsimta test -mapping Prompts
Prompt Value
Enter table name: table-name

Parameters

input-string

Optional input string to run through the mapping.

Description

imsimta test -mappingmay be used to test the behavior of an MTA mapping table. The string resulting from mapping an input string will be output along with a list of any metacharacters specified in the output string.

If an input string is supplied on the command line, then only the result of mapping that input string will be output. If no input string is specified, then imsimta test -mapping will enter a loop, prompting for an input string, mapping that string, and prompting again for another input string. imsimta test -mapping will exit when a CTRL/D (UNIX) is entered.

Note that this utility is testing only the formal syntax and formal result of a mapping table; it is not testing what the mapping table means (the effect of the mapping table) for actual MTA operation. In particular, for testing the effect of *_ACCESS sorts of mapping tables, see instead the test -rewrite utility.

Or in the other (less semantic, more syntactic) direction, note that the matching of wildcards in mapping table patterns (left hand sides of entries) may be tested in detail via the test -⁠match utility, which may be of particular interest when using "complex" wildcards such as character "glob" matches, or IP address prefix matches.

Switches

-context (default), -nocontext

(New in MS 7.0) The -context switch is the default, and causes the mapping table to be probed as if operating in a normal, MTA usage, application (with normal MTA initialization having been performed). -nocontext causes the mapping table to be probed as if operating in a mode without normal MTA initialization, and hence may be useful for testing mapping table operation in non-MTA contexts.

-debug, -nodebug (default)

The mapping test process is capable of producing additional, detailed information about the sequence of steps in the mapping probe(s) and match(es). Such information is particularly likely to be of interest (useful) with iterative mapping tables, or mapping tables that involve callouts; that is, such debug information is most likely to be of interest when exploring implications of $C, $L, or $R metacharacter use, or effects of callouts such as to other mapping tables, to the general database, to LDAP, or to Oracle or site-supplied routines. The -debug switch enables this output; it is disabled by default.

-destination_channel=channel

(New in MS 8.1.0.1) The -destination_channel switch is used to specify a destination channel when the MTA is initialized for writing. The source channel is used if no desitnation channel is specified. See the documentation on the -source_channel switch below for additional information.

-flags=list-of-characters, -noflags (default)

The -flags switch is used to specify particular flags to set during the mapping testing; for instance, the E (envelope), B (header/body), R (backwards pointing), or I (message id) flags when testing a REVERSE mapping. Multiple flags may be specified by concatenating them, e.g., -flags=BR.

-image_file (default), -noimage_file

When the -image_file switch is specified (the default), the MTA will load the compiled configuration file CONFIGROOT/advanced/config_data (located prior to MS 7.0 via the imta_config_data MTA Tailor option). When -noimage_file is specified, then imsimta test -mapping will unconditionally ignore any compiled mapping information and instead read mapping information directly from the named MTA mapping groups (Unified Configuration) or the mappings file (legacy configuration).

-input=filename

(New in MS 8.0) By default, imsimta test -mapping takes input from stdin. The -input switch may be used to specify a different source for input.

-mapping_file=filename

This switch instructs imsimta test -mapping to use the specified mapping file rather than the default MTA mapping file, CONFIGROOT/mappings (located prior to MS 7.0 via the imta_mapping_file MTA Tailor option). This switch has no effect unless -noimage_file is specified or no compiled configuration exists; use of any compiled configuration will preclude reading any MTA mapping values (Unified Configuration) or physical mapping file (legacy configuration); this switch also has no effect when an XML configuration is in use.

-option_file=filename, -nooption_file

This switch instructs imsimta test -mapping to use the specified option file rather than the default MTA option file, CONFIGROOT/option.dat (prior to MS 7.0 located via the imta_option_file MTA Tailor option). This switch has no effect unless -noimage_file is specified or no compiled configuration exists; use of any compiled configuration will preclude reading any MTA options whether from mta.option-name (Unified Configuration) or from a physical option file (legacy configuration). Use of the switch -nooption_file will prevent the MTA option file from being read in when there is no compiled configuration. These switches have no effect when an XML configuration is in use.

-originator=address

(New in MS 8.1.0.1) The -originator switch is used to specify the envelope from (MAIL FROM) address when the MTA is initialized for writing. The value "mail@fom" is used if no originator address is specified. See the documentation on the -source_channel switch below for additional information.

-output=output_file_spec

(New in MS 8.0) By default, imsimta test -mapping writes output to stdout. The -⁠output switch may be used to direct the output of imsimta test -mapping elsewhere.

-reload, -noreload (default)

The -reload switch may be used to tell the utility to reread MTA mapping group options (Unified Configuration) or the mappings file (legacy configuration) if the mapping table name specified is not found cached in memory.

-source_channel=channel

(New in MS 8.1.0.1) Mappings do not depend on the MTA being initialized for writing a message, but some mapping plugins do. In order to test such plugins, the -source_channel can be used to cause the enqueue logic to be initialized using the specified channel. Also see the -originator and -destination_channel switches, which can be used to specify the envelope from (MAIL FROM) address and destination channel, respectively.

-sources (default), -nosources

(New in MS 8.0) The -nosources switch may be used to suppress the (new in MS 8.0) output of segment sources.

-table=table-name

This switch specifies the name of the mapping table to test. If this switch is not specified, then imsimta test -mapping will prompt for the name of a table to use.

Examples


# imsimta test -mapping -noimage_file -mapping_file=IMTA_TABLE:mac_mappings.sample
Enter table name: MAC-TO-MIME-CONTENT-TYPES 
Input string: BINHEX|7344424e|4d535744|Test.doc
Output string: APPLICATION/MSWORD 
Output flags: [0, 'Y' (89)] 
Input string: ^D
#

In the above UNIX example, the sample MAC-TO-MIME-CONTENT-TYPES mapping is tested. The -mapping_file switch is used to select the mapping file mac_mappings.sample instead of the default mapping file.


# imsimta test -mapping -flags=A -table=X-FLAGS
Input string: testing
Output string: testing plus A flag 
Output flags: [0, 'Y' (89)] 
Input string: ^D
# imsimta test -mapping -flags=B -table=X-FLAGS
Input string: next
Output string: next without A flag 
Output flags: [0, 'Y' (89)] 
Input string: ^D

The above example assumes that the mappings file contains a mapping table:


X-FLAGS 
 
   *              $C$:A$0$ plus$ A$ flag$Y$E 
   *              $;A$0$ without$ A$ flag$Y   

That X-FLAGS mapping table outputs the original input string plus suffix string " plus A flag" if the input flag "A" was present, or outputs the original input string plus suffix string " without A flag" if the input flag "A" was not set. In the above test -mapping utility output, it can be seen that input flags, if any, do not carry over to being present amongst the set of output flags: an input flag set via the -flags switch does not carry over to appear amongst the output flags in the "Output flags:" portion of the output. Input flags and output flags are distinct and separately stored. Also note how the entry with the $:A test has that test "wrapped" with the "$C...$E"; this is to cause the mapping process to "continue on" if that entry (in particular the test for the presence of the input flag "A") failed, but "end" if the test succeeded. In this particular example, the "$E" could have been omitted since the only subsequent entry explicitly checked for the opposite ("A" flag not present) condition. However wrapping with "$C...$E" is better practice, and is commonly used in entries containing tests.


See also: