faxcmd - UxFax fax client and command interpreter.

faxcmd < command_file
faxcmd
faxcmd command [options]
faxcmd send [send_options]

Faxcmd is the user client process of UxFax. This program provides a command line interface, plus a full menu based interface. It is used to administer and monitor the spooler activity, and also to submit documents for transmission.

Most facilities are accessible within the menu based interface. But there is also a full compliment commands which allow these same facilities to be integrated into other applications.

All of the commands listed below are recognised by the fax client command interpreter (faxcmd). Most of these commands also require arguments. The commands are described in detail later;

attach	Attach a modem driver.
cancel	Cancel a fax request.
check	Unimplemented command.
config	Invoke the minimum configuration screen.
confirm	Acknowledge a received fax.
copy	Copy a received fax to one or more users.
create	Create (and send) a document.
database	Internal command.
detach	Detach a modem driver.
echo	Verify fax server communications.
exec	Execute a glossary shell script.
exit	Exit (quit) the fax program.
faxconfig	Internal command.
forward	Forward a received fax to one or more users.
gclose	Close a glossary file.
gopen	Open a glossary file.
header	Internal command.
help	Unimplemented command.
history	Trace the history of a fax request.
kick	Force transmission of a waiting fax request.
licence	Invoke the program license screen.
license	Invoke the program license screen.
menu	Invoke the full user interface menu.
pi	Invoke the program interpreter.
quit	Quit (exit) the fax program
restart	Shutdown and startup the spooler.
resubmit	Resubmit a fax request.
run	Run a (user defined) fax report/program
send	Send a fax.
shutdown	Stop the fax server.
startup	Start the fax server.
status	Display the status of the server or a fax request.
summary	Display a summary of a submitted fax.
uncompress	Internal command.

The send command accepts the following options;

file	Name of file to send
recipient [ ... ]	Fax recipient name or number
-attach attachment [ ... ]	Preprepared G3 attachments
-now	Send the fax immediately
-ok	Do not ask for confirmation
-panel	Display the fax control panel
-retry retry_scheme	Use the named retry scheme
-std/-fine	Send fax in standard/fine resolution
-tmp tempfile	Use temporary file as source file
-time [ DD/MM/YY ] HH:MM	Send a specific time (and date)
-type type	Specify the source file type
-ref reference	Reference ID for the fax request
-reply userid	Reply address for confirmation
-scan [scan_option]	Find fax number in the source file
-base64	Input file is BASE64 encoded

Faxcmd may be called in several forms. In the first form, commands are read from standard input. e.g.:

$ cat << EOF | faxcmd > echo > EOF Faxcmd: Request 'echo' sent Thu Jul 22 14:48:37 1993 Server: Command CMD_ECHO rcv'd from root@IDmel The fax server is running $

In the second form, faxcmd will run interactively. After running  the program, it will display a prompt. Commands will then be read from the prompt  until  end-of-file  is  encountered or  the  quit  command  is entered. e.g.:

$ faxcmd faxcmd> echo Faxcmd: Request 'echo' sent Thu Jul 22 14:49:57 1993 Server: Command CMD_ECHO rcv'd from root@IDmel The fax server is running faxcmd> quit $

In the third form, faxcmd will treat the command line arguments passed  to  the  program as a command to be executed. Only one command can  be passed  in  this  form  and the program will  terminate  when  it  has completed.

$ faxcmd echo Faxcmd: Request 'echo' sent Thu Jul 22 14:59:23 1993 Server: Command CMD_ECHO rcv'd from root@IDmel The fax server is running $

In most cases, faxcmd will be invoked with the full user interface. In the  following  two examples, the first command will invoke  the  full spooler interface;

faxcmd menu

The next command will invoke the "Facsimile Control Panel" to submit a file for transmission:

faxcmd send file -panel

The following commands are recognised by faxcmd:

attach driver detach driver These  commands  are used to attach or detach  selected  modem drivers.  The  modem drivers are identified by a name  in  the "Fax Modem"  data  base which is accessible through  the  menu interface.

