XFAX 4.3a - User's Guide

14. Command reference

Here we describe the syntax of each command in the software. You can use -v as an option for most of the commands to get syntax information for the command. To get debug information, especially good for faxmaster, use -debug or -xdb.

All scripts supplied with XFAX are example scripts of which the functionality is not guaranteed. However, the intention with these scripts is that they should be as complete as possible and improvements are being made on a regular basis.

The following command-line utilities are available in XFAX.

14.1 Commands

14.1.1 faxadm

Syntax: faxadm

Script which gives the user a simple, text-based, menu for the administration of his/her fax environment.

14.1.2 fax2bmp

Syntax: fax2bmp

Converts a fax file to bitmap format. This functionality will be extended.

14.1.3 fax2hp

Syntax: fax2hp

Converts a fax file to HP Laserjet format (PCL code). Used by faxmaster and faxprint for printing out faxes.

14.1.4 faxclean

Syntax: faxclean [-older days] [-to date]

Used to clean out the statistics file.

Parameters:

-v Shows the program version and syntax.

-older days Indicates that information older than the number of days given should be removed.

-to date Indicates that information up to and including the date stated will be removed.

14.1.5 faxlogon

Syntax: faxlogon [-q] [-u user]

Used for connection to the fax server, faxmaster.

Parameters:

-v Shows the program version and syntax.

-q Does not write information to the screen.

-u user Logs on as specified user. The specified user can be an existing user or a fictitious user. In a mail coupling it can for example be the sender's mail address.

The user cannot utilize the services of the fax system before he/she is connected to the fax host via faxlogon. When the maximum number of users in accordance with the licence agreement has been reached, faxlogon will deny any new users connection to the fax host.

14.1.6 faxmail

Syntax: faxmail

Script which is used on integration with mail software, e.g. sendmail. Faxmail is described in more detail in the chapter "XFAX connected to mail".

14.1.7 faxmaster

Syntax: faxmaster [-debug] [-xdb] [-r] [-v]

Parameters:

-v Shows the program version and syntax.

-debug Means that information on events during program running are written to standard out.

-r Shows the return codes from the various fax commands.

-xdb Display more detailed debug information.

This is the fax server which does all work on behalf of its clients and users. The fax host maintains fax queues, checks authority and licence information and reads data, control and statistic files. Faxmaster is normally started from one of the initiation scripts (rc-files) which are run when the system is started up. After this it remains in the background and doing its job without any fuss. Any fault messages are written out in the file ETCDIR/Log/faxmaster.

Faxmaster must be restarted when the configuration file, ETCDIR/config, or the serializing file, ETCDIR/.serial, are modified.

14.1.8 faxmime

Syntax: faxmime [-e | -file]

Used to extract information from a file on the MIME format. The result is written on stdout and consists partially of codes and partially of the file name with the extracted attachments. The following codes can occur:

!FROM The identity of the sender

!SUBJECT The subject line

Files which are created are called <pid>.<seqno>.<ext> where the seqno is the enclosure's sequence number in the file, ext is the file's extension, which can for example be txt for a text file, and pid is the processor's id and is guaranteed to be unique.

You can then choose which enclosures you want to use and which ones you wish to discard.

Parameters:

-dir dir Indicates which directory the extracted enclosures will end up in. Normally /tmp.

-e Reads standard input, codes to BASE64 and writes in standard output.

-noheader Indicates that the program will not work mail-headers.

-prefix str Adds str to the prefix before pid in the file name.

14.1.9 faxprint

Syntax: faxprint[-q] [-d printer] [ID [ID ...] | file]

Used to print out a fax on an HP Laserjet compatible printer.

Parameters:

-v Shows the program version and syntax.

-q Does not write information to the screen.

-d printer Specifies that the printout will be sent to the stated printer.

The argument can be either a fax-ID or the name of a fax file. The printout data is sent to the standard printer if no special printer is specified. The printer should be HP Laserjet compatible and the data must not be filtered, i.e. the printout should be raw, otherwise it will be garbage. E.g. faxprint -d LASER 13 or faxprint D.510.000.

14.1.10 faxq

