PMDF System Manager's Guide

6.2.3 Conversion Control

The actual conversions performed by the conversion channel are controlled by rules specified in the PMDF conversions file. The conversions file is located via the PMDF_CONVERSION_FILE logical name (OpenVMS), or PMDF tailor file option (UNIX), or Registry entry (NT), and is usually the file PMDF_TABLE:conversions. on OpenVMS, or /pmdf/table/conversions on UNIX, or C:\pmdf\table\conversions on NT.

The PMDF conversion file is a text file containing entries in a format that is modelled after MIME Content-Type: parameters. Each entry consists of one or more lines grouped together; each line contains one or more "name=value;" parameter clauses. Quoting rules conform to MIME conventions for Content-Type: header line parameters. Every line except the last must end with a semicolon. Entries are terminated by either a line that does not end in a semicolon, one or more blank lines, or both. For example, the following entry (on OpenVMS) specifies that application/wordperfect5.1 parts in messages sent to the local channel should be converted to DDIF:

out-chan=l; in-type=application; in-subtype=wordperfect5.1; out-type=application; out-subtype=ddif; parameter-copy-0=*; out-mode=block; command="CONVERT/DOCUMENT 'INPUT_FILE'/FORMAT=WORDP 'OUTPUT_FILE'/FORMAT=DDIF"

Or the following entry (on Tru64 UNIX) specifies that application/x-ddif parts in messages sent out to the Internet should be converted to PostScript:

out-chan=l; in-type=application; in-subtype=x-ddif; out-type=application; out-subtype=postscript; parameter-copy-0=*; command="ddifps $INPUT_FILE $OUTPUT_FILE"

6.2.3.1 Conversion Entry Scanning and Application

The conversion channel processes each message part by part. The header of each part is read and its Content-Type: and other header information is extracted. The entries in the conversion file are then scanned in order from first to last; any IN- parameters present and the OUT-CHAN parameter, if present, are checked. If all of these parameters match the corresponding information for the body part being processed, then the conversion specified by the remainder of the parameters is performed. Note that an entry must include an IN-TYPE clause in order to match. More specifically, the matching checks:

if the IN-CHAN and OUT-CHAN parameters match the channels through which the message is passing; and
if the PART-NUMBER matches the structured part number⁷ of the message part; and
if all of the IN-PARAMETER-NAME, IN-PARAMETER-VALUE, IN-SUBTYPE, and IN-TYPE, parameters match the Content-Type of the message; and
if all of the IN-DISPOSITION, IN-DPARAMETER-NAME, and IN-DPARAMETER-VALUE parameters match the Content-Disposition of the message; and
if the IN-DESCRIPTION matches the Content-Description of the message; and
if the IN-SUBJECT, IN-A1-TYPE, and IN-A1-FORMAT match the headers of the immediately enclosing message message/rfc822 part.

Only if all specified parameters match is the entry consider to match. Scanning terminates once a matching entry has been found or all entries have been exhausted. If no entry matches no conversion is performed.

If the matching entry specifies DELETE=1, then the message part is deleted. Otherwise, the command specified by the COMMAND parameter is executed.

Once an entry with a COMMAND parameter has been selected the body part is extracted to a file (on OpenVMS, in a manner specified by the FDL-OVERRIDE and FDL-STRING parameters). The converter execution environment is prepared as specified by the PARAMETER-SYMBOL-n and DPARAMETER-SYMBOL-n parameters, as well as all of the OUT- parameters. The OUT-TYPE, OUT-SUBTYPE, OUT-DESCRIPTION, OUT-DISPOSITION, and OUT-ENCODING parameters are used to specify the initial values for the corresponding DCL symbols (OpenVMS) or environment variables (UNIX and NT). The OUT-PARAMETER-NAME-n, OUT-PARAMETER-VALUE-n, OUT-DPARAMETER-NAME-n, and OUT-DPARAMETER-VALUE-n parameters are used to modify the Content-Type: and Content-Disposition: headers, which are passed to the command in the INPUT_HEADERS file.

Finally, a subprocess is created to run the command specified by the COMMAND parameter. The command should perform the necessary conversion operation, reading the file specified by the INPUT_FILE DCL symbol (OpenVMS) or environment variable (UNIX and NT) and producing the file specified by the OUTPUT_FILE DCL symbol (OpenVMS) or environment variable (UNIX and NT). The command may optionally specify its own MIME headers in the file specified by the OUTPUT_HEADERS DCL symbol (OpenVMS) or environment variable (UNIX and NT).

On OpenVMS, the command may optionally define job table logical names with which to pass information back to the conversion channel.

On UNIX and NT, the command may optionally set options in the OUTPUT_OPTIONS file to pass information back to the conversion channel.

Conversion operations are terminated and no conversion is performed if the spawned command returns an error.

If the command succeeds, the output symbols (OpenVMS) or options (UNIX and NT) are processed, the resulting output file is read as specified by OUTPUT_MODE, and if the OVERRIDE-HEADER-FILE parameter was set to 1, the output header file is read. A new body part containing the converted material and converted header is constructed according to the specified output symbols OUTPUT_TYPE, OUTPUT_SUBTYPE, OUTPUT_DESCRIPTION, OUTPUT_DISPOSITION, OUTPUT_ENCODING.

