PC Online 1997 December

home *** CD-ROM | disk | FTP | other *** search

/ PC Online 1997 December / PCO1297.ISO / FilesBBS / DOS / INF121X.EXE / user.doc < prev

Wrap

Text File | 1996-11-09 | 84.8 KB | 1,982 lines

______ ___________________ ______ > |____________| InfoMail/386 1.20 |____________| < ~~||~~| Centurion |~~~~~~~~~~~~~~~~~~~| 2:2502/666 |~~||~~ || ~~~~~~~~~~~~ ~~~~~~~~~~~~ || || || || || || || || CENTURION || || || || || || -*- || || || || || || InfoMail/386 1.20 || || || || A Document Server for Fidonet Systems || || || || Copyright (C) Damian Walker 1996 || || || || || || -*- || || || || || || USER GUIDE || || || || || || _____ || || (____() || || / / || || / / || || (____() || || _______ || || (_)|||(_) || || ||||| || || ||||| || || ||||| || || ||||| || || ||||| || || ||||| || || ||||| || || /~~~~~\ || || ~~~~~~~ || || || || || || || || || || ____________ ____________ || __||__| Copyright |___________________| 1996 |__||__ > |~~~~~~~~~~~~| (C) Damian Walker |~~~~~~~~~~~~| < ~~~~~~ ~~~~~~~~~~~~~~~~~~~ ~~~~~~ InfoMail/386 1.20 User Guide 1. INTRODUCTION Welcome to InfoMail/386 1.20! This file is the user guide, which acts as a step-by-step tutorial on setting up a sample InfoMail installation. You are encouraged to print out this part of the manual and follow the instructions, especially if you don't have experience of earlier versions of InfoMail. To complement this file, there is a user reference document and a developer's guide. There are also files containing a full table of contents for all the documentation, and an alphabetic index referencing pages in all the document files. 1.1. What is InfoMail? InfoMail/386 1.20 is a document server for Fidonet systems. It scans your netmail directory for messages addressed to it, and performs some action based on those messages. Its basic function is to send out documents which the user has requested. A document is usually in the form of a text file, which can be sent in the body of a reply to the user who requested the document. A secondary function is to allow users to alter documents remotely, via netmail. This allows users who cannot run InfoMail themselves to have their own documents hosted at another system. As an extension to its basic function, this version of InfoMail also allows users to conduct a simple search of the document list, so that users can find documents on subjects that interest them. This is especially useful to systems with a large number of documents. There are many uses which InfoMail can be put to. It has been used to send out BBS information, echo descriptions and rules, reviews of games, FAQ documents and even a price list. The number of other uses which may be found for it are limited only by the imagination. **************************************************************** This program is in the public domain. This means that the program can be distributed and used, for an unlimited period, free of charge. If you find InfoMail useful, the author would be interested to hear from you. Your views on the program, and the uses you may find for it, are valuable information. **************************************************************** Introduction U- 2 InfoMail/386 1.20 User Guide Although the program name and code is protected by copyright, the author would be pleased to see similar programs appearing for the PC and other platforms. Should you as an author wish to write your own document server, feel free to use the data structures, addressing methods and macros which InfoMail uses. Feel free also to use 'InfoMail', 'InfoMail Update' and 'InfoMail Search' as the default names for your program to answer to. The author is more interested in InfoMail as a widespread idea than as a vehicle for presonal fame and (!) fortune. 1.2. System Requirements This version of InfoMail has been written for DOS-based IBM PC compatibles with an 80386 processor or better. This is a limitation of the author's compiler, rather than a deliberate attempt to restrict the systems on which the program will run. At the time of writing, users of 286s and slower machines may use InfoMail 1.11, which is still supported. If you wish to see a new version of InfoMail for 8086-based systems or 286's, let the author know. If there is enough demand, an 8086 version of the program will appear. InfoMail should run on any type of text screen used with mainstream PC's. It was developed on a VGA system which has had both colour and monochrome monitors connected during development. It has yet to be tested with a true monochrome (Hercules/MDA) system. The program knows nothing of 80x43 or 80x50 text modes, and the full-screen configuration utilities will only use the top half of an 80x50 screen. In order to be useful, InfoMail must be used at a Fidonet system which uses a *.MSG netmail directory. This includes FrontDoor, Terminate, and also static mailers such as BinkleyTerm and Xenia if these mailers are used with a mail processor supporting *.MSG message areas. The program also requires a DPMI server to be present. It is supplied with CWSDPMI, a free DPMI server created for the DJGPP compiler and programs developed with it. If your operating system does not have its own DPMI server for DOS sessions (e.g. DOS), CWSDPMI.EXE must be in the current directory or the DOS path in order for InfoMail to be run. 1.3. Disclaimer **** IMPORTANT **** No warranty or guarantee is provided with this program. While the author has attempted to ensure that the program is fully operational and bug-free, no responsibility can be taken by the author in the event that damage or inconvenience is caused by the program. Run InfoMail at your own risk. Introduction U- 3 InfoMail/386 1.20 User Guide 1.4. Acknowledgements Thanks go to the following people for their help in the ongoing development of InfoMail: Bill Welch (ex 2:254/222), for beta testing version 1.00. Bill Birrell (2:2504/200), for beta testing versions 1.00, 1.10, 1.11 and 1.20, and for general programming help in the C echo. Steven Holme (2:2503/201), for beta testing versions 1.00, 1.10 and 1.20, and for some useful suggestions. Jim O'Neill (2:256/68), for beta testing version 1.10. Martyn Wilkins (2:442/608), for promoting version 1.00 in echomail, and for beta testing versions 1.10, 1.11 and 1.20. Peter Barley (2:2502/666.15), for beta testing versions 1.00, 1.10, 1.11 and 1.20, and for many useful suggestions. Andy Altoft (2:2502/666.2107), for beta testing versions 1.00 and 1.10. Peter Burnett (2:441/80), for some useful suggestions, and for beta testing versions 1.11 and 1.20. Joaquim Homrighausen (2:202/330), for hatching versions 1.00 and 1.11 on SDSFRONT, thus attracting interest in the program from across the world. Also thanks must go to Joaquim for allowing his interface design to be used for this and previous releases of InfoMail. Kev Baillie (2:2502/1), for beta testing versions 1.11 and 1.20, and for many useful suggestions for 1.20 and future releases of InfoMail. Colin Spice (2:440/7), for beta testing version 1.20. Ronald Troost (2:285/709), for beta testing version 1.20. 1.5. Version History Version 1.00, original InfoMail, with the following features: - Alterable name and address - Universal kill flag for outgoing messages - 8-character document names - Posts documents up to 8k in size Introduction U- 4 InfoMail/386 1.20 User Guide Version 1.10, first upgrade release, with these additions: - Global header and footer files for outgoing messages - 16-character document names - Document access counter - Macros for use in headers, footers and documents - Secret (unlisted) documents - Expanded subject line for outgoing messages - Optional kill and other message flags for each document - Remote maintenance of documents (passworded for security) - Posts documents up to 16k in size - Automatic upgrade facility - Increased speed of document posting - A couple of aesthetic minor interface bugs fixed - A 386 version of the program Version 1.11 - Document List display bug corrected - Some errors in the documentation were corrected Version 386 1.20 - Configurable log filename - Configurable message size up to 64k - Ability to split large documents into multiple messages - Option to keep outgoing error messages and notices - A document list search utility - Options to keep various types of inbound message - All outgoing messages are sysop-configurable - Multiple AKA's per installation - Indexed (sorted) document list - Request passwords for added security - Secondary document messages (useful for held file attaches) - Optional monochrome 'colour' scheme - Some extra macros, including two document list macros Introduction U- 5 InfoMail/386 1.20 User Guide 2. SETTING UP INFOMAIL The procedure for initially setting up InfoMail will vary, depending upon whether you are installing the program for the first time, or upgrading from a previous version. This section deals with the former case, and assumes that you are starting from scratch. A later section deals with the procedure for upgrading. Before setting up InfoMail for the first time it is necessary to create a new directory for the program and extract the contents of the distribution archive into it. Since you are reading this, it is assumed that you have already got that far. Then you must ensure that you have a DPMI server set up. If your operating system doesn't offer a DPMI server for DOS sessions, or you have disabled it, then you can use CWSDPMI which is supplied in the archive. Simply copy CWSDPMI.EXE into a directory on your path; InfoMail will then find it and load it each time INFOMAIL.EXE is run. See the reference guide section 9.1.2 for further details about CWSDPMI. The examples in this tutorial use the directory name C:\INFOMAIL as an example; you will have to adjust all references to this directory to match whatever directory you are already using for the program. To begin with, a simple installation of the program is all that is necessary; none of the frills need be used. This will be enough for you to see the program working and get a feel for how the separate components work, before proceeding to make use of some of the more complex aspects of the program. 2.1. The Configuration Editor The first component of the program to visit is the configuration editor. Assuming that you are in the C:\INFOMAIL directory, type the following at the command prompt: INFOMAIL CONFIG Captialisation is unimportant in this, and all, aspects of InfoMail. After you have pressed <RETURN>, you should be presented with the main configuration editor screen, which is centred upon a window like the following: Setting Up InfoMail U- 6 InfoMail/386 1.20 User Guide ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ▒╒═══════════════════════════════════════════════════════════╕▒▒ ▒│ Netmail .\ │░▒ ▒│ Log File .\INFOMAIL.LOG │░▒ ▒│ Active Yes Max Msg Size 16384 Kill Outb Errors Yes │░▒ ▒│ Requests InfoMail Kill Inbound Requests Yes │░▒ ▒│ Updates InfoMail Update Kill Inbound Updates Yes │░▒ ▒│ Searches InfoMail Search Kill Inbound Searches Yes │░▒ ▒│ Header │░▒ ▒│ Footer │░▒ ▒│ Doc List │░▒ ▒│ File Err │░▒ ▒│ Inactive │░▒ ▒│ Accept │░▒ ▒│ Reject │░▒ ▒│ Results │░▒ ▒│ AKA List │░▒ ▒╘═══════════════════════════════════════════════════════════╛░▒ ▒▒░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░▒ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ As you load the configuration editor for the first time, it creates the file INFOMAIL.CFG in your InfoMail directory, and writes to it the default settings shown in the window above. But since the default settings do not provide a complete and workable installation, there are a few details you have to supply yourself. 2.1.1. Netmail Directory The first field you will have to change is the very top one, labelled 'Netmail'. The prompt at the bottom of the screen tells you that this is your *.MSG netmail directory. Unless you are planning on running InfoMail while in your netmail directory, you will have to change this field from the default setting. If your netmail directory is C:\FD\MAIL, you would enter C:\FD\MAIL in this field. Notice that the current version of InfoMail supports only *.MSG type netmail areas. If you currently use a Hudson or JAM area for your netmail, you will have to change to *.MSGs before you attempt to use the program. 2.1.2. Log File The default settings also use the current directory as a starting point for the log file. Although the current directory is C:\INFOMAIL at the moment, this probably won't be the case when you come to run InfoMail as a regular part of your setup. So the 'Log File' field will have to be changed to explicitly show the full pathname of your log file. Setting Up InfoMail U- 7 InfoMail/386 1.20 User Guide Assuming you want your log file to reside in the InfoMail directory, this field should contain 'C:\INFOMAIL\INFOMAIL.LOG'. Note that the file doesn't have to be called INFOMAIL.LOG; some sysops like to append the logs of all their software onto the same file. 2.1.3. AKA List The only other field that needs changing in the configuration editor is the AKA List. When you first install InfoMail there are no addresses stored, since the program has no idea what your Fidonet addresses are. To add your address, select the 'AKA List' label. This will take you to a submenu, which contains options for adding and deleting addresses to the list. No edit option is provided; to change an address you must delete the old address and add a new one. To add an address, press INS as the prompt at the foot of the screen indicates. Then a cursor appears and you can enter a 4D Fidonet address; for Centurion this would be 2:2502/666. Enter your address here, and press ENTER. The AKA List menu will reappear. If you have further addresses you want to add to InfoMail, do it now. InfoMail can cope with as many AKAs as will fit in memory, but it will only display as many as can fit on the screen beside the 'AKA List' label. So if you have a lot of AKA's, make sure you're entering them correctly. If you make a mistake while adding your AKAs, or you want to delete an AKA for another reason, press DEL on the AKA List menu and type in the address you want to delete. It will then disappear from the AKA list. Once you have finished adding addresses, press ESC to exit the AKA List menu. 2.1.4. Other Fields to Edit Now you have done all you need to do in the Configuration Editor. However, there are a few fields which will not be revisited later in this tutorial, so they will be explained here. The 'Requests', 'Updates' and 'Searches' fields define the names that InfoMail will answer to. It is recommended that you leave these as they are, in order to maintain some sort of standard from the users' point of view; most current installations of InfoMail 1.11 around the world answer to the names of 'InfoMail' and 'InfoMail Update'. Setting Up InfoMail U- 8 InfoMail/386 1.20 User Guide However, if you really want to change these names then it is simply a case of changing the relevant fields on the configuration screen. If you want to do something silly such as using the same name for all three, then the Request name would take precedence over the other two names, with the Update name coming next; i.e. if you change these fields to: ▒│ Requests SillyServer Kill Inbound Yes │░▒ ▒│ Updates SillyServer Kill Inbound Yes │░▒ ▒│ Searches SillyServer Kill Inbound Yes │░▒ then InfoMail will accept a message to 'SillyServer' as a document request. If the 'Requests' field were then changed to something else, then a message to 'SillyServer' would be taken as a document update. 2.1.5. Exiting the Configuration Editor To exit from the configuration editor just press ESC. Any changes to the configuration will be saved to the file INFOMAIL.CFG when before the command prompt reappears. 2.2. Setting Up Documents Your next task in getting InfoMail up and running is to define one or more documents, since a document server without any documents could hardly be regarded as useful. The tool for this job is the Document List Editor, which is invoked by typing: INFOMAIL LIST at the command prompt. Upon issuing this command, you will be presented with a screen of which the central window resembles the following: ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ▒╒═══════════════════════════════════════════════════════════╕▒▒ ▒│ X Document Subject │▒▒ ▒│ │░▒ ▒│ │░▒ ▒│ │░▒ ▒│ │░▒ ▒│ │░▒ ▒│ │░▒ ▒│ │░▒ ▒│ │░▒ ▒│ │░▒ ▒│ │░▒ ▒╘═══════════════════════════════════════════════════════════╛░▒ ▒▒░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░▒ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ Setting Up InfoMail U- 9 InfoMail/386 1.20 User Guide The first time you load the Document List Editor, two files will be created: INFOMAIL.DAT and INFOMAIL.NDX. These are the document list files. The document list is always sorted alphabetically, hence the presence of an index file INFOMAIL.NDX. Currently the document list is empty. 2.2.1. Adding a Document The procedure for adding a document is very easy-- just press INS. A blank document record will appear, looking something like this: ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ▒╒═══════════════════════════════════════════════════════════╕▒▒ ▒│ Document ░░░░░░░░░░░░░░░░ │░▒ ▒│ Active? │░▒ ▒│ Listed? │░▒ ▒│ Macros? │░▒ ▒│ Routing │░▒ ▒│ Subject │░▒ ▒│ Status │░▒ ▒│ Request │░▒ ▒│ Update │░▒ ▒│ File │░▒ ▒│ 2nd File │░▒ ▒│ Accesses │░▒ ▒╘═══════════════════════════════════════════════════════════╛░▒ ▒▒░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░▒ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ InfoMail is waiting for you to enter a name for the new document. At this point your options are twofold. You can press ESC or ENTER (leaving the document name blank), in which case you will be returned to the document list window without having added a document. A far more sensible option is to enter a document name here and now. There is a sample document supplied with the InfoMail archive, which will be used to illustrate the procedure. For want of a better name, call this document 'Sample' (without the quotes). Once you have entered the document name, some default field values appear, and you can alter the values of some of the fields. 2.2.2. Subject Line The first field to change for this example is the 'Subject' field. This is the subject line which will grace outbound messages containing this document, each time it is requested. At the very least, it should contain the name of the document, but since it is independent of the document name it can contain something a little more descriptive. For this example, enter 'A sample document' as the subject. Setting Up InfoMail U-10 InfoMail/386 1.20 User Guide 2.2.3. Document Filename You will need to tell InfoMail where it can find the document file itself, for when it comes to post it in response to a user's request. This is what the 'File' field is for, and it should contain the full path and filename of the document text file. The sample file supplied is called DOCUMENT.SAM, so you should enter C:\INFOMAIL\DOCUMENT.SAM as the document filename. 2.2.4. Saving the Document Record The subject and filename are the only two fields which need to be altered in order to set up a document; for the time being, all the other fields can be left as they are. To save the document record simply press ESC. InfoMail will save an incomplete record (for later completion, perhaps) if you press ESC before having entered all the necessary fields. For a bit of practice, set up another document. Call this one what you like, and give it any subject line that takes your fancy. When you come to enter the filename, make sure the file doesn't yet exist; i.e. don't try to use an existing text file on your system for this example. This document entry will be used to illustrate how to build up a document text file. The examples in this document will assume the name 'MyDocument' has been used, with the description 'My Example Document' and the filename 'C:\INFOMAIL\MY.DOC'. 2.2.5. Editing and Deleting Documents To edit a document after you've saved it, you just highlight its entry in the document list window and press ENTER. The document record will reappear, and you can alter the fields in the same manner as when you first entered the record. Note that the document name cannot be edited on an existing document record. Deleting and undeleting documents is easy. If you want to try out an example, add another document record to play with. Since you're just going to delete the document, you don't really need to enter a subject line or filename for it. To delete a document record, highlight its entry in the document list and press DEL. An asterisk (*) will appear next to the document name, signifying that the record is to be deleted. Pressing DEL again will remove the asterisk, thus providing an undelete function. 2.2.6. Exiting the Document List Editor To exit the Document List Editor just press ESC while browsing the document list window. All records have already been saved before you reach this point, since they are saved and sorted as you finish entering the details of each record. Setting Up InfoMail U-11 InfoMail/386 1.20 User Guide It is at this point that any records you have marked as deleted are removed permanently, so be careful when deleting a lot of records. There is no separate 'purge' or 'pack' option for the document list, it's all done each time you exit the Document List Editor. 2.3. Creating Document Text Files InfoMail documents are standard ASCII text files. You can use any text file of up to 64k in size as an InfoMail document, and often InfoMail is used as a means of distribution of existing documents such as BBS bulletins or files available for FReq, rather than having documents created specifically for it. If you have been following the examples so far, you should have two documents set up. One, 'Sample', already has a text file; if you want to see it, then view the file DOCUMENT.SAM using a text editor or the DOS TYPE command. The other document, named 'MyDocument' for the sake of the following examples, does not yet have a text file, and it is this example which this section will deal with. The first thing to do is to create the text file for this example. Edit the file MY.DOC (or whatever filename you have chosen), and put in some text. You could import some text from an existing file if you like. There is nothing special about InfoMail document text files. They use standard ASCII carriage return/linefeed pairs, and may use any characters which your network allows in netmail messages. There are some tips for more effective-looking documents, though. The first of these involves the way that Fidonet message editors read, display and (sometimes) write messages. Fidonet messages are reformatted in real time by message readers. This allows the margins of a single message to differ on each recipient's screen, depending on the individual recipient's display size and software setup. Because of this, most good message editors only include a carriage return only at the end of a paragraph, rather than at the end of each line. The message reader will automatically word wrap the paragraphs when the message is received. Since text files used by InfoMail are destined to end up as Fidonet messages, they may make use of this facility. If you are creating a text file which is used exclusively as a document for a document server, it may be a good idea to format the file with each paragraph on a single line. Setting Up InfoMail U-12 InfoMail/386 1.20 User Guide Such a text file would look ugly in most DOS text editors, and it may be necessary to reformat the file with a CR/LF at the end of each line while editing, removing the extra CR/LFs before you save the text. If you don't edit the file that often then you may find it worth the effort to produce a better looking result at the users' end. Kludge lines may be included in document text files if you feel the need. For example, you may like to preserve the character set used for users whose message readers support this feature. Kludges should be included as they are in normal messages, i.e. with the ASCII character 1 (smiley face) as the first character on the line. You may find it entertaining to try and confuse InfoMail by including addressing information kludges in your document text file. However, all addressing kludges and the PID will be replaced by corrected kludges in the outgoing message when the document comes to be posted. 2.4. Testing out Your Installation Assuming you've followed the steps so far, you should have a ready-to-use configuration with your address(es), netmail directory and log filename set up, you should have two documents in the document list, and both documents should have a text file ready to post. So all that's needed now is to try out the program and see how (if?) it works. In order to test the setup properly, you'll need to have a message waiting for InfoMail to pick up. So load your message editor and enter the following netmail: ================================================================ By: <your name>, <your address> To: InfoMail, <your address> Re: Sample ---------------------------------------------------------------- <whatever you like here> ================================================================ This is the format of an InfoMail request message. If you've changed the 'Request' name in the configuration editor, then the new name you supplied should go in the 'To:' field, in place of 'InfoMail'. The address in the 'To:' field should be one of the addresses in the AKA list, and the message body of a document request is ignored, so you can put anything you like in there. Note: It's a bad idea to leave the message body completely blank when you're requesting a document from another system, since some mailers and mail processors delete netmails which lack text, before other programs get to see them. Setting Up InfoMail U-13 InfoMail/386 1.20 User Guide Once you've saved the message, you can exit from the message editor and run InfoMail's netmail scan. Assuming you are back in the C:\INFOMAIL directory, type the following at the command prompt: INFOMAIL SCAN This is the heart of InfoMail, where the program actually does the job it was designed for. If you've entered the request message correctly, you should see the following message appear on the screen: * Processing request from <your name>, <your address> When InfoMail has scanned all the netmails in your netmail directory, the message '* Finished!' should appear and the command prompt should return. If you reload your message editor, you should see that InfoMail has posted the following message in response to your request: ================================================================ By: InfoMail/386 1.20, <your address> To: <your name>, <your address> Re: A Sample Document ---------------------------------------------------------------- Welcome to InfoMail/386 1.20! This is a sample document created for the tutorial in the User Guide. Please see the user guide for more details. ================================================================ Try repeating the procedure for the second document you set up in the Document List Editor. Assuming everything works correctly, you are now ready to add InfoMail to your batch files as a fully functioning part of your system. 2.5. Running InfoMail Regularly The exact procedures here will differ from system to system. If you are a point, you will either want to run InfoMail manually, or if you are using a system based on batch files then you will want to add InfoMail to your polling batch file. If you are a node then you should run InfoMail automatically-- either once per day in your daily maintenance, or after each call when mail is received. The latter method is used at the author's system, meaning that incoming document requests are dealt with immediately. Either way, it would be useful to be able run InfoMail from outside its own directory. InfoMail provides for this possibility in two ways. The first way is using a -PATH switch on the command line. The way to use the path switch is as follows: Setting Up InfoMail U-14 InfoMail/386 1.20 User Guide INFOMAIL SCAN -PATH C:\INFOMAIL This assumes that the C:\INFOMAIL directory is in your path; if not then the full pathname to INFOMAIL.EXE would be required, as in: C:\INFOMAIL\INFOMAIL SCAN -PATH C:\INFOMAIL The -PATH switch can also be used in conjunction with the LIST and CONFIG commands, allowing the configuration editor and the document list editor to be loaded from outside InfoMail's own directory. However, the -PATH parameter makes cumbersome command lines, so an alternative method is provided for running InfoMail from outside its own directory, and this is more in line with other comms-related programs. This method is the INFOMAIL environment variable. In your AUTOEXEC.BAT, or at some other time before you run infomail, you would set the INFOMAIL environment variable as follows: SET INFOMAIL=C:\INFOMAIL If the -PATH switch is omitted from the INFOMAIL command line, then the program looks for the INFOMAIL environment variable in order to locate the config and document list files. Note that the -PATH switch overrides the environment variable. Note also that filenames of documents and the log file are not affected by either -PATH or the INFOMAIL environment variable; you still need to enter a full path for those. One more command line parameter which is useful for all parts of InfoMail (i.e. the SCAN, LIST, CONFIG and UPGRADE commands) is the -MONO switch. Adding this to any valid InfoMail command line will cause the program to use a 'colour' set which is more appropriate to display on monochrome screens. Once you have put InfoMail in your mail system's batch file, it will be fully operational, and the initial setup is complete. It will respond to document requests from other systems in the same way as it responded to your own requests. Perhaps now is a good time to replace 'Sample' and 'MyDocument' with some genuinely useful documents. 2.6. Upgrading InfoMail This section is exclusively for those who are upgrading from a previous version of InfoMail. If you've installed InfoMail from scratch, you will want to skip this section. If you are upgrading from a previous version of InfoMail, there is a utility included with the package to allow you to set up InfoMail/386 1.20 quickly and easily, using your existing configuration files from InfoMail 1.00, 1.10 or 1.11. Setting Up InfoMail U-15 InfoMail/386 1.20 User Guide Before upgrading your setup, it is advisable that you make a full backup of your existing InfoMail directory. A simple copy operation to a temporary directory will do the trick, or perhaps you would like to archive your existing installation for a longer term so that you can ensure your InfoMail/386 1.20 setup works correctly over a period of time. After you have backed up your directory, remove all the standard InfoMail files apart from INFOMAIL.CFG and INFOMAIL.DAT. Unless you have extra files in the directory (such as headers, footers or documents) the easiest way to do this is to delete everything and copy the two files named above back into your InfoMail directory. Now is the time to unpack the InfoMail/386 1.20 archive into your InfoMail directory. Once this is done, you're ready to run the InfoMail upgrade utility. Type the following at the command line: INFOMAIL UPGRADE If all goes well, you should see three messages on the screen. The first tells you that the configuration file is being upgraded. The second tells you that the document list file is being upgraded; if you have a lot of documents then this could take some time. The final message tells you that the process is finished. This upgrade procedure upgrades your existing setup almost exactly, but you may need to alter the log file settings. If, before running INFOMAIL UPGRADE, you have used the -PATH parameter to direct InfoMail to its data files, as described in a previous section, or you have an INFOMAIL environment variable set up, then your log file should take its pathname from this, and InfoMail will add to the existing log file. If you didn't use -PATH or the INFOMAIL environment variable then the log file will always be written to whatever the current directory is when InfoMail is run. In this case, you have to put a full path name in the 'Log File' field. To load the configuration editor, type: INFOMAIL CONFIG and select the 'Log File' field label. You will now be given an opportunity to enter a more acceptable log filename, such as C:\INFOMAIL\INFOMAIL.LOG. Once you have set the log filename, press ESC to exit from the configuration editor. The next change you have to make is to the InfoMail command line in your batch files, as the syntax has been changed for this version. You should implement the following changes in batch files and any other place you call InfoMail: Setting Up InfoMail U-16 InfoMail/386 1.20 User Guide What was... Becomes... -Pdirectory -PATH directory -S CONFIG -L LIST -U UPGRADE -? <nothing> <nothing> SCAN Notice that INFOMAIL by itself now displays help, and to run a netmail scan you need to issue the command INFOMAIL SCAN. See also the added -MONO switch discussed in section 2.1.5. Apart from these small details, the upgrade procedure creates an installation of InfoMail/386 1.20 which directly imitates the earlier version of the program, and doesn't take advantage of any of the more advanced features of InfoMail/386 1.20. The following sections of this manual, which deal with those more advanced features, will be useful for first-time users and upgrading users alike. Setting Up InfoMail U-17 InfoMail/386 1.20 User Guide 3. MORE CONTROL OVER YOUR DOCUMENTS This section deals with some of the more advanced features of InfoMail, concerning the behaviour of individual documents, and the display of their contents to remote users. 3.1. Creating Secret Documents Sometimes it is desirable or necessary to create documents which are for restricted viewing, or which should only be approached from certain channels such as references in another document on your system. This subsection deals with creating such documents. 3.1.1. Hidden Documents When a user attempts to request a document which is not present on your system, a message is sent in reply telling them that the document they wanted does not exist. Included in this message as standard is a brief list of documents, hence this particular response is known as the 'Document List'. It is possible to prevent a document appearing in document list. The reasons for doing this are obvious: it ensures that a particular 'secret' document doesn't come to the attention of a casual browser who has stumbled upon the document list. The author uses this facility to esure that certain documents are approached through the 'proper' channels, creating a proper hierarchy of information with designated entry points. If a user knows the name of a document which is unlisted, they may still request it without requesting the associated listed document, of course. Other sysops use this feature to create secret documents. The document is unlisted, and its name is known only to those they tell about the document, thus the document name acts as its own password. To flag a document as being hidden from the document list, a field exists in the document list record, labelled 'Listed'. Setting this field to 'No' on a document prevents that particular document from appearing in a document list. 3.1.2. Password Protection Sometimes the above is not enough to prevent sensitive documents from being seen by prying eyes. Or perhaps for some reason you want to have a listed document which is not available to all and sundry. In which case, a feature new to InfoMail/386 1.20 is available, which allows you to password protect any document, listed or not. More Control over your Documents U-18 InfoMail/386 1.20 User Guide As with hidden documents, password protection is available via the document list editor, by setting a field in the document list record. This is labelled 'Request' (not 'Password', since there is another password associated with documents, covered later). Setting the request password means that a password must be supplied on the subject line of a request message, as in the following example: ================================================================ By: <your name>, <your address> To: InfoMail, <your address> Re: Sample <password> ---------------------------------------------------------------- <whatever you like here> ================================================================ If the password is omitted from a request, InfoMail posts an error message informing the user that their request was rejected. Leaving the request password blank means that a password is not required for the document. So the same error message will be sent to a user who adds a password to a request for a document which doesn't have one. 3.2. Using Expandable Macros A feature available in versions of InfoMail from 1.10 onwards is the availability of expandable macros which may be placed in the document text. This allows information to be added to documents which might differ each time the document is requested. Macros are surrounded by braces (i.e. '{' and '}'), and consist of a letter and an optional number; the number may come before or after the letter within the macro; InfoMail isn't fussy about this. Including the number in a macro ensures that the macro is always expanded to a constant length, allowing macros to be used in tables without affecting the formatting. Each particular macro type has a maximum size, and exceeding this size in the length number you include in the individual macro will result in a macro of the maximum size being produced; thus {D23} would produce a 16-character document name. Omitting the length number is more usual for including a macro in normal text. Since the length of the resulting expanded macro is variable, notice should be taken of the hint in section 2.1.3, to include entire paragraphs on one line. This means that the outgoing document message will be reformatted in an aesthetically pleasing way by the user's message reader. More Control over your Documents U-19 InfoMail/386 1.20 User Guide Note that expanded macro output is never truncated by including a length number. Thus the document 'MyDocument', when used with a macro {D8} would be output as 'MyDocument' not 'MyDocume'. Macros useful in documents include the program ID, the request name and address for InfoMail, the name and Fidonet address of the user, details about the current document, a document access counter, and even a document list. It is a bad idea to include macros in documents which are also available by file request, or as bulletins for BBS users. This is because the macros will only be expanded when the message is requested via InfoMail (your BBS software and your file request processor know nothing of InfoMail macros). 3.2.1. Program Information It is simple to include the program name and version in your documents (in this release, 'InfoMail/386 1.20'). The macro for doing this is {P} or {P<number>}, where <number> is in the range 1 to 35. The advantage of including this macro instead of the text 'InfoMail/386 1.20' in your document is that the macro will change if you upgrade your installation of InfoMail. Thus a document which has the following in its text file: Document produced by {P} Would produce the output 'Document sent by InfoMail 1.11' if you were using version 1.11 of InfoMail, but would have changed automatically to 'Document sent by InfoMail/386 1.20' when you upgrade the software. Also available as macros are the request name and the AKA in use by InfoMail for the current message. These use the macros {I<number>} and {A<number>}, where {I} is the InfoMail request name and {A} is the AKA. The maximum macro length for the InfoMail request name is 35, and the maximum length of the AKA is 23. So, in a document containing the following in its text file: If you send the following message: ======================================================== To: {I}, {A} Re: ABOUT -------------------------------------------------------- (anything in the message body) ======================================================== then information about this system will be returned to you via routed netmail. More Control over your Documents U-20 InfoMail/386 1.20 User Guide the 'To:' line would be expanded into something resembling the following: To: InfoMail, 2:2502/666 The address would be the AKA to which the user had sent the request message, so the correct AKA should always be returned for the user's network. 3.2.2. User Details The user's name can be included in the document using the {N} or {N<number>} macro, where <number> ranges from 1 to 35. The user's full name is used from the incoming request message. Similarly, the user's Fidonet address can be included using the {U} or {U<number>} macro, where {number} ranges from 1 to 23. This allows us to elaborate upon the latest example given in section 3.2.1, as follows: If you send the following message: ======================================================== By: {N}, {U} To: {I}, {A} Re: ABOUT -------------------------------------------------------- (anything in the message body) ======================================================== then information about this system will be returned to you via routed netmail. If the user 'Damian Walker' of 2:2502/666.3 writes to InfoMail at 2:2502/666, requesting the document above, the document posted in response would contain this: ======================================================== By: Damian Walker, 2:2502/666.3 To: InfoMail, 2:2502/666 Re: ABOUT -------------------------------------------------------- As well as the full user name, the first and last names of the user can also be included in the document using the {F} and {L} macros respectively. Each of these macros can contain a constant length of 1 to 35 characters. As an example, a document could contain the following as its first line: More Control over your Documents U-21 InfoMail/386 1.20 User Guide Hello {F}! in which case the outgoing document would start with: Hello Damian! if the author had requested a document. Possible uses of the {L} macro are not as readily apparent, but it was included in the package for the sake of completeness. 3.2.3. Document Record Information Various fields from the document record can be included as document macros. The most useful example of this is the document name, which is included using the macro {D} or {D<number>}, where <number> ranges from 1 to 16. The subject line can also be included, using the {S} or {S<number>} macro: <number> in this case ranges from 1 to 71. In order to illustrate these, look at the following example: Thank you for requesting document "{D}", entitled "{S}" which would be expanded to something resembling the following in an outgoing document message: Thank you for requesting document "Sample", entitled "A Sample Document" In response to a request from an InfoMail user, the operating system filename of the document has been included as a macro as from InfoMail/386 1.20. This is the {O} or {O<number>} macro, where <number> ranges from 1 to 63. So the document containing this in its text file: This is the file {O} might be expanded to This is the file C:\INFOMAIL\DOCUMENT.SAM in an outgoing document message. The final document-related macro is the access counter. This corresponds to the 'Accesses' field in the document list record, and it is increased by one each time the document is requested. So as well as letting the sysop know how often a document has been requested, this information can also be relayed to users, using the {C} or {C<number>} macro, where <number> ranges from 1 to 5. Something like: More Control over your Documents U-22 InfoMail/386 1.20 User Guide This document has been accessed {C} time(s) might expand to This document has been accessed 15 time(s) in an outgoing document message. Although the 'Accesses' field cannot be directly edited in the document list editor, it can be reset to 0 simply by select the field. This is useful when you are requesting a document a number of times to test its initial setup; resetting the access counter to 0 afterwards gives a more accurate count to the user. 3.2.4. Document List Document lists can be included in documents themselves. This allows you to set up a dedicated 'List' document for example, one which you can advertise to users, but which doesn't include the 'error' overtones of the standard document list response. A standard-style document list as used by InfoMail itself can be included in any document using the {W} macro ({D} already being used for the document name). Think of {W} meaning 'what' as in 'what documents are available'. Output of the following document: The following documents are available by sending a message to {I} and {A} with the document name on the subject line: <blank line> {W} <blank line> (end of list) would look something like: The following documents are available by sending a message to InfoMail at 2:2502/666 with the document name on the subject line: Sample MyDocument (end of list) Another macro exists which gives a document name and subject line for each document. This is the {X} macro (eXpanded list, if you like); replacing the {W} in the previous example with an {X} would create the following output to users requesting the document: The following documents are available by sending a message to InfoMail at 2:2502/666 with the document name on the subject line: More Control over your Documents U-23 InfoMail/386 1.20 User Guide Sample A Sample Document MyDocument My Example Document (end of list) This is much more informative as a document list, although the output can be a bit bulky if you have a lot of (listed) documents on line, hence the default document list described in section 3.1.1 uses the {W} macro output. Note that if you include a length number in the {W} or {X} macro, it will be ignored. The output of these macros is not suitable for inclusion as a single field in a table, so a length number is of no use. 3.2.5. Other Macro Considerations The option to switch macros off is provided, particularly since you may want to use InfoMail to post documents automatically generated by some other piece of software. If such documents contain brace characters ('{') InfoMail will become confused as it tries to expand them as macros-- unless you set 'Macros' to 'No' to prevent macro expansion in that particular document. If you wish to include a left brace in a document over which you have control of the contents, you can do this using the {{} macro (i.e. a left brace within a pair of braces). Right braces can be used indiscriminately, except within macros. But since no valid macro contains a right brace character, there is no reason to try and do this anyway. 3.3. File Attaches and Direct Messages In response to requests from InfoMail users, a feature was added to InfoMail 1.10 onwards, to allow file attaches to be created in response to document requests. Since file attaches can rarely be routed, you also have the option of crashmailing any document response (which could be expensive), or putting it on hold for the requesting user to pick up. 3.3.1. Setting the Status Field for File Attaches To create a file attach, you must make some changes to the document record in the document list editor. The first field which must be changed is the 'Status' field. When you edit the Status field, you are presented with six options at the foot of the screen, which are the various message attributes supported by InfoMail. The main one you are interested for file attaches is 'File', toggled by pressing 'F'. Unless some form of file routing is set in place in your network, you will have to crash the document file attach or put it on hold. The 'Crash' and 'Hold' attributes provide for this, and may be toggled using the 'C' and 'H' keys respectively. More Control over your Documents U-24 InfoMail/386 1.20 User Guide In addition to this, you will of course have to include the name of the attached file as the 'Subject' field, as is normal Fidonet practice for file attaches. Bear in mind that if you use the {X} macro to create document lists, the filename of the attached file will appear as the subject of the document in the list. If this looks too ugly for your taste, you could mark the document as unlisted. Although the message is a file attach message, you will still have to create a document text file in addition to whatever file you are attaching. Treat this as a covering note for the file attach, a message informing the user of the name of file they have just received. 3.3.2. Considerations for File Attaches on Hold If you have created a file attach which will be held for users to pick up, they will want to know when that file is available. This is where the seconary document file comes in. The '2nd File' field of the document record defines a secondary file which will be posted when the document is requested; this differs from the primary document file in that it is always sent via routed netmail, and it will never contain any attribute other than Pvt, Local, Kill (if Kill is one of the attributes in the Status field). You would use the secondary document to inform users that the file was waiting at your system for pickup. This prevents them from having to estimate how long their request has taken to reach your system and how often you process InfoMail requests. Another thing to consider about file attaches on hold is that the requesting user may never pick them up. InfoMail does not currently check outgoing messages, so you will have to scan your netmail directory manually for file attaches which have not been picked up, or use a netmail tool like NetMgr. 3.3.3. Using the Status Field for Other Purposes As well as file attaches, the Status field can be used for file requests or file updates, simply by including the correct attribute in the document record, in conjunction with the Crash or Hold attributes as appropriate. The uses for including File requests or Update requests as outgoing documents are not exactly obvious, but some enterprising user may come up with some way to use the feature. The other attribute supported by InfoMail is 'Kill'. Setting 'Kill' on a document means that outgoing document messages will have the 'Kill' flag set; this prevents your netmail directory (or 'Sent Netmail' area) from being clogged up by responses from InfoMail. More Control over your Documents U-25 InfoMail/386 1.20 User Guide 3.4. Remotely Updating Documents The remote update is a very useful feature added to InfoMail in version 1.10, allowing remote users to maintain documents on your system. This is useful in the event that a remote user cannot run InfoMail; perhaps they are a BBS user, they run their mailer on a platform other than the DOS PC, or they use a message area type other than *.MSG for their netmail. All the local sysop has to do is set the document up in the first place. The document would be set up in the document list editor like any other document, but in addition, a password would be set protecting the document against update by unauthorised users. The update password is set using the 'Update' field in the document list editor, and it acts in a similar fashion to the 'Request' password. However, lack of an update password does not allow the document to be updated without a password; it prevents the document from being updated at all. This is how you prevent your normal documents from being updated remotely. To update their document, all the user has to do is send a message like the following: ================================================================ By: <user name>, <user address> To: InfoMail Update, 2:2502/666 Re: <document> <password> ---------------------------------------------------------------- New document contents go in the message body ================================================================ 'InfoMail Update' is the update name as set up in the configuration editor; if this has been changed, then obviously the new update name should be used instead of 'InfoMail Update'. The address would obviously vary to suit your system. When such an update message is received by InfoMail, the contents of the message body are placed in the document file as named by the 'File' field in the document record. InfoMail posts a response message when it updates a document, as confirmation to the updating user. The secondary document file remains unchanged, as does the actual document record; only the contents of the primary document file may be updated in this way. Notice that kludges from the incoming message are included in the document file, including MSGID, TOPT, FMPT, INTL and PID. This is no reason to worry, though. These are replaced with the correct information by InfoMail when it posts the file to users. The kludges were left in the document file in order that special information such as character sets could be left as the document updater intended; InfoMail 1.10/1.11 would remove all kludges, so such information was lost. More Control over your Documents U-26 InfoMail/386 1.20 User Guide 3.5. Making a Document Temporarily Inactive There are times when you don't want a document on your system to be requested. Sometimes this is when the information becomes out of date, or you are waiting for a document update to arrive from a remote user before allowing the document to be requested. In the former case, the document could simply be deleted, and reinstated when updated information becomes available. However, this means that the document record has to be recreated, which could become tiresome if a large number of documents should be inactivated for a period of time. In the latter case the document couldn't be deleted, as an update would then be rejected. It could be marked as unlisted, but this wouldn't prevent users from requesting the document and, if the first document update hadn't arrived, users would receive a disconcerting error message saying the file is missing. To cover for these eventualities, a document flag 'Active' is available. When set to 'No', document requests are politely rejected, and the user is informed that the document is temporarily off-line. When you want to activate the document again, you simply set the 'Active' field to 'Yes'. More Control over your Documents U-27 InfoMail/386 1.20 User Guide 4. MORE CONTROL OF YOUR OVERALL SETUP There are some facilities offered in InfoMail's configuration editor which allow manipulation of the overall behaviour of the program (as opposed to behaviour of individual documents). This section tells you how to make good use of these. 4.1. Different Log Files Upon loading the configuration editor, you can see that one of the fields is 'Log File'. This allows you to set the log file for InfoMail to write to. Note: this field is not optional. If InfoMail cannot create or open its log file, it will not run. The log file is important in tracking down mistakes in configuration. Some sysops like to combine the log files for all their software into one file. Other sysops keep separate log files for each piece of software, but all in one directory. Whatever your preference, you can use the 'Log File' field to set up the log file as whatever file/pathname you want. The InfoMail log file is in a format shared by a number of other Fidonet programs, so combining the log file with that of, say, FrontDoor or RemoteAccess (compact setting) will still produce a log file which is cleanly laid-out and easy to read. 4.2. What to Do with Inbound and Outbound Messages InfoMail offers you the option of whether to kill inbound messages or to mark them as 'Rcvd' after processing. Separate controls are given for inbound document requests, updates and searches. There are three fields in the configuration editor labelled 'Kill Inbound ...', one for requests, one for updates and one for searches. When one of these is set to 'Yes', inbound messages of the appropriate type are deleted when they have been processed. If you set one of these to 'No', messages of that type will be kept, and marked as 'Rcvd' (so that InfoMail will not attempt to process them again). Setting one or more of these fields to 'No' can act as a diagnostic aid, for instance, when users contact you regarding failed requests, updates and searches. Another field is available, entitled 'Kill Outbound Errors'. This allows you to specify whether outgoing messages which are not document messages (such as document lists, update confirmation, search results and error messages) have the 'Kill' flag set. Again, this is useful as a diagnostic tool, and it allows you to view what the outbound messages look like during the normal use of the program. More Control of your Overall Setup U-28 InfoMail/386 1.20 User Guide 4.3. Message Headers and Footers InfoMail allows you to add a standard header and footer to all your outbound messages, including documents, document lists and all other messages. You can specify a header and footer file by simply entering the full path and filename of the header and/or footer files in the 'Header' and 'Footer' fields of the configuration editor. If the 'Header' field is left blank, no header file precedes the normal text of outgoing messages. Similarly, the 'Footer' field can be left blank to prevent a footer from being added to each outgoing message. Headers and footers may contain macros just like documents, so you could include a standard greeting like Hi {F}! <blank line> as your header. These macros are always expanded, regardless of the 'Macros' setting of the document being posted. The behaviour of some of these macros varies when the outgoing message the header/footer is attached to is not a document (e.g. the {D} macro is not a document name on the document list message, but the name of the non-existent document requested by the user). 4.4. Splitting Large Messages The maximum size of outgoing InfoMail messages is 64k. However, this is still too large for some systems, so it may be a good idea to limit the outbound message size even further. This is where the 'Max Message Size' field becomes useful. As default, this is set to 16k (16384), which is often the upper limit of some mail processing software. It could be argued that this is about the largest message you would want to send via routed netmail, but this limit should not apply to documents sent directly or held for direct pickup. The option is given to increase this to a value not exceeding 65535, or even to decrease it if your uplink is having trouble with messages of this size. Instead of truncating larger messages, the messages will be split into chunks of whatever you have set the 'Max Message Size' to. So a document of around 64k would be split into four messages of 16k if the default maximum size is used (not counting kludges, headers and footers). Documents over 64k will always be truncated, however. More Control of your Overall Setup U-29 InfoMail/386 1.20 User Guide When creating large documents, bear in mind the fact that other systems may decide not to route them. It might be a good idea to consult your uplink(s) before implementing large documents in InfoMail, or alternatively, send large documents directly or put them on hold. In this latter instance, a small text file set up as a secondary document could inform users that the main document is ready for direct pickup. 4.5. Customising the Standard Responses After a number of requests from users of InfoMail to allow the document list message to be customised, the facility was added to allow customisation of all outgoing InfoMail errors and non-document responses. This is the purpose of the fields 'Doc List', 'File Err', 'Inactive', 'Accept', 'Reject' and 'Results' in the configuration editor. To customise one of these messages, simply create a text file with the message you want to send to the user, and include the filename in the relevant field in the configuration editor. In effect, you are creating 'special' documents which are sent in response to events, rather than normal document requests. Macros are expanded in all response messages, and because of this, some of the standard InfoMail responses deserve more detailed consideration. 4.5.1. Customising the Document List Although the name of this response is 'document list', it is not necessary to post a full document list to users when they request a non-existent document. This is particularly useful if there are a lot of mistakes made by users requesting documents, or you have a lot of documents on-line. When creating the document list message, the choice is yours if and how you include the document list. If you want a standard document list, include the {W} macro where you want the document list to appear in the message, as in the following example: Hello {F}! <blank line> The document {D} does not exist! Check the spelling of your request message against the following list of documents: <blank line> {W} More Control of your Overall Setup U-30 InfoMail/386 1.20 User Guide Note the inclusion of the {D} macro to represent the document the user tried to access, rather than the name of any particular document in existence (or the name of the document list response itself). If you want to include subject lines in the document list, use the {X} macro instead of the {W} macro. This list could become rather large, so it may be a good idea to stick to the {W} macro for this standard response, and use the {X} macro in an actual list document which has to be specially requested, as mentioned in section 3.2.4. If you have such a special document containing a document list, you can omit the document list macro altogether from the 'document list' response, and simply direct the user to that specialised list document. This is more econimical for systems with a large number of documents, and/or a large number of erroneous document requests. The value of the following {C} macro is zero in a document list response, and the {O} (filename) macro is blank. The {S} (subject) macro in such a response is 'Failed document request/update'. Other macros retain their usual values. 4.5.2. Customising the Document Search Results The document search facility allows users to post a message to InfoMail asking for a list of documents which contain a certain word in the document tag or the document subject. The format of an inbound search message is as follows: ================================================================ By: <user name>, <user address> To: InfoMail Search, 2:2502/666 Re: <searchword> ---------------------------------------------------------------- <document body ignored> ================================================================ The name 'InfoMail Search' is configurable using the 'search' field in the configuration editor. If the <searchword> contains a space, anything after the space is ignored. The default search response includes a brief introductory 'your search produced the following documents' type message, and a list of documents in {W} format. You can specify an alternative file using the 'Results' field in the configuration editor. If you use this file for its normal purpose, then you must include either a {W} or an {X} macro somewhere in the text file, wherever you want the list of documents to appear. These macros have a slightly altered meaning in this type of output message: the format of the list is the same, but the list will contain only matching entries, rather than a list of all documents. More Control of your Overall Setup U-31 InfoMail/386 1.20 User Guide If you wish for some reason to disable searching, you could specify a text file which contains a brief explanation message along the lines of 'sorry, the document search facility is not available here', which does not include the {W} or {X} macro. In a document search response message, the {D} macro expands to match the search criteria, and the {C} macro expands to the number of matching documents found. The {O} macro stays blank, and the {S} macro expands to 'Document Search Results'. 4.5.3. Customising the Other Responses Since all the other responses refer to some activity based around a single document file, there is nothing special to consider about the expansion of the macros, with the exception of the subject {S} macro. This will contain a suitable summary of the purpose of the message, as follows: File Err Document file not found Inactive Inactive document Accept Document update accepted Reject Document update/request rejected All other document-related macros ({D}, {O} and {C}) contain the correct information as read from the document record. So, for instance, the 'File Err' message posted when a document file is missing could contain the text Please inform the sysop that the file {O} is missing in which case a concientious user could give the sysop all the information needed to correct the situation. 4.6. Inactivating the Setup As with the task of temporarily deactivating a document, it may be desirable to temporarily take the entire InfoMail setup off-line. The 'Active' field in the configuration editor allows you to do this; set it to 'No' in order to take InfoMail off-line. All InfoMail processes will function except the netmail scan; running INFOMAIL SCAN with the 'Active' field set to no will cause the program to halt immediately after the 'Centurion InfoMail' banner has been displayed. Using this option to take the program off-line prevents the need for hunting down all calls to INFOMAIL.EXE in your batch files or anywhere else you may call the program. More Control of your Overall Setup U-32 InfoMail/386 1.20 User Guide 5. CONCLUSION In the unlikely event that you have followed this user guide from beginning to end, you should have a thorough understanding of how to use the InfoMail program to its full potential, as every aspect of the program has been covered in the tutorial. Other useful documents include the Reference Guide, which you can use to find out the use of the individual configuration settings, document details, macros, program components and the command line. There is also a Developer's Guide, for people who may want to write programs to interface with InfoMail. There is an Index which directs you to specific pages in these three document files, and an overall Contents table containing the contents of all the document files (and their filenames). With all this documentation, there's no excuse for not R'ing TFM... It is hoped that you will find InfoMail useful. As mentioned earlier in the document, the author would appreciate a netmail from you, saying what you think of the program, and what uses you have found for it. Suggestions for improvement are also welcome; indeed, several of the improvements built into InfoMail since version 1.10 have been things which the author would not have thought to include himself. Version 1.00 has attracted interest around the world, despite the fact that other document servers had already been written. The improvements in version 1.10/1.11 attracted more people to this easy way of distributing information to interested parties, and hopefully this latest version will be just as well received as the other versions were. Although I cannot guarantee that a future version of InfoMail will be released, your ideas for new features will be welcome. Enjoy! Damian Walker, Centurion (2:2502/666), October 1996. Conclusion U-33