ADVANCED SERVER CONFIGURATION

This chapter describes how to configure some of the advanced features of HylaFAX. In addition it discusses how many of the modem-specific configuration parameters work together when sending and receiving facsimile. The set of per-modem configuration parameters provides a flexible mechanism for working around many modem and system limitations. This chapter includes the following sections:

A separate chapter discusses setup and configuration of the support for transmitting messages to alpha-numeric pager terminals.

Local Identifier Support

The facsimile communication protocols include messages that identify the sending and receiving devices using a 20-character string. The T.30 facsimile protocol specifies that these strings should use only numbers, the ``+'' symbol, and space. Many fax machines and modem however are capable of accepting a wide range of ASCII characters. By default HylaFAX will use the canonical form of the local phone number for the local identity when sending or receiving facsimile. This phone number is specified with the per-modem FAXNumber configuration parameter. If the LocalIdentifier parameter is specified, however, HylaFAX will use it instead. Unlike FAXNumber which is converted to a canonical form that conforms to the T.30 specification, the value of the LocalIdentifier can be any ASCII string; for example, Beware that not all Class 2 and Class 2.0 fax modems support arbitrary ASCII local identifier strings. If you encounter problems verify your modem supports this functionality by sending the following commands (if it is a Class 2 modem): The response to the AT+FLID=? command should indicate the range of ASCII characters the modem will accept in a local identifier string.

Dial String Rules

A dial string specifies how to dial the telephone in order to reach a destination facsimile machine, or other device. This string is supplied by a user with each outbound job. User-supplied dial strings need to be processed in two ways by the HylaFAX server processes: to craft a canonical phone number for use in locating the receiver's capabilities, and to process into a form suitable for sending to a modem. In addition client applications may need to process a dial string to formulate an external form that does not include private information such as a credit card access code. Phone number canonicalization and dial string preparation are done according to dial string processing rules that are located in a file specified in the server configuration file; The generation of an externalized form for a dial string is done by rules that optionally appear in DIR_LIBDATA/dialrules on client machines (where DIR_LIBDATA is the pathname setup at the time the software is configured for compilation).

Dial string rules are an important part of HylaFAX as they permit local PTT conventions to be handled entirely on the HylaFAX server machine (e.g. the need to dial ``1'' before certain numbers but not others). Client applications are then free to use a canonical format for phone numbers that is location independent. Dial string rules combined with the ModemDialCmd also permit modem-specific idiosyncrasies such as the syntax for doing a ``flash hook'' to be handled transparently. Finally, dial string rules can be used to provide dialing aliases such as mapping ``a-zA-Z'' to the corresponding numeric codes.

Consult dialrules(4F) for detailed information.

Tagline Support

HylaFAX includes support for tag lines; a line of text imaged at the top of each outgoing facsimile page. Tag lines imaging requires the specification of: When tag lines are enabled the fax server will image a line of text across the top of each outgoing facsimile page using the specified tag line format string and font. This procedure is done on-the-fly, just like a fax machine does it. However, because the fax server has lots of information about the outbound facsimile job, the imaged tag line may be setup to display a variety of information.

A 100 dpi 18point Lucida Typewriter font from the X Window System is included in the HylaFAX distribution for use in imaging tag lines. Experiments indicate this is a reasonable font to use. You can however use an alternate font of your liking.

On Silicon Graphics systems a tag line font can be installed by converting one of the compressed font files provided with the standard X server; e.g.

To enable use of the font and imaging of the tag lines setup the TagLineFont configuration parameter:

If font files are stored on your system in an uncompressed format then you can reference the file directly using an absolute pathname. Relative pathnames must be specified with respect to the top of the spooling area. If the TagLineFont parameter references a non-existent file or a file that does not contain a valid PCF font then tag line support will be disabled and a message will be logged through syslog.

The default tag line format string is ``From %%n|%c|Page %%p of %%t'' which prints three fields containing the phone number of the server, the date and time of the outgoing job, and the page number and total pages for the job. Consult the TagLineFormat parameter description in config(4F) for information on configuring a different format string.

The tagtest(1M) program may be used to try out different tag line formats and fonts before they are configured for use by the server.

Finally, be certain the host bit order is configured to reflect the order of bits on your machine. The host bit order should be properly setup at the time the configure script is run. If the server has the wrong host bit order then tag lines will be imaged incorrectly.

