MAX_FAX FACSIMILE SERVER FOR QNX CONTENTS PAGE 컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� MAX_FAX COMMANDS 1 Entering Commands 1 Getting Help With MAX_FAX 2 Sending A Fax 2 Displaying A Received Fax 2 Printing A Received Fax 3 Cutting A Received Fax 4 Marking A Received Fax To Be Saved 5 Unsaving A Fax 5 ADVANCED MAX_FAX COMMANDS 6 Deleting A Received Fax 6 Starting MAX_FAX 6 Stopping MAX_FAX 6 Editing the Send Schedule 7 Clearing Out The Schedule Files 7 SENDING A DOCUMENT 8 Creating A Document 8 Simple Options For Maxsend 9 Advanced Options For Maxsend 10 Maxsend Configuration 12 More About Documents For Maxsend 12 Logfiles 14 Sequence Of Sends 15 Mailmerge By MAX_FAX 16 Flat File 17 Specifying Parameter And Variable Values 18 Notes On Using Variables 20 SETTING UP TELEPHONE LISTS FOR MAX_FAX 21 Phone Number Directory 21 NNX List 21 Creating The Datafile 22 Sending A Fax 22 Receiving Faxes 23 INSTALLATION OF MAX_FAX 24 Hardware Installation 24 Software Installation 25 Modifying Script Files 27 Shutdown 28 Printer Setup 28 DIP Switch Settings 29 MAX_FAX COMMANDS Page 1 ENTERING COMMANDS Commands must be typed in exactly as shown. There must be space between each parameter. There must not be any spaces in the midst of a parameter itself. A command might be long enough to wrap around to the next line. Examples: maxsend letter.doc 287-6614 a=1 p=6 Correct. maxsend letter.doc 287-6614a=1 p=6 Wrong. Space missing between the parameters. maxsend letter.doc 287-6614 a = 1 p = 6 Wrong. Extra spaces in the middle of a=1 & p=6. Required parameters must be entered in the positions shown. Optional parameters may be entered in any sequence, provided that they follow any required parameters. Examples: maxsend letter.doc 287-6614 a=1 p=6 Correct. maxsend letter.doc 287-6614 p=6 a=1 Correct. maxsend p=6 letter.doc 287-6614 a=1 Wrong. Optional parameter where required parameter must be. maxsend 287-6614 letter.doc p=6 a=1 Wrong. Required parameters not in required order. Parameters must be entered with the case shown. Upper and lower case have different meanings. Examples: maxsend letter.doc 287-6614 a=1 p=6 Correct. maxsend letter.doc 287-6614 A=1 P=6 Wrong. GETTING HELP WITH MAX_FAX MAXHELP Page 2 The maxhelp command may be used anywhere to view this document on line. There are no parameters. Note that all commands will briefly remind you of their parameters. QNX4: use maxsend This will display the options QNX2: maxsend ? for the maxsend command. SENDING A FAX MAXSEND This command is used to send a document. It is described in detail under Sending A Document. The simplest form of maxsend is: maxsend letter.doc 1-416-287-6614 This will send the file letter.doc to 1-416-287-6614 DISPLAYING A RECEIVED FAX MAXDSP The maxdsp command is used to display a fax which has been received. The video resolution is determined by the video display adapter. Fax images can be displayed on consoles only. The image is scaled automatically to the width of the display. A solid line is drawn at the end of each page to indicate it. The maxdsp command will determine the fax file to be displayed in two ways. Received faxes are automatically given a filename with an incrementing number. The file rxfax0012 is the twelveth fax received. The most common form of the maxdsp command identifies the fax to be displayed by number, like this: maxdsp 12 This will display received fax file 12 with any one of the following filenames: /max_fax/recv/rxfax0012 /max_fax/recv/p_rxfax0012 /max_fax/recv/s_rxfax0012 This will work when maxdsp is executed in any directory. Received faxes which were copied to another directory, renamed or cut must be identified with their filespec. The other form of the maxdsp command requires specifying the file to be displayed, like this: maxdsp signature.fax signature.fax must be in current directory or in /max_fax/recv maxdsp /fax/logo.fax QNX 4 Note: A parameter -s prior to the faxspec will cause the int10 graphics emulator to use 800x600 mode. If not supported correctly by the hardware, this may lock up your screen ! QNX 2 Note: If you specify a drive as the beginning of the filespec, it will be interpreted to mean a received fax number, for example: maxdsp 3:/fax/logo.fax will display /max_fax/recv/rxfax0003 rather than /fax/logo.fax The following keys may be used during display of a received fax: Page 3 KEY USE 컴� 컴� ESC, Break Exit Downarrow Next Screenful Of Current Page Uparrow Previous Screenful Of Current Page Page Down Next Page Page Up Previous Page Home Top Of Current Page / Top Of First Page Grey Plus Expand Resolution To 1 Screen Pixel Equals 1 Fax Pixel Grey Minus Compress Fax Page Width To Screen Width (Default) Right Arrow Shift Display Right On Fax Page (Expanded Mode Only) Left Arrow Shift Display Left On Fax Page (Expanded Mode Only) * Invert Display For Upside Down Fax NOTE: Quite a lot of processing is required to decompress a received fax image as it is displayed. Each keystroke typed is acted on in sequence, but this may require more time than you expect. Operations are prematurely terminated to begin processing for the next request, which allows paging or scrolling without waiting for the screen to be completely redrawn. Avoid holding down a key and allowing it to repeat, which will require lots of time to process each of those actions. PRINTING A RECEIVED FAX MAXPR The maxpr command is used to print a fax which has been received. This command is actually a script which is modified at installation time to identify the printer which is to be used for output. Often this command is set up on installation to run automatically on each fax as it is received, but it can still be used to reprint another copy of the fax. The maxpr command will determine the fax file to be printed in two ways. Received faxes are automatically given a filename with an incrementing number. The file rxfax0012 is the twelveth fax received. The most common form of the maxpr command identifies the fax to be printed by number, like this: maxpr 12 This will print received fax file 12 with any one of the following filenames: /max_fax/recv/rxfax0012 /max_fax/recv/p_rxfax0012 /max_fax/recv/s_rxfax0012 This will work when maxpr is executed in any directory. If the filename is rxfax#### this command will rename it to p_rxfax#### to indicate that it has been printed. Received faxes which were copied to another directory, renamed or cut must be identified with their filespec. The other form of the maxpr command requires specifying the file to be printed, like this: maxpr signature.fax signature.fax must be in current directory or /max_fax/recv maxpr /fax/logo.fax QNX 2 Note: If you specify a drive as the beginning of the filespec, it will be interpreted to mean a received fax number, for example: maxpr 3:/fax/logo.fax will print /max_fax/recv/rxfax0003 rather than /fax/logo.fax CUTTING A RECEIVED FAX MAXCUT Page 4 Often, only a portion of a received fax is desired. Cut pieces may be used to include your company logo or your signature as part of a transmitted text document. These pieces are cut from a received fax with the maxcut command. The maxcut command is most conveniently used when the maxdsp command is also used in another window. This allows checking the results with a minimum of typing. To cut out a piece of a received fax, maxcut extracts scan lines beginning with the scan line specified and ending at the scan line specified. The extracted piece is saved to a new file in the same format as a received fax file. The original file is not harmed by this process. The maxcut command is entered as follows: maxcut faxfile cutfile f=# l=# {p=#} The faxfile is likely a received fax file. The cutfile is the new file to be created. The parameter f=number is the first fax scan line to save. The parameter l=number is the last fax scan line to save. The p=number is an optional parameter which may be used to specify the page number of a multi-page fax. It is not possible to shift a piece to the left or right on a page. It is not possible to cut a piece which extends across two pages. As an example, lets create a cut piece for including your signature in documents. First write your signature on a piece of paper, then send it with another fax machine to MAX_FAX. Cut the fax, keeping almost all of it. maxcut /max_fax/recv/rxfax0012 /user/linda/signature.fax f=1 l=1000 Change to another window and view the result. maxdsp /user/linda/signature.fax Press ESC to exit maxdsp and change back to the first window. Push the up arrow to recall the previous line typed and change the amount of the fax to be kept, narrowing in to just the part with your signature. (QNX 2 Note that sometimes the command is not recalled correctly by QNX. It is also possible to have an invisible character at the start of the line which will prevent the shell from executing the line - delete it.) maxcut /max_fax/recv/rxfax0012 /user/linda/signature.fax f=200 l=600 Alternately cut and view the fax until only the scan lines which are your signature remain. See the section More About Documents For Maxsend for instructions on how to include your signature in a document. MARKING A RECEIVED FAX TO BE SAVED MAXSAVE Page 5 To avoid manually entering the filename of each received fax which is to be deleted because it is no longer wanted, there is a command which delete them all together. However, if there was a received fax which you wanted to keep, that command would remove it. To avoid this, it is possible to mark a received fax to avoid it being accidentally deleted. The maxsave command will mark a file to be kept by renaming it from rxfax#### or p_rxfax#### to s_rxfax####. The command is entered with the number of the received fax to be saved, like so: maxsave 12 This will mark (rename) rxfax0012 to be saved as s_rxfax0012. UNSAVING A FAX MAXUNSAVE To allow a fax to be deleted after it was protected with maxsave, run the command maxunsave with the number of the received fax to be unprotected. For example: maxunsave 12 This will rename s_rxfax0012 back to p_rxfax0012. ADVANCED MAX_FAX COMMANDS Page 6 The following commands will typically be used by the system administrator. DELETING A RECEIVED FAX MAXDEL Unwanted received faxes may be conveniently deleted with the maxdel command. Specify the fax to be removed by its number, like this: maxdel 12 This will remove p_rxfax0012. This command will not delete a received fax which has not yet been printed or has been marked as protected by maxsave. STARTING MAX_FAX MAXSTART This command is a script file, modified during installation which is used to start the MAX_FAX system. It is usually executed automatically by the system when it is powered up. See Software Installation for more detail. STOPPING MAX_FAX MAXSTOP This command must be used to halt MAX_FAX. This will gracefully shut down the administrator. Faxes in process will be completed, but no new sends or receives will begin. The administrator will finish when all max_card tasks terminate and then maxstop will return. The C-Tree server must be stopped after max_admin. Before shutting off the computer run these commands: maxstop ctstop (QNX 2 only) Documents which are queued to be sent when maxstop is executed will be sent when the system is started next. If the power is lost during operation, documents in the process of being sent will be left in limbo. Run maxsch to delete or resend these documents on an individual basis. Optional parameters may be specified: QNX 4: maxstop -q Suppress max_admin not found message if QNX 2: maxstop +q max_admin not running. QNX 4: maxstop -h Immediate halt ! Faxes in process are QNX 2: maxstop +h terminated and queued for resend. EDITING THE SEND SCHEDULE MAXSCH Page 7 Maxsch is a program will allows examining and modifying the schedule database on the fly. Documents are indexed by four categories: those to be sent, those being sent now, those that were successfully sent and those that failed to be sent. The display of a document includes all of the command line options associated with the document, including the values of the included variables. Maxsch is an interactive program which is simple to use. Only valid entries are accepted and they take effect immediately. Maxsch is primarily used to correct a fax phone number and resend a document. It is also used to delete old entries. The information for a document which is currently being sent cannot be modified. NOTE: If the power is lost while the system is running, the documents currently being sent will be left in limbo. Stop the system with maxstop. Maxsch will now allow those entries marked as "SENDING" to be modified. Press F10 to set those documents to "TO SEND" and then run maxstart. CLEARING OUT THE SCHEDULE FILES MAX_SCHED The schedule files contain all the information MAX_FAX uses to determine which document to send next. The max_sched command should be run occasionally after many documents have been sent to clean out the files and reduce their size. If power is lost while MAX_FAX and C-tree are in operation, it may be necessary to run this command to reset corrupted schedule files. All entries queued in the schedule are erased by max_sched. NOTE: max_sched must be run only when the system is shut down. That is, after maxstop ctstop (QNX 2 only) SENDING A DOCUMENT Page 8 CREATING A DOCUMENT MAX_FAX can send a document of text which you create or it will retransmit a fax which has been received. Let's prepare a simple document and send it, then go on to use some advanced options. The QNX editor ed can be used to create the document. A word processor may be used if the file is saved after editing with the ascii text option. The text is entered just as if you are typing in a letter which you would print off and then mail. Put 60 or fewer lines of text on a page and 86 characters or less on each line. Use a form feed as the first character on the line to begin a new page. vedit: Type Ctrl-P Ctrl-L ed: Type Ctrl-L If you are using a word processor, you will probably use other keystrokes to activate the force a new page function. If you use tabs, they will be spaced in 4 character intervals. With vedit, type Alt-C to change the tabs if required. Type in a letter similar to this one with your favourite editor: March 1, 1990 Laura Smith Super Electronics Limited 11 Fortune Gate Scarborough, Ontario M5C 4P3 Dear Laura, Thank you for your order ! Enclosed is the credit application which you requested. Please have it filled out today by your accounting department so we will be able to ship your order tommorrow. Regards, Paul Davidson Save the file as letter.doc Send letter.doc as a fax by typing this command: maxsend letter.doc 1-416-287-6614 Enter the telephone number with the same digits as if you were dialing a telephone. The telephone number shown can be used to send this test fax to Qenesis Inc. or you can send this test fax to a friend. The maxsend command is used to enter the fax into a C-Tree database containing a list of documents to send. This document will be sent in priority order, along with other documents which may be ready to be sent. If for some reason the transmission does not get through, (perhaps the receiving machine is busy) MAX_FAX will automatically make up to 6 attempts to send it. SIMPLE OPTIONS FOR MAXSEND Page 9 The maxsend command has many options. Some simple ones which might be commonly used will be described first. These options may be used in combination. Maximum Attempts If you are uncertain of a fax phone number you may not want MAX_FAX to make 6 attempts at sending. On the other hand, if a fax machine to which you wish to send is notoriously busy you may wish to try more than 6 attempts. The number of attempts may be specified when you send the document by adding a=# to the end of the command. For example, this command will make only 2 attempts: maxsend letter.doc 1-416-287-6614 a=2 MAX_FAX will continue to make attempts until the document is sent successfully or the maximum number of attempts have been tried. Delayed Send You may wish to send your document at a future time, perhaps to take advantage of less expensive telephone rates. Specify the time at which the first transmission attempt should begin by adding t=time to the end of the command. The send may be delayed by up to 23 hours and 59 minutes. The time may be entered in many forms which will be recognized, such as these examples: maxsend letter.doc 1-416-287-6614 t=11:00pm each of these is the maxsend letter.doc 1-416-287-6614 t=1100p same time: 11:00pm maxsend letter.doc 1-416-287-6614 t=11p maxsend letter.doc 1-416-287-6614 t=23:00 maxsend letter.doc 1-416-287-6614 t=2300 maxsend letter.doc 1-416-287-6614 t=23 maxsend letter.doc 1-416-287-6614 t=2:00am each of these is the maxsend letter.doc 1-416-287-6614 t=0200a same time: 2:00am maxsend letter.doc 1-416-287-6614 t=0200 maxsend letter.doc 1-416-287-6614 t=02 Mail Notification If you have Mail or some other system which responds to the same command, MAX_FAX can notify you by mail of the results. The defaults chosen when MAX_FAX was installed will determine if this will happen automatically without you specifically requesting it. In any case, you can override this default when you use the maxsend command by adding n=? at the end of the command. There are three possibilities. No = MAX_FAX will not send you a message. Yes = MAX_FAX will send a message of success when the fax has been sent, or a message of failure after the last attempt failed. Error = MAX_FAX will only send a message of failure after the last attempt failed. Enter the command like this: maxsend letter.doc 1-416-287-6614 n=y send a message maxsend letter.doc 1-416-287-6614 n=e send a message if failure maxsend letter.doc 1-416-287-6614 n=n do not send a message maxsend letter.doc 1-416-287-6614 n=d use max_admin default maxsend letter.doc 1-416-287-6614 user max_admin default ADVANCED OPTIONS FOR MAXSEND Page 10 Priority Each document to be sent has an associated priority so MAX_FAX can send the most important documents first. Priorities are most useful when sending many faxes. With only a few to send, then the priority is unimportant since each will be sent promptly anyway. The priority levels are valued as 0 to 9. Zero is the highest and sent first. More than one document may have the same priority value, in which case the document are sent in order of submission. The priority is specified by adding p=# to the end of the maxsend command, like this: maxsend letter.doc 1-416-287-6614 p=2 send with priority 2 If the priority is not specified with the maxsend command, a single document submitted will have a priority value of 4. If a group of documents are submitted together (more on multiple sends later), they will each have a priority value of 6. Thus, without specifying the priority, single sends will be sent before all of those submitted for a mass transmission. Font Group III fax machines may transmit with 2 different resolutions. Normal scans 100 lines per inch on the paper. Fine resolution scans 200 lines per inch, which improves the quality of the image sent, but requires twice the data to be sent (also requiring twice the transmission time). Fine is used only for very detailed images. The resolution must not be changed during a transmission. MAX_FAX supports two text character fonts for each resolution; standard and compressed. Compressed allows more characters per line than standard. The font and the graphic resolution are both specified by adding f=# at the end of the maxsend command, such as in these examples: maxsend letter.doc 1-416-287-6614 f=0 normal, standard maxsend letter.doc 1-416-287-6614 f=1 fine, standard maxsend letter.doc 1-416-287-6614 f=2 normal, compressed maxsend letter.doc 1-416-287-6614 f=3 fine, compressed There is no image improvement for text only documents in fine resolution. Received faxes which were sent to MAX_FAX in fine mode may be sent again in either normal or fine resolution as desired. Group If there is more than one MAX_FAX card in your system, the cards may be grouped. This is determined by the installation. The cards will be grouped by the type of telephone line they are connected to. This permits directing a document to be sent on a particular telephone line. Local sends would be on a local line, long distance sends might be on an OUTWATTS line and receives may be come in on yet another line or group of lines. Many cards may be in the same group, or each card may be in a group of its own. The group which the document is to be transmitted by is specified by adding g=# to the end of the maxsend command. If g=A is added, the group will be adaptive. If a local call, the selected group is 0. If a long distance call, the selected group is 1. If the group is not specified, then the group will be group 0. Examples: maxsend letter.doc 1-416-287-6614 g=2 use a card in group 2 maxsend letter.doc 1-416-287-6614 g=5 use a card in group 5 maxsend letter.doc 1-416-287-6614 g=A use a card in group 0 or 1 Error Message Output The error messages output by maxsend may be directed to a file/device by adding o=spec. Example: maxsend letter.doc 287-6614 o=/log/errfile Page 11 IF YOU SPECIFY THE GROUP, BE ACCURATE, SINCE A DOCUMENT TO BE SENT BY A GROUP WHICH DOES NOT HAVE ANY CARDS, WILL NEVER BE SENT. NO ERROR MESSAGE WILL BE ISSUED SINCE A CARD BELONGING TO THE GROUP MAY BE INSTALLED ON A NODE WHICH IS NOT UP. THE DOCUMENT WOULD BE SENT WHEN THAT COMPUTER IS TURNED ON. Header String Each fax machine identifies itself to the machine at the other end when the two first connect. Twenty characters (typically the telephone number the fax is connected to) may be used. They may be any printable ASCII characters, but not graphic characters. The header string printed on the top line of each page includes this identification string. On installation of MAX_FAX, this string is defined by default and the value will be used unless another is specified by adding h="max 20 char string" at the end of the maxsend command. Example: maxsend letter.doc 1-416-287-6614 h="QENESIS INC." To suppress the entire information line at the top of the fax include the parameter h=n. Page numbers are suppressed also. Logfile Each send submitted is logged to permit checking the sends requested and the results. Unique files are used for each user, by user name. By default the files will be: /max_fax/sendlog.paul the sends requested /max_fax/sent.paul the sucessful sends /max_fax/notsent.paul the failed sends If you desire the logs to be kept in a specific directory, it may be specified by adding l="dir/dir/dir" on maxsend command line: maxsend letter.doc 1-416-287-6614 l=/logfiles This option is particularly useful to track each send if you are sending many documents on behalf of a variety of clients. User Name Many options use the user login to separate results for each user. This allows you to look at log files which contain only references to requests you have made without scattering them amongst those of other users. If you desire to separate these further, specify a unique user name by adding u=name at the end of the maxsend command. This name will be used for the sendlog filename, the sent filename, the notsent filename and mail notification. For example: maxsend letter.doc 1-416-287-6614 u=ar for accounts receivable maxsend letter.doc 1-416-287-6614 u=promo for promotions This option is particularly useful to track each send if you are sending many documents on behalf of a variety of clients. The user name may be null if you wish to omit .user from the end of the log filenames. Extention If you wish to allow a fax number of less than seven digits, add the parameter e=y, otherwise maxsend will return an error that the number is too short. MAXSEND CONFIGURATION Page 12 The default values for maxsend are configurable. There are defaults built in to the MAX_FAX system which will be used unless other options are specified. Configuration files may be used to alter the defaults used network wide or by each individual user. The maxsend configuration file is called maxsend.cfg and is searched for first in the current directory, next in the user's home directory and last in the /max_fax directory. The first one found is used, the rest are ignored. That is, the options of more than one configuration file will not be merged. Options specified in a configuration file always overide the system defaults. Options specified with the maxsend command will always overide the values in the configuration file. The format of the configuration file is quite flexible. Each option may be specified on the same line, separated by one or more spaces, or on separate lines. The document name, telephone number and flatfile may also be specified in the configuration file ! In your application, it may be convenient to set up different mass sends in different directories and enter all the command options in the configuration file in each directory. MORE ABOUT DOCUMENTS FOR MAXSEND MAX_FAX can send a text document or resend a received fax. Received faxes may be included with text documents which are sent. Cut pieces of received faxes may also be included with text documents which are sent. This may be used to send complete pages previously received or to add graphics such as logos or signatures. Graphics need to be received as a fax, then the piece to be included must be extracted with the maxcut command. If a complete received fax is to be included, it need not be cut. Received Faxes Received faxes are automatically saved in the directory /max_fax/recv. Filenames are created when faxes are successfully received with accending numbers. The first is rxfax0001 and the next is rxfax0002 and so on. A received fax printed by maxpr is marked as such by modifying the filename with a leading p_ to produce p_rxfax0001. A received fax may be marked special with the maxsave command if you particularly want to save it by modifying the filename with a leading s_ to produce s_rxfax0001. It is best to leave received faxes in the /max_fax/recv directory and named as they are since many commands allow referencing these files easily by number. For example: maxpr 125 print /max_fax/recv/rxfax0125 or /max_fax/recv/p_rxfax0125 or /max_fax/recv/s_rxfax0125 Commands which allow referencing by number will operate on these files when executed from any directory. A piece of a received fax cut by the maxcut command will maintain the exact file format as a received fax and may be named anything and saved in any directory. ASCII Documents Page 13 Text documents must contain printable ASCII characters hex 20 to 7E, plus the extended graphics characters, hex 80 to FE. This means that special printer control codes such as ESC E will print an E only. A few graphics characters have special meaning to MAX_FAX and will not be printed. 86 characters per line with standard font and 132 characters per line with compressed font are permitted. Characters beyond this limit wrap around to the beginning of the same line and make an interesting mess. Four position tabs are supported. A maximum of 60 lines of text fit on a page. New pages must be forced with a form feed 0C hex or an extremely long page will result. Newlines may be the QNX 4 and UNIX 0A hex, QNX 2 record separator 1E hex, or DOS carriage return and line feed 0D 0A hex. This means that imported documents need not be converted ! Files may be merged within a text document during sending. Another text document may be included or a received fax (or a cut piece of one) may be included. Includes may be nested five levels deep. To include a file, begin a text line with the special character � and follow it immediately with the complete filespec of the file to be included. The character � is hex code AF which can be generated by typing ALT A F. EXCEPT for a form feed character which may be used to begin a new page, the character � MUST be in the first position on the line. The complete filepath must be specified, since the MAX_FAX background tasks are not running within your current directory. The include must be the only thing on that text line. No new pages are automatically generated, so short pieces can be merged on the same page. The length of an included file cannot be predetermined, so it is necessary for you to include form feeds as required to begin new pages where desired. Examples of includes: �/user/linda/signature.fax include a signature �/max_fax/recv/p_rxfax0001 include a received fax �/letter/para1.doc include a paragraph of text �/brochures/max_fax.fax include a received fax Lets do an example of a letter with 2 included pieces of received faxes. (NOTE: space at beginning of lines is non-existent, just used for readability) Improving letter.doc: �/fax/logo.fax March 1, 1990 Laura Smith Super Electronics Limited 11 Fortune Gate Scarborough, Ontario M5C 4P3 Dear Laura, Thank you for your order ! Enclosed is the credit application which you requested. Please have it filled out today by your accounting department so we will be able to ship your order tommorrow. Regards, �/user/paul/signature.fax Paul Davidson LOG FILES Page 14 MAX_FAX produces a variety of files containing logging information which is quite useful in determining the status of fax documents. A variety of files log documents queued, sent and failed, separately for convenience. Batches of documents may be logged in individual files. The log files are stored in the directory /max_fax. Received faxes are listed in the file /max_fax/receive.log This file may be viewed by typing: maxlog As a default, each user has 3 separate log files containing only information about sends which they requested. The sendlog file contains a list of each document submitted along with the parameters specified. /max_fax/sendlog.linda Linda may view the contents of this log file by typing: maxsendlog The sent logfile contains a list of documents successfully sent, along with the date and time of the transmission. /max_fax/sent.linda Linda may view the contents of this log file by typing: maxsent The not sent logfile contains a list of documents which were not sent. Along with the date and time of the last attempt is the error message of the last attempt. MAX_FAX made as many tries as determined by the maximum number of attempts without success before giving up. A few errors will cause MAX_FAX to give up after the first attempt. For example, if the document file to be sent cannot be opened. /max_fax/notsent.linda Linda may view the contents of this log file by typing: maxfail or maxnotsent The maxsend command allows the name of the user to be changed. This feature is used to further separate the logfiles by client or by function. A single file is used to log operational errors encountered by MAX_FAX. Error messages printed on displays often go unnoticed. These errors are also copied to a file so that they may be reviewed. /max_fax/error.log This file may be viewed by typing: maxerror SEQUENCE OF SENDS Page 15 If many faxes are queued to be sent, the order of attempts will be as follows: if a MAX_FAX card is ready to send, it requests a document the search for a document is restricted to the group the card belongs to the search begins with priority 0 at the oldest time if the time to send is prior to now, the document is selected, otherwise the search continues with the next priority until a document is selected if all priorities have been tested, the card may receive calls NOTES: If two documents in the same group are due to be sent the highest priority will be attempted first. Documents for different groups are never compared in the decision of which to send. If a send fails, the delay time after the previous attempt is doubled (to a maximum of 16 min) and the new delay time is added to the time now which becomes the new time to send. The delay times between sends currently are (in minutes) 1,2,4,8,16,16,16,... The effect of this is to make retries soon after the initial attempt in case the fax machine was busy, and then lengthen the delays so that all attempts are not made before the receiving machine gets the paper roll changed. If many documents are queued roughly at the same time, each will get an initial attempt before any get retried, because the time to send is sorted as later. It is also possible for a lower priority document to be sent during the retry delay of a higher priority document. If a fax is to be sent with priority 0, the delay time between attempts will be 1 minute (as opposed to decaying to 16 minutes). ***** PLEASE NOTE ***** If a telephone number is incorrect, all retry attempts will occur. If you are sending late at night to save telephone charges, this could be extremely annoying to some people ! Please verify fax numbers ! MAILMERGE BY MAX_FAX MAXSEND Page 16 Mailmerge means that a letter is sent to many different people, but each letter is customized so that it is unique for that person. It is usually addressed with their own name and address and often the body of the letter is modified to include information unique to that person. This is achieved by creating a letter containing variables which will be filled in with unique data at the time of transmission. Variables A variable is a place holder for information which will be filled in with data while the document is being sent. MAX_FAX permits 26 different variables which are labeled A through Z. A variable is identified in the ASCII document by preceeding the variable name with the special symbol � (obtained by typing ALT E F). Lets create a letter as an example. The following variables will be used: �L Last name �F First name �S Salutation �A Address �T Town �P Province �C Postal Code Wherever these variables appear in the document, data will be filled in during transmission. Other than the variables representing a few items, the letter is entered exactly as a standard letter would be. The letter: (/user/linda/brochure.doc) �/user/linda/logo.fax March 1, 1990 �F �L �A �T, �P �C Dear �S �L, Thank you for your recent enquiry regarding our products. Enclosed are the brochures you requested. If I can be of further assistance please call me at (416) 287-6593. Sincerely, �/user/linda/signature.fax Linda Davidson FLAT FILE Page 17 The data required to fill in the variables is presented in a "flat file". The file must consist of data in columns with one line per document to be sent. This file can be easily created. One method is to redirect the printer output to a file and print the customer name and address list. All database programs provide some facility to do this. The following file will be used in the examples: (/user/linda/cust.dat) Johnson David Mr. 121 Elm Street Toronto Ontario M1C 5B9 293-4567 Black Jim Mr. 10 King Street Scarborough Ontario M2D 5L7 287-6614 Smith Pam Mrs. 454 Hills Road Kingston Ontario K2G 2S1 1-705-992-4321 Murray Bill Mr. 6 Quiet Court Markham Ontario L1D 7X8 294-4567 Jones Tricia Ms. 59 Park Avenue North York Ontario M4Q 7Y8 986-3456 For the second line, the letter would actually be sent as follows: (company logo would appear here) March 1, 1990 Jim Black 10 King Street Scarborough, Ontario M2D 5L7 Dear Mr. Black, Thank you for your recent enquiry regarding our products. Enclosed are the brochures you requested. If I can be of further assistance please call me at (416) 287-6593. Sincerely, (signature would appear here) Linda Davidson The maxsend program scans the flat file. For each line in the file, a fax is scheduled. This is similar to issuing a maxsend command once for every line in the flat file. If an error is found on a line a fax will not be sent for that line but processing will continue for the other lines. A fatal error will halt processing immediately, for example, if the flat file could not be opened. SPECIFYING PARAMETER AND VARIABLE VALUES Page 18 Parameters are items which modify the behaviour of the program or the conditions under which the fax is sent. For example, the number of attempts or the priority of the fax may be specified. Parameters default to a predetermined value if not specified. See Simple Options For Maxsend and Advanced Options For Maxsend for details on the use of each of the parameters. Parameters are identified on the command line with lower case letters. Variables are strings which can be merged into the document. Variables default to nothing if not specified. Variables are identified on the command line with upper case letters. Any parameter and any variable may be specified to have a constant value which would be the same for every document to be sent. Often, however, the parameters and variables have different values for each document sent. The values are taken from the specified field in the flat file. A parameter or variable with a constant value is given with = Examples: a=6 specifies the number of attempts to be 6 p=5 specifies the priority of the document to be 5 A=Jeff specifies the variable �A to be replaced with Jeff S=�/user/jeff/signature.fax specifies the variable �S to be replaced with �/user/jeff/signature.fax A parameter or variable with a different value for each line is given with } The field containing the data is identified by the column it begins in and the number of characters for the length of the field. Trailing spaces can be kept if desired by adding a period to the end of the specification. Examples: a}10,2 specifies the number of attempts to be the value in the field beginning at column 10 for 2 characters p}133,1 specifies the priority of the document to be the value in the field beginning at column 133 for 1 character A}50,22 specifies the variable �A to be replaced with the value in the field beginning at column 50 for 22 characters S}75,30. specifies the variable �S to be replaced with the value in the field beginning at column 75 for 30 characters, keep trailing spaces The command is to be entered in the following form: maxsend x=flatfile document telephone {optional parameters and variables} The actual command for the example would use the following fields: VARIABLE DESCRIPTION FIELD PARAMETER �L Last name 1,9 L}1,9 �F First name 10,8 F}10,8 �S Salutation 18,5 S}18,5 �A Address 23,16 A}23,16 �T Town 39,12 T}39,12 �P Province 51,8 P}51,8 �C Postal Code 59,8 C}59,8 Telephone number 67,14 }67,14 The command as entered: Page 19 cd /user/linda maxsend x=cust.dat brochure.doc }67,20 L}1,9 F}10,8 S}18,5 A}23,16 T}39,12 P}51,8 C}59,7 a=1 p=5 This command will pass through the flat file and try to fill each variable. No sends will be scheduled. An error message will be given for any line which cannot be interpreted. The message will indicate the problem parameter and the line in the flat file. The message will indicate either error or warning. An error occurs if the line could not be processed. If this was not actually a test pass no fax would be submitted for this line. A warning is given if the value matched to a parameter was not legal. A default value was assigned instead. If this was not actually a test pass, a fax would have been submitted for this line with the substituted value. If any warnings or errors are given, the flat file should be corrected. To actually submit the documents for sending the parameter c=n is added to the end of the command. maxsend x=cust.dat brochure.doc }67,20 L}1,9 F}10,8 S}18,5 A}23,16 T}39,12 P}51,8 C}59,7 a=1 p=5 c=n The maxsend command will report the number of lines in the flat file and the number of documents submitted. The maxsend command can often get quite tedious to enter. Most often you will continue to use the flat file with the same field definitions. In this case, a very simple script can be created so that the line need not be entered repeatedly. To create a script: Edit a file and type in the command. Add $1 $2 $3 with QNX 4 or #1 #2 #3 for QNX 2 after the command so that it may be modified slightly without having to edit the file frequently. Tell QNX that the file is an executable script. For example, lets create the script /user/linda/testscript maxsend x=cust.dat brochure.doc }67,20 L}1,9 F}10,8 S}18,5 A}23,16 T}39,12 P}51,8 C}59,7 a=1 p=5 #1 #2 #3 QNX 4: chmod a+x testscript QNX 2: chattr testscript a=+e Now to issue the command just type: testscript This saves a lot of typing and avoids entry errors. This ran the check pass on the database. Run it again to submit the documents. Also, change the number of attempts to 4. testscript c=n a=4 Note that the number of attempts parameter was already entered in the script. An optional parameter may appear more than once on the line. The last value is the one that is used. NOTES ON USING VARIABLES: Page 20 Each variable may occur more than once in the document. Two different variables may take data from fields which overlap in the file. A variable may contain the name of a file to be merged into the document. Merged documents may also reference the variables ! An empty variable will not fill any space in the document. The trailing spaces of a variable are removed so that Markham , Ontario becomes Markham, Ontario. If you are filling in a form, you would require the variable to always insert the same number of characters. Add a period to the end of the parameter to disable trailing space removal. Examples: T}39,12 Remove trailing spaces T}39,12. Keep trailing spaces The total length of the strings in all variables cannot exceed 256 characters including one termination character for each variable up to the last one used. For example, if the variables A, C, and F are used, 6 termination characters are stored (for ABCDEF) so the maximum length of the total of the three variables is 256 minus 6 equals 250 characters. SETTING UP TELEPHONE LISTS FOR MAX_FAX Page 21 Telephone lists in MAX_FAX serve two functions, using names instead of numbers for dialing and automatically dialing correctly for long distance and local calls. Two data files are entered which contain the needed information. A program is run which creates the data file which is used by MAX_FAX. PHONE NUMBER DIRECTORY This directory is a list of names and their fax phone numbers. Each user may have a directory of their own or they might use the default directory. Edit the file /max_fax/maxsend.tel or another filename in your current directory. Enter the information as: name fax phone number Each entry must be a different line. The names and numbers must not contain any spaces. The name must be right at the beginning of the line. The number is separated from the name with as many spaces or tabs as you desire. Upper and lower case may be used but are not unique. Save the file. Example: Qenesis 1-416-287-6614 QNX 1-613-591-3579 NNX LIST MAX_FAX will automatically determine if a number which was entered as long distance is actually a local number and dial it accordingly. For example, a fax machine in Toronto is dialed from Vancouver long distance as 1-416-287-6614. Dialed locally within Toronto, the same machine is dialed as 287-6614. Many databases will produce a flat file with 1-416-287-6614 so it is necessary to strip the 1-416 from the number. To do this, the long distance prefix plus a list of local exchanges is needed. Sometimes more than one list is necessary, depending on your local telephone network. As many lists as required are entered into the same file as follows: Edit the file /max_fax/maxsend.nnx (or another filename in your current directory). Enter the information as: Example: 1st line: string to match 1-519- 2nd line: string to replace it with (empty line) 3rd line: tab exchange > 754 more lines: tab exchange (repeat as required) > 755 line: new string to match 1-519- line: string to replace it with 1- more lines: tab exchange (* matches all exchanges) > * The above example will dial 1-519-287-6614 as 287-6614 (a local call) and dial 1-519-296-9876 as 1-296-9876 (a long distance call within own area) A match string must begin the line without any spaces or tabs. A replacement string must be on the line following the match string and must begin the line without any spaces or tabs. Exchanges are identified with a single tab beginning the line. As many exchange lines as required may be entered. An asterisk will match all exchanges. CREATING THE DATAFILE Page 22 With the two files maxsend.tel and maxsend.nnx entered, run the command to create the data file for the maxsend command as follows: maxphone This will create /max_fax/maxsend.dat If you are creating multiple versions enter any of the three filespecs which are not the default as: maxphone {t=telephone.file} {n=nnx.file} {d=data.file} For example, if you have a unique telephone file in your home directory and you wish to use the default nnx file, enter: cd (which changes to your home directory) maxphone t=myphone.tel d=maxsend.dat This will create maxsend.dat in your home directory. When you issue the maxsend command now within your home directory, your custom data file will be used. If maxsend.dat is not found within the current directory when the maxsend command is issued, /max_fax/maxsend.dat is used if it exists. Since all users will not need this file, no error message is issued if no file is found. SENDING A FAX To send a fax to a number which is contained in the data file, enter the name instead of the number as: maxsend letter.fax qnx The fax number for QNX will be used if found, otherwise the error message Error, no telephone number listed will be shown. Names may be used when doing multiple sends with a flatfile. RECEIVING FAXES Page 23 Sometimes it is desirable to perform certain functions when a fax is received. MAX_FAX can automatically print faxes if desired, but it can be configured to perform different operations on faxes received from different sources. Each fax machine contains a 20 character identification which it exchanges with the other fax machine when they first connect. Naturally this ID string can be used to identify a particular machine. The file /max_fax/maxrx.list contains a list of ID strings and operations to be performed when a given ID is matched. Thus it can easily be arranged for you to be given a mail message for instance whenever your most important customers send you a fax. It is also possible to recognize a machine and do absolutely nothing with the fax. This is great for not printing "junk mail" faxes or deleting them. The structure of the /max_fax/maxrx.list file is quite simple. A line containing an ID string is followed by one or more lines which are to be executed if the string is matched. This sequence is repeated for as many IDs as required. Comment lines may be included with " as the first character on the line. ID lines must be precisely 20 characters long and must exactly match the ID sent by the remote machine. Check the receive log which lists the ID string for each fax received. Spaces must be included exactly. A line beginning with the character @ will be a header line which will match every ID which was not previously matched. It may be included near the end of the list to print faxes received from unidentified machines. Execution lines are all the lines following the ID line, which begin with a tab character. They will be executed one after the next if the ID matches. Execution terminates when the next ID line is encountered. An execution line may contain one or more occurances of the character ~ which will be replaced with the received fax number. eg. 613 519 3579 > maxpr ~ will execute the following whenever a fax is received from QNX. maxpr 1234 where 1234 happened to be the fax number in this instance. An example pf a complex file is included. QNX 4: /usr/lib/max_fax/examples/maxrx.list QNX 2: /max_fax/source/maxrx.list NOTE: Turn on the display of blanks and tabs to make editing this file easier ! vedit: Alt-C Display Newline character 174 Tab character 16. ed: Alt-T Alt-B INSTALLATION OF MAX_FAX Page 24 HARDWARE INSTALLATION 旼컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� � � � DO NOT DO ANYTHING WITHOUT THE COMPUTER POWERED OFF ! � � � 읕컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴� Handle the board carefully to avoid damage by static. Touch a large metal object first, hold the board by the edges only and avoid touching the gold edge connector. Set the base address of the MAX_FAX cards as shown below. Each card must occupy a different address, which also must not conflict with other devices in your computer. Interrupts are not used so many cards may be installed in a single machine. An expansion chassis may be used to provide more available slots. The max_card task will try any address within the first 1M range. See the table of settings for popular addresses. DIP SWITCH SETTINGS: NOTE: Switch Off - Bit Value 1, Switch On - Bit value 0 Dip Switch 8 7 6 5 4 3 2 1 Address Bit 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 Address Value 1 X X X X X X X X 0 0 0 0 0 0 0 Addresses in the range D000 to DFFF are good choices since that range is most often used for Expanded Memory which is not usually installed in a QNX system. Refer to the table of dip switch setting for some popular choices. Seat the board firmly in any 8 or 16 bit slot and screw it down. Connect the supplied telephone wire to the telephone wall jack and the jack on the board slot cover which is closest to the volume control knob. Note that the board requires a full ring signal to answer and may not respond to some internal telephone systems or call routing devices. A telephone or other device may be connected to the jack on the slot cover which is closest to the motherboard. A device connected to this jack will be disconnected during fax operations. Time to test the hardware ! Start up the system and stop any tasks which keep files open, in case of problems. SOFTWARE INSTALLATION Page 25 TESTING MAX_FAX CARDS MAX_FIND To determine what addresses cards are actually installed at and if the cards are functional, run max_find. This program reads all of memory from A000 to EF80 to find the board(s). The addresses are listed as cards are found. For addresses set outside this range - you are on your own. Max_card will work at any address within 1M provided it does not conflict with other hardware. Memory on other cards may be read by max_find which may alter their behaviour ! Problems are quite unlikely but it is best to be on the safe side. Only run max_find when the system is ready for a shutdown. That is, no other users and only necessary tasks are running. Reboot the computer after running max_find. BACKGROUND TASKS MAX_FAX Administrator max_admin is the administrator which controls all the MAX_FAX cards. Only a single instance of the program is run in the background, typically on the server machine. WITH QNX 2 ONLY, the Clearinghouse (network systems only) and the C-Tree server are required and must be started before max_admin. max_admin parameters: k=y Keep partial receives, that is faxes received with errors. k=n Do not keep partial receives. n=y Notify user with Mail that fax was sent or not. n=e Notify user with Mail when fax could not be sent. n=n Do not notify user with Mail. NOTE: alternative mail systems may be used by replacing the mail command. QNX 4: max_admin shells 'mailx -s "fax docspec sent" user