About how to use QuickStar FAX Pro V1.08 Copyright (c) 1995-1997 Anthony Mai QuickStar Fax Pro V1.08 (QFAX) is a shareware FAX program for PCs. It is a DOS program, but it can be run either in the DOS environment or in the DOS session launched from the Windows. QuickStar Fax Pro (QFAX) is written by Anthony Mai (at Pennsylvania State University, USA) and brother Zeqiu Mai (in China). Anthony Mai is currently a member of the Association of Shareware Professionals. The official ASP OMBUDSMAN Statement as well as the contact information of ASP can be found in the REGISTER.TXT file. The author can be contacted at E-Mail address QFAX@QFAX.COM. You can find the mailing address of the author in the file REGISTER.TXT. QFAX V1.08 was released in Mar. 10, 1997. Please visit the author's web site for latest upgrades: http://WWW.QFAX.COM QFAX is a command line fax sending and receiving program. QFAX is a very remarkable shareware for a few good things: a.Small in size and memory requirement. b.Very easy and straight forward to use. c.It's fast. Sends an average of 3 pages per minute at 14400 bps modem speed, normal resolution. d.It's very flexible and can be used by other softwares as a fax engine or a fax broadcast program. e.It allows you to insert PCX graphics and pre-defined strings. This USAGE.TXT file will explain the detailed usage in five parts. 0.Basics of QFAX 1.Configuration File 2.Command Line Syntax 3.Advanced usages 4.Trouble shoting ========================================================================== 0.Basics of QFAX What can be faxed by QFAX? Three kinds of files can be faxed by QFAX: Plain text files QFAX *.FAX files FAX files from other fax programs When faxing a plain text files QFAX will first convert the files to QFAX FAX files, one for each page of fax. And then fax them out. It is a one step procedure. When QFAX is used to fax QFAX *.FAX files no conversion is necessary. If you have received a fax using QFREC.EXE the received fax is recorded as a series of *.FXR files. Those *.FXR files normally can be faxed out again directly without any conversion. Faxing FAX files used by other fax programs, like WinFax's *.FXD and *.FXR files requires a two step procedure. First you convert the original files to QFAX compatible FAX files using QFREC.EXE. Then you use QFAX to fax them out. A new feature in QFAX allows you to insert PCX graphics files in the fax so you can also use it to fax PCX graphics files indirectly by inserting the name of the PCX files in a text file using a special format and then fax that text file using QFAX. Another new feature allows you to insert user-defined strings in the original text file, this way you can personalize each individual fax sent even though you are faxing the the same text file. Please check the "Advanced Usage" section for details of how to insert PCX files and user-defined strings. Before you use either QFAXEXE or QFREC.EXE you have to make sure the QFAX.CFG file is properly configured. The next section will talk about the specifications of the QFAX.CFG file. QFAX rely on QFAX.CFG to get information of which Comm Port the modem occupies, what AT initialize string will be sent to the modem to initialize it for fax, and information of fax page layout. QFAX.CFG is a plain text file and you can use DOS edit to modify it. Or you can run the QFAXCONF.EXE program to help modify it. The most important thing in QFAX.CFG is the CommPort number and the InitString. If the CommPort number is wrong QFAX won't even be able to Reset the modem and do other initialization. If the InitString is not appropriate QFAX may or may not report any problem in Initialize modem, but the fax probably will not be accomplished successfully. If both the CommPort and InitString are set up properly, QFAX should be able to send and receive fax normally, though the fax page layout etc will depend on other settings in the QFAX.CFG file. Setting up the correct InitString is the most tricky part of getting QFAX or any other fax program to work. Unfortunately it is not always easy and obvious. Please refer to the included INIT.LST file for a list of recommended InitString, check your modem manual for more info, visit the web site "Ask Mr. Modem" at http://MOLLY.IPA.NET/MODEM/ or E-Mail the author at QFAX@QFAX.COM for help. Once you configure QFAX correctly, the simplest way to send a fax is use a single DOS command like this: QFAX myfile.txt 1-800-555-1212 If you do not want QFAX to dial any number, or you want to dial the number manually using a phone instead, just replace the fax number with a single ',' key, like: QFAX myfile.txt , For more sophisticated usage please refer to the other three sections of this USAGE.TXT file. ========================================================================== 1. Configuration file The only configuration file required is QFAX.CFG file. It must be located under the same directory as the QFAX executable programs. You can specify additional configuration file on the QFAX command line using the "-cfg" option flag (See the "Command Line syntax" section"). Additional configuration file will have the same syntax as QFAX.CFG file. It is primarily used to define user-defined strings or change other fax settings without the need to modify QFAX.CFG every time. QFAX.CFG is a plain text file and is constructed line by line. Each individual configuration line can be added or removed from the file. The order in which those lines present in the QFAX.CFG file does not matter, as long as the syntax of each line is correct. If a certain configuration line is missing in the file, QFAX uses the default for the corresponding parameter. You can modify the QFAX.CFG file manually using the DOS edit. Or you can run to QFAXCONF.EXE program to help configure it. You can start the QFAXCONF.EXE program in two ways: "qfaxconf" or "qfaxconf -d". The "-d" on DOS command line will let qfaxconf.exe detect the modem port at start up. It's better to avoid using the "-d" option if you already know the CommPort. The complete format of the qfax.cfg file is shown below. It is NOT necessary to include every line in the QFAX.CFG file. Each configuration parameter will have a default value so if it is not fount in QFAX.CFG, the default will be used. ----------------------------- QFAX.CFG file ------------------------------ CommPort 2 InitString AT&F&C1&D2&K3M2L3 PhoneNumber 1-234-567-8900 TelephoneLine Tone DialRepeatTimes 3 NoDelay No Font 16 LineSpace 6 AsciiSpace 2 Size 748 1048 Margin 64 56 TopLine 7 WaitTime 55 BusyWait 30 RemoveFile No Define YOURNAME John_Smith Define MYNAME Anthony_Mai ---------------------------- End of file -------------------------------- The following is detailed explaination of what each configuration line is. Each configuration line can be added or removed from the file. And the order in which the lines appear does NOT matter. ----------------------------------------------------------------------- CommPort 2 The most important parameter is the CommPort number. It identify what COM port your fax/modem uses. Possible number is from 1 to 8. Please check your system set up or consult a knowledgable person to find out your modem port. Or use QFAXCONF.EXE to detect it by using the following DOS command: qfaxconf -d The default is 2. Possible COM ports are: CommPort COM/IRQ Base_address Description 1 COM1/IRQ4 3f8 This is probably the mouse port, not the Modem 2 COM2/IRQ3 2f8 --> most commonly used modem port 3 COM3/IRQ4 3e8 4 COM4/IRQ3 2e8 --> commonly used modem port 5 COM3/IRQ2 3e8 also called COM5 6 COM4/IRQ2 2e8 also called COM6 7 COM3/IRQ5 3e8 also called COM7 -> commonly used alternative port 8 COM4/IRQ5 2e8 also called COM8 InitString AT&F&C1&D2&K3M2L3 This sets the AT command QFAX will send to the fax/modem to initialize it for fax. QFAX will work properly only if proper InitString is used. For QFAX to read the InitString correctly you must observe the following points: 1. Leave NO space within the InitString itself. 2. ALL letters must be in upper case, i.e., in capital letters. A note about the "M2L3" at the end of above example InitString: It will not effect the fax but will set the modem speaker on and the volume to be loudest during the fax process so you can hear how the fax is going on. Once every things are tested OK you can remove the "M2L3" to keep the modem quiet. The above default InitString will work with most brands of modems. But there are also a lot of fax modems which requires a very different InitString, for example the USR modems. To find an appropriate InitString you can resort to the following solutions: 1.Check the included file INIT.LST which lists recommended InitStrings 2.Find out what other fax or communication program use for your modem and copy the same string to see if it works. 3.Check your modem manual to find a recommended AT initialize string. 4.Visit the World Wide Web site "Ask Mr. Modem" to find out. They list InitStrings of many brands of modems: http://molly.ipa.net/modem/ 5.Ask for the help from QFAX author by E-Mail: QFAX@QFAX.COM 6.Try to construct an InitString yourself. If you have to try to construct an InitString by yourself keep these guidelines in mind: * Always stats the string with "AT&F". The "&F" is an AT command that sets factory defaults for most parameters of the modem. * Be sure to include something to set "Hardware Flow Control". Or another word it may be called "RTS/CTS Flow Control" * Leave no spaces within the string. Do NOT use a string longer than 38 characters. Some commands like "E1", "V1" are not needed. QFAX will set them by an "ATE0V1" command after initialization. * Use all captalized letters. PhoneNumber 1-800-555-1212 This is the ID string of your local fax station, i.e., your own phone number. This string should NOT exceed 20 characters. This string will be exchanged during fax negotiation for fax devices to identify each other. This is also the string that will show up on top of each fax page sent, if you configure to use teh fax topline. See the "TopLine" configuration parameter below. TelephoneLine Tone Use "Tone" for touch tone dialing phone lines. Or "Pulse" for pulse dialing phone lines. Most phone lines in USA is touch tone. Most modems use either "ATDT" (Tone) or "ATDP" (Pulse) for dialing a number. If your modem uses something odd, contact the author for solution. Default is Tone. DialRepeatTimes 3 Times it will repeat the dial if the line can not be connected due to busy phone line or other reasons. Default value is 3 times. Font 16 This specifies which one of the two character fonts will be used. Allowable numbers are 16 or 24. 16 means the 8x16 bitmap font will be used. 24 means it will use the 12x24 bitmap font. This will also decide the fax resolution QFAX will use in fax transmission. The 16 font is associated with standard resolution (204 Dots Per Inch horizentally, and 98 DPI vertically). The 24 font is associated with high resolution (204 DPI horizentally and 196 DPI vertically). Using the 16 font will give you shorter transmission time but 24 will give you higher visual quality of the fax. Default is 16 (8x16 font). LineSpace 6 Number of blank fax scan lines between text lines. Default is 12. That means a gap of 12/196 = 0.06 inch between text lines. If standard fax resolution is used QFAX will divide the specified number by 2 so the space gap measured in inches will remain the same (= LineSpace/196) Reducing this number will reduce the space between lines hence allow more text lines on one fax page. Always use an integer for this number. The Minimum allowable is 0. The default is 6. AsciiSpace 2 Character pitch (space between characters measured by dots). Each dot is equivalent to 1/204 Inch. The default value is 2 dots (2/200 Inch). Reduce this number will allow more characters on each text line. Always use an interger for this number. The minimum allowable is 0. The default is 2. Size 748 1002 Size of the text area of the faxed document, measured in unit of 1/100th of inch, must be integer. Default is 748 1002, which is 7.5"x10" and leaves approximately half inch margin on the standard 8.5"x11" paper. The default value: 748 1002 has been carefully selected so normally you do not need to change it. Note this is the size of text area, NOT the size of the whole fax paper. FAX paper size is always 8.5 inch wide and the length can be either fixed at 11 inches or unlimited. Margin 58 28 Left (the first number) and Top (the second number) margin of the transmitted fax page, measured in 1/100 of inch. The default value: 58 28 (left margin 58, top margin 28) has been carefully selected so normally you do not need to change it. NoDelay No After initialize the modem and get ready to dial the fax number to send fax QFAX may either go immediately to dial the number, or wait for the user to press an enter key to proceed. You can put either a "Yes" or a "No" after the "NoDelay" to tell QFAX whether it should pause or not. default is No: It will pause for user to press enter before the start of fax dialing. WaitTime 55 The time (in seconds) that modem will wait for a connection after it dials the fax number. The maximum you can set is 255 seconds and the minimum is 15 seconds. Default is 55 seconds. TopLine 7 The setting of Title Line on each faxed page. It must be an integer between 0 - 7. How the Title Line looks. A complete Title line will be constructed like the following if 7 (default) is used: Bookmark-ICON From:********* Time:********** Page # of # 0 No No No 1 Yes No No 2 No Yes No 3 Yes Yes No 4 No No Yes 5 Yes No Yes 6 No Yes Yes 7 Yes Yes Yes If 0 is used there will be no title line at all. BusyWait 30 Number of seconds it will wait before re-dial the fax number, if the fax line is busy or if it fail to establish connection after the amount of time defined by WaitTime. Default is 55. RemoveFile No This will specify whether QFAX will remove the converted *.fax files once the fax is sent. "Yes" tells QFAX to remove the created *.fax after the fax page is sent. "No" means keep those *.fax files created. Define STRNAME John_Smith This is a new feature in QFAX V1.08. You can define certain strings to be inserted in text files when faxed. The strings defined should contain NO spaces. If spaces are needed they are replaced with the "_" key like the example shown above. In the above example it defines the string named STRNAME to be "John Smith". In the text file you want to fax you can then insert the string using this format: ~<$STRNAME> and it will be replaced with the string "John Smith" when faxed. You can have multiple "Define" configuration lines to define more than one strings. You can also define strings on the command line. A total of 16 strings can be defined. But the string "DATE" and "TIME" are already defined as current date and time string in QFAX, so it leaves you a maximum of 14 strings that you can define. Since it is not convenient to modify the qfax.cfg every time to change the definition of strings, you can take all those "Define" lines out and put them in a separate configuration file, like temp.cfg. Then call this additional configuration file using the "-cfg" option flag. Like "QFAX -cfg temp.cfg mylett.txt 1-800-555-1212". ------------------------------------------------------------------------ Please be noted that after a certain period, un-registered version will not be able to set some of the above papameters, i.e., LineSpace, AsciiSpace, Size. And the default value of these fax parameters may be different from what's listed above. The paper size will be a bit less than a full page. Once you register it will resume the best default values and allow you to set them to any thing. ========================================================================== 2.Command Line Syntax The QFAX package contains three executable files: QFAX.EXE The fax sending program QFREC.EXE The fax receiving/converting program QFAXCONF.EXE Configuration program QFAXCONF.EXE has two possible usages on the DOS command line: qfaxconf qfaxconf -d With the "-d" it will detect the modem port first at start up. Once it starts the usage is self explaining. Just follow the instructions on the computer screen. The command line syntax of QFAX.EXE can be very simple or very complicated. The simplest usage is like this: qfax text_file_name Fax_number But if you need specify additional configuration informations or you need to fax multiple files in one fax session you may construct a more sophisticated command line. The QFAX command line is composed of four parts: QFAX, option flags, file names, fax number. It will look like this: qfax [-option flags] file1 [file2] [file3...] [fax_number] You can specify no option flags at all or as many option flags as you need. Any option flags must be inserted between the QFAX command and the file names. Each option flag begins with a '-' sign. Following the option flags are names of text files or fax files you want to fax out. You can specify one, two, or many file names. Each of the file names can be the exact name or can be a wild card name specification (e.g., lett*.txt) and can contain a path name (e.g., \mydir\myfile.txt). Following the file names is the fax number that you want to fax to. If you omit the fax number on the command line, QFAX will ask for it after the program starts. You can use ',' instead for the fax number in certain situations. Please see "Advanced usages" section. The following are possible option flags you can use with qfax.exe You can use none of these flag, one, two, or many. -r --> Delete the created *.fax file at end -f --> The files to be faxed are fax files -16 --> Use 8x16 ASCII Font -24 --> Use 12x24 ASCII Font -ls 12 --> Line space set to 12 -as 2 --> Ascii space set to 2 -size 748 1002 --> size of text area (width, height) -rep 3 --> Repeat dial 3 times if not connected -nod --> No delay before dialing fax -def NAME John_Smith ->Define the string NAME to be "John Smith" -cfg myfile.cfg --> Define additonal configuration file If you simply type QFAX at the command line with nothing following it. It will display a help screen to remind you how to use QFAX. The -def option flag is a new feature in QFAX Version 1.08. It allows you to define define certain strings to be inserted in the text file to be faxed. Use this format in the text file for string insertion: ~<$NAME> i.e., The format is ~<$ followed by the name of the string and then followed by >. The defined string ("John Smith") will be shown on the fax. Another thing you can insert in text files are PCX files. There are no limits on how many PCX files you insert on one page, but QFAX can not process more than 4 PCX files at a time, so you have to make sure on ANY horizental scan line you should not have more than 4 PCX graphics. For example if you line up 5 images from left to right on one line it causes a problem, but if you have 10 PCX files on a page arranged from top to bottom, it is OK. The PCX files must be in the same directory as the text file for QFAX to find them. Use this format to insert PCX files: ~ The following are examples of allowable QFAX commands: qfax myfile.txt 123-4567 --> convert the text file "myfile.txt" to fax and fax it. qfax lett*.doc lett*.txt 567-1234 --> find all text files match lett*.doc and lett*.txt, and fax qfax -f ..\docs\fax*.fax 555-1212 --> find all files match fax*.fax in directory \doc and fax them out as already pre-processed fax files. qfax -24 -nod myfile.txt 1-800-432-5678 --> convert myfile.txt to fax using 12x24 font. Go directly to faxing right after the file processing is completed. qfax -def CUSTOMER John_Smith myletter.txt 1-800-555-1212 --> Define the string CUSTOMER in file MYLETTER.TXT to be "John Smith" and fax the file to 1-800-555-1212 qfax -cfg custom.cfg myletter.txt 1-800-555-1212 --> Read additional configuration info in file CUSTOM.CFG and then fax the file myletter.txt to 1-800-555.1212 The file CUSTOM.CFG will contain configuration lines of the same syntax as those in QFAX.CFG file. You can define multiple strings in CUSTOM.CFG so they can be placed in the MYLETTER.TXT file. ------------------------------------------------------------------------- QFREC.EXE fax receive and/or decode program The enclosed QFREC.EXE program is a multi-functional program. It can be used in one of two ways: a.Receive an incoming fax on the phone line. And save it as FAX files or PCX picture files. You can them use any PCX viewer to view the PCX files. Or you can then re-send out the faxes received using the QFAX.EXE program. b.Decode fax files of any format or created by any fax programs into PCX picture files, or into QFAX compatible FAX files so you can fax them out using QFAX. Suppose you have an un-expected fax call and you have no fax receiving program running in the background, launching a fax receive program upon hearing the fax tone and trying to receive the fax may be a bit too late. Well, not with qfaxrec.exe. When you run qfaxrec.exe, it can set up your computer ready for receiving an incoming fax in just 1 second! You will never miss another fax ever again with qfaxrec.exe. The command syntax of QFAXREC.EXE is like this: qfaxrec [-option flags] [filename] The option flags can be any of the following: (Or you may omit them all) -nod --> NoDelay. Do not pause after modem reset and before fax receiving. (The default is to delay) -c --> Do file decoding/conversion instead of receiving fax (Default is to receive fax). -f --> Convert file to FAX (QFAX compatible FAX format) file (default is to convert to PCX file) -r --> Use reverse bit order when converting FAX files. -1 --> Specify low resolution when converting a fax file. -2 --> Specify high resolution when converting a fax file. The filename is the name of the file to be received (if receiving a fax) or the name of the file to be converted (if converting a file). Example: qfaxrec document.fxr --> Receive a fax and save as document.fxr. It will save the fax to a series of files like docum001.fxr, docum002.fxr, docum003.fxr ... And then convert to PCX files: docum001.pcx, docum002.pcx, docum003.pcx ... Assume you attempted to send a 5 page fax using WinFax and you were able to locate the WinFax fax files located in the c:\winfax\data\ directory: 34560001.fxd 34560002.fxd 34560003.fxd 34560004.fxd 34560005.fxd Now you want to convert them to QFAX compatible fax files so you can then use QFAX.EXE to fax them to a list of receivers. You would do: qfaxrec -c -f 34560001.fxd (After processing 34560001.fxd it will automatically look for the next file in sequential number, until all files are processed.) The above command will work for WinFax *.FXD and *.FXR files. But if you have problem converting fax files used by other fax programs it could be that the bit order is reversed. Just try again with the "-r" option: qfrec -c -r -f 34560001.fxd A series of files are then created: 34560001.fax 34560002.fax 34560003.fax 34560004.fax 34560005.fax And then you can use the following QFAX command to fax it out: qfax -f 34560*.fax 1-800-555-1212 One note: The *.fxr files of faxes received using QFREC.EXE can be normally used by QFAX to fax without the need of any conversion, though a conversion step will improve the performance, like say shorten the fax transmission time and make the fax more reliable. =========================================================================== 3.Advanced usages of QFAX In this section we talk about example usages of QFAX in different situations. We will talk about it in 5 parts: * Dialing Tactics: Usage of ',' as Fax Number * Insert PCX Graphics and Pre-Defined Strings * Calling QFAX From Your Own Application * Personalized Batch Fax Sending * Other Potential Usages * Dialing Tactics: Usage of ',' as Fax Number When you use the ',' instead of a numerical key as part of the fax number, the modem will pause a certain amount of time for each ','. The length of this pause can be configures using the S8 register. For example if you want the modem to pause 5 second for each ',', you can just add "S8=5" to the end of InitString in QFAX.CFG file. This ',' pause is very useful in some situations: * If you just want QFAX to conver the text file to FAX, but do not dial any number or fax, do this: QFAX myfile.txt , And when it askes you to press enter to continue, just press 'q' to quit. * If you need to manually dial a fax number instead: QFAX myfile.txt , When it is real and askes you to press enter to continue, you pick up the phone and dial to get connected. When the remote fax is ready to receive fax, press the enter key. * You want automatic dialing but your phone line required some special dialing sequence, such as it needs to dial the fax number first, then wait 10 seconds, then dial a password to get through. You can do so like this: QFAX myfile.txt 1-213-555-1212,,,5678 * After the dialing you expect an answer machine to pick up the phone line, you have to wait 30 seconds to skip the message and then get to the fax machine: QFAX myfile.txt 1-213-555-1212,,,,,, There are certainly other tactics you can use in dialing. Just remember, a ',' in the phone number means a pause for the modem. * Insert PCX Graphics and Pre-Defined Strings You can insert PCX graphics and pre-defined strings in text files you want to fax out. The syntax for insertion is very simple: To insert PCX files, do like this: ~ To insert pre-defined string, use this format: ~<$STRNAME> In the case of inserting PCX file you have adjust the text lay out and leave enough room for the PCX file inserted, otherwise it will overlap with the text. The space needed for the PCX file depends on the pixel sizes of the PCX file (how many dots horizentally and vertically) and the fax resolution used (or another word which of the two fonts are used). The resolution information of original PCX file is discarded, only the pixel sizes count. For standard fax resolution mode (using font 16): Image Width = (Width in dots)/102 Inches Image Height = (Height in dots)/98 Inches For high fax resolution mode (using font 24): Image Width = (Width in dots)/204 Inches Image Height = (Height in dots)/196 Inches It is better to illustrate PCX file and graphics file using an example. Assuming we need to fax the same business letter to 2 different customers regarding 2 different business issues. We want to include the company logo (logo.pcx) as well as the manager's signature (sign.pcx) in the fax. We can write a template letter like this: --------------------- The file mylett.txt --------------------------------- ~ From: Anthony Mai Box #28, 10 Vairo Blvd. State College, PA 16803 USA ~<$DATE> ~<$TIME> To: ~<$CUSTOMER> ~<$ADDRESS1> ~<$ADDRESS2> Dear ~<$CUSTOMER>: I send this fax to you regarding the business of ~<$BUSINESS>. So and so. So and So. Thank you very much. Sincerely yours, ~ Anthony Mai -------------------------- end of mylett.txt ------------------------------ In this example we have used the following strings: DATE TIME CUSTOMER ADDRESS1 ADDRESS2 BUSINESS The string DATE and TIME has been defined already by QFAX as the date and time when the fax is send. You have to define CUSTOMER, ADDRESS1, ADDRESS2, BUSINESS. You have three ways to define them: a. Add the following configuration lines to the QFAX.CFG file: Define CUSTOMER John_Smith Define ADDRESS1 1200_Maple_Road_Apt._15 Define ADDRESS2 Los_Angeles,_CA_90000 Define BUSINESS QFAX_Shareware b. Use the same configuration like a. But instead of put them in the QFAX.CFG file, put it in a separate file temp.cfg. And in the QFAX command line use -cfg to load the definition: QFAX -cfg temp.cfg mylett.txt 1-800-555-1212 c. Define them on the QFAX command line: QFAX -def CUSTOMER John_Smith -def ADDRESS1 1200_Maple_Road... A note about the '_' used in the string definitions, you have to replace any space in the string with a '_' to make a single word string. QFAX will convert the '_' back to space when faxed. So the received fax will look like this: ------------------------- The fax page sent ---------------------------- ----------------------- From: Anthony Mai | Company Logo | Box #28, 10 Vairo Blvd. | | State College, PA 16803 USA ----------------------- 03/15/97 15:25:03 To: John Smith 1200 Maple Road Apt. 15 Los Angeles, CA 90000 Dear John Smith: I send this fax to you regarding the business of QFAX Shareware. So and so. So and So. Thank you very much. Sincerely yours, ------------------- | sign.pcx | ------------------- Anthony Mai ------------------------- End of the fax page -------------------------- So when you need to send the same letter to next customer. All you need to do is replace the definition in the QFAX.CFG file, or replace the temp.cfg file's contents with new definitions, or change the QFAX command line. * Calling QFAX from your own applications Because of the compact size of QFAX and it's simple DOS command line user interface, you can call QFAX from your own C/C++ application to send faxes automatically. All you need is implement the QFAX command using a single spawnv() function. And by detecting the return value of the spawnv() function your application can find out whether the fax is successful or not. When QFAX is properly configured such calling will be totally automatic and requires no user intervention or keyboard inputs. When you have a C program calling QFAX repeatedly to send fax to different fax numbers, you have built a simple and effective fax broadcasting system! You can probably send between 1000 to 200 faxes in one night using such a fax broadcasting program. And because this new version of QFAX allows you to personalize the fax using a template text file and the string defining feature, you can write a personalized fax broadcasting program easily! I have included a simple C program MANYFAX.C to demonstrate how you can call QFAX from your own application. What manyfax.exe does is very simple: it read the file name and fax number from a list file, one at at time, then it uses a spawnv() function to do the same thing as the DOS command "QFAX filename fax_number", and get the return code, and write the fax result to a log file, and repeat again until all fax numbers in the list has been read in and faxed. The return code from QFAX execution are listed below. You can also find those return codes in the manyfax.c program Return code Meaning 0 FAX Successful. All pages sent. -1 Systematic errors: File not found, Out of Memory or No response from Modem, etc. 1 FAX was aborted due to an error. Only some pages have been faxed. 2 FAX was aborted due to an error. no fax page was transmitted. 3 FAX handshake procedure was unable to finish. FAX aborted. Nothing sent. 4 Unknown error after dialing. Fax link was never established. 5 Unable to determine whether it is a Class 1 or Class 2 fax/modem, so it can't continue to fax. 6 Unable to reset or initialize modem. Probably there a syntax error in the InitString or wrong CommPort number. 10 No Dial Tone on Phone Line. 11 Telephone Line Busy. No connection. 12 A connection wasn't established after dialing, the remote fax is probably not there to receive fax. Please read the manyfax.c program file to see a real example how spawnv function is used to call QFAX and get the return code. Needless to say, it should be very easy for you to modify the manyfax.c and use it to do the specific kind of personalized fax broadcasting you as want. Please feel free to do so. The author will appreciate it if you send a copy of the modified manyfax.c to the author's E-Mail at QFAX@QFAX.COM. I will later release a better generall purpose fax broadcasting program which makes use of QFAX, and I will release both the source and the executable together on my web site as a valuable addition to QFAX V1.08 package. One note: You will definitely have to register QFAX with the author to be able to use QFAX for un-attended automatic faxing, or otherwise QFAX will keep asking for a license number, which will then require some keyboard input to make it continue. Please check the register.txt file for registration information. The current registration fee is still $20 but the author is considering raising the fee in the future due to overwhelming response received of QFAX. * Personalized Batch Fax Sending The included program MANYFAX.C as well as it's executable, though very simple, is a very powerful tool in batch sending personalized faxes. You may simply enter "manyfax" on DOS command line with nothing following it and it will display a help screen to remind you the usage. To use MANYFAX to send personalized batch fax, first you need to prepare a fax list file, second you need to prepare a template text file that will be personalized when faxed. Below is an example template letter: ------------------------- mylett.txt ----------------------------------- From: Mr. Anthony Mai 10 Vairo Blvd. Box #28 State College, PA ~<$DATE> ~<$TIME> To: ~<$NAME> ~<$Address1> ~<$Address2> Dear ~<$NAME>: I am sending you this fax regarding the personalized batch fax sending program I wrote. It makes use of the QuickStar Fax Pro program as a fax engine and it uses the insert user-defined string feature of QFAX to personalized each individual faxes sent. This fax is send using the said program. What do you think about it? Sincerely yours, ~ Anthony Mai ------------------------------------------------------------------------ The strings NAME, Address1, Address2 can be defined to the actual customer name and address when faxed. You have to prepare a fax list that contains these information. The fax list will be very similar to an address book. The following is an example that can be used with the above sample letter: ----------------------- mylist.lst fax list file ----------------------- Name: Anthony Mai Address1: Box #28, 10 Vairo Blvd. Address2: State College, PA 16803 Fax: 1-814-867-1468 Name: John Smith Address1: 500 Main Street Address2: Boston, MA 01568 Fax: 1-213-598-6670 Name: TeleCorp Groups Address1: 312 Midway Road Address2: Portland, OR 20340 Fax: 1-800-234-5678 ------------------------------------------------------------------------ You can see the file is separated into many individual entries. The fax number is the last item define for each entry. It must be the last item for each name because once MANYFAX.EXE reads in a fax number, it will go ahead and send the fax first, before continue reading the rest of the list. Each line defines a string. The format is always like this: The name of the string, followed by the colon (':') immediately, and then by one or a few space keys, then the string to be defined. Unlike in the configuration file or command line syntax, here you do NOT need to replace the space in teh strings into '_'. MANYFAX.EXE will take care of it. The important thing is the ':' must be present for MANYFAX.EXE to read it correctly. When MANYFAX.EXE reads in an entry it will create a temprary configuration file TEMP.CFG, then call QFAX with the "-cfg temp.cfg" option flag. The usage syntax of MANYFAX.EXE is: MANYFAX [-db list_file] [-log log_file] file#1 file#2 .... You can omit either the "-db list_file" part or the "-log log_file" part. The default list file if MANYFAX.LST and the default log file is MANYFAX.LOG. You can specify one, two or many files to be faxed together. Certainly you do not need to specify a fax number. They will be read from the list. Depends on what kind of database system you have, you should have little difficulty creating a fax list file from your customer list database files. Or you can even edit one manually. * Other potential usages Because of the compact size of QFAX and it's capability of being used by other applications as an automatic fax engine, and QFAX sticks to it's core functionalities without attaching too many whistles and sexy bells, the potential usage of QFAX is un-limited. QFAX did not start up as a shareware program. At first I tried to learn fax modem programming and wrote an easy to use fax program since I sent faxes to my wife in China regularly but WinFax is very slow and very inconvenient in send Chinese documents as fax. It was only intended for my own usage so simplicity and speed (to save international phone money!) is my top consideration. It was a great success and so I released it as a shareware program, first a Chinese version, then I change it to an English version. And now I have a Hebrew language compatible version. I received a lot of encouragements from enthusiastic users. Some of them tried to use QFAX on their palmtop computer because the size is so small and it's so easy to use. At that time I didn't even know there are palmtop computers around. Soon after that I developed a HP palmtop specific QFAX program. Later some other user who need to send a lot of faxes suggested that the simple DOS command could be implemented in a C/C++ program easily and by calling QFAX repeated from an automatic program one can do fax broadcasting easily. I probed into that potential usage and later I added the C program MANYFAX.C to show users how to implement QFAX DOS commands in their own application and gain fax capability easily. I am sure there could be other potential usages of QFAX, and I encourage QFAX users to probe into new potential usage and give me feedbacks and suggestions. With your help I will make it better in the future. And you will benefit from the constant improvement of QFAX because once registered, you can alway upgrade to newer versions of QFAX for free! Just keep an eye on my new web site. Any new releases will be shown on my web page first. Please mark this down: http://WWW.QFAX.COM Recently I will be working on a simple and low cost fax on demand program which will give enough flexibility to the users so they can configure it to fit their need, while I will keep the usage as simple as possible. I am also working on a telephone answering program. When I get time I will also develop a Win 95 version of QFAX. =========================================================================== 4. General Troubleshooting Modem can not reset The screen displays Modem reset...Failed This may mean that the CommPort setting in the QFAX.CFG file is wrong. But it could also mean that the modem has a slow response in reseting. If the message following seems to be fine, you do not need to worry about it. Otherwise check the QFAX.CFG and your modem manual for the correct CommPort setting. And try again. If necessary try to cold reboot (turn off the power and turn back on) the computer. If you are running QFAX from the DOS session launched in the MS Windows, and you believe you have used the right CommPort number. it's possible that you have not configured the Com Port correctly in Windows. To configure Com Port in Windows, select the "Main" program group. Then select "Control Panel". Then select "Ports". Then select the Com Port that your modem occupies, click on "Setting". Then you can set the baudrate to be 19200, 8 data bits, none parity, 1 stop bits, and choose "Hardware" flow control. And then click on "Advanced" and set the correct base I/O port address as well as IRQ number. Finally click on OK. You may have to re-start Window for any changes to take effect. Be careful do NOT change any thing for Com1. That's probably the serial mouse port and if you screw up the mouse port the mouse may malfunction. Modem reset OK but initialization failed The screen displays Can't initialize. Error *** This is probably because the modem can not understand the InitString defined in your qfax.cfg file. Check modem manual for a recommendation of the initialization string. Or use the same initialization string used by other fax softwares used on your computer. If it still doesn't work, make the InitString in the QFAX.CFG file the simplest one: InitString AT&F&C1&D2 or InitString AT&F Check the InitString list at the end of this file for a recommended InitString for your modem. Please be aware that no spaces are allowed within the string. And please do not use excessively long InitString. Fax transmission failed or aborted This is generally due to either an in-appropriate InitString for the type of fax/modem you use, or bad telephone line conditions. Or maybe you are communicating to a fax machine in-compatible with regular fax machines. Check your phone line condition and try again. Also try to send fax to other fax number and see if it works. Check the InitString list at the end of this file for a recommended InitString. Please be aware that fax devices in the world are different from each other and most fax equipments divert away from the fax standard more or less. Good fax softwares or fax machines should be able to communicate with most fax machines in the world but fax failures still happen frequently, sometimes even between two fax devices from the same manufacturer. QFAX has been tested thousands of times against many different fax devices to make sure it works reliably. But still there's no guarantee it always works. If you are able to use QFAX to fax to some fax numbers reliably but always fail on some numbers consistently, please contact the QFAX author at QFAX@QFAX.COM. Your problem report will be a very precious information to help to improve the reliability of QFAX. The author is willing to help you to solve problems relate to QFAX, whether you are registered or not. You can find the author contact information in next page of this file, or you may simply type "qfax" on DOS command prompt to see a help screen. --------------------------------------------------------------------------- About shareware programs Shareware is a concept in software distribution. Please notice that shareware softwares are NOT free softwares. Shareware authors believe that like other products, the consumers have a right to try a computer software before making a decision of purchasing it. Shareware programs will allow you to have a 30 days free trial period to try and test the program before you make any payment. You pay only if you find the program useful and you like to keep it. As a shareware author I believe people like you are honest and will be glad to make a flat payment and register the software if you find this program is really useful to you! The shareware concept is good for both the software consumers and software writers, but only with your support will the shareware concept survive and expand. Shareware authors need your support to write more and better shareware products! As the author of QFAX, one of VERY FEW shareware DOS fax programs that is available, and especially it cuts fax transmission time greatly, I wish I can devote more time in making it better and better. But this will not happen unless people register this software with me and show me their support. The QFAX software have been tested thoroughly before formal release so as to make sure it will work on most computers. However I can't provide any guarantee that it will work on your computer. Use it at your own risk. Like authors of most other softwares, the author hereby disclaims any kind warranty or responsibility in regard to your usage of the QFAX software. Please read the register.txt file for a warranty statement before you proceed to use the QFAX software. If you have any questions regarding the QuickStar Fax Pro program, feel free to contact me via E-Mail, Phone or Letter. I can be reached at the address below (Please use E-Mail if possible): Mr. Anthony Mai Box #28, 10 Vairo Blvd. State College, PA 16803 U.S.A. Tel. 1-(814)867-3385(H) 1-(814)867-1468(H) E-Mail: QFAX@QFAX.COM (Prefered) E-Mail: QFAX@USA.NET AOL: QuickStar1@AOL.COM CompuServe: 102773,370 If you want to register QFAX, the registration is quick and easy. And the fee is only $20 (plus sales tax if you are in Pennsylvania). Please read the REGISTER.TXT file for information regarding the benefit you will have in registering, and method of how to register. CompuServe users can register QFAX on CompuServe using SWREG. Just type "go swreg" on CompuServe and it will guide you through. Check out the file register.txt for more detail. Please remember that you still need to E-Mail the QFAX serial number to the author afterward. The SWREG ID number for QFAX is 8913. When you get to QFAX using SWREG, it may show you an older QFAX version. Don't worry about the version. Registered user will always enjoy unlimited free upgrading to latest QFAX version. Once I receive your registration letter I will let you know the valid QFAX license number. You only need to enter that number once. Once you entered that number QFAX will become full functional right away! If you have registered older version of QFAX, please contact the author for an update license number. Thanks! -------------------------------------------------------------------------- For latest version visit World Wide Web site http://WWW.QFAX.COM --------------------------------------------------------------------------