In alphabetical order, so none of them can object, I extend thanks and credit to:
• Henry Coleman of Coleman Custom Software (FAXMAN)
• B.J.Guillot (communications)
• Joseph Puglielli of Crandell Group (fax groupIII conversions)
• Bill Vick of Lamar Computers (research and 32-bit coding)

Copyright Notices
• A fully featured fax facility for TSX32, FAX32 © 1994 Computer Advocacy Inc, North York, Ontario Canada as described in this manual. All rights reserved.
• PCL 5 Conversion Software © 1991-1994 Crandell Group Inc., Santa Barbara, California USA. All rights reserved.
• BGFAX © 1993 B.J. Guillot, Houston Texas USA. All rights reserved.

What is FAX32?

FAX32 is a TSX32 facility for sending and receiving faxes through fax modems. Modems may be shared for both data and fax purposes, for dialing in and dialing out. Multiple concurrent out-bound fax modems are supported. The system has tie-ins to SMTP email and TSX-Online.

In its sending process, FAX32 translates messages consisting of ASCII text and PCL tokens into Group III fax format. Using Adobe typeface fonts and a simulated PCL5 HP LaserJet Series III printer, a fax-format rendition of that message is created. This image then transmitted through a Class 2 or 2.0 fax modem.

FAX32 may be invoked in several ways:
• by using a standard TSX32 command-line interface.
• via any language with "spawn" capabilities can launch FAX32.
• by placing a file in the AUTOFAX directory with an embedded FAX32 command
• by a user sending an email message
• by the system receiving an email message

Regardless of the technique used, all the work happens in the background, so interactive jobs proceed unimpeded. Here are some examples of the command line interface:

A full description of all the command line parameters is included in this document.

TOC The Receiving Process

The receiving process stores fax images on disk for viewing and optional printing to HP-LaserJetII (PCL4 compatible) or HP-LaserJetIII (PCL5 compatible) printers.

FAX32's installation may be run in either DOS or TSX32.
• PKUNZIP the distribution into an empty temporary directory.
• From that directory:
•     Under DOS, type INSTALL
•     Under TSX, type RUN INSTALL

The installation procedure consists of:
• Install FAX32 which prompts you for a directory (typically C:\FAX32SYS) into which FAX32 files will be copied.
• Configure FAX32 which taylors FAX32 for your specific needs. Included here is an option to add one line to your LSTARTUP.CMD file (the one that TSX runs whenever your system is started). This will cause FAX32's startup file FAXSY:FAXSTART.CMD to be executed whenever TSX starts up. Execution of FAXSY:FAXSTART is critical: it serves to set various system symbol & logical assignments, to set various program parameters and (optionally) to start the detached FAXWAIT job.
• Review RELEASE.TXT allows you to browse the release notes file. This file documents changes and issues that have been made to FAX32 (This is a standard text file.)

Should you subsequently need to make configuration alterations, change directory (CD) into the FAXSY: directory and issue the command SETUP.

TOC Permanent Installation

When FAX32 is installed, it operates in Demonstration Mode until a Permanent Installation is done.

The two modes are identical except for the fact that, in Demo Mode:
• Every outbound fax has a message superimpossed on top of it.
• The /PCX command line option is not available.
• The inbound FAXWAIT processor broadcasts periodic messages.

To convert your Initial Installation to a Permanent Installation:
• Insure that other users are not currently faxing
  
• If FAXWAIT is running, issue the command STOP/PROGRAM=FAXWAIT
  Issue the command: FAX /INSTALL
  FAX32/INSTALL always displays an Installation Code which is valid until next Saturday. It then prompts you for a Response Key. Response Keys are given to fully paid installation sites by contacting Computer Advocacy Inc or your supplier.

TOC Sending faxes from the TSX prompt

The FAX command causes an outbound fax job to be batch queued for processing. This is the "command line" method for initiating a fax.

The process may begin immediately or at some future time that you indicate. In either case, the command-line process exits immediately after parsing and scheduling your job.

The SHOW EVENT command may be used to view the status of fax jobs that have finished or are currently executing.

The SHOW BATCH command may be used to view pending fax jobs.

When your fax job completes, your terminal will beep several times. A rhythmic pattern indicates the fax was successfully transmitted. A constant pattern indicates transmission failure.

Command Syntax
        FAX[/qualifiers] input_file [/qualifiers]
Parameters
        input_file is the name of a file to be faxed.
        The format of this file must be one of the following:
               - Standard ASCII text file
               - A PCL4 or PCL5 file
               - A file that was previously converted to fax format

If input_file is not already in rasterized fax format, it will be converted. By default, the converted file is given the same name but is placed in directory FAXOUT: and is deleted when the fax completes. Qualifiers
Qualifiers are of the form:
        /XXX for qualifiers that do not require a value or
        /XXX=YYY for qualifiers that require a value
where XXX is a qualifier and YYY is its value

The minimal command necessary to cause a fax to be sent would be:
        FAX filename /PHONE=phone_number

Qualifiers may be specified in any order. Non-ambiguous short forms are allowed. Where a qualifier value is to contain spaces, the entire string must be enclosed in double quotation marks.

The following is a list of all FAX qualifiers.