cancel request_no This command will cancel the specified request number and remove it from the current queue. e.g.; faxcmd> cancel 827 Faxcmd: Request 'cancel' sent Wed Dec 1 14:19:36 1993 Server: Command CMD_CANCEL rcv'd from menno@ID486 Request 0827 has been cancelled

history request_no This  command will provide a history listing for the specified request number. e.g.; faxcmd> history 827 +------------------------------------------------------------+ |             History of facsimile request 0827              | +------------------------------------------------------------+ Req   Seq   Date      Time   Operation            Result 0827  0000  01/12/93  14:08  Prepare file         Success 0827  0001  01/12/93  14:08  Paginate file        Success 0827  0002  01/12/93  23:00  Send fax             Waiting

kick request_no This command will kick the specified request number, this will result in that request being moved to the top of the queue, or if another fax is currently being transmitted it will try immediately following completion of the current transmission. e.g.; faxcmd> kick 827 Faxcmd: Request 'kick' sent Wed Dec 1 14:18:33 1993 Server: Command CMD_KICK rcv'd from menno@ID486 Request 0827 has been kicked

menu This command will invoke the full menu-driven user interface.

send file recipient [ ... recipient ] [ options ] This command is used to submit a fax transmission request to the spooler. In it's most basic form, only the file and recipient need to be supplied as arguments. After entering the command, a "Fax Transmission Summary" will be displayed summarising all the transmission parameters and you will be prompted to confirm. e.g.; faxcmd> send Utools/fax/demo/demo.vi 8242108 +------------------------------------------------------------+ |               Facsimile Transmission Request Summary       | +------------------------------------------------------------+ File name       : test.fax (/users/menno/test.fax) File type       : ASCII - Unix text file Attachments     : None Dial Mode       : Manual Recipient 1     : 819-0533      Number only) Send when       : Off peak - if applicable Retry Scheme    : default Resolution      : Fine - 200dpi vertical Ready to send [y/n]? Detailed descriptions of the send command and it's options are provided elsewhere.

startup shutdown restart These commands will start, stop and restart the spooler, respectively. Restart performs  the same  function as  the two other commands, shutdown and startup combined.

status request_no This command will display the current status of a request. The details displayed may differ, depending whether it is a received or transmitted fax, and whether it is complete or active. e.g.; faxcmd> status 827 +-----------------------------------------------------------+ |          Status of queued facsimile request 0827          | +-----------------------------------------------------------+ Final Status    : Complete Last operation  : Send fax Last result     : Success Parent request  : 0827 No. Pages       : 1 Retries         : 0 Submitted       : 01/12/93 14:08 Next Due        : 01/12/93 23:00 User            : menno@ID486 Alias           : Halliday Fax No          : +1-233-312-2323 Without  any arguments, this command will display the  current status of the spooler and each of the attached modem drivers. e.g.; faxcmd> status Faxcmd: Request 'status' sent Wed Dec 1 14:15:11 1993 Server: Command CMD_STATUS rcv'd from menno@486 Server status: 1 modem(s) attached, 0 active task(s) Modem           Mode                    Status modem1          Send and Receive        Waiting

summary request_no This  command will provide a summary for the specified request number. e.g.; faxcmd> summary 827 +------------------------------------------------------------+ |               Facsimile Transmission Request Summary       | +------------------------------------------------------------+ File name       : test.fax (/users/menno/test.fax) File type       : ASCII - Unix text file Attachments     : None Dial Mode       : Manual Recipient 1     : 819-0533      Number only) Send when       : Off peak - if applicable Retry Scheme    : default Resolution      : Fine - 200dpi vertical

config Invoke  the "Minimum Configuration" screen. This screen allows you  to  configure the minimum data necessary to run  the  fax server.  This command is ordinarily used during  installations and upgrades.

confirm request_no Received  faxes  appear in the received queue with  "RxUnread" status  until they are acknowledged by the recipient  (owner). Received  faxes are acknowledged with this command. This  will change the status of the request to "Complete". This  command  is equivalent to the receive queue menu  option Request/Acknowledge. See also, copy and forward.

