PMDF System Manager's Guide
Previous Contents Index

22.1.3 Conversion Control

The actual processing performed by the conversion channel is 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 all message parts should be run through a site-supplied virus checking command procedure: 


in-channel=*; in-type=*; in-subtype=*; 
  parameter-symbol-0=NAME; parameter-copy-0=*; 
  dparameter-symbol-0=FILENAME; dparameter-copy-0=*; 
  message-header-file=2; original-header-file=1; 
  override-header-file=1; override-option-file=1; 
  command="@pmdf_com:check-virus.com/output=pmdf_log:check-virus.out"

22.1.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: Only if all specified parameters match is the entry considered 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).

Note
The file specified by OUTPUT_FILE must be created by the command procedure (OpenVMS) or script (Unix and Windows). If you do not wish to make any changes, you must copy INPUT_FILE to OUTPUT_FILE . If you do not supply an OUTPUT_FILE then the part will be deleted.

On OpenVMS, the command may optionally define job table logical names 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.

22.1.3.2 Available Parameters

The rule parameters currently provided are shown in Table 22-2.

Table 22-2 Available Conversion Parameters
  Parameter Meaning
  COMMAND Command to execute. 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. 1
  DELETE 0 or 1. If this flag is set, the message part is deleted. (If this is the only part in a message, then a single empty text part is 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 command.
+ 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 is overriden by an FDL-STRING Content-Type: parameter.
+ FDL-STRING OpenVMS FDL information used to construct the input file for the command. Prior to executing the command, the body part is written into an RMS file created using this FDL information. An FDL-STRING parameter overrides 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 (wildcards allowed). The actions specified by this entry are only performed if the message is coming from the specified channel.
  IN-CHANNEL Synonym for IN-CHAN.
  IN-DESCRIPTION Input MIME Content-Description header.
  IN-DISPOSITION Input MIME Content-Disposition header.
  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 actions specified by this entry are 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 actions specified by this entry are 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 actions specified by this entry are only performed if this field matches the MIME subtype of the body part.
  IN-TYPE Input MIME type to match (wildcards allowed). The actions specified by this entry are 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 (wildcards allowed). The actions specified by this entry are only 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 output file. This should be one of: BLOCK, RECORD, RECORD-ATTRIBUTE, or TEXT.
  OUT-ENCODING Encoding to apply to the output 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 command.
  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. 2
  SERVICE-COMMAND The command to execute to perform service conversion. This flag causes an entry to be ignored during conversion channel processing. SERVICE-COMMAND entries are instead performed during character set conversion processing. 3
  TAG Input tag, as set by a mailing list [CONVERSION_TAG] named parameter, must match.

+Supported only on OpenVMS; ignored on UNIX and NT.
++Available on UNIX and NT only
1Except see the RELABEL and SERVICE-COMMAND parameters, which cause entries to be ignored during conversion channel processing, but do affect character set conversion.
2See Section 6.3.2 for more information on character set conversion and using the RELABEL parameter.
3See Section 6.4 for more information on character set conversion and using the SERVICE-COMMAND parameter.

Parameters not listed in the preceeding table are ignored.

22.1.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.

22.1.3.4 Predefined Symbols or Environment Variables

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

Table 22-3 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 command should read this file.
  INPUT_HEADERS The name of the file containing the original headers for the enclosing part. The command 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 command should read this file.
  OUTPUT_FILE The name of the file where the command should store its output. The command should create and write this file.
  OUTPUT_HEADERS The name of the file where the command should store MIME headers for an enclosing part. The command 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 to which the command should write options (such as status values).

+Available on UNIX and NT only

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

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

Table 22-4 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 completion status for the script.

+Available on UNIX and NT only

22.1.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 22-5 shows the list of symbols that can be used.

Table 22-5 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 22-5, any parameter 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 22-3 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:site.com that attempts to perform various operations, 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:site.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, \\ .

22.1.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"

22.1.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.

Note that the envelope From: information is included in the MESSAGE_HEADERS file in the X-Envelope-From: header, and the envelope To: information is in the X-Envelope-To: header. However, if you have specified the nox_env_to keyword on your conversion channel definition, these headers will not be included.

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

Note

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

Previous Next Contents Index