This process is repeated for each part of the message until all parts have been processed.

6.2.3.2 Available Parameters

The rule parameters currently provided are shown in Table 6-1.

Table 6-1 Available Conversion Parameters
Parameter Meaning

COMMAND Command to execute to perform conversion. This parameter is required; if no command is specified, the entry is ignored. Note: On NT, if the command contains a backslash, it must be escaped with another backslash. For example: C:\\PMDF\\TABLE\\TEST.BAT.§

DELETE 0 or 1. If this flag is set, the message part will be deleted. (If this is the only part in a message, then a single empty text part will be substituted.)

DPARAMETER-COPY- n A list of the Content-Disposition: parameters to copy from the input body part's Content-Disposition: parameter list to the output body part's Content-Disposition: parameter list; n = 0, 1, 2, .... Takes as argument the name of the MIME parameter to copy, as matched by an IN-PARAMETER-NAME-m clause. Wildcards may be used in the argument. In particular, an argument of * means to copy all the original Content-Disposition: parameters.

DPARAMETER-SYMBOL- n Content-disposition parameters to convert to environment variables (DCL symbols on OpenVMS) if present; n = 0, 1, 2, .... Takes as argument the name of the MIME parameter to convert, as matched by an IN-DPARAMETER-NAME-m clause. Each DPARAMETER-SYMBOL-n is extracted from the Content-Disposition: parameter list and placed in an environment variable or DCL symbol of the same name prior to executing the converter.

+ FDL-OVERRIDE 0 or 1; if 1 the FDL information specified by the FDL-STRING entry parameter is used unconditionally; if 0 the FDL-STRING entry parameter will be overriden by an FDL-STRING Content-Type: parameter.

+ FDL-STRING OpenVMS FDL information used to construct the input file for the converter. Prior to conversion the body part is written into an RMS file created using this FDL information. A FDL-STRING parameter will override the FDL-STRING entry parameter unless FDL-OVERRIDE is 1. Usage of this parameter is restricted to OpenVMS systems.

IN-A1-FORMAT Input A1-Format from enclosing message/rfc822 part.

IN-A1-TYPE Input A1-Type from enclosing message/rfc822 part.

IN-CHAN Input channel to match for conversion (wildcards allowed). The conversion specified by this entry will only be performed if the message is coming from the specified channel.

IN-CHANNEL Synonym for IN-CHAN.

IN-DESCRIPTION Input MIME Content-Description.

IN-DISPOSITION Input MIME Content-Disposition.

IN-DPARAMETER-DEFAULT- n Input MIME Content-Disposition parameter value default if parameter is not present. This value is used as a default for the IN-DPARAMETER-VALUE-n test when no such parameter is specified in the body part.

IN-DPARAMETER-NAME- n Input MIME Content-Disposition parameter name whose value is to be checked; n = 0, 1, 2, ....

IN-DPARAMETER-VALUE- n Input MIME Content-Disposition parameter value that must match corresponding IN-DPARAMETER-NAME (wildcards allowed). The conversion specified by this entry is only performed if this field matches the corresponding parameter in the body part's Content-Disposition: parameter list.

IN-PARAMETER-DEFAULT- n Input MIME Content-Type parameter value default if parameter is not present. This value is used as a default for the IN-PARAMETER-VALUE-n test when no such parameter is specified in the body part.

IN-PARAMETER-NAME- n Input MIME Content-Type parameter name whose value is to be checked; n = 0, 1, 2, ....

IN-PARAMETER-VALUE- n Input MIME Content-Type parameter value that must match corresponding IN-PARAMETER-NAME (wildcards allowed). The conversion specified by this entry is only performed if this field matches the corresponding parameter in the body part's Content-Type: parameter list.

IN-SUBJECT Input Subject from enclosing message/rfc822 part.

IN-SUBTYPE Input MIME subtype to match for conversion (wildcards allowed). The conversion specified by this entry is only performed if this field matches the MIME subtype of the body part.

IN-TYPE Input MIME type to match for conversion (wildcards allowed). The conversion specified by this entry is only performed if this field matches the MIME type of the body part.

MESSAGE-HEADER-FILE 0, 1, or 2. If set to 1, the original headers of the immediately enclosing message part are written to the file represented by the MESSAGE_HEADERS symbol. If set to 2, the original headers of the message as a whole (the outermost message headers) are written to MESSAGE_HEADERS.

ORIGINAL-HEADER-FILE 0 or 1. If set to 1, the original headers of the enclosing part are written to the file represented by the INPUT_HEADERS symbol.

OUT-A1-FORMAT Output A1-Format.

OUT-A1-TYPE Output A1-Type.

OUT-CHAN Output channel to match for conversion (wildcards allowed). The conversion specified by this entry will only be performed if the message is destined for the specified channel.

OUT-CHANNEL Synonym for OUT-CHAN.

OUT-DESCRIPTION Output MIME Content-Description if it is different than the input MIME Content-Description.

