PMDF System Manager's Guide
Previous Contents Index

37.2.17 G3_TO_FAX Channel

Outgoing FAX transmissions are handled by the G3_TO_FAX channel which acts as a driver for the FAX modem. E-mail messages presented to outgoing FAX channels are, at some point, converted to a G3 file by the PS_TO_G3 channel and then queued to the G3_TO_FAX channel for transmission. As the G3_TO_FAX channel is an ordinary (generic) PMDF channel, PMDF's store and forward capabilities are used to handle situations in which a FAX transmission cannot be effected immediately.

The master_debug channel keyword may be used with the G3_TO_FAX channel to produce debugging output in the message submission job's log file.

Currently, the DCE FaxBox/30, Fujitsu dexNET 200 (firmware version 1.9 or later), and selected Service Class 2 modems are the only FAX modems supported by this channel.

OpenVMS Note
The G3_TO_FAX channel requires SYSLCK privilege. The G3_TO_FAX channel uses cluster-wide resource locks to control access to the G3 files it processes. By default, all PMDF processing jobs have SYSLCK privileges. If you have restricted the privileges available to PMDF processing jobs, then take the steps necessary to ensure that these jobs have SYSLCK privileges.

37.2.17.1 Previewing and Editing G3 Files

Note that G3 files are not plain text files. To inspect or edit the contents of a G3 file, use the PMDF G3 utility. See Chapter 30 for a description of the PMDF G3 utility.

37.2.17.2 Supported Mapping Tables

G3_TO_FAX channels support two special mapping tables which may be used to grant or deny permission for a FAX to be sent, and to alter a specified FAX telephone number. These two mapping tables are, respectively, the FAX_VALIDATE and FAX_NUMBER mappings. Familiarity with the mapping file is assumed in the following description of these mappings. Consult Chapter 5 for information on the location and use of the mapping file.

37.2.17.2.1 FAX_VALIDATE Mapping Table

The FAX_VALIDATE mapping table provides a simple mechanism to grant or deny permission to send a FAX based upon the name of the channel sending the FAX, the originator of the FAX, any authorization code they may have provided with the AUTH addressing attribute, and the telephone number to which the FAX is to be sent. For more sophisticated screening, use the FAX_VALIDATE shareable image hook described in Section 37.2.17.3. Note that unlike that hook, the FAX_VALIDATE mapping may not be used to alter the FAX telephone number. Alterations may, however, be done with the FAX_NUMBER mapping described in Section 37.2.17.2.2.

The left-hand side of each entry in the FAX_VALIDATE mapping table takes the form 


channel-name|from-address|auth|telephone-number
where channel-name is the name of the channel doing the check, from-address is the envelope From: address of the message's originator, auth is any authorization or access code specified with the AUTH addressing attribute, and telephone-number is the FAX telephone number to be dialed. Only the digits 0--9 should appear in the number.

The right-hand side of each entry should specify either $Y or $N. A $Y grants permission for the FAX to be sent; a $N denies permission. In the case of a $N, an optional text string giving a rejection message to be returned to the originator may also be specified as shown in Example 37-5. If the mapping table lookup produces no result, then the FAX will be allowed to be sent. That is, only a result specifying $N will prevent the FAX from being sent.

In Example 37-5 below, there are five entries in the FAX_VALIDATE mapping table. In all of the entries, the channel name is considered immaterial and ignored. The first entry has the effect of allowing anyone from the process.com domain to send a FAX anywhere. The second entry allows anyone to send a FAX anywhere provided that they specified "/AUTH=xyzzy/" in the FAX address when they addressed their message. The third entry allows anyone to send a FAX to any telephone number in the +1 909 area code while the fourth entry allows anyone to send a FAX to any seven digit telephone number which will presumably be a local call. The final entry rejects anything which was not permitted by any of the previous entries. In addition, it generated the rejection message "Non-local calls not permitted". The dollar signs in that message are required so as to "quote" the spaces in the string.

Example 37-5 FAX_VALIDATE Mapping Table 

FAX_VALIDATE 
 
  *|*@*process.com|*|*         $Y 
  *|*|xyzzy|*                  $Y 
  *|*|*|1909*                  $Y 
  *|*|*|%%%%%%%                $Y 
  *|*|*|*                      $NNon-local$ calls$ not$ permitted

When both a FAX_VALIDATE image hook and mapping have been specified, the image hook will first be called. If it does not reject the FAX, then the mapping will next be applied. If a FAX_NUMBER mapping has also been supplied, then it will be applied after the FAX_VALIDATE mapping.