Adaptive Answer Support

Adaptive answer is the ability for a modem to determine whether an incoming phone call is for data, fax, or voice use. If a modem supports a good adaptive-answering facility then it should be enabled with the ModemSetupAACmd and HylaFAX will service fax, data, or voice calls as identified by the modem and specified in the modem configuration files. For example, Beware however that for some modems adaptive-answer support works properly only when the modem is left in Class 2 or Class 2.0; this may be a problem if you want to configure the modem to ``idle in Class 0'' to avoid confusing naive programs that make use of the modem for outbound calls.

The adaptive-answer algorithm used by some modems can confuse some fax machines and/or data modems. If you do not intend to service both data and fax calls you may not want to configure adpative-answer for inbound calls.

If a modem does not support adaptive-answering, then there are several options. If the modem is a Class 1 modem, then HylaFAX provides a simple adaptive-answering strategy whereby incoming calls are first answered as if they are for a fax machine and, if that fails, then answered as if they are for a data modem. This facility is enabled by specifying something like:

in the configuration file. The above lines cause the fax server to do the following in response to an incoming phone call:
  1. Issue "AT+FCLASS=1;A" to answer the phone call in Class 1; i.e. as a fax machine (issuing CNG tones).
  2. Send TSI and DIS frames as required by the fax protocol.
  3. Wait for DCS from the caller (if it is a fax machine).
  4. Timeout waiting for DCS in 10 seconds (or whatever is specified for Class1RecvIdentTimer).
  5. Issue "ATH+FCLASS=0;A" to hangup and then re-answer the phone in Class 0; i.e. as a data modem.
This technique assumes many things about the capabilities of the modem and the local telephony service and may not work for all Class 1 modems or for all locales.

Note also that by reversing the order of the items specified in the AnswerRotary parameter you can get HylaFAX to answer first for data and then for fax. If calls are answered first as data, then you may need to constrain the timeout used to recognize a data call so that time still remains to setup a fax connection. Consult your modem manual and the ModemAnswerResponseTimeout configuration parameter.

A second facility supported by the fax server in lieu of adaptive answering is a rotary of answering techniques. The general idea is that a list of alternative ways to answer the phone is supplied and the server will rotate through the list on consecutive inbound calls until it finds one that works. For example, one might specify something like:

which would instruct the server to answer incoming calls as if they were from a fax machine until a call was received from a data modem, in which case it would then answer subsequent calls as a data modem until a non-data call was received (in which case it would go back to fax). The rotary list can have up to three items, with items being selected from one of: fax, data, voice, extern, and any (answer a call of an unknown type). The extern answering request forces an external application (the ``egetty'' program) to be invoked to deduce the type of an inbound call (and possibly handle it). The voice answering request causes a ``vgetty'' program to be invoked to handle the call. Finally, in conjunction with the rotary answer facility there is an AnswerBias parameter that can be used to specify an index into the rotary list to use after successfull calls. In the above example, this parameter can be used, to force calls to always be answered first as data by specifying: Note that the adaptive-answer and rotary answer facilities differ only in whether the rotary of answering techniques is applied to a single call or to consecutive calls.

Caller-ID Support

Caller-ID is a feature provided by phone companies whereby information about a calling party is passed to the receiver prior to answering a call. This facility is not universally available and not all modems are capable of processing the provided signals. For modems that are capable of processing caller-ID information HylaFAX provides the following support. Note that HylaFAX parses caller-ID information according to two configuration parameters, CIDName and CIDNumber, that specify how to identify a caller's name and phone number (if provided by the modem). For example, for a ZyXEL U1496 modem, the appropriate configuration parameters to use for caller-ID are: Consult config(4F) for a full description of the caller-ID-related configuration parameters.

Distinctive Ring Support

Distinctive ring is a feature provided by phone companies whereby multiple phone numbers can be directed to a single phone line with different ring patterns for each phone number. This is a simple mechanism that can be used to distinguish between incoming fax, voice, and data calls (i.e. all fax calls are directed to one number, voice to a different number, and data to a different number).

HylaFAX supports distinctive ring capabilities through the RingFax, RingData, and RingVoice modem configuration parameters. Modems that support distinctive ring send a different RING status message to the host depending on the ring pattern presented by the phone company. By setting the configuration parameters faxgetty will match the appropriate RING status message and use the information to treat the inbound call as fax, data, or voice before answering the call. For example,