OUT-DISPOSITION Output MIME Content-Disposition if it is different than the input MIME Content-Disposition

OUT-DPARAMETER-NAME- n Output MIME Content-Disposition parameter name; n = 0, 1, 2, ....

OUT-DPARAMETER-VALUE- n Output MIME Content-Disposition parameter value corresponding to OUT-DPARAMETER-NAME-n.

OUT-MODE Mode in which to read the converted file. This should be one of: BLOCK, RECORD, RECORD-ATTRIBUTE, TEXT.

OUT-ENCODING Encoding to apply to the converted file.

OUT-PARAMETER-NAME- n Output MIME Content-Type parameter name; n = 0, 1, 2, ....

OUT-PARAMETER-VALUE- n Output MIME Content-Type parameter value corresponding to OUT-PARAMETER-NAME-n.

OUT-SUBTYPE Output MIME type if it is different than the input MIME type.

OUT-TYPE Output MIME type if it is different than the input type

OVERRIDE-HEADER-FILE 0 or 1. If set, then MIME headers are read from the OUTPUT_HEADERS symbol, overriding the original MIME headers in the enclosing part.

++ OVERRIDE-OPTION-FILE 0 or 1. If set, then the conversion channel reads options from the OUTPUT_OPTIONS symbol.

PARAMETER-COPY- n A list of the Content-Type: parameters to copy from the input body part's Content-Type: parameter list to the output body part's Content-Type: parameter list; n = 0, 1, 2, .... Takes as argument the name of the MIME parameter to copy, as matched by an IN-PARAMETER-NAME-m clause. Wildcards may be used in the argument. In particular, an argument of * means to copy all the original Content-Type: parameters.

PARAMETER-SYMBOL- n Content-Type parameters to convert to environment variables (DCL symbols on OpenVMS) if present; n = 0, 1, 2, .... Takes as argument the name of the MIME parameter to convert, as matched by an IN-PARAMETER-NAME-m clause. Each PARAMETER-SYMBOL-n is extracted from the Content-Type: parameter list and placed in an environment variable or DCL symbol of the same name prior to executing the converter.

PART-NUMBER Dotted integers, e.g., a. b. c... The part number of the MIME body part.

RELABEL 0 or 1. This flag causes an entry to be ignored during conversion channel processing. However, if this flag is 1, then MIME header relabelling is performed during character set conversion. ^tm

SERVICE-COMMAND The command to execute to perform service conversion. This parameter is required; if no command is specified, the entry is ignored. Note that this flag causes an entry to be ignored during conversion channel processing; SERVICE-COMMAND entries are instead performed during character set conversion processing.®

TAG Input tag, as set by a mailing list [CONVERSION_TAG] named parameter, must match.

**Table 6-1 Available Conversion Parameters**
	Parameter	Meaning
	COMMAND	Command to execute to perform conversion. This parameter is required; if no command is specified, the entry is ignored. Note: On NT, if the command contains a backslash, it must be escaped with another backslash. For example: C:\\PMDF\\TABLE\\TEST.BAT.§
	DELETE	0 or 1. If this flag is set, the message part will be deleted. (If this is the only part in a message, then a single empty text part will be substituted.)
	DPARAMETER-COPY- n	A list of the `Content-Disposition:` parameters to copy from the input body part's `Content-Disposition:` parameter list to the output body part's `Content-Disposition:` parameter list; n = 0, 1, 2, .... Takes as argument the name of the MIME parameter to copy, as matched by an `IN-PARAMETER-NAME-m` clause. Wildcards may be used in the argument. In particular, an argument of `*` means to copy all the original `Content-Disposition:` parameters.
	DPARAMETER-SYMBOL- n	`Content-disposition` parameters to convert to environment variables (DCL symbols on OpenVMS) if present; n = 0, 1, 2, .... Takes as argument the name of the MIME parameter to convert, as matched by an `IN-DPARAMETER-NAME-m` clause. Each `DPARAMETER-SYMBOL-n` is extracted from the `Content-Disposition:` parameter list and placed in an environment variable or DCL symbol of the same name prior to executing the converter.