/AFTER and /DELAY	represent when the fax is to be sent. If neither is specified, the implication is Send it now.
/AFTER=date-time	is optional. It indicates a precise date and/or time when the fax is to be sent. The format for date-time complies with standard TSX32 date specifications: dd-mmm-yyy:hh:mm[AM/PM] where dd is the day of the month, mmm is the first three letters of the name of the month, yyyy is the year (if only two digits are specified and the value is greater than or equal to 80, 1900 is added; if a value is specified that is less than 80, 2000 is added), hh is the hour of the day, mm is the minute of the hour. AM or PM may be specified after the time if you prefer to use a 12 hour designation. If the date portion of a date-time value is omitted, today is assumed. If the time portion is omitted, the beginning of the day (00:00) is assumed. Also note that the word TOMORROW can be used as a date-time value     /AFTER=TOMORROW implies tomorrow at 00:00     /AFTER="TOMORROW+3" implies tomorrow at 03:00 (quotes important)
/DELAY=time	is optional. It indicates when the fax is to be sent as "how long from now". The "time" portion of this date-time qualifier is added to the current date and time to internally construct a /AFTER qualifier.
/DELETE> and /NODELETE	are optional. They indicate the disposition of the output rasterize file after the fax has been sent. (It is this rasterized file that actually gets sent.) If not specified, /DELETE is assumed. It is reasonable to specify /NODELETE if you intend to send the same fax again and wish to save on the processing time necessary to convert the input file to an output file. See also /OUTPUT
/EVENT and /NOEVENT	cause, respectively, the enabling or disabling of an event log called FAXOUT. If one of these switches are specified, all other parameters and qualifiers areignored. By default, FAX32 sets up an event log of 20 records. You can change this by specifically declaring the size of the event log by saying something like:         FAX /EVENT=35 Use the SHOW EVENT command to monitor the disposition of outbound faxes. Use the SHOW BATCH command to review the status of pending faxes.
/FINE	is optional. It causes your input_file to be processed with double resolution: approximately 200x200 dots to the inch. By default, the resolution is 200x100. To put this in perspective, note that the resolution on a laser printer is typically 300x300 dpi. A /FINE resolution is more pleasing to the eye but typically takes twice as long to transmit.
/FROM="string"	is optional. It pertains to the banner that appears on the top of each page. We recommend that you enclose string in double quotes. If you do not specify /FROM=string, the "From" portion of the banner indicates only your "fax identification" (See FLID in Installation) If you specify /FROM=string, the "From" portion of the banner consists of string followed by "@" followed by your fax identification.
/JOB=jobnumber	is optional. If specified, FAX32 "pretends" that the fax was requested by this Job ID.
/MANPCX=pcxfilspc	is optional. This switch allows you to use a PCX file as a "background" page applicable only on those pages where your input_file contains the PCL command requesting a manual paper feed. The PCL escape sequence for "feed paper from manual tray" is        <ESC> & l 2 H (spaces inserted for clarity; 3rd character is a lower case L). Pcxfilspc must be a full file specification and the extension must be .PCX If, for example, your input_file contained this escape sequence at its start, the effect would be that pcxfilspc would be a "cover page". (See also /PCX and Subsidiary File Merging below.)
/MODEMS=string	is optional. This switch allows you select a subset of modem pool for purposes of this fax only. String should be enclosed in double quotes.         Eg:/MODEMS="TTB0:/CTS"
/OUTPUT=outfile	is optional. It indicates a precise file specification that is to be used for the output rasterized file constructed on the basis of your input_file. If not specified, the raster output is given the same name but is placed in logical directory FAXOUT: NOTE: There must exist a directory with a logical assignment for FAXOUT even if you do not use it.
/PCX=pcxfilspc	is optional. This switch allows you to use a PCX file as a "background" page applicable to all pages. Pcxfilspc must be a full file specification and the extension must be ".PCX" This facility might be used to cause every page to appear on "preprinted" letterhead. (See also /MANPCX and Subsidiary File Merging)
/PHONE=string	is optional. It is the number to dial. If not specified, no dialing occurs.
/PREFIX=string	is optional. If /PREFIX=string is specified, the characters contained in are pre-pended to the phone number. If /PREFIX is specified but no explicit string is provided, the value of the symbol called FAX$PREFIX is used. Typical uses for /PREFIX are:      your PBX requires a special number to get an outside line EG: /PREFIX=9,      your long distance carrier requires a special account code
/RETRY=number	is optional. The default for this value is contained in the value for the system symbol FAX$RETRY. That value is typically set in the file FAXSY:FAXSTART.CMD The value of RETRY indicates the total number of times to try a phone number before giving up. A busy signal results in a 1 minute delay before a retry is attempted. Note that, if a connection failure occurs for any reason, other than a busy signal, only one additional retry attempt will be made.
/SETUP[=srf_filnam]	is optional and represents FAX32's handling of setup/reset files. /SETUP=srf_filnam causes srf_filnam to be entirely merged before input_file (setup) and at each point where a PCL "reset" sequence <ESC>E is encounterd. /NOSETUP bypasses any setup/reset processing. If neither /SETUP nor /NOSETUP is specified, FAX32 does setup/reset processing using the default setup/reset file. The default setup/reset file name is:       either: the value defined in symbol FAX$SETUP       or: DEFAULT.SRF if FAX$SETUP is undefined. If srf_filnam does not contain a file extension, .SRF is assumed. All setup/reset files must reside in FAXSY: Do not specify a device or directory as part of srf_filnam. Examples: /SET=myset use FAXSY:MYSET.SRF (unspecified) use FAXSY:DEFAULT.SRF if FAX$SETUP is undefined (unspecified) use FAXSY:NORMAL.SRF if FAX$SETUP contains "NORMAL" /NOSETUP No setup/reset processing Note! Do not put <ESC>E in a setup/reset file! This would cause infinite recursion! Note As distributed, DEFAULT.SRF contains the PCL command to set 66 lines per page. Note! If you intend on using a setup/reset file as a cover page, you must insure that your input-file does not contain any <ESC>E reset commands. The setup/reset file is merged both at your input-file's start AND whenever <ESC>E is encountered.
/SHORT	is optional. If specified, transmission time is minimized by forcing each page to be as short as possible.
/TO=string	is optional. It pertains to the banner that appears on the top of each page. We recommend that you enclose string in double quotes. If you do not specify /TO=string, the "To" portion of the banner indicates only the number you are dialing as specified by /PHONE. If you specify /TO=string, the "To" portion of the banner consists of string followed by "@" followed by the phone number you are dialing as specified by /PHONE
/TT=ttname:	is optional. If this switch is specified and the /JOB switch is not specified, FAX32 "pretends" that the fax was requested by terminal ttname:         Example: /TT=TTA0:
/VERSION	causes FAX32 to display its version number and then stop.

The FAX32 engine supports an input_file consisting of ASCII text and PCL tokens. It creates a rasterized graphics image of this file by simulating a PCL5 HP LaserJet printer "out of the box".