Copy Quality Checking

HylaFAX will automatically check the quality of received facsimile and regenerate rows of data that have errors in them. This facility is termed copy quality checking and is only done if the modem is incapable of doing this task itself, or if the software is configured so that modem copy quality checking is disabled.

Copy quality checking is automatically done in the server for Class 1 modems. To configure copy quality checking directly in a Class 2 or Class 2.0 modem--when the modem is capable--setup the Class2CQCmd parameter for the modem. For example,

This enables copy quality checking for receiving and sets the copy quality parameters so that acceptable page quality requires that no more than 10 consecutive bad rows of data may be present and less than 5% of the rows in a page have errors in them. To disable copy quality checking in the modem use If a modem indicates that it supports copy quality checking but Class2CQCmd has not been specified then HylaFAX will note this when the modem is prepared for use.

Copy quality checking in the server (for any style of modem) is controlled by two configuration parameters: PercentGoodLines and MaxConsecutiveBadLines; see config(4F) for more information. These parameters define the criteria by which the server decides if a received page has acceptable copy quality. Pages that are deemed unacceptable are rejected and the sender is told to resend the page.

Beware that many fax machines are incapable of resending pages that have unacceptable copy quality because they do not buffer a full page image.

If you encounter problems with the copy quality checking support you can disable it by setting either the PercentGoodLines or MaxConsecutiveBadLines parameters to 0; e.g.

Note however that doing this means you may receive facsimile that are unreadable.

Continuation Cover Pages

A continuation cover page is a cover page automatically generated by HylaFAX when retransmitting an outbound job after a protocol error abnormally terminated a previous transmission. This cover page is only generated when a user-submitted cover page has already been transmitted; it is intended to identify the sending system and provide information about why the retransmit is being done. HylaFAX generates the cover page using the parameters supplied when the job was submitted. In addition it provides a comments section that identifies the transmission as a continuation of a previous job and describes why the previous attempt to transmit failed (this may be useful to the receiver).

By default HylaFAX does not enable continuation cover pages. To enable use of this feature the ContCoverPage configuration parameter must be set to the pathname of a cover sheet template file to use in generating continuation cover pages. This cover page template file is passed to the mkcover(1M) script, or to the program specified with the ContCoverCmd configuration parameter; consult the mkcover manual page for a description of this file.

Time-of-Day Usage Scheduling

HylaFAX can be configured so that outbound calls are placed only during certain hours of the day. This can optionally be configured on a per-destination basis, making it easy to reduce phone costs by processing toll calls only during the time when off-peak rates are available.

By default outbound calls are permitted at any time. To constrain calls to a particular time or range of times the TimeOfDay parameter can be setup according to the syntax specified in config(4F). This syntax is consistent with the syntax used by the UUCP software. For example, to permit outbound calls only between 9AM and 5PM local time the following might be used:

Per-destination Controls

HylaFAX supports many controls on the operation of the scheduler and related software. For example, outbound jobs may be restricted so that processing is only done at certain times of the day. All of these parameters can be specified in the configuration file used by the central HylaFAX scheduler process. Parameters specified in this way apply to all outbound jobs. It is also possible to specify these parameters on a per-destination basis using the DestControls configuration parameter. This parameter specifies the pathname of a file that holds per-destination control parameters; destctrls(4F).

Per-destination controls are especially useful for controlling which phone numbers can be called. For example, by specifying an entry of the form:

any outbound job that would cause HylaFAX to phone 911 would automatically be rejected with the submitter notified by electronic mail using the specified message.

Another useful feature of this facility is the ability to delay toll calls to off-hours so that off-peak phone rates may be used. Entries of the form:

might be used to permit calls to US area codes 415 and 510 at any time of day, but force all other calls to be done only during off hours. Note that the parameters specified in the configuration file serve as the default values to use when scheduling an outbound job. That is, if a parameter value is not obtained from the destination controls file then it is taken from any parameters specified in the configuration file. For example, if the above rules had not included the last line that matched ``.*'', then the time-of-day to use for long-distance calls would have been that specified in the configuration file (by default Any).

Automatic Truncation of Whitespace