copy request_no user A  received  faxes  may be copied to another  user  with  this command.  This  will  change  the status of  this  request  to "Complete",  but  it will create a duplicate request  for  the named  user, and this new request willl appear in the received queue with the status "RxUnread". This  command  is equivalent to the receive queue menu  option Request/Copy. See also, confirm and forward.

create [type] [method] [-send] The  type argument names the document outline to be used  when creating  the  fax.  The  default outlines  shipped  with  the software are "Fax", "Letter", "Memo" and "Blank". The  method  argument names the the "dialing" method. If  this argument is not provided, the default method "Individual" will be used. The "-send" option will allow the newly created document to be sent  immediately  using UxFax. After document creation,  you will  be  asked to confirm the file name of the newly  created document,  and  then  the  facsimile  control  panel  will  be displayed so the document may be sent.

echo This command is used to quickly determine if the fax server is running.  If  the  server is running, it will respond  with  a message, or else the client will report an error.

exec glossary Execute a shell script embedded within a glossary entry of an opened glossary file. The glossary entry is named in the command argument. The glossary file must be pre-opened by the program, e.g. UxFax2.local, or it may be within a glossary file manually opened with the gopen command.

exit quit Exit the client command line interpreter.

forward request_no user A  received  faxes may be forwarded to another user with  this command.  This  will  retain  the status of  this  request  as "RxUnread",  but  the owner of the request will be changed  to that named in the command. This  command  is equivalent to the receive queue menu  option Request/Forward. See also, confirm and copy

gopen file gclose file Open or close the named glossary file. Any glossary entries within opend files are then accessible by the other commands,  exec  or run.

licence license Invoke  the software license screen. (The two spellings of the same command are allowed).

resubmit request_no recipient [ ... recipient ] [ options ] Cancel and resubmit a queued request. The request is nominated by  the  first argument. All other arguments are identical  to the "send" command arguments and option.

run report [arguments ...] [-print printer] Execute  the  named report. The report is the name of  a  file containing  a "PI" report definition. If the filename does not include  a  pathname,  it will be the name of a  file  in  the standard  directory, $Utools/fax/reports. Otherwise it  should be  an  absolute  or  relative   pathname  to  a  "PI"  report definition. Any other arguments will be passed to the report as arguments. All  reports  definitions  include a  "main()"  program  entry function. The additional command line arguments will be passed as arguments to this function.

pi  Invoke  the program interpreter in interactive mode. e.g.; faxcmd> pi pi> a=3; b=5; c=a*b; pi> ?c; 15 pi> return; faxcmd>

There are several variations on how the "send" command may be used.

faxcmd send file recipient [...] [send_options]

When sending faxes from the command line, instead of having to provide the  recipient  fax number, you can provide a search string that  will find  any  matching address records from the menu address  data  base, e.g.:

faxcmd send /tmp/test.fax "matt hamburg"

Notice  that  the name is fully enclosed in quotes. This is  necessary because the search string includes spaces. If the name did not include a  space, the quotes would not be necessary. If this search results in more  than  one  match,  all matching records would  be  displayed  as recipients.  The search may be further refined by including additional keywords, e.g.:

faxcmd send /tmp/test.fax "matt hamburg scos"

This  name matching used in the "send" command line requires that  one of  the  words in the search string is the key sort field in the  data base (the last name).

A  recipient  does  not need to be supplied if the "-scan"  option  is supplied.  In this case program will scan the named file for a number. A number is found according to rules given in the environment variable $FAX_PREFIX, or these rules may be given as an argument to the "-scan" option itself.

faxcmd send file -scan [scan_option] [send_options]

If  the "file" argument is given as a dash, the program will read  the file to be submitted from standard input. This is most useful when the faxes  are  being submitted automatically from a report  generator  or some  othe  application, or when the fax client is integrated into  an "lp" line printer spooler. In this case, the "-scan" option would most probably be used as well.