+	FDL-OVERRIDE	0 or 1; if 1 the FDL information specified by the FDL-STRING entry parameter is used unconditionally; if 0 the `FDL-STRING` entry parameter will be overriden by an `FDL-STRING Content-Type:` parameter.
+	FDL-STRING	OpenVMS FDL information used to construct the input file for the converter. Prior to conversion the body part is written into an RMS file created using this FDL information. A `FDL-STRING` parameter will override the `FDL-STRING` entry parameter unless `FDL-OVERRIDE` is 1. Usage of this parameter is restricted to OpenVMS systems.
	IN-A1-FORMAT	Input A1-Format from enclosing `message/rfc822` part.
	IN-A1-TYPE	Input A1-Type from enclosing `message/rfc822` part.
	IN-CHAN	Input channel to match for conversion (wildcards allowed). The conversion specified by this entry will only be performed if the message is coming from the specified channel.
	IN-CHANNEL	Synonym for `IN-CHAN`.
	IN-DESCRIPTION	Input MIME `Content-Description`.
	IN-DISPOSITION	Input MIME `Content-Disposition`.
	IN-DPARAMETER-DEFAULT- n	Input MIME `Content-Disposition` parameter value default if parameter is not present. This value is used as a default for the `IN-DPARAMETER-VALUE-n` test when no such parameter is specified in the body part.
	IN-DPARAMETER-NAME- n	Input MIME `Content-Disposition` parameter name whose value is to be checked; n = 0, 1, 2, ....
	IN-DPARAMETER-VALUE- n	Input MIME `Content-Disposition` parameter value that must match corresponding `IN-DPARAMETER-NAME` (wildcards allowed). The conversion specified by this entry is only performed if this field matches the corresponding parameter in the body part's `Content-Disposition:` parameter list.
	IN-PARAMETER-DEFAULT- n	Input MIME `Content-Type` parameter value default if parameter is not present. This value is used as a default for the `IN-PARAMETER-VALUE-n` test when no such parameter is specified in the body part.
	IN-PARAMETER-NAME- n	Input MIME `Content-Type` parameter name whose value is to be checked; n = 0, 1, 2, ....
	IN-PARAMETER-VALUE- n	Input MIME `Content-Type` parameter value that must match corresponding `IN-PARAMETER-NAME` (wildcards allowed). The conversion specified by this entry is only performed if this field matches the corresponding parameter in the body part's `Content-Type:` parameter list.
	IN-SUBJECT	Input Subject from enclosing `message/rfc822` part.
	IN-SUBTYPE	Input MIME subtype to match for conversion (wildcards allowed). The conversion specified by this entry is only performed if this field matches the MIME subtype of the body part.
	IN-TYPE	Input MIME type to match for conversion (wildcards allowed). The conversion specified by this entry is only performed if this field matches the MIME type of the body part.
	MESSAGE-HEADER-FILE	0, 1, or 2. If set to 1, the original headers of the immediately enclosing message part are written to the file represented by the `MESSAGE_HEADERS` symbol. If set to 2, the original headers of the message as a whole (the outermost message headers) are written to `MESSAGE_HEADERS`.
	ORIGINAL-HEADER-FILE	0 or 1. If set to 1, the original headers of the enclosing part are written to the file represented by the `INPUT_HEADERS` symbol.
	OUT-A1-FORMAT	Output A1-Format.
	OUT-A1-TYPE	Output A1-Type.
	OUT-CHAN	Output channel to match for conversion (wildcards allowed). The conversion specified by this entry will only be performed if the message is destined for the specified channel.
	OUT-CHANNEL	Synonym for `OUT-CHAN`.
	OUT-DESCRIPTION	Output MIME `Content-Description` if it is different than the input MIME `Content-Description`.
	OUT-DISPOSITION	Output MIME `Content-Disposition` if it is different than the input MIME `Content-Disposition`
	OUT-DPARAMETER-NAME- n	Output MIME `Content-Disposition` parameter name; n = 0, 1, 2, ....
	OUT-DPARAMETER-VALUE- n	Output MIME `Content-Disposition` parameter value corresponding to `OUT-DPARAMETER-NAME-n`.
	OUT-MODE	Mode in which to read the converted file. This should be one of: `BLOCK`, `RECORD`, `RECORD-ATTRIBUTE`, `TEXT`.
	OUT-ENCODING	Encoding to apply to the converted file.
	OUT-PARAMETER-NAME- n	Output MIME `Content-Type` parameter name; n = 0, 1, 2, ....
	OUT-PARAMETER-VALUE- n	Output MIME `Content-Type` parameter value corresponding to OUT-PARAMETER-NAME-n.
	OUT-SUBTYPE	Output MIME type if it is different than the input MIME type.
	OUT-TYPE	Output MIME type if it is different than the input type
	OVERRIDE-HEADER-FILE	0 or 1. If set, then MIME headers are read from the OUTPUT_HEADERS symbol, overriding the original MIME headers in the enclosing part.
++	OVERRIDE-OPTION-FILE	0 or 1. If set, then the conversion channel reads options from the OUTPUT_OPTIONS symbol.
	PARAMETER-COPY- n	A list of the `Content-Type:` parameters to copy from the input body part's `Content-Type:` parameter list to the output body part's `Content-Type:` parameter list; n = 0, 1, 2, .... Takes as argument the name of the MIME parameter to copy, as matched by an `IN-PARAMETER-NAME-m` clause. Wildcards may be used in the argument. In particular, an argument of `*` means to copy all the original `Content-Type:` parameters.
	PARAMETER-SYMBOL- n	Content-Type parameters to convert to environment variables (DCL symbols on OpenVMS) if present; n = 0, 1, 2, .... Takes as argument the name of the MIME parameter to convert, as matched by an `IN-PARAMETER-NAME-m` clause. Each `PARAMETER-SYMBOL-n` is extracted from the `Content-Type:` parameter list and placed in an environment variable or DCL symbol of the same name prior to executing the converter.
	PART-NUMBER	Dotted integers, e.g., a. b. c... The part number of the MIME body part.
	RELABEL	0 or 1. This flag causes an entry to be ignored during conversion channel processing. However, if this flag is 1, then MIME header relabelling is performed during character set conversion. ^tm
	SERVICE-COMMAND	The command to execute to perform service conversion. This parameter is required; if no command is specified, the entry is ignored. Note that this flag causes an entry to be ignored during conversion channel processing; `SERVICE-COMMAND` entries are instead performed during character set conversion processing.®
	TAG	Input tag, as set by a mailing list `[CONVERSION_TAG]` named parameter, must match.