HylaFAX can be configured to automatically discard trailing whitespace in outbound facsimile. This truncation is termed page chopping and can be setup so that it is done for every page, only the last page of each document, or not all. Page chopping is performed during document preparation and is applied to all submitted documents, no matter what format they are submitted in. By default HylaFAX will only chop the last page of a document and at least 3 inches of trailing whitespace must be present before the page will be truncated. The PageChop and PageChopThreshold configuration parameters control the page chopping support. Clients can override the defaults setup on the server for each outbound job through command line options to sendfax and client-side configuration parameters.

Modem Classes

Groups of modems can be referenced by name using a facility termed modem classes. A modem class defines a logical name for a set of modem devices on a server. This name can be used by clients in the same way that a specific modem device is used. The default modem to use for outbound jobs, ``any'', is actually just a predefined modem class. Modem classes are useful for groups that want to logically partition a set of modems on a single server.

Modem classes are defined with the ModemClass configuration parameter. Each definition specifies a name and a regular expression that identifies the set of modems that are to be included in the class. For example,

is the builtin definition for ``any''. Regular expressions are matched against device identifiers for modems that are signalled to faxq by faxmodem or faxgetty.

Modem Priorities

The HylaFAX scheduler process assigns modems to outbound jobs based on three criteria: the modem is considered ready for use, the modem is a member of the requested modem class (if any was specified), and the modem's capabilities support the requirements of the job (e.g. transmission of high-resolution 2D-encoded data). When multiple modems are present on a server machine it is also possible to force an order to the set of modems that are considered for allocation by assigning each modem a priority. This can be used, for example, to reduce the likelihood of assigning modems that are heavily used for inbound calls; e.g. near the front of a hunt group.

Modem priorities are specified using the ModemPriority configuration parameter. Priority values are integer numbers in the range 0-255 with lower values meaning higher priority.

Modem priorities are passed to the HylaFAX scheduler by the faxgetty processes or with the faxmodem program. Priorities can be dynamically changed by using the faxconfig program to send a new priority to a faxgetty process (who in turn will notify the scheduler), e.g.

or with the -u option to the faxmodem program when operating in a send-only environment. The ability to dynamically alter the priority of modems means it is easy to reconfigure modem usage based on time-of-day and traffic patterns.

Transcoding of Received Facsimile

Transcoding refers to the on-the-fly conversion of encoded data. HylaFAX supports transcoding of received facsimile so that received documents can be stored in files using an optimal compression algorithm. If the RecvDataFormat configuration parameter is set it defines the format for writing received facsimile data, one of: ``1-D MR'', ``2-D MR'', ``2-D MMR'', or ``adaptive''. An ``adaptive'' format is the default; it causes the received data to be written using the data format negotiated by the sender and receiver. Using gives the most space-efficient data format. Note that RecvDataFormat defines the encoding of the page data, not the file format: this is always TIFF.

Automatic Processing of Received Facsimile

It is desirable to deliver inbound facsimile directly to receipients. HylaFAX routes inbound facsimile through the faxrcvd(1M) shell script. This script may be tailored to use local knowledge and/or tools to route and deliver inbound facsimile. In particular, if facsimile are received from well-known senders and always directed to a specific person faxrcvd can be tailored to automatically dispatch these facsimile by electronic mail; consult the manual page for details. Services such as Direct Inward Dial (DID) are not supported because the hardware uses non-standard programming interfaces. In the future, when updated versions of the ITU facsimile protocols are supported in commercial fax modems HylaFAX will be able to use routing information provided in the protocol to do automatic delivery of inbound facsimile.

Another common request is to automatically print received facsimile as they arrive. This is easy to do by editing the faxrcvd script to use a program such as fax2ps or tiff2ps to convert the TIFF/F file and then submit the resulting PostScript; e.g.

Note that TIFFBIN is known to be the pathname of the directory where the TIFF tools have been installed (see faxsetup and the file etc/setup.cache in the spooling area).

Rejecting Junk Facsimile

By default HylaFAX will accept inbound facsimile from any caller. If the QualifyTSI configuration parameter is setup then HylaFAX will receive inbound facsimile only if the caller sends an acceptable Transmitting Subscriber Identification (TSI) string; a string that uniquely identifies who the sender is. HylaFAX determines which TSI are acceptable by using the rules given in the file specified with QualifyTSI. This mechanism provides a way to automatically reject junk facsimile. Note however that because a TSI is not authenticated in any way it is a simple matter for a caller to masquerade as an acceptable sender and bypass the access control mechanism. Consult tsi(4F) for complete details of this facility.