37.2.17.2.2 FAX_NUMBER Mapping Table

The FAX_NUMBER mapping table may be used to make simple changes to a FAX telephone number. For more sophisticated changes, use the FAX_VALIDATE shareable image hook described in Section 37.2.17.3.

The left-hand side of each entry in the FAX_VALIDATE mapping table takes the form 


channel-name|device-name|auth|telephone-number
where channel-name is the name of the channel doing the mapping, device-name is the actual device name associated with the modem which will be used, auth is any authorization or access code specified with the AUTH addressing attribute, and telephone-number is the FAX telephone number to be dialed with all non-numeric characters removed.

The right-hand side of each entry should either specify $Y along with a new telephone number to use in place of telephone-number, or $N. When $N is specified or no matching entry is found, then telephone-number will be the number dialed.

Suppose that the modem on terminal line VAX$TXA6: uses a PBX line and requires that a "9,," be prefixed to the numbers to be dialed. The example below addresses this case. 


FAX_NUMBER 
 
  *|VAXA$TXA6:|*|*                 $Y9,,$2

The FAX_NUMBER mapping is always applied after any FAX_VALIDATE image or mapping.

37.2.17.3 Shareable Image Hooks

Sites may exercise two shareable image hooks:
  1. FAX_VALIDATE: This routine, when supplied via the logical PMDF_FAX_VALIDATE, is called before a delivery attempt is made for message. FAX_VALIDATE is called once per recipient of the FAX message. The G3_TO_FAX channel passes to FAX_VALIDATE the following information: the channel name and a flag specifying the presence or absence of the master_debug channel keyword; the e-mail address of the message originator (in RFC 822 format) as determined from the envelope From: header; the FAX telephone number as specified by the message originator; the number of deliveries attempted so far for the recipient; the total page count for the message; any authorization code specified with a /AUTH= item in the FAX address; and the device name associated with the modem which will be used. FAX_VALIDATE may, by returning the value false, disallow transmission of the message and may optionally specify a message string to be returned to the message originator via an e-mail message. Among other uses, this provides a mechanism whereby sites can allow unlimited local FAXing with upper bounds on page counts, or screen messages based upon their originator. Moreover, FAX_VALIDATE may modify the FAX telephone number and thereby add access codes, dial string modifiers, area codes, etc. to user supplied FAX telephone numbers. The modified number is never displayed on the transmitted FAX nor communicated to the message originator; the modified number is only displayed in the log file of the message submission job if the G3_TO_FAX channel is marked master_debug .
  2. FAX_LOG_USAGE: This routine, when supplied via the logical PMDF_FAX_LOG_USAGE, is called after a delivery attempt has been made for a FAX message. This routine is called once per recipient of the message and passed the following information: the channel name and a flag specifying the presence or absence of the master_debug channel keyword; the e-mail address of the message originator (in RFC 822 format) as determined from the envelope From: header; the FAX telephone number as specified by the message originator; the total page count for the message; the estimated phone call duration; a status code giving the disposition of the delivery; the last response code received from the FAX modem; the time stamp stored in the mail.log file if logging is enabled for the channel; any authorization code specified with the /AUTH= item; and the numeric message status stored in the G3 file. This information can then be placed in usage logs or passed on to site-dependent usage accounting software. Note that when the logging channel keyword is used with the G3_TO_FAX channel, usage information is written to the file mail.log in the PMDF log directory, i.e., to the OpenVMS file PMDF_LOG:mail.log. By altering the value of the numeric status parameter, a FAX may be prematurely aborted or its status otherwise altered.

The files fax_validate.for, fax_validate.pas, and fax_validate.c in the examples subdirectory of the PMDF documentation directory serve as examples on how to use these two hooks. In those files, complete details on how to use the hooks are given in the form of comments.

37.2.17.4 Option Files

Option files are used to set several run-time G3_TO_FAX options on a per channel basis. Option files are stored in the PMDF table directory and have names of the form x_option, where x is the name of the G3_TO_FAX channel to which the option file applies. It is not necessary that every or any G3_TO_FAX channel have an option file; i.e., option files are not required for G3_TO_FAX channels but merely used to alter default actions taken by such channels.

See Section 37.2.15.3 for a description of the format of option files.

The available options are:

ACKNOWLEDGEMENT (integer)