To the extent that you need to modify your "simulated LaserJet", the /SETUP qualifier (see above) is provided to allow you to taylor that environment by specifying PCL tokens that define such things as initial font, paper type, lines per page, margins etc.

In addition to normal PCL tokens, special FAX32 tokens allow merging of entire PCL and/or PCX files into the input stream at the point where these tokens are encountered.

A PCX file may be merged as part of the input stream of characters found in input_file by inserting a token with the following syntax:

        "+PCX position : pcxfilspc"
(spaces for clarity only)

"+PCX	is a double quote followed by a plus sign followed by the 3 characters PCX
position	is a single letter that indicates the image's desired position         L for Left         R for Right         C for Centre         T for Top-Centre         H for Here
:	is a colon
pcxfilspc	is the full file specification of the PCX file. Its extension must be PCX You may use single-colour PCX files less than 1728 pixels wide.
"	is the closing double quote

For example, input_file might be a letter that is to contain a signature. At an appropriate place, it would contain:

Yours Truly,"+PCXH:c:\pcxfiles\signatur.pcx" See also /PCX and /MANPCX above which are qualifier switches placed on the command line as opposed to this discussion of PCX merge tokens which are imbedded in the input_file.

A PCL file may be merged as part of the input stream of characters found in input_file by inserting a token in it with the following syntax:
        <esc> + pclfilspc (spaces for clarity only)
where

<esc>	is an escape character (Hex 1B) (Decimal 27)
+	is a plus sign
pclfilspc	is a full file specification. The extension must be .PCL

See also the /SETUP above which is a qualifier switch placed on the command line as opposed to this discussion of PCL merge tokens which are imbedded in input_file.

AUTOFAX is a facility that periodically scans all files in a predetermined directory. Files in this directory that include an embedded FAX command are faxed automatically.

The logical AUTOFAX: must point to a directory that is uniquely used by AUTOFAX. In other words, don't put anything in the AUTOFAX: directory other than faxable files.

The embedded fax command sequence must occur within the last 2,048 bytes of the file.

The sequence of characters representing the fax command must precisely follow the following specification:

• /switches... represents the one or more FAX32 command line switches.
• There is no filename specified in the embedded command.
• The sequence begins with two left-square brackets immediately followed by the upper case string FAX
• The sequence ends with two right-square brackets.

AUTOFAX periodically scans the directory whose logical name is AUTOFAX: Files in this directory that meet the syntax specification described above are processed as follows:
• The fax command is extracted from the file.
• The characters that comprise the embedded fax command (including the "[[" and "]]") are replaced with nulls.
• The file is renamed as AUTOFAX:\GOOD\fax####.$$$ where #### is a number.
• The extracted FAX32 command is executed upon the new file in AUTOFAX:\GOOD\
• Error messages are written to the FAXOUT event log.

The embedded fax command may contain a specific indicator of who is to be notified when the fax is sent. (See /JOB and /TT). Alternatively, if the filename "looks" like the name of a terminal (for example: AUTOFAX:TTD7.PCL>/TT>) then that terminal (in this example, TTD7) will be notified.

Files in the >TT>AUTOFAX: directory that do not meet the syntax specification described above are moved to AUTOFAX:\BAD\fax####.$$$

The renaming technique insures that files less than 2 weeks old will not be overwritten.

A macro written for W/P 5.1 called FAX32.WPM is included with your distribution. It should be copied to your WP macro directory. If you name it ALTF.WPM, it is invoked by simply pressing ALT-F.

This macro prompts the Word Perfect operator for the most common FAX32 qualifier switches and then invokes the Word Perfect print function.

In order to use this macro, you must define a "printer" suitable for FAX32. Its definition must be based on PCL4 (eg: HPLaserJet II) or PCL5 (eg: HPLaserJet III) printer.

This "printer" must be "named" FAX32.   IE:
    For "1 Name" specify FAX32

     For "2 Port" specify "8 Other" and Word Perfect will then prompt you for a "Filename or Device". Respond with a file-specification or (better) a logical that translates to a file-specification which is in the AUTOFAX directory.

The recommended technique (which also avoids simultaneous filename collisions) is to use a logical like:
     2 Port   FAXFILE:
Each user should have a different FAXFILE definition that translates to a file name in the AUTOFAX directory. This can be accomplished by editting the TSX startup file (typically SY:START.CMD is used for all lines) that is assigned to the user's line. Edit that file to include something like ...
   x:=$jobinfo("ttname")
   assign AUTOFAX:$eval(x[1:$length(x)-1]).PCL FAXFILE:
... When a user logs on, this rather cryptic expression will assign a value to FAXFILE that will reflect his particular terminal. For example, the user who is on TTD7: will have a unique definition of FAXFILE which will be AUTOFAX:TTD7.PCL

There's a good reason making this file name look like the name of a terminal. AUTOFAX does not know from which terminal a fax request was originated. This makes it difficult to know who to notify later. However, if the file name (in this example, TTD7) looks the a terminal name, then that terminal will be notified with a beep pattern indicating the success or failure of the fax.

The macro embeds the FAX32 AUTOFAX command in such a way that the command will be seen by AUTOFAX but will not appear on paper if you choose to print the document to a LaserJet.

FAXMAN is the FAX32 Inbound Fax Manager. It allows you to peruse a listing of faxes received, to print them or delete them. If the terminal you run FAXMAN from appears to TSX as a "console device" (eg: Maxstation, VGA console), you have the additional option of being able to view fax documents on your screen.

To run FAXMAN, type (as you might have guessed) FAXMAN

The first consideration to be made for receiving faxes (assuming you want to receive faxes at all) is when they should be printed.

Do you want incoming faxes to be queued for printing as soon as they arrive? You'll be able to see your faxes sooner this way.

Perhaps you get a lot of "junk faxes" that you'd rather not have printed. Your alternative is to "not print now". Using FAXMAN you can select only those faxes that you wish printed. If you're running from a graphics-capable station, you can view your faxes on-screen as well as choosing to print or not print them.