UUCP Lock Files

HylaFAX implements shared inbound/outbound modem usage using UUCP lock files. In normal operation each modem has a faxgetty process listening for data from the modem. When an inbound call is received the modem emits a RING status message that wakes up the appropriate faxgetty process. faxgetty then checks the UUCP lock file for the port to make sure the port is not busy for outbound use. If the port is busy (i.e. a UUCP lock file is present), then faxgetty will stop listening on the port and wait for the outbound use to terminate. If the port is not busy, then faxgetty will answer the call according to the parameters specified in the configuration file.

For this scheme to work outbound callers must install a UUCP lock file before using a modem. This lock file must be created using the same conventions understood by HylaFAX. In particular the lock file name must be consistent and the file contents must include the process ID of the lock file owner written either as a binary or ascii value according to the system-specific conventions.

HylaFAX supports several schemes found on different systems. The appropriate scheme is normally setup according to the target system at the time that HylaFAX is configured for building. It is possible, however, to override these parameters through the runtime configuration files; consult the config(4F) manual page for information about the UUCPLockType configuration parameter. In addition to the lock type there are configuration parameters that control the protection mode of the lock file (UUCPLockMode), the directory in which lock files are created (UUCPLockDir), and a timeout parameter used to purge stale lock files. Again, consult config(4F) for a full description of these parameters.

Modems that Lie about their Capabilities

Class 2 and 2.0 fax modems all too frequently have bugs in their firmware. Sometimes it is possible to workaround firmware problems by restricting a modems' capabilities. To do this the Class2DCCQueryCmd configuration parameter may be set in the per-modem configuration file. By default this parameter holds the command to send the modem to query its capabilities. However if the query string has a leading ``!'' then no command is sent to the modem and instead the remainder of the string is treated as the response returned by the modem. Thus to avoid using a particular modem capability all you need to do is setup a capabilities string that has a restricted set of modem capabilities.

Capabilities are returned using a syntax specified in the Class 2/2.0 specification:

where, Each parameter is specified as single value, range of values (e.g. 0-3), or list of values (e.g. 0,1,2). The values are given in the Class 2/2.0 specification and in the following table (note that this table does not list values defined in the latest ITU T.class2 specification):

Param Value Description Param Value Description
vr 0 98 lines/inch df 0 1-D Modified Huffman
1196 lines/inch 12-D Modified Huffman
br 0 2400 bits/sec 22-D Uncompressed Mode
14800 bits/sec 32-D Modified Modified Read
27200 bits/sec ec0disable ECM
39600 bits/sec 1enable T.30 Annex A, ECM
412200 bits/sec 2enable T.30 Annex C, half duplex
514400 bits/sec 3enable T.30 Annex C, full duplex
wd 0 1728 pixels in 215 mm bf 0 disable file transfer modes
12048 pixels in 255 mm 1select BFT, T.434
22432 pixels in 303 mm st 0 scan time/line: 0 ms/0 ms
31216 pixels in 151 mm 1scan time/line: 5 ms/5 ms
4864 pixels in 107 mm 2scan time/line: 10 ms/5 ms
ln 0 A4, 297 mm 3scan time/line: 10 ms/10 ms
1B4, 364 mm 4scan time/line: 20 ms/10 ms
2unlimited length 5scan time/line: 20 ms/20 ms
6scan time/line: 40 ms/20 ms
7scan time/line: 40 ms/40 ms

An example use of this mechanism is found in the prototype configuration file for the AT&T DataPort modem. The rev C01.66.10 firmware for the DataPort returns an invalid string for the AT+FDCC=? query command so the prototype configuration file supplies a valid one instead:

Beware of specifying that a modem has capabilities that it does not; HylaFAX is likely to try and make use of them!

Configuration Parameter Usage During Modem Setup

There are many configuration parameters that control the operation of HylaFAX in resetting and initializing a modem. This section presents these parameters and explains how they fit together in normal operation. By understanding how these parameters are used it is possible to control many aspects of the operation of HylaFAX.