faxcmd send - recipient [send_options] < file

All transmission characteristics may be altered by options passed to the send command.

file If the file argument is a dash ("-") symbol, the file will be read from standard input, otherwise this argument will name the file or prepared document. If the file argument includes a path, the file will be prepared as a document type determined by the user's preferences. Otherwise the file may be the name of a prepared file. Prepared files are named in the "Prepared File" data base which is accessible through the menu interface.

recipient [ ... recipient ] The transmission may be sent to one or more recipients. The recipient may be either a phone number or a name alias from the "Address Data" data base, or a group ID from the "Address Group" data base, in which case the fax will be broadcast to all group members.

-attach attachment [ ... attachment ] Multiple attachments may be appended to the transmission. Each attachment is a named entry in the "Prepared File" data base.

-now The fax will be transmitted immediately, instead of off-peak.

-ok By default, the send command will require confirmation before submitting the request. With this option, faxcmd will not ask for confirmation.

-panel Invoke the full user interface "Facsimile Control Panel". This option may be supplied in place of the recipient to allow manual dialing from the control panel.

-retry retry_scheme The fax will be transmitted using the "default" retry scheme in the "Retry Scheme" data base unless another scheme is named using this option.

-std -fine Sends the file at standard resolution (100dpi) instead or file (200dpi) resolution. Default is fine.

-tmp tempfile This option is used when invoking the command directly from within another application where the document is named by the first argument (file), but a full copy of the document is kept in another temporary file. This option is used specifically when integrating faxcmd with with word-processors and other editors.

-time [ DD/MM/YY ] HH:MM  Transmission will be delayed until the nominted time (and date).

-type type  Used to specify the type of file being passed. Configured types are; The supported document types may be any one of the following; UniplexII - Uniplex (tm) WP vi - Visual Editor (ASCII) ASCII - Unix text file PCL - LaserJet print file G3 - UxFax generic fax file WP51 - Word Perfect (tm) WP PS - PostScript (requires Ghostscript) PCF - Print Control Forms Syntax PCR - Print Control Report Writer PCX - PC Paint Brush Format DCX - MSW Fax Viewer Format TIFF - Tagged Image File Format

-ref reference When faxes appear in the fax queue, the "recipient" field will ordinarily display the fax number or the last name of the recipient. But if this option is supplied with the submission, the "reference" string will be displayed instead. This is useful in automated environments, so that some reference data is displayed instead so faxes may be more readily identified in the queue. The "reference" may be any string of up to 20 characters. If the string includes a space, the argument must be enclosed in quotation marks.

-reply userid  When faxes are submitted via the LP spooler, the identity of the originating user is lost and cannot be used for return mail notification. This new command line option allows the userid to be set in the command line when sending faxes. This presents a security problem, or at least potential for fraudulent usage of the software. So this option is restricted to use by selected users only.

-scan [scan_option]  The document will be automatically scanned for a fax number according to the rules given in the scan_option, or according to the rules set in the environment variable FAX_PREFIX. This variable may be set in the custom environment of UxFax. The format of the variable and the scan_option is the same; -scan Prefix[x][y] FAX_PREFIX=Prefix[x][y] Where: Prefix is a string expected to preceed the number. x is the count of the occurence of a number. y is the mimimum number of digits. (default 6) The arguments Prefix and y are optional, and the square brackets form part of the expression. As a minimum, only the count x or the Prefix needs to be given. A phone/fax number is any string of digits which may include a single space, dash or a matched pair of brackets. The argument y nominates the minimum number of digits which will be recognised as a phone/fax number. e.g.;  Fax:[2] Find a number following the second occurence of the prefix "Fax:". [2] Find the- second occurence of a number.  [3l[4] Find the third number with at least 4 digits.  Fax:  Find the first number following the prefix "Fax:".

-base64 This option only applies when the file option is "-", indicatiing that the file is to be read from standard input. If this option is also given, the input file is BASE64 encoded.