Description

DFsendfax transmits any plain text, PDF, or TIFF file to one or more recipients.

DFsendfax interacts with a DFdiscover outbound daemon. You must have at least one outbound daemon configured before DFsendfax will work. DFsendfax makes a temporary copy of the file to be sent. By default, this is in /usr/tmp, although it may be your home directory if there is no space available in /usr/tmp. The temporary copy of the file becomes owned by user datafax. DFsendfax places its options into a structure that it then sends to the outbound daemon. Which outbound daemon is used is determined by the DFdiscover master using a round-robin scheduling algorithm. The outbound daemon then makes a queue entry for the fax request in its work directory. It also copies (or remote copies, if necessary) the temporary file to a data file in its work directory. The outbound daemon then manages the queue entry until the scheduled time for sending arrives. At this point, the data file is passed to the system email service, DFprotusfax or HylaFAX, which attempts delivery of the document. If the transmission is successful, that status is forwarded to the outbound daemon which then executes zero or more of the success commands. If the transmission has failed, the outbound daemon either waits the number of minutes specified by the retry delay if one or more retries are still possible, or executes one or more of the failure commands. Finally, if the outbound daemon never receives a reply regarding the disposition of a fax, the outbound daemon de-queues the fax and executes the appropriate failure commands.

When specifying success or failure commands to execute at the completion of a fax session, you can reference the values of various arguments that you supplied in your original DFsendfax command. The values that you can reference are:

If your fax is successfully queued, DFsendfax echoes back the name of the file to be sent, the phone number of the recipients, the scheduled fax time, and the faxid of the queue entry. This faxid is unique within the system and can be used to monitor the status of the fax with DFfaxq, or to de-queue the fax with DFfaxrm. You should be aware that depending on how your outbound daemons are configured, it may take several seconds for a fax queued with DFsendfax to be detected so that it appears in the output of DFfaxq.

DFsendfax and DF_QCfax

The standard DFdiscover report program, DF_QCfax, uses DFsendfax to send Query Reports to participating sites in a study. If a Query Report is successfully transmitted, DFqcsent.rpc is executed (via the -sANY option) to mark the quality control notes as having being successfully sent to the investigator site. This is needed so that DFdiscover will display the correct status of queries in DFexplore, and is also needed if you intend to use the overdue allowance option when creating Query Reports. Thus you should always use DF_QCfax to send quality control reports and not DFsendfax.

Delayed Sending

DFsendfax can schedule a fax for transmission at a specified time, rather than the default which is immediately. This is specified by the -w option. The possible arguments to this option can have the following syntax:

now | today | tomorrow | <time spec> [<offset>]
                         (1)                (2)

If the time specified is in the past then this is the same as specifying now.

Options

-2	transmit the fax in fine mode. The default is standard mode.
-A4	transmit the fax using A4 sizing. The default is US letter size.
-F from	identify any files transmitted via email as originating from sender from.
-w #	the time that the file should be sent or emailed. The default is now. The specification of the time is similar to that allowed by the UNIX at.
-r #	the number of attempts to refax the file if the first attempt fails. The default is 2. The total number of attempts is the number of retries plus 1. Multiple attempts do not apply to emails as DFdiscover has no way of determining whether or not an email was delivered.
-d #	time, in minutes, between refax attempts. The default is 10 minutes. If the number of retries is 0, this value is ignored.
-p password, -P	encrypt the file to be emailed using the supplied password or using the password specified in the password file ~/.dfpdfpasswd. This option applies only to PDF attachments. Other file formats are sent unencrypted.
-c string	any comment string that you want to attach to the fax command. You can reference this comment field later when executing success or failure commands.
file	the file to be sent (required). It can be any text, PostScript®, TIFF, or PDF file. For faxing, DFdiscover uses HylaFAX to convert any non-TIFF file into a TIFF file. For emailing, PostScript® files are converted to PDF first (other formats are sent unchanged), and then sent as a MIME attachment to the specified email address. You must have at least read permission on any file to be sent.
recipients	a white-space delimited list of fax numbers or email addresses for recipients of the file (required). For each fax number include all long distance codes, etc. as required. Be careful not to include white-space characters inside a fax number as it will be interpreted as multiple fax numbers. Each email address must be in the format mailto:email_address where mailto: is fixed and required, and email_address is a valid email address. Warning DFdiscover does not perform validity checking on email addresses. Further, if the outbound service is configured to send documents via email only, any recipients that are not email addresses are quietly ignored.

DFsendfax provides commands that can be executed upon successful or unsuccessful completion of the transmission. Completion occurs after the specified number of retries have been attempted, if necessary. The command is executed in a Bourne shell as a background child process of the outbound daemon on the machine that the DFsendfax command was originally specified. There are four levels of commands that can be specified. They can be specified individually or in any combination. It is the user's responsibility to ensure that any concurrency issues that may arise as a result of more than one command executing simultaneously are planned for.

Exit Status

DFsendfax exits with one of the following statuses:

Examples

% DFsendfax /etc/printcap 5551212
Fax /etc/printcap
scheduled for sending to 5551212
at Thu Dec 3 08:45:26 1992
->Faxid is 317

% DFsendfax -w 23:00 -F repltyo@company.com /etc/fstab 9876543 mailto:luckyuser@hotmail.com
Fax /etc/fstab
scheduled for sending to 9876543 mailto:luckyuser@hotmail.com
at Thu Dec 3 23:00:00 1992
->Faxid is 318

% DFsendfax -w 'now + 30 minutes' \
-sEACH 'echo $DataFile faxed to $Number | mail $Requestee' \
-fEACH 'echo $DataFile FAILED to $Number | mail $Requestee' \
/etc/magic 1-800-555-1212 9876543