You originally make a choice during the Installation dialogue. You can change it by using SETUP which takes affect the next time FAXSTART.CMD gets run. You can change it immediately by typing

either:	FAX$PRINTNOW:===0	(disable immediate printing)
or:	FAX$PRINTNOW:===1	(to enable immediate printing)

The View option is only made available when FAXMAN is running on a graphics capable screen. When the Fax appears, you may press:

+ (plus sign)	to enlarge the image
- (minus sign)	to shrink the image
PgDn	for next page
PgUp	for previous page
ESC	to end the view

FAX32 keeps EVENT logs on outbound (FAXOUT) and inbound (FAXIN) activities. SMTP2FAX also writes to an event of that same name. In debug mode, additional events are written to the FAXDEBUG event. Event logs are viewed using standard TSX procedures.

The command SHOW EVENT is a general purpose event utility.
You may also use EVENT FAXIN or EVENT FAXOUT to monitor events to your screen or to some other output destination using EVENT/OUTPUT=filspc. See your TSX documentation for more information on event logs.

There is also a permanent file called FAXOUT:SUMMARY.LOG. One line gets added to this file for each out-bound fax.

The command file FAXSY:FAXSTART.CMD sets up a number of system symbol and logical assignments. It is one of several files created during the installation process and updated should you change directory into FAXSY: and run SETUP to modify your configuration.

SMTP2FAX represents one of the two components that facilate FAX32's "Email-to-Fax" capabilities. Its responsibilities are to handle incoming SMTP mail and, where appropriate, convert those mail messages to faxes. (See also "BBS2FAX" which describes FAX32's integration with outgoing email.)

As part of the regular incoming SMTPTOSS email job stream, SMTP2FAX quickly scans the top portion of each email message and determines if it is fax-mail or e-mail or both.
• If it's only an ordinary email message, it's left alone
• If it's only a fax email message, it's massaged and moved elsewhere for subsequent fax processing. SMTPTOSS (the regular email processor) will never see it.
• If it has multiple recipients, some of whom require faxing, it's massaged and copied to the fax processing directory. A version of it (with fax recipients removed) is left for SMTPTOSS to process in the usual manner.

How does it know?

Basically, when SMTP2FAX sees a recipient address which is numeric as in 5551212@abc.com it recognizes that "recipient" as a fax telephone number.

Using TSX-Online's "Forwarding address" you can arrange for users to always get their incoming Email faxed to them. Make sure that the "Forwarding type" is "Internet" and "Forwarding address" is #######@your-domain-name (where #### is fax number to be dialed).

With such a wide open and automated way of converting email messages to faxes, you'll want to be careful. Afterall, it's your phone that will be sending those faxes; they'll be showing up on your phone bill. You'll want some rules to determine which calls you're willing to make.

BBS:SMTP2FAX.CON is the configuration file where several types of rules are established which govern the actions taken by SMTP2FAX. When an email message arrives on your system with a recipient called who@domain.com,
• ACCEPT rules tell SMTP2FAX whether or not domain is a domain name for which it should consider who
• PASS/FAIL rules determine if who is allowable
• PREFIX rules define telephone number prefixes to be applied to who

By default, SMTP2FAX will consider mail addressed to recipients in your primary domain name and ignores all others. You can use "ACCEPT" rules to specify other domain names that SMTP2FAX should also consider. SMTP2FAX will ignore EMail messages where the "To"-domain is not in its "acceptable domains" list.

Accept rules are of the form:
     ACCEPT domain-name
Here is an example of some ACCEPT rules in our BBS:SMTP2FAX.CON Note that it is not necesary for us to "Accept ComputerAdvocacy.com" since ComputerAdvocacy.com is our primary domain name.
     ACCEPT advocacy.com
     ACCEPT electro.ca

Pass/Fail rules allow certain who phone numbers to be specifically allowed or disallowed.

As soon as the first Pass or Fail rule which is applicable to the who phone number is found, that rule determines whether or not this fax is or is not allowable and no further Pass/Fail rules are considered. Thus, the ordering of your Pass/Fail rules is significant.

If the matching rule was a "Pass", it is allowable.

If the matching rule was a "Fail", it is not.

Pass/Fail rules are of the form:
     PASS <pattern>
     and FAIL <pattern>

where <pattern> may be any string of zero or more digits for which an exact match is required. The special character * (asterisk) matches zero or more occurrences of anything.

Thus "1*" matches any phone number that begins with "1"

Here is an example of some Pass/Fail rules.

          Pass 14167391862  # Long distance to Alan is ok
          Fail 911          # Fail this specific number
          Fail 1*           # Fail any number beginning "1"
          Fail 0*           # Fail any number beginning "0"
          Pass *            # All other numbers are ok

You may wish to apply prefixes to some telephone numbers. For example, you wish to re-route certain numbers to alternate long distance carriers by prefixing the number with another sequence of digits.
Prefix rules are of the form:
     PREFIX <pattern> digits

where <pattern> may be any string of zero or more digits for which an exact match is required. The special character * (asterisk) matches zero or more occurrences of anything.

Thus "1*" matches any phone number that begins with "1"

Here is an example of some PREFIX rules. In this example, we want all numbers that begin with "418" to go through a carrier that we indicate by dialing "555-1212,5678," before we dial that number. For numbers that are not like this, we want to dial "9" as a prefix.
  PREFIX 418* 555-1212,5678,
  PREFIX * 9

As soon as a Prefix rule whose pattern matches the tentative phone number is found, that prefix is applied and no further prefix rules will be considered. Thus, the order of your individual prefix rules is significant.

For security purposes, neither the sender nor the receiver is informed of any prefix that you have applied.

You must be using AUTOFAX

In the sysop's Scheduling for Incoming SMTP mail, change the "Program:" to BBSBIN:SMTPTOSS.CMD and create BBSBIN:SMTPTOSS.CMD to contain:
      tpr bbsbin:smtp2fax
      run bbsbin:smtptoss.exp

This causes SMTP2FAX.TPR to be run immediately before SMTPTOSS.EXP is run. SMTP2FAX may modify or remove files before SMTPTOSS.EXP has a look at them.