§Except see the RELABEL and SERVICE-COMMAND parameters, which cause entries to be ignored during conversion channel processing, but do affect character set conversion.
+Supported only on OpenVMS; ignored on UNIX and NT.
++Available on UNIX and NT only
®See Section 6.1.3 for more information on character set conversion and using the SERVICE-COMMAND parameter.
^tmSee Section 6.1.2.2 for more information on character set conversion and using the RELABEL parameter.

Parameters not listed in the preceeding table are ignored.

6.2.3.3 Conversion Entry Parameter Value Wildcard Matching

The values of conversion entry parameter values may be specified as literal strings, or using wildcards as in PMDF mapping entry patterns. See Section 5.3.1 for a discussion of available wildcards.

For instance,

in-dparameter-name-0=filename; in-dparameter-value-0=*.wpc;

would match any Content-disposition: header filename parameter that has a ".wpc" extension. Or

in-dparameter-name-0=filename; in-dparameter-value-0=*.wp$[cd56]%;

would match any Content-disposition: header filename parameter that has a ".wpc", ".wpd", ".wp5", or ".wp6" extension.

6.2.3.4 Predefined Symbols or Environment Variables

Table 6-2 shows the basic set of DCL symbols (OpenVMS) or environment variables (UNIX and NT) available for use by the conversion command.

Table 6-2 Symbols for Use by the Conversion Channel
Symbol Description

INPUT_ENCODING The encoding originally present on the body part.

INPUT_FILE The name of the file containing the original body part. The converter should read this file.

INPUT_HEADERS The name of the file containing the original headers for the enclosing part. The converter should read this file.

INPUT_TYPE The content type of the input message part.

INPUT_SUBTYPE The content subtype of the input message part.

INPUT_DESCRIPTION The content description of the input message part.

INPUT_DISPOSITION The content disposition of the input message part.

MESSAGE_HEADERS The name of the file containing the original headers for an enclosing (outermost) message. The converter should read this file.

OUTPUT_FILE The name of the file where the converter should store its output. The converter should create and write this file.

OUTPUT_HEADERS The name of the file where the converter should store MIME headers for an enclosing part. The converter should create and write this file. Note that the file should have a format of header line, header line,..., blank line; be sure to include the final blank line.

OUTPUT_OPTIONS The name of the file from which the converter should read options (such as status values on UNIX).

**Table 6-2 Symbols for Use by the Conversion Channel**
Symbol	Description
INPUT_ENCODING	The encoding originally present on the body part.
INPUT_FILE	The name of the file containing the original body part. The converter should read this file.
INPUT_HEADERS	The name of the file containing the original headers for the enclosing part. The converter should read this file.
INPUT_TYPE	The content type of the input message part.
INPUT_SUBTYPE	The content subtype of the input message part.
INPUT_DESCRIPTION	The content description of the input message part.
INPUT_DISPOSITION	The content disposition of the input message part.
MESSAGE_HEADERS	The name of the file containing the original headers for an enclosing (outermost) message. The converter should read this file.
OUTPUT_FILE	The name of the file where the converter should store its output. The converter should create and write this file.
OUTPUT_HEADERS	The name of the file where the converter should store MIME headers for an enclosing part. The converter should create and write this file. Note that the file should have a format of header line, header line,..., blank line; be sure to include the final blank line.
OUTPUT_OPTIONS	The name of the file from which the converter should read options (such as status values on UNIX).

Additional symbols containing Content-Type: information can be created as they are needed using the PARAMETER-SYMBOL-n facility.

Table 6-3 shows additional symbols (OpenVMS) or "override" options (UNIX and NT) available for use by the conversion channel. The converter procedure may use these to pass information back to the conversion channel. To set these symbols on OpenVMS, the converter procedure should define corresponding logical names using the DCL command DEFINE/JOB. To set these options on UNIX or NT, set OVERRIDE-OPTION-FILE=1 in the desired conversion entry and then have the converter procedure set the desired options in the OUTPUT_OPTIONS file.

Table 6-3 Symbols (OpenVMS) or Options (UNIX and NT) for Passing Information Back to the Conversion Channel
Symbol or option Description

OUTPUT_TYPE The content type of the output message part.

OUTPUT_SUBTYPE The content subtype of the output message part.

OUTPUT_DESCRIPTION The content description of the output message part.

OUTPUT_DIAGNOSTIC Text to include in the error text returned to the message sender if a message is forcibly bounced (via PMDF__FORCERETURN by the conversion channel.)

OUTPUT_DISPOSITION The content disposition of the output message part.