By default, FAX delivery acknowledgements are only issued when transmission errors occur during an otherwise successful FAX transmission (ACKNOWLEDGEMENT=-1). When this channel option is set to an integer greater than or equal to zero, delivery acknowledgements are always sent after a successful FAX delivery regardless of whether or not transmission errors were reported provided that either NOTARY was not used to submit or relay the message to PMDF or, if NOTARY was used, that delivery reports (DSNs) were requested.8 Acknowledgements are preferentially sent to the delivery receipt address specified by a Delivery-receipt-to: header line. If no such header line is specified, then the address specified by a Reply-to: header line is used. Finally, if no Reply-to: header line is present, then the envelope From: address is used. If the originating message specifies a delivery receipt address of <>, then no acknowledgement will be generated. If USE_REPLY_TO=0 has been specified in the G3_TO_FAX channel option file, then the Reply-to address will never be used: if no delivery receipt is specified then the envelope From: address will be used regardless of whether or not a Reply-to: header line is present in the originating message. If set to a positive integer n>= 1 then status reports are sent every nth unsuccessful transmission attempt starting with the first attempt; i.e., on attempts 1, 1+n, 1+2n, 1+3n, .... For instance, if ACKNOWLEDGEMENT=1 then a status report will be sent every attempt until the message is successfully sent, and then, when the message is successfully sent, an acknowledgement will be sent. If, however, ACKNOWLEDGEMENT=5 then status reports will be sent on attempts 1, 6, 11, 16, etc., until the message is successfully delivered or returned. When it is delivered or returned, an acknowledgement is sent. Status reports are preferentially sent to the Warnings-to address specified by a Warnings-to: header line. If no such header line is specified, then the address specified by a Reply-to: header line is used. Finally, if no Reply-to: header line is present, then the envelope From: address is used. Status reports will not be sent if the originating message specifies a Warnings-to: address of <> or a delivery receipt address of <>. As with delivery acknowledgements, if USE_REPLY_TO=0 then the Reply-to address will never be used. Set ACKNOWLEDGEMENT=0 if you only want acknowledgements sent when the message is successfully transmitted.

ADVERTISEMENT (text string <= 252 characters long)

With this option, you may specify the name of a file the contents of which to include in status and delivery reports. Although this is intended for use with the Internet Remote Printing experiment (RFC 1486), it may be used for other purposes. The 250 byte length limit for Remote Printing advertisements is not imposed.

BACKOFF (integer >= 0)

When BACKOFF specifies an integer greater than zero, backoff retries will be attempted for FAXes which could not be delivered immediately. See Section 37.6.3.4 for details. By default, BACKOFF=0. When using the BACKOFF option, be sure to set the POST_INTERVAL option to a time period less than the minimum amount of time between transmission retries called for by the BACKOFF mapping table.

FAX_MODEM (text string <= 252 characters long)

By default, the G3_TO_FAX channel uses the logical PMDF_FAX_MODEM to access the terminal port to which the FAX modem is connected. With the FAX_MODEM channel option, the G3_TO_FAX channel may be instructed to use a different logical name (or device name or terminal port) to access a particular FAX modem or pool of modems. This is useful when more than one FAX modem is in use and pooling them together under a single logical name with multiple translation values is not desired. The value supplied with this channel option must be an ASCII string containing no more than 252 characters. See Section 37.6.3 for details on using multiple modems with the same channel.

FLOW_CONTROL (0 or 1)

This option is only supported by the Fujitsu dexNET 200 FAX modem. For all other FAX modems you must configure the modem yourself, saving the configuration setting in its configuration memory. This option specifies the method of flow control used to transmit data to the FAX modem and may assume one of two values: 0 or 1. By default, XON/XOFF (in-band) flow control is used, FLOW_CONTROL=1. To select CTS/RTS (out-of-band) flow control, place the line 


FLOW_CONTROL=0
in the channel option file. The line 


FLOW_CONTROL=1
selects the default method, XON/XOFF. Note that use of CTS/RTS flow control requires that the FAX modem be connected to a terminal port with modem control and that modem control be enabled for that port.

FSI (20 character string)

Specifies the content of the FAX Station Identification (FSI) string transmitted by the FAX modem to the remote FAX receiver. The FSI string is transmitted as part of the CCITT FAX T.30 handshake as the Transmitting Station Identification (TSI) to identify the phone number of the transmitting FAX modem. This ASCII string should contain no more than 20 characters. The FSI string has no default value and, by default, no FSI string is transmitted to the FAX modem. User supplied FSI strings (specified with the /FSI=string attribute-value pair (AVP) in the message To: line) will override the FSI channel option if the SET_FSI option is set to 1. The SET_FSI option, described below, has the default value of 0 which disables use of user supplied FSI strings.

SET_FSI (0 or 1)