In normal operation HylaFAX will first reset a modem and then prepare it for use with a setup procedure appropriate for the modem. Modem reset involves the following steps:

  1. Lower the Data Terminal Ready (DTR) signal, pause ModemResetDelay milliseconds, and then raise DTR. DTR is used to force a modem reset rather than sending a command such as ATZ to the modem because many modems can get confused and enter a state where commands sent from the host are ignored. Instead HylaFAX uses a hardware control signal to force the modem to do a reset operation. This usage requires that a modem respond to a DTR transition by resetting itself. Since modems all take different amounts of time to do a reset operation the time that HylaFAX waits for the modem to complete the reset operation is programmable. A certain Hayes Technical bulletin claims one should wait 2.6 seconds for a modem to complete a reset operation. In practice this is much longer than most modems need and this parameter can be reduced with a significant speedup in the overall setup process.
  2. Once the modem has been reset (assuming the modem monitors DTR and does the ``right thing'' in response to DTR being lowered), HylaFAX sets up the baud rate and flow control parameters for the tty device using the ModemRate and ModemFlowControl parameters.
  3. HylaFAX then flushes any data received from the modem since the reset and sends the following sequence of commands: 
    ModemResetCmds		any additional reset commands
ModemEchoOffCmd		disable modem echo of commands
ModemVerboseResultsCmd	enable verbose result codes
ModemResultCodesCmd	enable transmission of result codes
ModemNoAutoAnswerCmd	disable modem from auto-answering calls
ModemOnHookCmd		place modem ``on hook''
ModemPauseTimeCmd	configure delay for "," in dial string
ModemWaitTimeCmd	configure time to wait for carrier
modemflowcontrolcmd	establish DTE-DCE flow control scheme
ModemSetupDTRCmd	force desired modem response to DTR transition
ModemSetupDCDCmd	force desired modem response to DCD transition
    Note that these commands are sent as two separate AT commands, broken between ModemOnHookCmd and ModemPauseTimeCmd; this is done to avoid problems with certain modems.
The reset sequence must be successful for HylaFAX to consider the modem in an acceptable state and to proceed with the subsequent steps:
  1. Query the modem using ModemClassQueryCmd to verify it supports the functionality specified by the ModemType (this parameter can be used to control which class to use when a modem supports multiple classes).
  2. Set the modem into the appropriate class using ClassXCmd, where X is one of 0, 1, or 2, depending on the application.
  3. Identify the manufacturer, model, and firmware revision information using ModemMfrQueryCmd, ModemModelQueryCmd, and ModemRevQueryCmd parameters. This information is obtained early in the setup procedure in case special-case handling is required for the modem. Note also that for Class 1 modems it is typically not possible to query the modem for some of this information and it must instead be ``hard-coded'' in the prototype modem configuration file that is selected according to the product ID code returned by the ATI0 command.
  4. Identify the modem capabilities using the ModemDCCQueryCmd for Class 2/2.0 modems, or according to the capabilities of the Class 1 driver and the result of AT+FTM=? and AT+FRM=? commands for Class 1 modems.
  5. For Class 2/2.0 modems: establish whether the modem supports copy-quality checking and polled retrieval of documents; both these capabilities are automatically provided by the driver for Class 1 modems. If the modem supports copy quality checking, according to the result of the Class2CQQueryCmd and copy-quality setup commands are provided with the Class2CQCmd parameter, then the modem is setup accordingly.
Modem initialization is then carried out by sending the following commands to the modem:

- Class 2/2.0 modems:
Class2Cmd force the modem into Class 2/2.0
class2FlowControlCmd establish DTE-DCE flow control scheme
Class2TBCCmd select stream modem host-modem communication
Class2BORCmd set the bit order for HDLC and page data
Class2PHCTOCmd set the timeout during page transfer (Phase C)
Class2CQCmd enable copy quality checking
Class2NRCmd enable negotiation reporting (Class 2.0 only)
Class2PIECmd disable program interrupt handling (Class 2.0 only)
Class2BUGCmd enable HDLC frame reporting if requested
Class2DCCCmd initialize modem capabilities
Class2RELCmd+ enable reception of byte-aligned EOL codes
Class2CRCmd+ enable facsimile reception
Class2LIDCmd+ set local station identifier
ModemSetupAACmd+ enable adaptive-answer support

- Class 1 modems:
Class1Cmd force the modem into Class 1
class1FlowControlCmd establish DTE-DCE flow control scheme
ModemSetupAACmd enable adaptive-answer support

(Commands marked with a ``+'' are optional and sent to the modem only if it is to be setup to receive calls.)