TSX's program SMTPS.EXP deposits raw email messages in directory BBS:SMTPIN. Massaged versions of these .SIN files may be written to the AUTOFAX directory with an embedded FAX32 encoded command. The original .SIN file may or may not be removed from the SMTPIN directory.

An EMail message recipient is recogized as a fax if all characters preceding the first "." or "@" are numeric eg: 555-1212@mydomain.com and if "mydomain.com" is in its acceptable domains list.

SMTP2FAX may be caused to write verbose messages to the SMTP2FAX event by setting the symbol FAX$DEBUG:===1

Switch qualifiers may also be specified by placing their names after the phone number but before the "@" as
     555-1212.switch.switch@mydomain.com

The following optional switch qualifiers are supported

fine	causes the fax to be sent with fine resolution
notify	causes an email message to ALWAYS be sent back to the originator indicating the success or failure of the fax delivery. Note that a send failure will result in a notification message being sent back to the originator regardless of whether or not "notify" was specified.
{xxx}	causes the fax header to indicate "To xxx"

Examples:

    555-1212.fine@mydomain.com                use fine resolution
    5551212.notify@mydomain.com               send confirmation
    5551212.{ALAN}@mydomain.com               set "To"; to "ALAN"
    555-1212.fine.notify.{ALAN}@mydomain.com  all of the above

SMTP2FAX - scans all .SIN files (ie: Email messages) and examines the list of intended recipients

• If none of the recipients represent faxes the .SIN file is ignored.
• For each recipient which is a fax number, that number is filtered through the Pass/Fail rules for an Accept/Reject decision.
• If the fax is to be rejected, the originator is sent an EMail message advising him that his fax was NOT sent.
• If the fax is to be accepted, a suitably massaged copy of the .SIN file is written to the AUTOFAX directory for subsequent faxing by AUTOFAX/FAX32
• If ALL of the recipients are faxes, the .SIN file is deleted.
• If SOME of the recipients are NOT faxes, the .SIN file is re-written with the fax-recipients removed from its list.

BBS2FAX represents the second component that facilitates FAX32's "Email-to-Fax" capabilities. It is specifically aimed at integrating TSX-Online and FAX32. Its responsibilities are to handle outcoming BBS fax-mail. The several programs that comprise it require FAX32 Version 3 or greater.

The idea behind BBS2FAX was to allow TSX-Online e-mail or fax-mail message sending to be procedurally identical. The flexibility of TSX-Online and the TPL programming language together with the support and co-operation of S&H made it possible.

FAXSY:BBS2FAX.CON is the text editable Rule file that BBS2FAX uses to Pass or Fail fax telephone number addresses and apply any telephone number prefixes. FAXSY:BBS2FAX.CON is quite similar to BBS:SMTP2FAX.CON. Its structure is described there as part of the section Sending incoming SMTP email via fax

Your distribution contains SAMPLE.CON which is a sample of such a file. You should make your own FAXSY:BBS2FAX.CON

BBS2FAX.TPR should be scheduled to run periodically. It reads through the Fax email message base for all messages that need processing. Each intended recipient address of these messages is evaluated against the pass/fail rules in FAXSY:BBS2FAX.CON to determine whether or not they are acceptable.

An unacceptable recipient causes a "failure" email message to be sent locally from "faxclerk" to the original sender. The message will indicate the reason for the rejection.

An "acceptable" recipient does not guarantee success. FAX32 may later report a failure if it cannot actually deliver the fax.

Acceptable messages are processed for "dot commands". Dot commands (see below) may be used to enhance the image of the resultant fax, allowing extensions beyond the traditional appearance of an email message. They may cause effects, such as font changes and resolution control; or file inclusions, such as canned text, a graphical image of your signature, company letterhead, etc.

The resultant text (which includes an appended FAX32 command) is written to a file in the AUTOFAX directory.

AUTOFAX.EXP periodically picks up each file in the AUTOFAX directory, pulls the FAX32 command out of it, moves it to AUTOFAX:GOOD\ and initiates FAX32.EXP. (Generally you should find this directory is empty.)

When FAX32 has finished its fax attempt(s), it executes FAX2BBS.TPR with arguments specifying a BBSID as well as a success or failure indicator.

FAX2BBS.TPR updates the record in Message Base5 (per BBSID) by either clearing the UNPROCESSED flag (for a success) or by clearing UNPROCESSED and setting FAIL (for a failure).

Note: In addition, FAX2BBS also sets FLAG#31 (ie the last of the 32 flag bits that S&H uses for its messages). This bit (amongst almost 20 others) is undocumented. Although S&H has no current plans to use this flag, it is officially reserved for their use. FAX32 uses this flag in order to support message "resends". Although it is unlikely, it may become necessary to change this.

S&H has "officially" designated Message Base number 5 for FAX. You must define Message Base 5 for route=fax. This will be in addition to other routes (such as Local and Internet) that you already have.

In SYSOP - User Authorization - Privileges, you may choose to define a Sysop Privilege that you can then use to control whether or not a user will be given the option of using the FAX database. Let's assume that you create Sysop Privilege 15 (and call it "Allow fax"). Here's how you'd set up the FAX Mail database

In SYSOP - Mail Setup - Mail database setup, insure that you have an entry similar to the following:

Name	ID	Database	Area	Access
Fax	F	FAX	5	optional sysop defined expression eg: (s15)

When Message Base5 is first accessed, the BBS will create 3 files that represent this message area. They are BBS:FAX.MLC, FAX.MLD and FAX.SDX If you ever want to start off with a really clean slate, you can delete these three files and start all over again.

TSX-Online's "Add address" screen contains 4 prompts

    Description
    Route [*]  one of those options should be [F] = Fax
    Address (as appropriate for the route)
    Notes (optional)

^[*] The Graphical Client does not ask for route

For fax email, the address consists of 3 parts:

       the single character # (pound sign)
       a telephone number
       (optional) additional text
eg: # 1(416) 739-1862 Alan Cohen