This numeric value should be either 0 or 1 and specifies whether or not the G3_TO_FAX channel may use a user supplied FSI string. (Users may specify a FSI string with the "/FSI=string" attribute-value pair in their message To: line.) By default, this option has value 0 which disallows the use of user specified FSI strings. To allow the use of user supplied FSI strings, use the option 


SET_FSI=1
in the channel option file. When set to 1, a user supplied FSI string will override any FSI string specified in the channel option file with the FSI channel option.

MAX_DELIVERY_ATTEMPTS (integer between 1 and 253)

The MAX_DELIVERY_ATTEMPTS channel option controls the maximum number of delivery attempts to be made for a FAX message. If this option is not specified then 253 delivery attempts will be made. This number is a bit excessive and a value of 10 or 15 is probably appropriate for most sites.

MODEM_TYPE (CLASS2, DEXNET200, or FAXBOX30)

The MODEM_TYPE option specifies the type of FAX modem used by the channel. For instance, specify 


MODEM_TYPE=DEXNET200
if a Fujitsu dexNET 200 FAX modem is to be used. See Section 37.6.3 for details on using multiple modems with the same channel.

POST_INTERVAL (OpenVMS delta time specification)

Retransmission to a particular To: recipient of a message will only be attempted if the difference in time between the last transmission attempt and the current system time exceeds the POST_INTERVAL time. The value of the POST_INTERVAL time, if not specified in the option file, is determined as follows: If not specified in the channel definition, the channel periodicity is 1 (i.e., service the channel every service period). It is best to keep POST_INTERVAL less than PMDF_POST_INTERVAL for the following reason: suppose that at 0:00 hours, the G3_TO_FAX channel runs and tries to deliver a message to several To: recipients; now suppose that after successfully delivering the message to the first three recipients, that then delivery fails at 0:10 to the fourth and final recipient. This fourth and final recipient is given a time stamp of 0:10 hours. Then, four hours later at 4:00 PMDF-FAX again tries to deliver the message (PMDF_POST_INTERVAL = 0 4:00:00) to the one remaining To: recipient. If POST_INTERVAL were set to PMDF_POST_INTERVAL, then four hours would not have elapsed since 0:10 and no attempt would be made until 8:00 to deliver the message to the remaining recipient.

PRIORITY (integer > 0)

This option specifies the base priority to which the G3_TO_FAX channel is to elevate itself while transmitting a FAX. The CCITT FAX standards set a minimum speed on the rate of FAX transmission. Because of this minimum, at times the G3_TO_FAX channel needs to maintain an average transmission rate of at least 7200 baud. By default, the G3_TO_FAX channel elevates its base priority to 5 while actually communicating with the FAX modem. To select, for instance, a priority of 6, place the line 


PRIORITY=6
in the channel option file.

PULSE (0 or 1)

This option is not supported by the DCE FaxBox/30; for that modem the method of dialing is staticly set when the modem is first installed. Refer to Section 37.5.1.2 for instructions on how to change the dialing method. By default, the Fujitsu dexNET 200 and Service Class 2 modems will use touch tone dialing when placing a call. By specifying PULSE=1, the modem may be instructed to place calls using pulse dialing. When PULSE=1 is specified, the G3_TO_FAX channel merely prepends the dial string modifier P to the front of each phone number prior to dialing and users may override this action by placing a T dial string modifier in their FAX telephone number. Specifying PULSE=0 causes the dial string modifier T to always be prepended to the front of each phone number prior to dialing, which users may override with a P modifier in their FAX number.

RETURN_CONTENT (0 or 1)

When this option is set to 1 and the PS_TO_G3 channel option RETURN_CONTENT=1 was also set, the contents of the FAX will be preserved in PostScript form in case the FAX cannot be delivered; if a bounce message needs to be generated by the G3_TO_FAX channel, that bounce message will then include the PostScript corresponding to the attempted FAX. The default is 0, meaning that no such content preservation is attempted.

RETURN_HEADERS (0 or 1)

By default, the header lines for the originating message are appended to the bottom of mail messages issued by the G3_TO_FAX channel (e.g., status reports). The display of these headers may be suppressed by specifying RETURN_HEADERS=0 in the option file. RETURN_HEADERS=1 yields the default behavior.

SPEAKER (0, 1, or 2)

This option is only supported by Fujitsu dexNET 200 FAX modems. This option controls the speaker on the FAX modem and has a default value of 1 (speaker on only while the FAX modem is dialing the remote FAX receiver). The possible values for this option are:
Value Action
0 Speaker always off
1 Speaker on while dialing, off during transmission
2 Speaker always on