Flow control is explicitly set separately for Class 0 (data) operation and Class 1, 2, 2.0 (fax) operation. To configure the use of a different flow control scheme in each class simply override the default definition of the ClassXCmd parameter; e.g.

Note however that this will only work for outbound usage; doing something similar for inbound processing is more complicated because the modem, rather than the host, decides when to switch between Class 0 and Class 1, 2, 2.0. Consequently HylaFAX must react to events rather than initiate them. This work is also complicated by the fact that many modems do not accept commands (or are confused by commands) from the host during certain critical sections of inbound call processing.

Modem Parameter Usage for Outbound Calls

An outbound facsimile job is broken up into phases that correspond roughly to the phases defined in the CCITT T.30 facsimile protocol: The last three phases may be repeated multiple times depending on the number and characteristics of the facsimile being transmitted.

To send a facsimile a phone call must be placed. HylaFAX takes the following actions:

  1. Lock the modem.
  2. Initialize the modem for outbound facsimile use.
  3. Instruct the modem to place the phone call.
The corresponding set of commands sent to the modem are:

- Class 2/2.0 modems:
Class2Cmd force the modem into Class 2/2.0
class2FlowControlCmd establish DTE-DCE flow control scheme
Class2TBCCmd select stream modem host-modem communication
Class2BORCmd set the bit order for HDLC and page data
Class2PHCTOCmd set the timeout during page transfer (Phase C)
Class2CQCmd enable copy quality checking
Class2NRCmd enable negotiation reporting (Class 2.0 only)
Class2PIECmd disable program interrupt handling (Class 2.0 only)
Class2BUGCmd enable HDLC frame reporting if requested
Class2DCCCmd initialize modem capabilities
Class2LIDCmd set local station identifier
Class2SPLCmd request polling status (if a polled receive is to be done)
Class2DDISCmd setup initial session parameters (optional)
ModemDialCmd place the call

- Class 1 modems:
Class1Cmd force the modem into Class 1
class1FlowControlCmd establish DTE-DCE flow control scheme
ModemDialCmd place the call

Note that the modem is always switched into the appropriate class and flow control scheme before placing the call. For Class 2 modems that do not properly implement the AT+FDIS command the Class2DDISCmd parameter must be configured so that HylaFAX will setup initial session parameters before placing the phone call.

If the call completes and a facsimile transmit session is started then HylaFAX will send ModemSendBeginCmd to the modem. This parameter can be used to enable servicing that must be done only while Carrier Detect (CD) is asserted to the host. For example, on Sun systems it is not possible to enable RTS/CTS flow control on serial ports implemented with the ZS8530 unless CD is asserted; to workaround this problem for outbound calls one can use:

to force HylaFAX to enable RTS/CTS flow control on the host tty device after carrier is established. Beware however that some modems raise and lower CD during Class 1 operation and this can cause problems for systems with restrictions of this sort.

The next phase in the processing of an outbound job is the selection of station capabilities. The receiver is required to transmit a series of messages that provide its identity and capabilities (e.g. whether it can accept 2D-encoded facsimile data). HylaFAX examines the received capabilities and compares them to the capabilities required for the job. If the receiver is capable of accepting the documents to be sent then HylaFAX proceeds with the transmission. Otherwise HylaFAX will disconnect and, either re-prepare the outbound documents according to the receiver's capabilities or reject the job because it cannot be sent.

Page transfer requires the selection of session capabilities that correspond to the page to be transferred and the actual transfer of the page data to the modem. HylaFAX handles documents with varying page characteristics. In particular this means that documents with a mixture of high res and low res data (e.g. a low res cover page followed by high res image or text) are handled transparently.

For Class 2 modems session parameters are set using the Class2DISCmd (note that this is not the same as Class2DDISCmd). If the negotiated session parameter needs to be changed then this command will be sent to the modem. The Class 2 specification requires that a modem accept this command at any time prior to an AT+FDT command. However because some modems do not properly implement this part of the specification the Class2DDISCmd is provided to workaround modem limitations. Beware however that modems that require Class2DDISCmd may not be capable of renegotiating session parameters at all; this can be an annoying problem.