The first occurence of any character OTHER than one of the following indicates the end of the actual fax phone number. The entire address, however, appears as the "TO" in the header of the fax.

        0 1 2 3 4 5 6 7 8 9 (digits)
        *  (asterisk)
        #  (number)
        ,  (comma)
        () (brackets)
           (white space)

The body of a Fax mail message can be editted the same as any other mail message. The exception is that "attached files" are unnecessary and are not allowed. The body of the message may contain special "dot commands" that can enhance your fax message.

The "Receipt" option is supported.
The "Resend" option (from your Outbox) is supported.

Dot commands (both pre-defined and definable by the system manager) are available to enhance your fax message. An example of a dot command is:
   .Bold-on which you might define to turn bold print on.

Dot commands always start at the beginning of a line. The syntax is:
   .command [parameter [parameter] ]

• These commands and parameters are case insensitive.
• Any text that does not conform to this syntax is treated as ordinary text.
• Some commands are "positional". They cause an action to occur at the point within the message at which they occur. For example, ".PAGE" causes a new page to be started at the position where it is placed.
• Other commands are "global" in scope. Their location may be anywhere within the message. For example, ".FINE" indicates that you wish this message to be transmitted in "fine" rather than "standard" resolution.

The following would be treated as ordinary text rather than commands because their syntax is not correct

.page One   the page command does not expect any parameters
.page       command did not begin at column 1
. fine      intervening white space between "." and command

A message HEADER consists of lines such as those shown below. The text of the header is ususally considered distinct and apart from the text of the body and usually appears before it.

          DATE: xxx, xx-xxx-xxx xx:xx
            TO:  xxxxx xxxxxxxxx
          FROM: xxxxxxx xxxxxxx
       SUBJECT: xxxxxxxxxxxxxxxxxxxxxxxx
      X-MAILER: TSX-Online-FAX32

.NOHDR	indicates that you don't want any header in this message
.FINE	causes the fax to be sent in fine (200x200dpi resolution) rather than standard (200x100dpi)
.LONG	causes all pages to be padded with blank lines so that each fills approximately 11 inches.

.HDR	causes the header to be placed at this point instead of at top-of-file. (See also .NOHDR)
.PAGE	inserts a page break (ASCII 12=^L)
.INCLUDE filspc	where "filspc" is a fully qualified file specification, causes the insertion of "filspc"
.INCLUDE symbol	queries the environment for symbol;. If symbol exists and its value is a fully defined file specification, the contents of that file are inserted
.OUTPUT filspc	causes output to written to filspc Using this command bypasses most of the faxing process. If BBS2FAX sees this command, it will NOT write its output to the AUTOFAX directory but writes to filspc instead. Thus a fax will NOT be sent. Use of this command is intended for design purposes. Depending on their nature, ".included" files may not be displayable. However, dumping it to a LaserJet printer should result in the same appearance as if it were faxed.

You can also create your own Dot Commands for text-substitutions and file-inclusions.

The intention behind text-substitutions is primarily to provide a way to include characters that either cannot be easily remembered or cannot be entered at all into the BBS editor. Examples include cryptic PCL escape sequences which are used to achieve special effects, such as font selection.

Despite their flexibility, use of a large number of Dot Commands can be complex. That's where a little bit of pre-planning comes in handy.

For example, you might design a company letterhead that involves bold, italics and several differently sized fonts. Since this same letterhead will be used often, use the .OUTPUT command to create an output file of your letterhead and keep it in a safe place. Once done, you could make a .LETTERHEAD command which would include that file. (See "Tip!" below for an overview of this idea.)

File-inclusion commands are similar to .INCLUDE commands. The key difference (which is also applicable to text-substitution dot commands) is that they may be defined on a user-by-user basis.

A sample of FAXSY:SYMBOLS.BBS (called SYMBOLS.EG) is included with your distribution and shown at the end of this section.

SYMBOLS.BBS lines are formatted as:

        <user> SYMBOL_NAME = value_string
where value_string is a text substitution with optional parameters
    or <user> SYMBOL_NAME = <file-spec>
where file_spec (delimited by angle brackets) is a full filspc.

To make a line applicable to all users, specify a null-user, ie: <>
Null-user <> definitions should be placed AFTER specific <user> definitions:

EG:  <alan> .LETTERHEAD = <FAXDOC:CAI.HDR>
     <mike> .LETTERHEAD = <FAXDOC:REPEATO.HDR>
     <>     .LETTERHEAD = My Company\n123 Anystreet\nTel 555-1212\n

Thus, a user who enters .LETTERHEAD in a fax message will get (presumably a letterhead that is) something appropriate for that individual user.
Lines that do not begin with "<" are ignored.

A number of PCL 5 escape sequences to do such things as change the Font are included in the sample SYMBOLS.BBS file

TIP! If you wish to construct a file (your letterhead for example), create a working file (say,) X.X and edit it to contain your proposed text and dot commands.
• put a dot command like .OUTPUT MYHDR.HDR in it
• run the BBS and include (via <ESC> F) your X.X file
• BBS2FAX will create MYHDR.HDR for you
• Print MYHDR.HDR to a laser printer
• Take out the .OUTPUT command and fax it somewhere.
• Add <> LETTERHEAD = <DIR:MYHDR.HDR> to your SYMBOLS.BBS

!
! Format of each line is   <bbs username> NAME = VALUE
!                or just   <> NAME = VALUE
! If VALUE is delimited by <> as in <filspc> it is assumed to be a fully
! qualified file specification whose contents are be included.
! If VALUE is NOT delimited by <> it is treated as a format string
! which may contain one or more occurrences of "%s" indicating
! where parameters are to be inserted.
!
! If "bbs username" is non-null, line applies to sender="bbs username" only
! If "bbs username" is null, line applies to anybody
!----------------------------------------------------------------------
        <alan> LETTERHEAD = <FAXDOC:CAI_HDR.FAX>
        <mike> LETTERHEAD = <FAXDOC:REPEATO.FAX>
        <> LETTERHEAD = MyCompany\n123 Anystreet\nTelephone 555-1212
