******************************************************************** * These notes are based on the BETA test documentation of BBS2FAX. * * They have subsequently been encorporated into MANUAL.HTM * ******************************************************************** The entire FAX32 documentation has been re-written in HTML format and is included with your distribution as MANUAL.HTM It is also available at http://road.com/fax32 The beta test included TPL sources which are not included in the production release. (If you really want them, ask.) BBS2FAX DOCUMENTION ------------------- These notes describe FAX32's integration into TSX-BBS and have been designed for both the end user and developer. Reference in these notes is also made to the FAX32 documentation and the SMTP2FAX documentation. The whole thing is in MANUAL.HTM CONTENTS -------- Installation Distribution Notes Overall Program Logic and Components Message Base 5 Fax addresses and address book entries Entering a fax-email message Dot commands INSTALLATION ------------ The file UPGRADE.ZIP at our FTP site (road.com) in the FAX32 directory is appropriate if you are already running Version 2.22 or greater. Otherwise, it is recommended that you obtain a complete FAX32 distribution. It is available at our FTP site (road.com) in the FAX32 directory. It is called FAX32.ZIP and is about 2.3MB. If you do not yet have FAX32 installed, you should do it first. Follow the installation procedures for FAX32. Insure that AUTOFAX.EXP is running as a detached job. Confim that FAX32 is working properly. Whether you're installing FAX32 from scratch or just the upgrade, you'll need a FAX32 installation key. Remember to insure that FAXWAIT and/or FAX32 is NOT running at the time you enter your installation key. A version of TPR.EXP dated on/after March 19/97 is required due to changes made by Dan Cappannari in support of FAX32 requirements. Copy the following to FAXSY: ---------------------------- FAX32.EXP (requires an installation key) BBS2FAX.TPR FAX2BBS.TPR SAMPLE.CON (edit to your requirements and rename BBS2FAX.CON) SYMBOLS.EG (edit to your requirements and rename SYMBOLS.BBS) Schedule BBS2FAX.TPR to run periodically. Documentation ------------- BBS2FAX.DOC (this file) Source files (for development purposes) --------------------------------------- The following source files are not necessary to run the system. They are available to the developer who might wish to make his own modifications. BBS2FAX.TPL FAX2BBS.TPL GETREC.INC (Note: logical SMTP2FAX: is used for this #include) PASSFAIL.INC (Note: logical SMTP2FAX: is used for this #include) DISTRIBUTION NOTES ------------------ The TPL programs that make up the distribution are provided in source (.TPL for developers who wantthem) and executable (.TPR). The command TPR BBS2FAX VERSION displays the Version Date of BBS2FAX.TPR The command TPR FAX2BBS VERSION displays the Version Date of FAX2BBS.TPR OVERALL PROGRAM LOGIC and COMPONENTS ------------------------------------ FAXSY:BBS2FAX.CON is the text editable Rule file that BBS2FAX uses to Pass or Fail fax telephone number addresses and apply any telephone number prefixes (see SMTP2FAX.DOC for a more detailed explanatin of pass/fail rules) Your distribution contains SAMPLE.CON which is a sample of such a file. You should make your own FAXSY:BBS2FAX.CON BBS2FAX.TPR should be scheduled to run periodically. It reads through the Fax email message base for all messages that need processing. Each intended recipient address of these messages is evaluated against the pass/fail rules in FAXSY:BBS2FAX.CON to determine whether or not they are acceptable. An unacceptable recipient causes a "failure" email message to be sent locally from "faxclerk" to the original sender. The message will indicate the reason for the rejection. An "acceptable" recipient does not guarantee success. FAX32 may later report a failure if it cannot deliver the fax. Acceptable messages are processed for "dot commands". Dot commands (see below) may be used to enhance the image of the resultant fax, allowing extensions beyond the traditional appearance of an email message. They may cause effects, such as font changes; or file inclusions, such as canned text, a graphical image of your signature, company letterhead, etc. The resultant text (which includes an appended FAX32 command) is written to a file in the AUTOFAX directory. AUTOFAX.EXP (See FAX32 documentation) periodically picks up each file in the AUTOFAX directory, pulls the FAX32 command out of it, moves it to autofax:good\ and initiates FAX32.EXP. (Generally you should find this directory is empty.) FAX32.EXP When FAX32 has finished its fax attempt(s), it executes FAX2BBS.TPL with arguments specifying a BBSID as well as a success or failure indicator. FAX2BBS.TPL updates the record in Message Base5 (per BBSID) by either clearing the UNPROCESSED flag (for a success) or by clearing UNPROCESSED and setting FAIL (for a failure). Note: In addition, FAX2BBS also sets FLAG#31 (ie the last of the 32 flag bits that S&H uses for its messages). This bit (amongst almost 20 others) is undocumented. Although S&H has no current plans to use this flag, it is officially reserved for their use. FAX32 uses this flag in order to support message "resends". Although it is unlikely, it may become necessary to change this. Message Base 5 -------------- S&H has "officially" designated Message Base number 5 for FAX. You must define Message Base 5 for route=fax in your BBS. This will be in addition to other routes (such as Local and Internet) that you already have. In SYSOP - Mail Setup - Mail database setup insure that you have an entry similar to the following: Name ID Database Area ---- -- -------- ---- Fax F FAX 5 When Message Base5 is first accessed, the BBS will create 3 files that represent this message area. They are BBS:FAX.MLC, FAX.MLD and FAX.SDX If you ever want to start off with a really clean slate, you can delete these three files and start all over again. FAX ADDRESSES and ADDRESS BOOK ENTRIES -------------------------------------- The BBS's "Add address" screen contains 4 prompts Description Please select type of entry from the following list: (one of which should be [F] = Fax Address (as appropriate for the route) Notes (optional) For fax email, the "address" is a telephone number (see also "Prefix" in SMTP2FAX.DOC) The first character of telephone number should be "#". Although the address may contain any characters, the first occurence of any character OTHER than one of the following indicates the end of the actual fax phone number. The entire address, however, appears as the "TO" in the header of the fax. 0 1 2 3 4 5 6 7 8 9 (digits) * (asterisk) # (number) , (comma) () (brackets) (white space) ENTERING A FAX-EMAIL MESSAGE ---------------------------- The body of a Fax mail message can be editted the same as any other mail message. The exception is that "attached files" are unnecessary and are not allowed. The body of the message may contain special "dot commands" that can enhance your fax message. The "Receipt" option is supported. The "Resend" option (from your Outbox) is supported. DOT COMMANDS ------------ Dot commands (both pre-defined and definable by the system manager) are available to enhance your fax message. An example of a dot command is ".Bold-on" which might be defined to turn bold print on. Dot commands always start at the beginning of a line. The syntax is: .command [parameter [parameter] ] - These commands and parameters are case insensitive. - Any text that does not conform to this syntax is treated as ordinary text. - Some commands are "positional". They cause an action to occur at the point within the message at which they occur. For example, ".PAGE" causes a new page to be started at the position where it is placed. - Other commands are "global" in scope. Their location may be anywhere within the message. For example, ".FINE" indicates that you wish this message to be transmitted in "fine" rather than "standard" resolution. The following would be treated as ordinary text rather than commands because their syntax is not correct +---------------+ |.page One | page command does not expect any parameters | .page | command did not begin at column 1 |. fine | intervening white space between "." and command +---------------+ Definition: A message HEADER consists of lines such as those shown below. The text of the header is ususally considered distinct and apart from the text of the body. usually appears b DATE: xxx, xx-xxx-xxx xx:xx TO: xxxxx xxxxxxxxx FROM: xxxxxxx xxxxxxx SUBJECT: xxxxxxxxxxxxxxxxxxxxxxxx X-MAILER: TSX-Online-FAX32 GLOBAL DOT COMMANDS ------------------- The following are global commands. They may be placed (at the beginning of a line) anywhere in the message. .NOHDR indicates that you don't want any header in this message .FINE (See /FINE in FAX32 documentation) causes the fax to be sent in fine (200x200dpi resolution) rather than standard (200x100dpi) .LONG (See /SHORT in FAX32 documentation) causes all pages to be padded with blank lines so that each fills approximately 11 inches. POSITIONAL DOT COMMANDS ----------------------- .HDR causes the header to be placed at this point instead of at top-of-file. (See also .NOHDR) .PAGE inserts a page break (ASCII 12=^L) .INCLUDE filspc where "filspc" is a fully qualified file specification, causes the insertion of "filspc" .INCLUDE symbol queries the environment for "symbol". If "symbol" exists and its value is a fully defined file specification, the contents of that file are inserted .OUTPUT filspc Using this command bypasses most of the faxing process. If BBS2FAX sees this command, it will NOT write its output to the AUTOFAX directory but writes to "filspc" instead. Thus a fax will NOT be sent. Use of this command is intended for design purposes. Depending on their nature, ".included" files may not be displayable. However, dumping it to a LaserJet printer should result in the same appearance as if it were faxed. FAXSY:SYMBOLS.BBS DOT COMMANDS ------------------------------ You can also create your own Dot Commands for text-substitutions and file-inclusions. The intention behind text-substitutions is primarily to provide a way to include characters that either cannot be easily remembered or cannot be entered at all into the BBS editor. Examples include cryptic PCL escape sequences which are used to achieve special effects, such as font selection. Despite their flexibility, use of a large number of Dot Commands can be complex. That's where a little bit of pre-planning comes in handy. For example, you might design a company letterhead that involves bold, italics and several differently sized fonts. Since this same letterhead will be used often, use the .OUTPUT command to create an output file of your letterhead and keep it in a safe place. Once done, you could make a .LETTERHEAD command which would include that file. (See "Tip!" below for an overview of this idea.) File-inclusion commands are similar to .INCLUDE commands. The key difference (which is also applicable to text-substitution dot commands) is that they may be defined on a user-by-user basis. A sample of FAXSY:SYMBOLS.BBS (called SYMBOLS.EG) is included with your distribution and shown at the end of this section. SYMBOLS.BBS lines are formatted as: SYMBOL_NAME = value_string where value_string is a text substitution with optional parameters or SYMBOL_NAME = where file_specification (delimited by angle brackets) is a full file specification. To make a line applicable to all users, specify a null-user, ie: <> Null-user <> definitions should be placed AFTER specific definitions: EG: .LETTERHEAD = .LETTERHEAD = <> .LETTERHEAD = My Company\n123 Anystreet\nTelephone 555-1212\n Thus, a user who enters .LETTERHEAD in a fax message will get a result depending on who he is. A number of PCL 5 escape sequences to do such things as change the Font are included in the sample SYMBOLS.BBS file Lines that do not begin with "<" are ignored. TIP! If you wish to construct a file (your letterhead for example), - create a working file MYHDR.X with your text and dot commands. - put a dot command like .OUTPUT MYHDR.HDR in it - run the BBS and include (via F) your MYHDR.X file - BBS2FAX will create MYHDR.HDR for you - Print MYHDR.HDR to a laser printer - Take out the .OUTPUT command and fax it somewhere. - Add <> LETTERHEAD = to your FAXSY:SYMBOLS.BBS file ! Sample FAXSY:SYMBOLS.BBS file. ! ! Format of each line is NAME = VALUE ! or just <> NAME = VALUE ! ! If VALUE is delimited by <> as in it is assumed to be a fully ! qualified file specification whose contents are be included. ! If VALUE is NOT delimited by <> it is treated as a format string ! which may contain one or more occurrences of "%s" indicating ! where parameters are to be inserted. ! ! If "bbs username" is non-null, line applies to sender="bbs username" only ! If "bbs username" is null, line applies to anybody !---------------------------------------------------------------------- LETTERHEAD = LETTERHEAD = <> LETTERHEAD = MyCompany\n123 Anystreet\nTelephone 555-1212 ! -------------------------------------------------------------------- ! These Escape sequences were lifted from a LaserJet III font printout ! -------------------------------------------------------------------- ! COURIER (the default font) <> COURIER = \e(8U\e(s0p10.00h12.0v0s0b3T ! Note: CGTIMES takes 1 parameter which is the point size (height) ! Eg: The following would request CGTIMES font at 12 points ! CGTIMES 12 ! CGTIMES 18 ! Here, "12" or "18" would be inserted at the position of "%s" <> CGTIMES = \e(8U\e(s1p%sv0s0b4101T <> ItalicsON = \e(s1S <> ItalicsOFF = \e(s0S <> BoldON = \e(s3B <> BoldOFF = \e(s0B !----------------------------------- End of File --------------------------