For Class 2/2.0 modems, page data is transferred using the AT+FDT command. This command instructs the modem that a page of facsimile data will follow. The modem is released to negotiate session parameters (as needed) and HylaFAX then waits for a response that indicates page data may be transferred to the modem. Class 2 modems indicate they are ready for page data by sending CONNECT followed by XON (DC1) to the host. (The ModemWaitForXON configuration parameter controls whether or not HylaFAX should wait for XON because some Class 2 modems do not follow this aspect of the spec.) Class 2.0 modems indicate they are ready for page data by sending a CONNECT response to the host (but no XON). Class 2 modems return OK to the host when they have accepted all the page data. Class 2.0 modems do not return OK.

After a page of data has been transferred to the modem HylaFAX indicates whether this is the last page to be sent and/or whether more documents are to come. A post-page message is then sent and a post-page response is awaited. Class 2/2.0 modems handle this exchange entirely within the modem. For Class 1 modems HylaFAX implements this part of the protocol on the host: the post-page message may be retransmitted as many as three times. A post-page response indicates whether a page was successfully received and/or whether or not the receiver wants to resynchronize the line due to a perceived loss in signal quality. HylaFAX is capable of retransmitting pages that a receiver deems unacceptable. HylaFAX will automatically retransmit a page up to three times if it does not receive a positive acknowledgement from the receiver.

Modem Parameter Usage for Inbound Calls

Inbound call handling is the most complicated part of the HylaFAX software. This is because modems vary so widely in the way they process inbound calls for fax, data, and voice use. Also, inbound calls typically require that a modem be configured before a call is received and many modems do not accept commands from the host until after a call has been recognized, accepted, and processing initiated.

HylaFAX handles inbound calls in the faxgetty program. The modem is initialized as described above and faxgetty then waits for a ring status message from the modem. On receiving input from the modem the following processing takes place:

  1. The modem is locked. If the modem cannot be locked because there is an outbound user in control of the modem then it is released and faxgetty will wait for the lock file to be removed.
  2. Wait for RingsBeforeAnswer rings, waiting at most 5 seconds for each ring status message. If distinctive ring support is configured (RingFax, RingData, and RingVoice) then the ring status messages are checked and the type of call is potentially deduced. If Caller-ID support is configured (CIDName and CIDNumber), then any Caller-ID information returned by the modem is parsed.
  3. If the appropriate number of rings was not received, then the line is hung up and the modem is reset and initialized.
  4. Check any Caller-ID information. If QualifyCID is configured and the caller is not acceptable, then reset and initialize the modem.
  5. If the call type is already known from distinctive ring information, then the call is processed immediately. If faxgetty was instructed to answer any type of call, then the call is answered as appropriate. However, if a particular type of call was to be processed (e.g. data) and the deduced type of call does not match, then the call is rejected and the modem is reset and initialized.
  6. If the call type is unknown then the call is answered according to the the current type specified by AnswerRotary and AnswerRotor.
  7. If the call is not successfully answered and if AdaptiveAnswer is enabled, the next item in the AnswerRotary list is used to immediately re-answer the call. This is repeated until a call is successfully answered or the list of choices in AnswerRotary is exhausted.
Call answering is done as follows:
  1. Send the modem one of ModemAnswerDataCmd, ModemAnswerFaxCmd, and ModemAnswerVoiceCmd according to whether the call is to be answered as data, fax, or voice, respectively. If any of these are not set then ModemAnswerCmd is used instead.
  2. Wait for a response from the modem that signifies carrier has been established and which identifies the type of call. The exact set of responses is given in config(4F).
  3. If ModemWaitForConnect is enabled, then HylaFAX will read responses from the modem until a CONNECT response is sent to the host or an error is detected; e.g.
  4. If a call is successfully answered, then one of ModemAnswerDataBeginCmd, ModemAnswerFaxBeginCmd, and ModemAnswerVoiceBeginCmd, is sent to the modem according to the call type deduced above. This mechanism is useful for modems that automatically change DTE-DCE communication to a fixed line speed or flow control setting for inbound facsimile calls.
At this point the call has been answered, carrier established, and the call type is known. For a data or voice call faxgetty forks and execs the appropriate program. The UUCP lock file is setup so that it is owned by the child (important for SLIP and PPP) and the parent handles cleanup of various resources when the child process terminates.

For fax operation faxgetty drops into the facsimile receive protocol.

More to be added.

How to operate a HylaFAX server. HylaFAX table of contents.

Sam Leffler / sam@engr.sgi.com. Last updated $Date: 1996/08/16 21:03:37 $.