TIME (12 or 24)

By default, the time displayed across the top of each FAX page will be in 12 hour format (e.g., 1:30 PM). To display the time in 24 hour format (e.g., 13:30), specify TIME=24. The default is selected with TIME=12.

TRUNCATE (0 or 1)

This option is only supported by the dexNET 200. When TRUNCATE=1 is specified in both the PS_TO_G3 and G3_TO_FAX channel option files, each transmitted page will be "cut short" so as to not, on the receiving end, output any blank, bottom portion of a page. See Section 37.2.9 for further details. For Service Class 2 modems, specifying TRUNCATE=1 in the PS_TO_G3 option file will result in the transmitted FAX being cut short; there is no need to also specify TRUNCATE=1 in the G3_TO_FAX option file for these modems. (Moreover, specifying TRUNCATE=0 in the G3_TO_FAX option file will have no effect for Service Class 2 modems.)

TTI (text string <= 24 characters long)

Specifies the content of the Transmitting Terminal Identification (TTI) string -- a 24 character ASCII string printed by the FAX modem across the top of each transmitted FAX page. This string should contain at most 24 ASCII characters. The TTI string has no default value; by default no TTI string is printed by the FAX modem. User supplied TTI strings (specified with the /TTI=string attribute-value pair (AVP) in the message To: line of the originating message) will override the TTI channel option if the SET_TTI option is set to 1. The SET_TTI option, described below, has the default value of 0 which disables use of user supplied TTI strings. It is recommended that a TTI string be provided for each G3_TO_FAX channel so that FAX recipients can quickly identify received FAX pages. (It is the developer's experience that unattended FAX machines scatter all received FAX pages on the office floor.)

SET_TTI (0 or 1)

This numeric value should be either 0 or 1 and specifies whether or not the G3_TO_FAX channel may use a user supplied TTI string. (Users may specify a TTI string with the "/TTI=string" attribute-value pair in their message To: line.) By default, this option has value 0 which disallows the use of user specified TTI strings. To allow the use of user supplied TTI strings, place the line 


SET_TTI=1
in the channel option file. When set to 1, a user supplied TTI string will override any TTI string specified in the channel option file with the TTI channel option.

USE_REPLY_TO (0 or 1)

One possible address acknowledgement and status report messages are sent to is the original message's Reply-To: address. Under some circumstances it is never appropriate to use the Reply-To: address for this purpose. The USE_REPLY_TO option controls the use of the Reply-To: address for acknowledgements. A value of one (the default) causes the Reply-To: header to be used in the normal course of events. A value of zero inhibits use of the Reply-To: header for acknowledgements.

Options specific to Service Class 2 modems

EXTRA_CMDS (text string <= 252 characters long)

A list of additional commands to send to the modem in order to initialize it. The specification (note the use of the backslash character, \) 


EXTRA_CMDS=cmd1\cmd2\...\cmdN
results in the commands 


ATcmd1<CR><LF> 
ATcmd2<CR><LF> 
... 
ATcmdN<CR><LF>
being issued. To send a literal \, specify \\. If any of the commands result in an error, then the modem initialization is deemed to have failed.

FLOW_CONTROL_CMD (text string <= 40 characters long)

Command to issue in order to select the desired flow control method. Has no default; no attempt is made to select a flow control method unless a command is specifically specified with this option.

MANUFAC_QUERY_CMD (text string <= 40 characters long)

Command to issue to query the modem's manufacturer. The default is +FMFR?.

NO_ANSWER_CMD (text string <= 40 characters long)

Command to issue to disable auto-answer; i.e., to prevent the modem from answering incoming phone calls. The default is S0=0.

ON_HOOK_CMD (text string <= 40 characters long)

Command to issue to cause the modem to go on-hook; i.e., to hang up the phone. The default is H0.

RESULTS_ON_CMD (text string <= 40 characters long)

Command to issue to request that the modem return result codes in response to modem commands. The default is Q0.

SOFT_RESET_CMD (text string <= 40 characters long)

Command to issue to reset the modem to the default profile. The default is Z for MultiTech modems and Z0 for other modems.

VERBOSE_OFF_CMD (text string <= 40 characters long)

Command to issue to request that non-verbose, numeric result codes be returned. The default is V0.

VERBOSE_ON_CMD (text string <= 40 characters long)

Command to issue to request that verbose result codes be returned. The default is V1.

Note

8 Note that the NOTARY specification, RFC 1891, mandates that if a message is submitted using NOTARY, then a "success" DSN may only be sent if success DSNs were explicitly requested.

Previous Next Contents Index