Fax2Send Shell API

Shell API Menu
Search Fax2Send Advanced
Overview
Queue a fax
Status
Retry
Cancel
Loglink
HpFaxSpool

Support Overview

Home Page
Cover Sheets Overview
Graphics and Stationary
Search
Site Map

Fax2Send Shell API - Queue a Fax

/usr/bin/fax2 - Add a new fax request to the queue

Examples

NAME

fax2 - Queue a Request for facsimile transmission.

SYNOPSIS

fax2 [-qcFER] [-mmail_level] [-nreal_name] [-Hheader_file] [-hheader_line] [-ttime] [-Aanswerback] [-dfax_unit_name] [-Ttag_data] [-larg_file] [-Dprinter] [-pphone_no | -Mmailshot_file] [[[-Ppreformat] file]... | [-]]

DESCRIPTION

Fax arranges for the named files and associated information (collectively called a request) to be sent as a facsimile message to a remote facsimile machine. If no file names are mentioned, standard input is assumed. The order in which files appear in the command line is the same order in which they will be "faxed".

Files can be in any of the following formats:

ASCII
HP Laserjet III / PCL5
Postscript (depends on Ghostscript installed with command /usr/bin/gs)
TIFF (all strictly black and white compressions)
BMP (strictly black and white)

If a "-" is used instead of a file name then the request is assumed to be a front sheet only.

Fax associates a unique id with each request and prints it on the standard output. The id can be used later to cancel (see fax2cancel) or retry (see fax2retry) the request.

A phone number should consist of only digits, spaces, the character '-' and the pause character ','.

Flags:

-A answerback	Check the answerback of the remote fax machine against answerback before transmitting the image.
-c	Make copies of the files to be faxed. Normally files will not be copied. If the -c option is not given, then the user should be careful not to remove any of the files before the request has been "faxed" in its entirety. It should also be noted that in the absence of the -c option, any changes made to the named files after the request is made but before it is "faxed" will be reflected in the "faxed" output.
-d fax_unit/group	Transmit the request on the specified fax unit or group. The Group for a fax modem can be defined with the Group parameter in the modem section of the config file.
-D printer	Whenever the loglink script or a format script is called set the environment variable UFXPRINTER to printer.
-E	Queue the request as an express fax. The user must be registered in the file /etc/fax2send/express.
-F	Transmit the request in fine quality (196 dpi vertically). The default is 98dpi.
-h header_line	Include a header/front sheet with the "fax". Information from the header_line string is pasted into the header file to produce the front sheet. See below for more details.
-H header_file	Use the specified file as the header/front sheet template for this request. The header_file must be on the Fax2Send server machine. A path name that deos not start with a / is taken relative to the directory /etc/fax2send/header/lang e.g /etc/fax2send/header/en. If this flag is not used or the file cannot be found then Fax2Send looks for $HOME/.faxheader and then for the file specified against Front_Sheet in the config file.
-l arg_file	Process the lines from arg_file as arguments to the fax command. One line per argument.
-m mail_level	Send mail after the files have been "faxed", transmission fails or transmission is completely abandoned. By default, mail is only sent to users when one of their requests is cancelled by another user or the Fax2Send system is able to stop transmission of a request on behalf of the user. A mail_level of 1 sends mail only if the request is abandoned. A mail_level of 2 sends mail only when the request is either sent OK or abandoned. A mail_level of 3 will send mail at every transmission attempt.
-M mailshot_file	Transmit the request to the destinations specified in the given mailshot file. See below for the format of a mailshot file.
-n real_name	Display a file or files under a pseudonym in the queue. This is very useful for application integration when each fax request may relate to a reference number of some kind.
-p phone_no	Transmit the request to the specified 'phone number. The special number "preview" may be used to test the formatting of a request. Other acceptable strings can be defined in the file /etc/fax2send/short_codes (see below).
-P script	Process the following file through the specified format script. The script must be stored in the folders /usr/lib/fax2send/Format/Class2. See below for more details.
-q	Suppress output from the fax command.
-R	Return only the request ID.
-t time	Queue the request for transmission at the specified time. The format of the time string is either hhmm (e.g 1800 for 6 p.m) or hhmm+d (e.g 1800+2 for 6 p.m in 2 days time).
-T tag_string	Whenever the loglink script or a format script is called set the environment variable UFXTAG to tag_string. This is very useful for close coupling of Fax2Send with another application.