! --------------------------------------------------------------------
! These Escape sequences were lifted from a LaserJet III font printout
! --------------------------------------------------------------------
! COURIER (the default font)
!
        <> COURIER = \e(8U\e(s0p10.00h12.0v0s0b3T
!
! Note: CGTIMES takes 1 parameter which is the point size (height)
! Eg: The following would request CGTIMES font at 12 points
!    CGTIMES 12
!    CGTIMES 18
! Here, 12 or 18; would be inserted at the position of "%s"
        <> CGTIMES    = \e(8U\e(s1p%sv0s0b4101T
        <> ItalicsON  = \e(s1S
        <> ItalicsOFF = \e(s0S
        <> BoldON     = \e(s3B
        <> BoldOFF    = \e(s0B
!---------------------- End of File ------------------

TOC Additional notes

Setup

To alter FAX32 configuration parameters after installation, change your current directory to FAXSY: and issue the command:
     SETUP
and select the "Configure" option from the menu.

Your modem may be capable of a higher baud rate than a heavily job-loaded or comparatively slow speed machine can sustain. A 25MHz 386 machine probably can't handle more than 7200 baud when sending a fax.

Your application can gain access to FAX32 by spawning or forking or detaching a FAX command. If you're running DOS program this is not quite so straightforward because a "DOS Shell" is typically a copy of COMMAND.COM rather than TSKMON. You could use TSXCMD.EXE to run a TSKMON command under a DOS shell, but you may find it's easier to just use AUTOFAX.

It may be easier to integrate your application to FAX32 by writing a file to the AUTOFAX: directory. In this case, make sure that you do not actually close the file until it's done. Otherwise, AUTOFAX.EXP may grab it away from you.

Remember that, since you are controlling the user interface, you must insure that your command syntax is correct!

The inbound FaxModem mgr's job FAXWAIT runs quietly detached in the background. If something goes wrong and it determines that it must abort, it tries hard to make sure somebody knows. It:
• broadcasts a message to all logged-on users and to any terminals whose state is "logged-off".
• defines a system wide symbol called FAX$WAITCRASH which contains the date and time of its impending demise.

You are advised to take advantage of FAX$WAITCRASH Put a line like the following in your LOGON.CMD (or the user startup file that gets executed when your users log on) that looks like this:

      if $isdef("FAX$WAITCRASH") then -
           display FAXWAIT WENT DOWN 'FAX$WAITCRASH

When FAXWAIT starts up, one of its first tasks is to delete the symbol FAX$WAITCRASH

Support for multiple in-bound fax modems is not yet available. Work on this has been curtailed pending your response on whether or not this is important.

Allowing inbound fax viewing from a TSXTERM station is possible although we havn't done it. TSXTERM only supports CGA graphics which are rather low resolution. Please advise.

If you have problems sending outbound faxes from a TSX32 network node where the faxmodem is located on another network, please advise us.

Fax modems support one or more "classes". For the most part, these are Class 1, Class 2, and Class 2.0
• Class 1 modems are not supported properly by FAX32.
• (Class 1 places a heavy burden on the CPU as compared with Class 2 and Class 2.0 where much of that work is accomplished within the modem itself.)
• There's a difference between Class 2 and Class 2.0. The official standard Class 2.0 took a long time to come out. In their rush, modem manufacturers released equipment compatible with the unofficial Class 2 to such an extent that Class 2 is more prevalent today than 2.0.
• Many of them, in fact, were buggy. You should insure that you've got the latest ROM Chip release for whatever modem you've got.
• Caveat emptor: In response to questions received from their customers, some modem manufacturers are known to have asked the customer to report the release number on his chip and then tell him that it's the latest version!
• If you're not sure which Fax Class(es) your modem supports, you can ask it to report back its list of supported classes. See "What Class of modem is that?" below.

• We've been quite happy with Supra modems (from Diamond). They are economically priced, support downloadable flash ROM and have LED read-outs to let you know what's going on.
• Warning: Some modems have been found to dislike certain fax machines!
• We recommend using modems that support fax-mode hardware (/CTS) flow control.
• External modems are recommended. Internal modems generate unwanted heat and typically cannot offer display read-outs or even an on/off switch.
• We've tested some modems here and have received reports from our users regarding several modems. Please let us know of your experiences and we'll make additions to this list.
  • BOCA 14.4
  • Cardinal 14400/V.42bis
  • GVC FAX 14400/V.42bis
  • Practical Peripherals PM14400
  • SupraFAXmodem 14.4ROM Chip 1.18
  • SupraFAXmodem 28.8 Use /CTS (Flash ROM V18 doesn't work!)
  • US Robotics V.Everything
  • ZyXel 14.4 has been found to dislike some fax machines!
  • Accura has been found to dislike some fax machines!

To confirm the Class of a modem on TTB0: you would issue the command
      SET HOST TTB0: and type
      AT+FCLASS=?
      (To disconnect SET HOST, press Ctrl \ )
Your modem should report back its class capabilities with something like:
      0,1,2,2.0
      ... which would indicate:
• 0 meaning data modem capable
• 1 meaning fax modem Class 1 capable
• 2 meaning fax modem Class 2 capable
• 2.0 meaning fax modem Class 2.0 capable

Typically, the modem itself retains a code representing its last completion status. To review that status, establish a cross-connect to the modem and then ask the modem to report its last error status by entering:
      AT+FAXERR?

Earlier versions of FAX32 had problems (that we'd like to think are licked) with Err:43 (+FHNG:43) data underrun errors. (You're "over your speed limit" ie: you're allowing a modem connection at a speed that's so high, that you can't feed data to the modem fast enough.)

These three terminal line parameters are reported (amongst many others) when you type a command similar to: SHOW TTB0: Each should be set to about 2,000. (IRINGSIZE is only relevant if you are also receiving faxes.)
To modify these settings, you must TSGEN a new kernel. Select:
      Manage Equipment list
      Unit Menu
      Unit Settings (These 3 buffer sizes are on Page 3 of 5)

Where possible, we recommend using hardware flow-control.
• You'll need a port that supports RTS/CTS
• You'll need a modem that supports hardware handshaking in fax mode.
• Although your modem likely supports hardware handshaking in data mode, it may not support it in fax mode! Confirm this by sending a fax while monitoring the line with the SPY command:
        SPY /INPUT /HEX /BINARY /MODEM TTB0:
• When the modem tells TSX to suspend output you will see one or both of:
        [13] (this is a software flow control)
        CTS dropped (this is hardware flow control)
• When the modem tells TSX that it's ok to resume output you will see one or both of:
        [11] (this is a software flow control)
        CTS detected (this is hardware flow control)
• If your modem supports hardware flow control in fax mode, it is recommended that you take advantage of it. To do so, either change FAXSTART.CMD and edit the definition of FAX$MODEMS (see "Under the hood" above for FAX$MODEMS symbol) or run the Setup program (which does the same thing).
• Via either method, you'll be changing (say) TTD7: to read TTD7:/CTS

We often use SPY to watch what's going on to and from a modem's TT line. (Type HELP SPY to see the options for SPY.)
For example:
      SPY /INPUT/OUTPUT/HEX/MODEM/BINARY/FILE=spy.log TTB0:
With /INPUT, expect to see a lot of monitored data on incoming faxes.
With /OUTPUT, expect to see a lot of monitored data on outgoing faxes.
/INPUT/OUTPUT causes inputs from the modem and outputs to the modem to be marked. Because it separately monitors input versus outputs, the sequencing is not always precise. For example, you might see:
      -I: ATDT739-1862
      -O: ATDT739-1862
suggesting that the input from the modem came before the output to the modem, when, in fact, the output to the modem really happened first.

/HEX	causes unprintable binary data to be formatted as [XX] where XX is in hex.
/MODEM	causes modem control signals such as CTS detected to be monitored.
/BINARY	causes software flow control XON and XOFF to be displayed as [11] and [13] respectively
/FILE=filename	causes the monitored results to be copied to filename

If you see "ERROR" being reported back from the modem (particulary near the beginning of a log), it probably indicates an invalid modem command.

FAX32 processes themselves fork and detach as many as two other processes that may run concurrently. Make sure your TSX32 gen parameter VMAXJOBS (maximum number of concurrent jobs allowed at any one time) is sufficient to the task.

Setting the system symbol: FAX$DEBUG:===1 causes lots of information to be written to the event log FAXDEBUG. This information may be helpful in problem resolution. One procedure is to recreate the problem and see if you get any hints from the debug log.
• Clear the event log beforehand by using the SHOW EVENT command and Resetting the event FAXDEBUG
• Run the interactive SHOW EVENT screen. (You can only see the last 20 lines this way.)
• Or: Run the command EVENT FAXDEBUG/OUTPUT=problem.log (You can view the entire problem.log this way.)

We necessarily play around a lot with the TSX settings for the modem's port. We try to insure that we always put things properly back together again. FAX32 only changes those TT settings that are not to it's liking. If it does make TT changes, it will restore them when it's done. For that reason: Don't kill FAX32! Most settings tend to be already fine and are never touched.

By setting the symbol FAX$DEBUG:===1 you can watch the FAXDEBUG event to see which settings are being modified. Here's a complete list of the ones that might be modified.

TTL_BITS TTL_EIGHTBIT TTL_FORM TTL_LFIN TTL_LOGON TTL_PAGE TTL_PARITY TTL_PHONE TTL_SCOPE TTL_SPEEDTTL_TAB

TTL_LC TTL_LFOUT TTL_TERMTYPE TTL_BININ TTL_BINOUT TTL_CR TTL_CTL TTL_UPCASE TTL_WIDTH TTL_ENDFF

TTL_HANDSHAKING TTL_XOFFCHR TTL_XONCHR TTL_BOARDHS TTL_BINUART TTL_ADDLF TTV_ECHO TTV_GAG TTV_PWKEY Modem reset string

Here's a sample configuration of a modem line in its "normal" state:

       TTB0:  Com 1
/NOADDLF        /ANYXON        /NOAUTOBAUD    /NOBACKRUB      /NOBININ
/NOBINOUT       /NOBINUART     /BITS=8        /NOBOARDHS
/CMDFILE=SY:START.CMD          /NOCOLOR       /CR             /CSRSTART=13
/CSREND=14      /CTL           /NODEAD        /DTR            /EIGHTBIT
/ENDFF=0        /NOFIXEDSPEED  /FORM          /NOGRAPHICS
/HANDSHAKING=RTSCTS            /ID_NUMBER=2   /IRINGSIZE=2048 /LENGTH=24
/LFIN           /LFOUT         /LOGON         /MONITOR        /MRESET=ATZ^M
/ORINGSIZE=2048 /PAGE          /PARITY=NONE   /NOPCDIM        /PHONE
/NOPRINTER      /NORESTART     /RTS           /SCOPE          /SILOSIZE=2048
/SKIP=0         /SPEED=38400   /NOSTART       /NOSYSPASSWORD  /TAB
/TERMTYPE=VT200 /TPCPS=0       /NOTPFFCLOSE   /NOTPFFOPEN     /TRIGGER=8
/VUARTBUF=512   /WIDTH=80      /XOFFCHR=13    /XONCHR=11
State=Logged off               Got_xoff=No    Sent_xoff=No
Data set status=NORING,NOCARRIER,DTR,DSR,RTS,CTS
Shift keys = NO SHIFT,NO CTRL,NO ALT,NO NUM_LOCK,NO CAPS_LOCK

The TSX command file FAXSY:FAX32RPT.CMD produces an output file called FAXSY:FAX32.RPT which contains a lot of information some of which may be helpful in diagnosing problems you may encounter.

The file FAXSY:BGFAX.LOG contains more information relating to the most recent inbound transmission. The file FAXSY:BGFAXi.LOG contains more information relating to the most recent outbound transmission on outbound modem #i

Should you call us with a problem, have FAX32.RPT, PROBLEM.LOG and BGFAXi.LOG handy. We may ask you to fax them to us or upload them onto our system.

Voice: (416) 739-0070
Fax and Dial-in: (416) 739-1862
Email: alan@ComputerAdvocacy.com