OUTPUT_ENCODING The content transfer encoding to use on the output message part.

OUTPUT_MODE The mode with which the conversion channel should write the output message part, hence the mode with which recipients should read the output message part.

+ STATUS The PMDF exit status for the converter.

**Table 6-3 Symbols (OpenVMS) or Options (UNIX and NT) for Passing Information Back to the Conversion Channel**
	Symbol or option	Description
	OUTPUT_TYPE	The content type of the output message part.
	OUTPUT_SUBTYPE	The content subtype of the output message part.
	OUTPUT_DESCRIPTION	The content description of the output message part.
	OUTPUT_DIAGNOSTIC	Text to include in the error text returned to the message sender if a message is forcibly bounced (via `PMDF__FORCERETURN` by the conversion channel.)
	OUTPUT_DISPOSITION	The content disposition of the output message part.
	OUTPUT_ENCODING	The content transfer encoding to use on the output message part.
	OUTPUT_MODE	The mode with which the conversion channel should write the output message part, hence the mode with which recipients should read the output message part.
+	STATUS	The PMDF exit status for the converter.

+Available on UNIX and NT only

6.2.3.5 Symbol Substitution in Conversion Entries

Certain values from the body part being processed may be substituted into a conversion entry by enclosing a corresponding symbol name in single quotes. Table 6-4 shows the list of symbols that can be used.

Table 6-4 Conversion Symbols for Substitution
Symbol Description

A1-FORMAT The value of the A1-Format: header.

A1-FUNCTION The value of the A1-Function: header.

A1-TYPE The value of the A1-Type: header.

DESCRIPTION The value of the Content-Description: header.

DISPOSITION The primary value of the Content-Disposition: header (for example attachment).

LANGUAGE The value of the Content-Language: header.

SUBJECT The subject of the message.

SUBTYPE The content subtype of the message part.

TAG The value of the input tag, as set by a mailing list [CONVERSION_TAG] named parameter.

TYPE The content type of the message part.

**Table 6-4 Conversion Symbols for Substitution**
	Symbol	Description
	A1-FORMAT	The value of the `A1-Format:` header.
	A1-FUNCTION	The value of the `A1-Function:` header.
	A1-TYPE	The value of the `A1-Type:` header.
	DESCRIPTION	The value of the `Content-Description:` header.
	DISPOSITION	The primary value of the `Content-Disposition:` header (for example `attachment`).
	LANGUAGE	The value of the `Content-Language:` header.
	SUBJECT	The subject of the message.
	SUBTYPE	The content subtype of the message part.
	TAG	The value of the input tag, as set by a mailing list [CONVERSION_TAG] named parameter.
	TYPE	The content type of the message part.

In addition to the symbols listed in Table 6-4, any option from the Content-Type: header (for example, name), or the Content-Disposition: header (for example, filename) may be specified.

Note

For the string value of the COMMAND parameter only, any of the symbols listed in Table 6-2 may be substituted using the standard command line symbol substitution for the given platform, i.e., preceding and following the variable's name with an apostrophe on OpenVMS, preceding the variable's name with a dollar character on UNIX, or preceding and following the variable's name with a percent sign on NT.

For example, with a site supplied command procedure PMDF_TABLE:converter.com that attempts to perform various conversions, one might use an entry along the lines of:

in-chan=tcp_local; out-chan=l; in-type=application; in-subtype=*; out-type='TYPE'; out-subtype='SUBTYPE'; command="@PMDF_TABLE:converter.com 'INPUT_FILE' 'OUTPUT_FILE' 'INPUT_TYPE' 'INPUT_SUBTYPE'"

To obtain a literal single quote in a conversion entry, quote it with the backslash character, \'. To obtain a literal backslash in a conversion entry, use two backslashes, \\.

6.2.3.6 Calling Out to a Mapping Table from a Conversion Entry

The value for a conversion parameter may be obtained by calling out to a mapping table. The syntax for calling out to a mapping table is

"'mapping-table-name:mapping-input'"

For instance, with a mapping table

X-ATT-NAMES postscript PS.PS$Y wordperfect5.1 WPC.WPC$Y msword DOC.DOC$Y

then on OpenVMS a conversion entry such as the following results in substituting generic file names in place of specific file names on attachments.

out-chan=tcp_local; in-type=application; in-subtype=*; in-parameter-name-0=name; in-parameter-value-0=*:[*]*; out-type=application; out-subtype='SUBTYPE'; out-parameter-name-0=name; out-parameter-value-0="'X-ATT-NAMES:\\'SUBTYPE\\''"; command="COPY 'INPUT_FILE' 'OUTPUT_FILE'"

Or on UNIX, a conversion entry such as the following results in substituting generic file names in place of specific file names on attachments.