Syntax: faxq [-reverse] [ -p | -s | -r | -f | -d [directory] [ -h ID ] [ -n ID ] [ -t tt:mm ID] [-x]

Used to show the various fax queues, to change the sending times for a special fax and to list fax files.

Parameters:

-v Shows the program version and syntax.

-p Shows the queue of outgoing faxes.

-f Shows the queue of faxes which it has not been possible to send.

-s Shows the queue of faxes which have been sent.

-r Shows the queue of received faxes.

-d [dir] Lists the fax files which are to be found in the directory dir.
If there is no argument, the program looks in the directory Fax under the user's home directory ($HOME). The information listed is, in sequence: ID, the recipient's fax number, the number of seconds connected, the number of retries, the time the fax has been in the queue and the number of fax pages. Note that you must have authority to read the directory in question.

-h Holds and releases faxes (hold).

-n ID Changes the time for the next transmission attempt to the given time in hours and minutes.

-x Lists the line used, cost and number of retries for sent and faulty faxes.

14.1.11 faxrm

Syntax: faxrm [-all queue] [-to date] ID [ID [ID ...]]

Used to cancel a fax that is in a queue for outgoing faxes. Furthermore, you can mark sent and faulty faxes that have been removed to avoid having a mass of old faxes when you look through your queues. However, the statistics are kept.

Parameters:

-all queue Indicates that all the faxes in the queue indicated should be cancelled.

-to date Used in combination with -all and indicates that only faxes up to and including a certain date should be removed.

-v Shows the program version and syntax.

You find out the ID of a fax by using the command faxq. Several faxes can be cancelled at the same time by giving several IDs separated by a space.

14.1.12 faxsend

Syntax: [-c id] [-s id] [-l file name] [-n note] [-p priority] [-t tt:mm] [-u user] [-d printer] [-q] fax number [file 1 [file 2...] | - ]

Converts a HP Laserjet file to fax format and sends information on the fax to the fax server which then takes care of the actual transmission.

Parameters:

-v Shows the program version and syntax.

-c id Chooses the national set of characters when converting the text file to fax format. Possible values of id:
0 (US), 1 (French), 2 (German), 3 (UK), 4 (Danish), 5 (Swedish), 6 (Italian), 7 (Spanish), 8 (Japanese), 9 (Norwegian), 10 (Danish 2) and 11 (Spanish 3).

The standard values are given by the keywords CHARACTER_SET in the configuration file.

-d printer Printing out of the file is done through the specified printer after the fax has been placed in a queue to the fax server.

-h Indicates that the fax should be parked, i.e. remain in the queue until it is released with the aid of faxq -h.

-id Writes the id(s) of the fax(es) in the queue on the screen.

-l filename Sends the same fax to all recipients whose fax number is in the stated file. The file should be a normal text file with one fax number per line. Comments can be set in by beginning the line with the symbol #.

-margin n Sets the default margin af the fax to 5 characters. See also: DEFAULT_MARGIN

-n string Ties a note string to the fax. This note is then shown in the fax queues. Maximum length is 80 characters.

-p priority Indicates that the fax should have a certain priority. Normally 4. Permitted values are 1-7. 1 indicates the highest priority.

-q Does not write information to the screen (quiet).

-s id Chooses the set of symbols when converting text files to fax format. Possible values for id:
0 Roman-8
1 Latin-1 (ISO 8859-1)
2 Windows
The standard value is given by the keywords SYMBOL_SET in the configuration file.

-simulate Runs a simulated fax transmission. This can be done to estimate the time and cost of sending a fax and to compare how these factors are affected by sending the fax at different times of the day. No fax is placed in the queue when this parameter is used.

-t tt:mm Gives a particular time when the fax is to be sent. In normal cases the fax is sent as soon as possible, but with this parameter the transmission can be postponed. The time is given in hours and minutes, e.g. faxsend -t 12:34 7586535 faxfile.

-u user Sends the fax as stated by the user.

- If this parameter is given, the program data reads from standard input instead of from the given files. E.g. faxsend 7586535 - <letter or cat letter | faxsend 7586535 -.

14.1.13 faxsr

Syntax: faxsr infile [-]

Used to make a search & replace in HP Laserjet files. See further details in the chapter XFAX and cover sheets.

Parameters:

- If this parameter is given, the program reads the data from standard input instead of the stated files.

14.1.14 faxstat

Syntax: faxstat [-g] [-v] [-s string]

Used to generate statistics reports and to show activity graphs.

Parameters:

-v Shows the program version and syntax.

-g Shows the activity graph, i.e. how many faxes are in the queue at different times of the day. This function can be used to see where the largest telephone costs are and possibly do something about this by locating fax transmissions to those times of the day when the telephone tariff is lowest.

-s "string" Selection string which describes which data should be included in the report. Example:
faxstat-s "date=960120-960125".

If no parameter is given, statistics of the number of faxes in the queue are shown, plus the number of unsuccessful faxes, the connected time and the cost for the call in accordance with the tariff tables in the file ETCDIR/cost.

14.1.15 faxwho

Syntax: faxwho [-u]

Used to find out which users are connected to faxmaster and from which tty: or IP addresses they are logged in.

Parameters:

-v Shows the program version and syntax.

-u When this parameter is given only unique user names are listed.

14.2 Exit codes

The client programs use the following exit codes:

2 Error in serialisation file

3 Error in configuration file

4 Invalid argument

6 Could not connect to faxmaster

13 Invalid recipient

16 Could not read recipients file

52 Out of disk space