NAME
AVAILABILITY
ELS, PLUS
SYNOPSIS
sendfax [ options ] [ files ]
DESCRIPTION
Sendfax queues fax requests for delivery by faxcico. Files not already in TIFF format will be converted.
This program provides programmers (as well as Faximum itself) with a low-level API. This is the lowest-level interface to the faxsched fax scheduler. For higher-level interfaces look at fxm and submittfax. For a low-level interface which bypasses the fax spooler, see mfax.
OPTIONS
-d Turn on debug messages.
-e script Use the next argument as the list of newline-terminated commands for sendfax.
-j Prints the request sequence on standard output. The sequence number can be used to track the request.
-k Delete the files provided as arguments after they have been read. The files will not be deleted if any errors are detected by sendfax.
-m Mail back error messages. Normally, error messages are displayed on the user's terminal. With this option, if any errors occur, they are collected in a file and mailed to the user.
-q Quiet mode. All job progress messages are suppressed.
-r Do not notify the fax scheduler when the fax requests are queued. This delays possible delivery of fax requests until faxsched does a queue run, or another sendfax is run without this option. Normally faxsched examines the queues once every minute or whenever a fax line becomes idle.
sendfax reads input from a command-line script (if the -e option is used), from any file names listed on the command line, or from standard input if no other sources of input are specified. Each line of input is interpreted as a command, or data for the most recent command. A line containing only an end ends input data for the most recent command. Commands are:
file Specifies the files to be sent and the conversions required. Following the file command is a list of lines each containing: a tagname; the path to the file; file type and conversion options; and a list of options.
The tagname is used elsewhere to identify the file. Its name is arbitrary but must be unique.
The file type specifies the conversion required. For example, ascii will convert a standard ascii file to a standard-resolution fax. Conversion options (such as resolution and page length) may also be specified. For example, "ascii -h -s 14" will generate a fine-resolution fax paginated to legal size paper.
See the directory .../faximum/convert/ for a list of all the supported conversions and refer to the manual page convert(C) for information on the conversion options.
Only two options are supported: nocopy and delete. sendfax normally makes its own copies of files to send in the spool area. nocopy will prevent copying of a file if the file requires no conversion (i.e. type tiff with no conversion options) and is readable to faxcico. Delete will delete the file when it has been copied to the spool area. No files will be deleted if any part of the sendfax request fails.
default Sets defaults for each fax request. The default section consists of a list of name = value pairs terminated with an end statement. For every fax request that follows, this default list will be copied to the list of request parameters. Any parameter explicitly listed in a fax request will override any default. This option is intended as a means of specifying parameters common to every fax request.
fax Submits a fax request. The fax command requires a single argument specifying a unique name for the destination (usually the fully qualified telephone number with no imbedded white space). This name will be used as the name of the queue directory in the spool directory (in .../faximum/destinations).
Following this command, there should be a list of name = value pairs specifying the parameters for this particular fax request. Except for the list of data files, all parameters are copied verbatim into the spooled control file for this request. Any parameter starting with data-file is assumed to be a data file for transmission. The value part of this data file parameter must be a tagname from a preceding file command. This tagname is replaced by the absolute path name of the (possibly converted and copied) file to be transmitted.
preview [preview-program]
Previews files to be transmitted. An optional argument specifies the path to the preview program; tiffdisplay is the default preview program. An end terminated list of tagnames, one per line, follows. The absolute path names of the files named by these tagnames are given as command-line arguments to the preview program. A non-zero exit status from the display program indicates to sendfax that no faxes are to be submitted and no further processing is required. This would normally occur if the user wished to cancel the request after previewing it.
print Prints a fax request. This command requires a list of arguments containing the shell command to execute and a list of arguments for that command. The argument $data-file1 will be replaced by the path names of the end terminated list of tagnames that follow the print command.
background
Tells sendfax to continue operating in the background so that the foreground task can continue operation. This keyword is usually placed after the preview section so that the printing (if any) and scheduling of the fax transmission can continue in the background. The background command (unlike the previous commands) is not followed by a line containing end.
signal Causes sendfax to send a signal to a specified process. The signal number is the first argument and the operating system process id the second.
The faximum.conf file (see config) may also contain defaults for many of these fields. The per request control file always overrides the global defaults contained in faximum.conf.
Valid name = value pairs follow. Note that only the device and data-file... parameters are required. All others are optional. If the parameter value contains white space, it must be quoted. The value component may be quoted using the same syntax as the shell, and may include any of the following escape sequences: \b (backspace), \e (escape), \f (formfeed), \n (newline), \r (carriage return), \t (tab), and nnn (character with octal value nnn).
For example:
name = value
name = "value value value"
name = "This \" string is funny"
abort-time = number
This specifies the time when the fax request is to be abandoned, at which point mail is sent to the originator reporting the problem and a message is placed in the system log file. The time value may be specified in one of three formats. A value of the form @seconds specifies an absolute time in seconds from the epoch (the standard format for the return value from the time system call). The form +seconds specifies a number of seconds since the request was submitted to sendfax. The form !seconds specifies a number of seconds since the request was first eligible to be sent (i.e. satisfied the limitations of the eligible-date and time-to-send parameters), regardless of whether a line was available at that time.
account-number = string
Any information provided will be copied verbatim into the accounting log file. By convention this string is of the form: "<billing code> <person> <company>"
alternate-count = number
This value specifies the maximum number of attempts that are to be made using the primary telephone number before trying the secondary telephone number. Once alternate-count attempts have been made, the system will try the secondary and primary telephone numbers alternately until successful or until one of the time or retry limits is reached.
alternate-device = device name
This value specifies the fax line and telephone number(s) to use when alternate-count attempts have been made using the primary telephone lines (see the device parameter below for more information on the format of this value).
banner = string
The string specified will be placed at the top of every transmitted page. Strings of the form $p will be replaced with the current page number, and $t will be replaced with the total number of pages in the FAX. Strings that start with a % symbol will be passed directly to the strftime(I) routine, which replaces the string with date and time information.
batch = yes/no
Specifies if a request can be batched with other requests that are queued for the same destination (i.e. transmitted during the same call).
completion-program = program-pathname
Can be called when a fax request is no longer considered for transmission because either it was successfully transmitted, or faxsched/faxcico will not attempt to retry at a later date. This program requires two arguments: the path to the control file and a brief message explaining why the request will no longer be considered for transmission. For security reasons, the completion-program must have fax's home directory (usually /opt/faximum) as the first part of its path name. It is the responsibility of completion-program to dispose of the request control file. (This feature is available only with Faximum PLUS.)
data-file1 = string
This specifies the tagname (see the file section above) of the first file to be sent (similarly for data-file2, data-file3...).
data-queued = date/time-string
Date a fax request was queued. Defaults to current date/time.
device = device name
This specifies the name of the FAX line to use and the actual string of digits to dial. This is the primary (fax line and) telephone number to use. (See alternate-count and alternate-device). The format is fax line name:telephone number or fax line name:telephone number:delay.
The fax line name may be one of the following: the name of the fax line configuration file in the /usr/fax/dev directory; the name of the device special file (in /dev); or @ followed by the line-type to use (faxcico will use any entry in /usr/fax/dev that has the specified line-type and that is idle).
The telephone number is the string of digits to dial (possibly with the delay characters `,' and `;'). The delay is the time in minutes from when the request was submitted until the system considers using the specified line.
If the system supports more than one phone line, there may be more than one fax line name:telephone number on the same line (separated by blanks, with the entire list in double quotation marks). The list is scanned from left to right for the first idle line.
eligible-date = number
This parameter specifies (in seconds since the epoch) the earliest (date and) time when this request may be considered for transmission. This is used to postpone transmission of a request until some later time and date. Note that delaying the FAX until a specified telephone discount period is usually done using the time-to-send parameter.
filter-value = value
This parameter specifies the filter value to use on the FAX modem for this transmission. If not specified, then the default filter value from the device configuration file (in the directory /usr/fax/dev) will be used. Not all fax modems use or support a filter value, and the purpose and range of valid values varies. Please refer to your fax board/modem's documentation for further information.
handle = value
This parameter specifies an arbitrary identification string that the application submitting the request can use for to identify the request (i.e. Purchase Order number or whatever). This value is put in the acct log and passed to the completion-program. This feature is only available in the Faximum PLUS product.
notify = yes/no
If set to `yes', the user who submitted the request will receive E-mail upon successful completion of the transmission (unsuccessful transmissions always result in E-mail).
priority = number
This specifies the priority of the fax request. If there is more than one fax request to send, the fax scheduler will choose the one with the numerically higher priority value.
reschedule-time = number
This parameter specifies the time at which this request is to be handed to the rescheduler (.../faximum/lib/resched) for possible escalation to more expensive telephone lines. Note that no such program is provided as part of Faximum; if this option is used, the user must provide the resched program.
retry-coversheet = tag
This allows a user to specify a coversheet to be used only if a fax is partially transmitted and must be restarted. As with data-file, tag must be the tagname of a file listed in the file section of the input script.
retry-delay = number
This specifies the delay (in minutes) between redial attempts. If not specified, the default delay is taken from the system configuration file (~fax/config).
retry-limit = number
This parameter places an absolute maximum limit on the number of attempts that the fax scheduler will make to send this fax in the event that the telephone number does not answer or is busy. If not specified, the default limit is taken from the system configuration file (~fax/config).
sent-by = username
User name to be used for E-mail and accounting.
suspend-completed-requests = yes/no
This causes successfully transmitted request control files to be renamed from cf... to ff....
suspend-failed-request = yes/no
This causes failed requests to be suspended (i.e. the control file prefix is changed from cf... to sf.... and is no longer considered by faxsched for transmission). Renaming the sf... file cf... will cause faxsched to reconsider the fax for transmission.
time-to-send = number
This specifies the interval during which attempts may be made to send this FAX (expressed as three time-intervals: the first applies Monday through Friday, the second on Saturday, and the third on Sunday). (Example: "1800-2400 1800-2400 0800-2400"). This is used to ensure that a FAX is only sent during certain telephone discount periods.
tsi = string
This specifies the transmitting station identification string. The string ought to be the fully qualified (country code, etc.) telephone number of the incoming FAX line for the company sending the fax.
tsia = string
This specifies the alphanumeric transmitting station identification string. Some fax boards support an alphanumeric identification string in addition to the standard numeric TSI.
EXAMPLE
This is an example of a minimal sendfax file that faxes a single ASCII file (which is deleted after being queued to send).
file
body /tmp/fcvr.BAAa10927 ascii delete
end
fax 16135551212
device = fax-line-1:16135551212
data-file1 = body
end
The following example shows the use of several sendfax command options.
file
cover /tmp/fcvr.BAAa10927 ascii delete
body1 /usr/doe/images/lit.tif tiff nocopy
body2 /tmp/graph.ps "ps -h -s 14"
end
preview
cover
body1
body2
end
background
print "tiffps $data-file1 | lp -dlaser"
cover
body1
body2
end
default
banner = "Company Inc. +1 234 567 9876 %c Pg $p/$t"
tsi = "1 234 567 9876"
priority = 99
retry-count = 30
retry-delay = 1
completion-program = /usr/fax/lib/myscript.sh
time-to-send = "1800-0800 1800-0800 0000-2400"
end
fax 16135551212
device = @ddd:16135551212 @fx1:5551212
data-file1 = cover
data-file2 = body1
data-file3 = body2
end
fax 16049268182
device = fax-line-1:16049268182
retry-delay = 10
data-file1 = cover
data-file2 = body1
data-file3 = body2
end
FILES
faximum.conf
system configuration file (for defaults)
.../faximum/convert/*
input file conversion programs
.../faximum/dev/*
fax line configuration files
.../faximum/destinations/*
spool area
.../faximum/log
fax log file
.../faximum/acct
fax accounting file
SEE ALSO
asciitiff(C), convert(C), faxsched(C), transmitfax(C), strftime(I)
Appendix E.