out-chan=tcp_local; in-type=application; in-subtype=*; in-parameter-name-0=name; in-parameter-value-0=/*/*; out-type=application; out-subtype='SUBTYPE'; out-parameter-name-0=name; out-parameter-value-0="'X-ATT-NAMES:\\'SUBTYPE\\''"; command="cp $INPUT_FILE $OUTPUT_FILE"

6.2.3.7 The Headers in an Enclosing Part or Message

When performing conversions on a message part, the conversion channel has access to the headers in an enclosing part, an enclosing message/rfc822 part, or to the outermost message headers if there is no enclosing message/rfc822 part.

For instance, the IN-A1-TYPE and IN-A1-FORMAT parameters can be used to check the A1-Type and A1-Format headers of an enclosing part, and the OUT-A1-TYPE and OUT-A1-FORMAT parameters can be used to set those enclosing headers. Or decisions about interior message part processing can be made based upon the message's outermost headers.

More generally, if an entry is selected that has ORIGINAL-HEADER-FILE=1, then the headers of that part are written to the file represented by the INPUT_HEADERS symbol. If an entry is selected that has MESSAGE-HEADER-FILE=1, then all the original headers of the enclosing message/rfc822 part are written to the file represented by the MESSAGE_HEADERS symbol. Or if an entry is selected that has MESSAGE-HEADER-FILE=2, then all the original headers of the outermost message are written to the file represented by the MESSAGE_HEADERS symbol.

If OVERRIDE-HEADER-FILE=1, then the conversion channel will read and use as the headers on that enclosing part the contents of the file represented by the OUTPUT_HEADERS symbol.

6.2.3.8 Bouncing Messages on UNIX and NT

On UNIX and NT, the OVERRIDE-OPTION-FILE conversion parameter may be used to tell the conversion channel to read values---such as a return completion status---from the OUTPUT_OPTIONS file. That return completion status may be one that requests that PMDF bounce the message. For instance, this may be useful when it is desired to bounce messages containing certain kinds of content.

If the OUTPUT_OPTIONS file contains the line

STATUS=pmdf_forcereturn-value

where pmdf_forcereturn-value is the value corresponding to PMDF__FORCERETURN, as defined in /pmdf/include/pmdf_err.h (UNIX) or C:\pmdf\include\pmdf_err.h (NT), then PMDF will bounce the original message.

If the OUTPUT_OPTIONS file also contains a line

OUTPUT_DIAGNOSTIC=text-string

then that text string will be included in the conversion error text returned to the message sender in the text of the bounce message.

Only a sample of the original message is bounced, the amount being controlled by the LINES_TO_RETURN PMDF option (see Section 7.3.4).

There are a couple of variations on the FORCERETURN behavior available.

A value of PMDF__FORCERETURN+1 will cause PMDF to return not the original message text, but the final message text including any modifications done by the converter. The number of lines of the message returned is controlled by the LINES_TO_RETURN option.

A value of PMDF__FORCERETURN-1 will cause PMDF to return the entire message, including any modifications done by the converter.

6.2.3.9 Bouncing Messages on OpenVMS

On OpenVMS, the converter can return a status to PMDF requesting that PMDF bounce the message. For instance, this may be useful when it is desired to bounce messages containing certain kinds of content.

If the converter returns the completion status PMDF__FORCERETURN, then PMDF will bounce the original message. See PMDF_COM:pmdf_err.h for the definition of PMDF__FORCERETURN.

If the logical name OUTPUT_DIAGNOSTIC is defined in the job logical name table to some text string, then that text string will be included in the conversion error text returned to the message sender in the text of the bounce message.

Only a sample of the original message is bounced, the amount being controlled by the LINES_TO_RETURN PMDF option (see Section 7.3.4).

There are a couple of variations on the FORCERETURN behavior available.

A value of PMDF__FORCERETURN-1 will cause PMDF to return the entire message, including any modifications done by the converter.

6.2.3.10 Conditionally Deleting Messages on UNIX and NT

On UNIX and NT, the OVERRIDE-OPTION-FILE conversion parameter may be used to tell the conversion channel to read values---such as a return completion status---from the OUTPUT_OPTIONS file. That return completion status may be one that requests that PMDF delete the message. This may be useful when it is desired to delete a message conditionally, depending on what it contains.

If the OUTPUT_OPTIONS file contains the line

STATUS=pmdf_forcediscard-value

where pmdf_forcediscard-value is the value corresponding to PMDF__FORCEDISCARD, as defined in /pmdf/include/pmdf_err.h (UNIX) or C:\pmdf\include\pmdf_err.h (NT), then PMDF will delete the entire message.

PMDF performs the same actions as for Sieve discard commands in mailbox filter files. For example, if the FILTER_DISCARD option is set to 2 in the PMDF option file, the message will be routed to the filter_discard channel (see Section 7.3.3).

6.2.3.11 Conditionally Deleting Messages on OpenVMS

On OpenVMS, the converter can return a status to PMDF requesting that PMDF delete the message. If the converter command returns the completion status PMDF__FORCEDISCARD, then PMDF will delete that entire message. See PMDF_COM:pmdf_err.h for the definition of PMDF__FORCEDISCARD. This may be useful when it is desired to delete messages conditionally, depending on what they contain.

PMDF performs the same actions as for Sieve discard commands in mailbox filter files. For example, the FILTER_DISCARD option is set to 2 in the PMDF option file, the message will be routed to the filter_discard channel (see Section 7.3.3).

6.2.3.12 Conditionally Deleting Message Parts on UNIX and NT

On UNIX and NT, the OVERRIDE-OPTION-FILE conversion parameter may be used to tell the conversion channel to read values---such as a return completion status---from the OUTPUT_OPTIONS file. That return completion status may be one that requests that PMDF delete the message part. This may be useful when it is desired to delete parts conditionally, depending on what they contain. In contrast, the DELETE=1 conversion parameter clause unconditionally deletes a message part.

If the OUTPUT_OPTIONS file contains the line

STATUS=pmdf_forcedelete-value

where pmdf_forcedelete-value is the value corresponding to PMDF__FORCEDELETE, as defined in /pmdf/include/pmdf_err.h (UNIX) or C:\pmdf\include\pmdf_err.h (NT), then PMDF will delete the message part.

6.2.3.13 Conditionally Deleting Message Parts on OpenVMS

On OpenVMS, the converter can return a status to PMDF requesting that PMDF delete the message part. If the converter command returns the completion status PMDF__FORCEDELETE, then PMDF will delete that message part. See PMDF_COM:pmdf_err.h for the definition of PMDF__FORCEDELETE.

This may be useful when it is desired to delete parts conditionally, depending on what they contain. In contrast, the DELETE=1 conversion parameter clause unconditionally deletes a message part.

6.2.3.14 Holding a Message on UNIX and NT

On UNIX and NT, the OVERRIDE-OPTION-FILE conversion parameter may be used to tell the conversion channel to read values---such as a return completion status---from the OUTPUT_OPTIONS file. That return completion status may be one that requests that PMDF hold (sideline) the message as a .HELD file in the conversion channel queue. This may be useful when it is desired to hold messages conditionally, depending on what they contain.

If the OUTPUT_OPTIONS file contains the line

STATUS=pmdf_forcehold-value

where pmdf_forcehold-value is the value corresponding to PMDF__FORCEHOLD, as defined in /pmdf/include/pmdf_err.h (UNIX) or C:\pmdf\include\pmdf_err.h (NT), then PMDF will hold the message.

6.2.3.15 Holding a Message on OpenVMS

On OpenVMS, the converter can return a status to PMDF requesting that PMDF hold (sideline) a message as a .HELD file in the conversion channel queue. If the converter command returns the completion status PMDF__FORCEHOLD, then PMDF will hold that message. See PMDF_COM:pmdf_err.h for the definition of PMDF__FORCEHOLD.

6.2.3.16 An Example on OpenVMS

The CONVERSIONS mapping and set of conversion rules seen in Examples 6-3 and 6-4 cause GIF, TIFF, and DDIF files sent to PMDF-FAX to be converted into PostScript automatically. Several of these conversions use the to_ps.exe routine provided with PMDF-FAX.

Example 6-3 Sample CONVERSIONS Mapping

CONVERSIONS IN-CHAN=*;OUT-CHAN=text_to_ps*;CONVERT Yes IN-CHAN=*;OUT-CHAN=ps_to_g3*;CONVERT Yes

Example 6-4 Sample Conversion Rules

out-chan=l; in-type=application; in-subtype=wordperfect5.1; out-type=application; out-subtype=ddif; out-mode=block; command="CONVERT/DOCUMENT 'INPUT_FILE'/FORMAT=WORDP 'OUTPUT_FILE'/FORMAT=DDIF" out-chan=ps_to_g3*; in-type=image; in-subtype=gif; out-type=application; out-subtype=postscript; out-mode=text; out-encoding=NONE; command="@PMDF_COM:TO_PS.COM" out-chan=ps_to_g3*; in-type=image; in-subtype=tiff; out-type=application; out-subtype=postscript; out-mode=text; out-encoding=NONE; command="@PMDF_COM:TO_PS.COM" out-chan=ps_to_g3*; in-type=application; in-subtype=x-ddif; out-type=application; out-subtype=postscript; out-mode=text; out-encoding=NONE; command="CONVERT/DOCUMENT 'INPUT_FILE'/FORMAT=X-DDIF 'OUTPUT_FILE'/FORMAT=PS" out-chan=text_to_ps*; in-type=image; in-subtype=gif; out-type=application; out-subtype=postscript; out-mode=text; out-encoding=NONE; command="@PMDF_COM:TO_PS.COM" out-chan=text_to_ps*; in-type=image; in-subtype=tiff; out-type=application; out-subtype=postscript; out-mode=text; out-encoding=NONE; command="@PMDF_COM:TO_PS.COM" out-chan=text_to_ps*; in-type=application; in-subtype=ddif; out-type=application; out-subtype=postscript; out-mode=text; out-encoding=NONE; command="CONVERT/DOCUMENT 'INPUT_FILE'/FORMAT=DDIF 'OUTPUT_FILE'/FORMAT=PS"

Note

⁷ The structured part number is the message part number as it would appear in PMDF MAIL.

Contents

Index

PMDF System Manager's Guide

6.2.3 Conversion Control

7 The structured part number is the message part number as it would appear in PMDF MAIL.

⁷ The structured part number is the message part number as it would appear in PMDF MAIL.