Mailshot Files

A mailshot file should have the following format for each line:

phone_number header_line

phone_number

See below for details of header lines.

Cover / Front Sheets

A header/front sheet is a merge file that can be prepended to a document prior to transmission.

The format of the header line is:

/field 1/field 2/......./

To include a / character in a field it should be delimited by a \ character.

The data in field n will be pasted into the nth blank field in the header file and any field with the number n inside.

More information on cover sheets.

Format Scripts

Before transmitting any file the Fax2Send system first executes a format script to translate the file from its native format to one suitable for faxing. The preformat script used depends on the type of the fax modem transmitting the request and the value given with the -P flag.

e.g If a request is to transmitted on a fax modem of type 'make' with format script format then the script to be executed will be /usr/lib/fax2send/Format/make/format.

Before executing the script Fax2Send sets up some environment variables:

FAXIN	Name of file to be formatted.
FAXOUT	Name of output file.
UFXLIB	Home directory for Fax2Send.
UFXSPOOL	Directory where Fax2Send spool and log files are stored.
UFXQUALITY	Set to 0 for coarse transmission and 1 for fine.
UFXHPFORMAT	Either slow or fast.
UFXID	ID of request being formatted.
UFXMAIL	Either yes or no.
UFXPRINTER	Set to value of argument given with -D flag.
UFXTAG	Set to value of argument given with -T flag.
UFXUSER	Set to logname of user.
UFXUSERHOST	Node name of machine that request was queued from.

If no preformat script is specified then the 'default' script is used.

Examples

Transmit the file letter to fax number 0207 123 456

fax2 "-p0207 123 456" letter

Transmit the file letter to 0207 123 456 formatted through the landscape preformat.

fax2 "-p0207 123 456" -Plandscape letter

Transmit the file letter to 0207 123 456 at 6 pm

fax2 -t1800 -p0207123456 letter

Put a front sheet on the fax and include the ASCII file /tmp/abc123.txt in the header.

fax2 -h"/Merge Field 1/Merge Field 2/...." -p0207123456 -Pheader /tmp/abc123.txt

Exit Codes

  1    Fax queued but daemon not running.
  0    Fax queued and daemon running.
  -220 No more licenses available.
  255  NetServer is down
  254  UFXLIB and UFXSPOOL not set OK
  253  Cannot obtain uname.
  252  Cannot obtain password entry.
  251  The env variable UFXLOGIN has been set to a value that
       does not match the uid.
  250  Cannot obtain password entry.
  249  Transmission permission denied.
  248  No phone number or argument in wrong place.
  247  Cannot access file.
  246  Empty file in request.
  245  Must use the -h flag if no file names given.
  244  Cannot gain access to the queue.
  243  -i flag only valid for telex command.
  242  Cannot access mailshot file.
  241  Bad mailshot file.
  240  -p flag only valid for fax command.
  239  Invalid phone number.
  238  Prohibited number.
  237  -g flag only valid for telex command.
  236  No name supplied with -n flag.
  235  No string supplied with -h flag.
  234  No string supplied with -A flag.
  233  -P flag in wrong position.
  232  No format script given with -P flag.
  231  Invalid time.
  230  -F flag only valid for fax command.
  229  -G flag only valid for the fax command.
  228  No name supplied with -d flag.
  227  Not defined.
  226  Express permission denied.
  225  Unknown flag
  224  Cannot read list of express users.
  223  No string supplied with -H flag.
  222  No string supplied with -D flag.
  221  No string supplied with -T flag.
  220  User licence limit exceeded.
  156  Other system error.