Documentation for POLYFAX, version 1.70 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ POLYFAX is Copyright (C) 1996-1997 B.J. Guillot. All Rights Reserved. Abstract: PolyFax is a new companion program for BGFAX which allows the user to easily send a fax to multiple clients ("broadcasting") Legal notice: It is against FCC regulations in the United States to send faxes to people without their prior permission. Many other countries also have similiar laws. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Installation of PolyFax ======================= 1. It is assumed you already have a working copy of BGFAX installed. 2. It is assumed you already have defined your "BGFAX" environment variable, and that it is present in the AUTOEXEC.BAT or other batch file that gets executed before PolyFax is started. (i.e., add a line that says "SET BGFAX=C:\BGFAX" at the top of your AUTOEXEC.BAT file, then reboot the computer.) 3. Copy the POLYFAX.EXE file into the same directory as BGFAX.EXE. 4. BGFAX.CNF should also be in this same directory. If you have not already looked through BGFAX.CNF, do so and make sure the com port and other information is configured correctly. Using PolyFax to Broadcast ========================== 1. You need to make a fax file that is capable of being sent by BGFAX. (i.e., the file must be in ZyXEL-ZFAX version 2, QuickLink II QFX, or TIFF-Class-F format.) The MAKEFAX.EXE program that comes with BGFAX is capable of converting ASCII (plain text), PCX, and DCX files into a format suitable for sending. (e.g., "MAKEFAX filename.txt output.fax") 2. You need to make an ASCII text file that contains all of the telephone numbers that you want to send to. Each telephone number should be on a line by itself. (so-called "" delimited.) Example: 507-9620 555-1212 713-507-9620 011-44-123456-78 3. After doing the above two steps you will need to have PolyFax initialize a quick-and-dirty "database". Two command line parameters are required: POLYFAX @PHONENUM.LST OUTPUT.FAX #MF:100 #MS:4800 This should take over 1 second or so to have PolyFax build the database. Note the at-symbol (@) in front of the filename containing the list of phone lines. The name of the file is just "PHONENUM.LST" but the "@" symbol is required by PolyFax. It is there to remind the user that will be using the so-called delimited list format. The #MF and #MS switches are optional. #MF:nnnnn sets a maximum number of failures per number. The default is an infinite number of failures. #MS:nnnn sets a maxium DCE bps rate for all fax numbers. The default is a maximum speed of 9600. You can override the defaults or the command line parameters by inserting the #MF and #MS directives directly in the phone number list file. Another example with more optional switches: 507-9620 /C2 #MS:4800 /FR:Bat_Man 507-9620-1 507-9620-2 #MF:3 #MS:7200 507-9620-3 #AF:C:\BP\PAS\2PGTEST.FAX 507-9620-4 /50 /FR:Super_Man #MS:nnnn specifies a maximum DCE speed #MF:nnnn specifies a maximum number of failures for a particular number before POLYFAX gives up (the number will be appended to the POLYFAX.BAD file) #AF:xxxxxxxxxxxx specifies an alternate filename is to be used 4. Now, do "POLYFAX /SEND" and that will make POLYFAX begin to send out all the faxes. It will not stop until the user aborts it (by hitting the escape key numerous times) or until all faxes have been sent. If you abort the send process, simply typing in "POLYFAX /SEND" will _RESUME_ the broadcast session where you last left off (_IF AND ONLY IF YOU HAVE *NOT* PERFORMED A DATABASE BUILD_, recall a database build/initialization is done whenever you use the "@" command.) 5. PolyFax will exit with an errorlevel 5 after all faxes have been sent. Technical Information ===================== a. How does PolyFax know where to resume sending if you have aborted the program? PolyFax keeps track of the broadcast session using a POLYFAX.DAT file. This DAT file is _not_ a text file. Do NOT attempt to manually edit the DAT file. The DAT file is only for internal use by PolyFax. If you delete the POLYFAX.DAT file, you will NOT be able to resume the fax broadcast session. The DAT file is constructed when you run PolyFax with the "@" command (database build/initialization). If you perform a "@" command and a POLYFAX.DAT file already exists, PolyFax will rename the OLD POLYFAX.DAT file to POLYFAX.BAQ. b. If a fax send attempt fails, PolyFax will advance to the next number in the list. PolyFax will continue to cycle through the database until every fax is marked as "sent" (unless you delete the DAT file or perform a database build/initialization.) c. Kinds of failures--Numbers below are the errorlevels generated by BGFAX's /SEND /ER mode ("extended results") Serious failures: 19,18,17,16,15,14,12 (see BGFAX.DOC) These "serious failures" are things such as timeouts, syncronization errors, firmware-implementation errors, etc. Trivial failures: 20 (user abort), 13 ("no carrier", "no answer"--remote never picked up), 11 ("no dialtone") 10 ("busy") 7 ("blacklisted") 0 (generic, non-fax-related failure) When a "trivial failure" occurs, PolyFax will just advance on to the next number, and try the trivial-failed number later. When a "serious failure" occurs, PolyFax will advance on to the next number, but will "remember" the serious error and will attempt to perform "countermeasures" the next time the bad number comes up. d. What kind of "countermeasures" ? PolyFax will keep track of how many times a serious error occurs on a particuilar fax number. For an "odd number" of serious errors, PolyFax will force BGFAX to use Class 1 mode. For an "even number" of series errors, PolyFax will let BGFAX use the highest fax mode (Class 2 or 2.0). If more than 2 serious errors have occured, PolyFax will limit BGFAX to use a maximum speed of 4800 bps with that fax number. e. Parameter Passing. "PolyFax /SEND /ab /cd /ef" will send those same parameters to BGFAX everytime when PolyFax shells to BGFAX. i.e., BGFAX will receive "BGFAX /SEND filename.fax phonenumber [countermeasures] /ab /cd /ef" The POLYFAX.LOG file will log all parameters passed to BGFAX. If you need to pass parameters for specific finicky fax machines, you can put those extra commands in the actual list file, i.e., 507-9620 507-9620 /C1 555-1212 would always have PolyFax force BGFAX force Class 1 mode when sending faxes to 507-9620. f. BE AWARE THAT POLYFAX WILL *NOT* TERMINATE UNTIL IT HAS SUCCESSFULLY FAXED EVERYONE IN THE LIST. YOU MAY HAVE TO ABORT IT BY HITTING "ESCAPE" MULTIPLE TIMES. NOTE: If you want to use BGFAX32 with POLYFAX instead of BGFAX, rename BGFAX.EXE to BGFAXDOS.EXE, and then rename BGFAX32.EXE to BGFAX.EXE. Regards, B.J. Guillot http://www.blkbox.com/~bgfax/ bgfax@blkbox.com +1-281-893-9320 voice +1-713-507-9620 bbs/fax