PC Online 1997 December

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

/ PC Online 1997 December / PCO1297.ISO / FilesBBS / DOS / INF121X.EXE / ref.doc < prev next >

Wrap

Text File | 1996-11-02 | 68.2 KB | 1,922 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 || || || || || || -*- || || || || || || REFERENCE GUIDE || || || || || || _____ || || (____() || || / / || || / / || || (____() || || _______ || || (_)|||(_) || || ||||| || || ||||| || || ||||| || || ||||| || || ||||| || || ||||| || || ||||| || || /~~~~~\ || || ~~~~~~~ || || || || || || || || || || ____________ ____________ || __||__| Copyright |___________________| 1996 |__||__ > |~~~~~~~~~~~~| (C) Damian Walker |~~~~~~~~~~~~| < ~~~~~~ ~~~~~~~~~~~~~~~~~~~ ~~~~~~ InfoMail/386 1.20 Reference Guide 1. INTRODUCTION This manual is the Reference Guide to InfoMail/386 1.20. It contains information about the InfoMail command line, the individual program components, the fields in the configuration and document records, a list of macros, and some other information about the program in reference form. First time users are recommended to at least scan through the user guide, which gives step-by-step instructions on how to set up the program, and also contains some how-to sections on setting up the more advanced features of the program to deal with certain common tasks. Also included in the user guide are introductory information such as the program's purpose, the system requirements, the disclaimer, acknowledgements and the version history. Introduction R- 2 InfoMail/386 1.20 Reference Guide 2. THE COMMAND LINE The InfoMail command line usage is as follows: INFOMAIL [<command>] [<switches>] where <command> is one of the following: SCAN - Netmail Scan CONFIG - Configuration Editor LIST - Document List Editor UPGRADE - Upgrade Utility and <switches>, if present, is one or both of the following: -PATH <path> Path to InfoMail files -MONO For monochrome users If no command is supplied, InfoMail displays a brief help screen which looks similar to this section of the manual. 2.1. The CONFIG command This loads the full-screen configuration editor. The configuration editor allows you set up InfoMail's main configuration parameters (i.e. those not tied to any particular document). The altered configuration is saved on exit. 2.2. The LIST command This loads the full-screen document list editor. The document list editor allows you to add, edit and delete records describing the individual documents hosted at the system. It also packs the file (permanently removing deleted records) on exit. 2.3. The -MONO switch This is a switch recommended for users of monochrome monitors (like the author). Although InfoMail's usual colour scheme is quite visible on a CGA/EGA/VGA monochrome monitor, it could be better. On Hercules/MDA screens the light blue borders are displayed with the underline attribute, creating an unattractive striped display when using the full-screen editors. The -MONO switch forces InfoMail to use black, grey and white colours exclusively, in any part of the program: CONFIG, LIST, SCAN, UPGRADE or the help screen. You can also use it if you really don't like the author's use of colours. The Command Line R- 3 InfoMail/386 1.20 Reference Guide 2.4. The -PATH switch By default, InfoMail will search for its files in the current directory. If an INFOMAIL environment variable exists, it will be used to find the files instead (see section 9.2). If the -PATH switch is present, the parameter following it will be taken as the path to InfoMail's files, and will override the INFOMAIL environment variable if it exists. The parameter after -PATH may be in upper or lower case, and it may contain DOS-style backslashes (\) or Unix-style forward slashes (/), or both, if strange-looking filenames take your fancy. You can add a trailing backslash if you like; InfoMail will add one internally if you don't. Use the -PATH switch in conjunction with one of the commands: CONFIG, LIST, SCAN or UPGRADE. When loading the configuration editor for the first time, any path supplied will be taken as the directory for the log file to reside in. 2.5. The SCAN command This command runs the netmail scan, reading the netmail directory for incoming netmails addressed to InfoMail and posting response messages based on them. This is the main part of InfoMail, and requires that the program is fully configured before use. 2.6. The UPGRADE command This is the upgrade utility, which takes the configuration and document list files of earlier versions of InfoMail and converts them to a format readable by InfoMail/386 1.20. A backup is recommended before attempting this operation. The Command Line R- 4 InfoMail/386 1.20 Reference Guide 3. THE KEYBOARD This section gives full details of all the keys used throughout the full-screen components of the InfoMail program. The keys are mainly self-explanatory, and are displayed at the bottom of each screen, but this section has been included for completeness and for reference in the event of ambiguity. 3.1. Editing Text Fields The following keys are available while editing text fields in all parts of the InfoMail program. Left Move cursor left Right Move cursor right Home Move cursor to start of line End Move cursor to end of line Del Delete character to right of cursor Backsp Delete character to left of cursor Enter Accept new field value Esc Reject new field value (revert to old value) 3.2. The Configuration Editor The following two sections deal with the keys available in the various parts of the configuration editor. 3.2.1. Editing the Configuration Record The following keys are available when editing the configuration record, i.e. when the configuration record is displayed and one of the field labels is highlighted. Up Up one field, or move to 'AKA List' when on 'Netmail' Down Down one field, or move to 'Netmail' when on 'AKA List' Enter Edit text/numeric field, or toggle Yes/No field, or edit AKA list if on AKA List field Esc Exit and save 3.2.2. Editing the AKA List After pressing ENTER when the AKA List label is highlighted, a submenu appears at the bottom of the screen. The following keys are available at this time. Ins Add another AKA to the list Del Remove an AKA from the list Enter/ Esc Accept the AKA list The Keyboard R- 5 InfoMail/386 1.20 Reference Guide After pressing INS or DEL, a valid Fidonet address must be entered. This means that when deleting, an existing address must be specified by typing it in manually. There is no menu bar or other selection mechanism. 3.3. The Document List Editor The following sections deal with the keys available while in the document list editor. 3.3.1. Browsing the Document List Upon first loading the document list editor, the document list will be displayed. This centres upon a window in which a number of documents are displayed, one record to a line, and one of the records will be highlighted. The keys at this point are as follows: Up Move up one document Down Move down one document Ins Add a new document Del Toggle delete (X) status of current document Enter Edit an existing document, or add a new document if blank record highlighted Esc Exit and remove records marked as deleted 3.3.2. Editing a Document Record The keys differ slightly when editing or adding a new document. When adding a new document, InfoMail will display a completely blank document record (even the Yes/No fields will be blank) and ask for a document name. Apart from the normal text editing keys described in section 3.1, the following keys are available: Enter Accept name and edit other fields Esc Abandon document and continue browsing After accepting a document name or when editing an existing record, the full document record will be displayed and one of the field labels will be highlighted. At this point, your keys are as follows: Up Up one field, or move to 'Accesses' when on 'Document' Down Down one field, or move to 'Document' when on 'Accesses' Enter Edit text field, or toggle Yes/No field, or toggle Routing between Standard and Smart, or reset Accesses field to 0, or edit Status field Esc Exit to document list and save changes Note that the 'Document' field cannot be changed, it is constant once the document name has been initially accepted. The Keyboard R- 6 InfoMail/386 1.20 Reference Guide 3.3.3. Editing the Message Status When you select the 'Status' field, its contents should be highlighted as if it was a text field, but the available keys are rather different: C Toggle crash attribute F Toggle file attribute H Toggle hold attribute K Toggle kill attribute R Toggle freq attribute U Toggle update attribute Enter Accept new status Esc Reject new status, revert to old status Crash and Hold are mutually exclusive, so when you switch one on, the other switches off. When switching one off, the other does not automatically re-appear though. A three-way version of this relationship exists between File, FReq and Update; when switching one on the others disappear. Switching one off does not make either of the others appear. The presence or absence of Kill does not affect the other attributes. The Keyboard R- 7 InfoMail/386 1.20 Reference Guide 4. CONFIGURATION FIELDS This section describes in detail the purpose of each of the fields in the configuration record, as edited by the configuration editor. 4.1. Netmail This is the directory in which your netmail *.MSGs are stored. It should have a trailing backslash, although InfoMail will add one for you if you don't put it in yourself. The directory name will also convert Unix slashes (/) to DOS backslashes (\), and convert the directory name to upper case. 4.2. Log File This is the full path and filename to your log file. You can enter the filename in upper or lower case, and with DOS or Unix slashes, although InfoMail will convert the name to the normal DOS standard once you have accepted it. This field is mandatory. If InfoMail cannot open its log file, then the netmail scan will refuse to run. 4.3. Active This is the Active flag, indicating whether the netmail scan should run. If set to Yes, InfoMail will function normally. If set to No, InfoMail will refuse to run a netmail scan, although the other parts of the program will function normally. This should be used to temporarily inactivate InfoMail (for maintenance, setup changes or diagnostics) without having to remove calls to INFOMAIL SCAN from your mailer batch files. 4.4. Max Message Size This governs the maximum size of an outgoing InfoMail document message, before addressing information such as TOPT, FMPT and INTL are added (so leave about 64 bytes for these). If a document file creates messages above this size, the document will be posted in a number of smaller messages. The maximum value for this field is 65535. The minimum value is 1, but setting the maximum message size this low would be rather stupid. 4.5. Kill Outbound Errors When set to yes, document lists, file not found errors, document inactive messages, update accepted/reject messages and search results will all have the Kill flag added to them. When set to no, such messages will remain on your system to be dealt with by you manually, or by another program. Configuration Fields R- 8 InfoMail/386 1.20 Reference Guide 4.6. Requests This is the name to which users should post document requests, and it is recommended that you leave this as 'InfoMail' to standardise the use of the program. Most existing installations of the program use this convention. Case is unimportant in this field; users may post to 'InfoMail', 'INFOMAIL' or 'infomail' and the program will treat the message as a document request. 4.7. Updates This is the name to which users should send remote updates to documents. It is recommended that you leave this as 'InfoMail Update' in order to standardise the use of the program. The existing systems which allow remote update and use the name 'InfoMail' for requests follow this convention (they have little choice, since earlier versions of the program just added the word 'Update' to the request name to ascertain the update name). 4.8. Searches This is the name to which users should send document search messages. It is recommended that you leave this as 'InfoMail Search' in order to standardise the use of the program. It cannot, however, be claimed that most existing systems follow this convention because the document search is a new feature to InfoMail/386 1.20. 4.9. Kill Inbound Requests/Updates/Searches These fields signify whether the relevant type of inbound message will be deleted after processing (if Kill Inbound is set to 'Yes') or merely marked as 'received' for you or your mail processing software to deal with (if set to 'No'). 4.10. Header and Footer These fields determine the filenames of the global header and footer. The header and footer are added to the top and bottom of each outbound message, i.e. documents and non-document response messages. Each field should contain the full DOS path and filename of the relevant file. If the header field is left blank, then there will be no header added to outbound messages; a similar rule follows for the footer field. 4.11. Doc List This is the text file posted each time a user requests a document which does not exist, and should be the full DOS path and filename of a text file. If it is not specified, a standardised document list is posted to the user. Configuration Fields R- 9 InfoMail/386 1.20 Reference Guide 4.12. File Err This is the text file posted to a user when the text file of the document they have requested is missing. This will most often happen with documents updated by remote users, if someone requests the document before the first update message has been sent. The field should contain the full path and filename of the text file. If left blank, a standardised message will be posted to the user. 4.13. Inactive This is the path and filename of the text file posted to a user when the document they have requested is marked as inactive. If it is not specified, a standardised message will be sent in its stead. 4.14. Accept This is the path and filename of the text file sent to a user on successful updating of a remotely-updateable document. A standardised message will be posted to the user if this field is not specified. 4.15. Reject This is the path and filename of the text file sent to a user when they attempt to request or update a document without specifying the correct password. It is also sent if a user specifies a password when requesting a document which is not passworded, or if the user tries to update a document which does not have an update password. If this field is left blank, a standardised message will be posted to the user. 4.16. Results This is the path and filename of a document search result template file, sent to the user when a document search is received. If it is not specified, a standardised search results message is posted to the user. 4.17. AKA List This field contains one or more Fidonet addresses, and defines the AKA's which the system answers to; i.e. your Fidonet addresses. This field is effectively mandatory, as if you don't define any addresses then InfoMail will not respond to any messages. Configuration Fields R-10 InfoMail/386 1.20 Reference Guide 5. DOCUMENT RECORD FIELDS This section describes the fields of the document record, visible when you edit a document in the document list editor. 5.1. Document This is the document name, or tag. It is the name which a user must place on the subject line when requesting the document. Although it is case insensitive, the case is preserved by InfoMail for output in document lists. The name cannot contain spaces. Spaces are converted to underline characters (_) by the upgrade program and the document list editor, for your convenience. Users requesting a document must type any underline in the name explicitly on the subject line of their message, since a space in the subject line separates a document name from a password. Note that the only time you can edit a document name is when adding a new document; InfoMail will ignore you if you try to select this field on an existing record. Make sure you get the case right before pressing ENTER to accept the document name! 5.2. Active This field serves a similar purpose to the field of the same name in the configuration record; it defines a document as inactive. If a user requests a document with the 'Active' flag set to 'No', InfoMail will post a polite refusal instead of the document text file. An inactive document can be updated remotely, however. When this field is set to 'Yes', the document behaves normally. 5.3. Listed This field defines whether a document will appear in a document list or not, including a list of matching documents in a document search result. Only if Listed is set to 'Yes' will a document appear in such a list, otherwise it will remain hidden. 5.4. Macros This field defines whether macros in the document text file will be expanded or not. If set to 'No', left brace characters ('{') will be treated as any other character, and will remain in the outgoing document message. If set to 'Yes', InfoMail will interpret a left brace as the start of a macro sequence, and attempt to expand it. Document Record Fields R-11 InfoMail/386 1.20 Reference Guide Usually this field should be left at 'Yes'. However, sometimes you may want to post as a document a file which has been generated by a third-party program, and such a file may contain brace characters as part of its normal text. In this instance you should set Macros to 'No' in order to avoid confusion. 5.5. Routing This field is currently unused, although you can toggle its value from Standard to Smart. It is there to interface with a possible future project which will implement routing of InfoMail documents in a more intelligent way than the simple 'Status' field or your mailer's routing facilities. 5.6. Subject This is the subject line for outgoing messages containing the text of this document. It is normally a more descriptive version of the document tag, although documents which have File Attach, File Request or Update Request status should use the subject line for filenames as per the normal Fidonet standard. 5.7. Status This field contains some of the attributes for outgoing messages containing the text of this document. The attributes which InfoMail supports are Crash, Hold, Update, File, FReq and Kill, although Pvt and Local are stamped on all outgoing messages as well. The Kill flag is relevant to both the primary and secondary document messages, but the other attributes apply only to the primary document file. The secondary document message is always sent routed regardless of the Status field. 5.8. Request This is the request password. If there is no request password for a document, then the user must request the document without a password on the subject line. If a request password is present, it must be added after the document tag on the subject line, separated from it by a single space. Password comparisons are case insensitive. 5.9. Update This is the remote update password. If there is no remote update password set for a document, then that document cannot be updated remotely. If a remote update password is present, then it must be included on the subject line, after the document name, in any remote update for the document. Document Record Fields R-12 InfoMail/386 1.20 Reference Guide 5.10. File This is the full path and filename of the primary text file for this document. For normal documents this is the only text file. On file attaches the text file is usually a covering note for the file which is attached with the message. This field is mandatory; without it, InfoMail will post a 'file missing' message to the user. 5.11. 2nd File This is the full path and filename of the secondary text file for this document. Normally it is unused. However, when a document is set up as a held file attach, it is desirable to send a second message, routed, to inform the user that a file attach is waiting. Thus the only message attribute which secondary messages carry from the Status field is 'Kill'. 5.12. Accesses This is the document access counter. It cannot be directly edited, but selecting this field in the document list editor causes it to reset to zero. Aside from its novelty value as an in-document macro and its limited informational value, it is quite useless. The option to reset it has been provided in the event that you have requested it when testing your configuration, and want to reset the counter when you are happy that the document is correctly set up. Document Record Fields R-13 InfoMail/386 1.20 Reference Guide 6. DOCUMENT MACROS InfoMail provides macros which can be embedded in document text files. These are expanded to provide some meaningful piece of information each time a message is posted. Such information may vary from one message to another, which is why it wouldn't be included verbatim. Macros are a letter and an integer included in braces ('{' and '}'), in any order. The integer stands for the minimum length of the expanded macro, and its range differs for each individual macro. You could specify the macro {D16} as {16D} or even {1D6} if it amuses you, and each would expand to a 16-character document name. This section provides a list of macros supported by InfoMail, and explains how to use each one. 6.1. {A} - InfoMail's Address This macro expands into the current AKA which InfoMail is operating under. If InfoMail is responding to a message addressed to 2:2502/666, then the {A} will expand to 2:2502/666 in the outgoing message. The maximum length of a Fidonet address is 23 characters (up to 4 integers of 5 digits, with a :, / and .), so {A24} and above create a 23-character address. 6.2. {C} - Access Counter When embedded in a document, in an error related to a specific document, or in a header or footer being added to a such a message, this is the 'Accesses' field from the document list record. It is increased before being included in the message, so the first time a document is requested it will be '1'. When embedded in a search results template, or in a header or footer added to search results, the {C} expands into the number of documents matching the search criteria. When embedded in a document list (as posted when the user requests a non-existent document) the {C} expands to 0. The maximum length for the expanded macro is 5 characters. This is the only macro in which fixed-length expansion is right-justified, i.e. '{C5}' would expand as ' 23' if the document had been accessed 23 times. 6.3. {D} - Document Name This is the document 'tag'. When embedded in a document or a response associated with a specific document (or a header/footer attached to such a message), this will expand to the tag of the relevant document. Document Macros R-14 InfoMail/386 1.20 Reference Guide When embedded in a document search template, or a header/footer attached to such a message, this will expand into the search criteria entered by the user on the subject line of the inbound message. When embedded in a document list, this macro will be expanded into an empty string. The maximum length of the {D} macro is 16 characters. 6.4. {F} - User's First Name This expands into the first name of the user, as extracted from the 'From' field of the inbound message. Thus in response to a message from 'Damian Walker', the {F} macro would expand as 'Damian'. The maximum length of this macro is 35 characters. 6.5. {I} - InfoMail Request Name This is the request name as set up in the configuration editor. It can be embedded in instructions on how to request other documents, or in a welcoming sentence such as 'thank you for writing to {I}'. The maximum length is 35 characters. 6.6. {L} - User's Last Name This expands into the user's last name, as extracted from the incoming message. Thus in a response to a message from 'Damian Walker', {L} would expand into 'Walker', and in a response to 'NetMgr 0.99' {L} would be '0.99'. Be careful of adding {F} and {L} together to create the user's full name; some users include their middle name or initial, and some users include suffixes such as 'Jr' or 'III' to their names. The {L} macro isn't as useful as it seems at first. Maximum length is 35 characters. 6.7. {N} - User's Full Name This expands into the full name of the user to whom the response is being posted, exactly as extracted from the 'From' field of the inbound message. The maximum length is 35 characters. 6.8. {O} - Operating System Filename of Document When embedded in a document, a document-related error or a header/footer attached to such a message, {O} returns the full filename of the document being requested. On other messages, {O} expands to a blank string. Maximum length is 64 characters. 6.9. {P} - Program Name and Version This macro allows you to impress users with your impeccable taste for document server software by telling them that you are running InfoMail/386 1.20. In InfoMail 1.11 it expands to 'InfoMail 1.11' and in later versions of InfoMail, the later program ID will be returned. The maximum formatted length is 35 characters. Document Macros R-15 InfoMail/386 1.20 Reference Guide 6.10. {S} - Document Subject Line This allows you to embed the subject line of the document. It is included only for completeness, since the user can see the subject line plainly in their message editor. When embedded into response messages other than documents, {S} will expand into the subject line of the error message being posted, making it equally useless in this type of message. The maximum formatted length is 71 characters. 6.11. {U} - User's Address This expands into the address of the user to whom the current message is being posted in reply. The maximum length of the formatted macro is 23 characters. 6.12. {W} - Document List Usually this macro expands out into an entire list of all document tags set up on the system. These are formatted four to a line, right-justified as per the author's preference (and nobody's complained about this up to now). Any formatted length included in the macro will be ignored since the list is not suitable for inclusion as a field in a formatted table. The usual use of this macro is as embedded in a document list response message, or in a specially created document list set up as a document in itself. It is also used in a document search results template, and decides the position and format of the list of documents. Obviously, in a search results message the {W} will expand into a list of only documents which match the search criteria, rather than a full document list as happens when it is included elsewhere. 6.13. {X} - Extended Document List This macro behaves in a similar fashion to the {W} macro, except that the document listing includes subject lines, and is formatted with one document per line instead of four. Again, the formatted length, if included, is ignored. As with the {W} macro, when included in a document search results template, only the documents matching the search criteria will be included in the list. 6.14. {{} - Literal Left Brace This macro provides a way to represent the '{' character in outgoing documents. Some sample C code could be represented as follows: Document Macros R-16 InfoMail/386 1.20 Reference Guide void main(void) {{} printf("Hello World\n"); } which would be expanded into the following output text: void main(void) { printf("Hello World\n"); } Document Macros R-17 InfoMail/386 1.20 Reference Guide 7. SCREEN MESSAGES This section is a reference of all the messages which appear on the screen, and in the case of error messages, what to do about them. 7.1. ! Cannot create configuration file This message indicates that the configuration editor cannot create the initial configuration file, INFOMAIL.CFG. This is usually a path error, for instance, trying to create a configuration file in a non-existent directory or a non-writeable drive. 7.2. ! Cannot create document list file This message indicates that the document list editor cannot create the initial document list files, INFOMAIL.DAT and INFOMAIL.NDX. This is usually a path error, for instance, trying to create a document list file in a non-existent directory or a non-writeable drive. Very occasionally, this error may arise as a result of a disk or network fault, or some other low level problem. If this is the case, check that the DAT file is not present before loading the configuration editor again (it may be that the DAT file could be created but not the NDX-- having a DAT without an NDX is no use to InfoMail). 7.3. ! Cannot open configuration file This error message is given by the netmail scan. It indicates that it cannot open the file INFOMAIL.CFG. This may arise because the file is not there, i.e. you haven't loaded the configuration editor before attempting a netmail scan for the first time. In this case, you'll have to load the configuration editor as described in the user guide, followed by the document list editor to prevent the error described in section 7.4 of this manual. It may also arise when InfoMail cannot find its files. For instance, you're running InfoMail outside its own directory with no -PATH switch or INFOMAIL environment variable. The solution-- run InfoMail from its own directory, set the INFOMAIL environment variable or use the -PATH switch. The error may also be displayed if the INFOMAIL.CFG is invalid; this could be because of corruption or because you haven't yet upgraded the files from a previous installation of an older version of InfoMail before attempting a netmail scan. Error Messages R-18 InfoMail/386 1.20 Reference Guide 7.4. ! Cannot open document list file This error is given by the netmail scan if for some reason it cannot open the document list file (INFOMAIL.DAT) and its index file (INFOMAIL.NDX). This may arise because the files don't yet exist, if you have run the netmail scan before the document list editor. In this case, the solution is simple-- run the document list editor to create the files! It may arise because you haven't indicated to InfoMail where the files are. To solve this, make sure that (a) you are in InfoMail's directory before running, (b) you have use the -PATH parameter to point InfoMail to its files, or (c) the INFOMAIL environment variable is set correctly. It could also arise if the files are invalid, such as when corruption occurs or when you try and run InfoMail/386 1.20 when using old data files from an earlier version. 7.5. ! Cannot open log file This error is issued by the netmail scan when it cannot open the log file for output. This will usually be because the log file has not been defined correctly in the configuration editor; to fix this, make sure that the log file is a valid path and filename to a writeable DOS drive and directory. 7.6. ! Cannot read netmail directory This error is issued when the netmail scan failed to find the netmail directory. This would usually be because the netmail directory has been incorrectly defined in the configuration editor; ensure that the netmail directory in InfoMail matches that of your mailer or mail processor. Ensure also that you are actually using a *.MSG netmail area rather than JAM, Hudson or Squish (none of which InfoMail can read). 7.7. ? Cannot read netmail message This occurs when InfoMail has trouble reading a netmail message which is known to exist. It will usually be a file sharing violation or, in unfortunate cases, corruption of a netmail file. In the case of a sharing violation, a later run of the InfoMail scan will probably pick up the offending netmail and process it then, as long as whatever program had the message file open in the first instance has closed the file since. In the case of file corruption, you will have to remove the offending netmail message. Error Messages R-19 InfoMail/386 1.20 Reference Guide In no instance is this a fatal error, if InfoMail cannot read one netmail message it will ignore it and progress to the next message. 7.8. * Conversion finished This simply indicates that the UPGRADE process has run successfully and the files from your installation of an earlier version of InfoMail have been converted to a format InfoMail/386 1.20 can read. Note that the original files are available in case a restoration of the previous InfoMail version is needed; these are named INFOMAIL.CF$ and INFOMAIL.DA$ (there is no INFOMAIL.ND$ since earlier versions of InfoMail had no document file index). 7.9. * Converting configuration file This indicates that the old configuration file has been successfully read and is now being converted to InfoMail/386 1.20 format. 7.10. * Converting document list file This indicates that the old document list file has been successfully opened and is now being converted to InfoMail/386 1.20 format. 7.11. Error: InfoMail is already running This error occurs mostly in multitasking environments, where there is a possibility of InfoMail being run simultaneously in multiple DOS sessions. It indicates that InfoMail might already be running elsewhere. The error could also be caused if InfoMail has crashed on a previous run, leaving its semaphore file behind. The semaphore file is named INFOMAIL.SEM and it is located in InfoMail's directory as defined by the -PATH switch or the INFOMAIL environment variable. This may be removed if you are sure that InfoMail is not running elsewhere. Creating the semaphore file manually will also result in this message being displayed when you try to run InfoMail; try it out if such things amuse you. 7.12. Error: cannot create semaphore This indicates that there was an error creating the semaphore file which InfoMail tries to drop as soon as it is run. Error Messages R-20 InfoMail/386 1.20 Reference Guide The most probable cause is that the path to InfoMail's files has not been correctly specified, and is pointing to a non-existent directory or a non-writeable device. In this case, correct the setting of the INFOMAIL environment variable or the parameter of the -PATH command you use to invoke InfoMail. 7.13. Error: cannot remove semaphore This error occurs when InfoMail cannot delete its own semaphore. You can cause this error yourself in a multitasking environment by deleting the semaphore file in one window while InfoMail is running in another. When InfoMail exits it then issues this error. In another instance, the error might be caused by a sharing violation or other file-system related error. In this case, ensure that the semaphore file has been deleted manually before attempting to run InfoMail again. 7.14. Error: type INFOMAIL alone for help This is a simple command line error. It results when you misspell a command word or switch, use the -PATH switch with nothing after it, or type complete nonsense. To solve it, simply check your command line and correct the error or, as the prompt says, type INFOMAIL on its own for a concise help screen. 7.15. * Finished! A simple message indicating that InfoMail has finished the netmail scan. This should be the last thing you see after the netmail scan has been run (apart from a 'cannot remove semaphore' error perhaps). 7.16. ! Invalid configuration file This error is output by the configuration editor if a file is present but cannot be loaded. This is usually caused by running INFOMAIL CONFIG with data files from an earlier version of InfoMail-- in this case run INFOMAIL UPGRADE before attempting to load the configuration editor. At other times it occurs because of file corruption, or when you have mistakenly copied a nonsense file over INFOMAIL.CFG. In the event of minor file corruption (a byte here or there), you can make partial corrections by ensuring the first 8 bytes of the configuration file read "INF120S"<NUL> where <NUL> is an ASCII zero. You would use a hex editor for this, not a text editor. In the event of irrepairable file corruption or copying other files over INFOMAIL.CFG the only solution is to use your latest backup of the INFOMAIL.CFG file, copying it over the damaged version of the file. If you haven't taken a backup, what a shame. Error Messages R-21 InfoMail/386 1.20 Reference Guide 7.17. ! Invalid document list file This is issued by the document list editor when an existing document list file or index file is corrupted or invalid. It most often occurs when running the list editor on a data file from an earlier version of InfoMail. In this case you must run the INFOMAIL UPGRADE procedure before attempting to edit documents. Other causes, as for the error described in section 7.16, are file corruption or overwriting of INFOMAIL.DAT and/or INFOMAIL.NDX with nonsense files. In the event of minor file corruption, it is not recommended that you attempt to restore these files with a hex editor, as errors here may show odd behaviour by the document list editor. Restore the files from your latest backup instead. 7.18. ! Missing or invalid configuration file This is a general error issued by the upgrade utility if it cannot find a valid configuration file from InfoMail 1.00 or InfoMail 1.10/1.11. To correct this, ensure that the files are in the InfoMail directory, i.e. where you would expect the new files to appear, before running the upgrade process. Remember to point InfoMail to these files using -PATH or the INFOMAIL environment variable, or alteratively, run INFOMAIL UPGRADE from InfoMail's own directory. 7.19. ! Missing or invalid document list file This error occurs when the InfoMail upgrade utility cannot find a valid document list file from version 1.00 or 1.10/1.11 to upgrade. See section 7.18 for details of how to deal with this error. 7.20. ! No netmails to read This appears when there are no *.MSGs at all in the designated netmail directory. If there are messages in the netmail directory not addressed to InfoMail, this message should not appear. If you see this message when first installing and testing InfoMail, check that the 'Netmail' field is correctly set up in the configuration editor. 7.21. * Processing request from... This message simply lets you know that InfoMail has found a document request, if you happen to be watching a netmail scan go by. It can be a useful diagnostic shortcut, allowing you to see that a test request was received and processed without having to load your message editor again. Error Messages R-22 InfoMail/386 1.20 Reference Guide 7.22. * Processing search from... This message appears whenever InfoMail processes a document search message found in the netmail directory. 7.23. * Processing update from... This message appears whenever InfoMail processes a document update message found in the netmail directory. Details of acceptance of rejection of the update are not displayed but may be found in the log file (see section 8). Error Messages R-23 InfoMail/386 1.20 Reference Guide 8. LOG FILE ENTRIES This section deals with the various entries you may find upon examination of the log file. Only the netmail scan process writes to the log file, it being assumed that you are usually present at the keyboard to witness the activities of the other program components such as the configuration editor. The log file is similar in layout to that produced by some other software, such as FrontDoor and GEcho. It is suitable for inclusion in compound log files if you like to keep the logs of all your software that way. Each netmail scan initialises by writing the following to the log file: <blank line> ---------- InfoMail/386 1.20, DD-Mmm-YY where DD-Mmm-YY is the current date. Each individual log entry has the following format: X HH:MM:YY <actual log entry text> where X is one of the following: ! for fatal errors causing an immediate exit ? for errors from which InfoMail can recover * for major log messages (message found, etc). + for minor messages such as file/message writes - for trivial log messages and HH:MM:YY is the time of the log stamp. The actual log entry text is freeform, and varies according to each event logged. Where a log file message has the same meaning and solution as an identical screen message, you are referred to the screen message's entry in section 7 (to avoid repetition of the same text in this manual). 8.1. ? Cannot open document file... This warning is written to the log file when InfoMail cannot open the document text file of a specific document. The log file includes details of the document to allow you to check your setup. Usually this warning occurs because a document's filename is incorrectly specified in the document list editor; to correct this problem you should check the document entry in the document list editor. Occasionally this warning may occur due to sharing violation errors or file system corruption. It is not a fatal error; InfoMail should inform the user of the problem and continue to process other messages. Log File Entries R-24 InfoMail/386 1.20 Reference Guide 8.2. ! Cannot read netmail directory This indicates that the netmail directory could not be found, refer to section 7.6 for tips on how to deal with this fatal error. 8.3. ? Cannot read netmail message This indicates that InfoMail had trouble reading an existing netmail message. Refer to section 7.7 for tips on how to deal with this. This is a warning rather than a fatal error, so InfoMail continues to process later messages. 8.4. ? Cannot write netmail message This error appears when InfoMail could not write a netmail message. This will usually happen due to sharing violation or file system errors. It will follow a 'Processing request/update/search from...' log entry; check the name and address in that message and (if you don't kill them) inbound messages to get details of what the user wanted if you wish to get in touch with the user afterwards. In the case of sharing violations, the best way to avoid this error is to ensure that no other application is reading/writing to the netmail directory when InfoMail is processing messages. Many programs allow semaphores to be used for this purpose. 8.5. - Document list closed This signifies (surprise) that the document list file has been closed, and is used along with the log entry described in section 8.6 to indicate the successful loading/exiting of InfoMail. 8.6. - Document list opened This shows that the document list has been opened successfully. If InfoMail has managed to get this far, it is a fair indication that initialisation has been fully successful, i.e. InfoMail's directory, all the configuration files, the log file and the netmail directory have all been initialised. When there are no inbound messages addressed to InfoMail, a normal log entry should read something like this: ---------- InfoMail/386 1.20, 27-Oct-96 - 10:01:58 Document list opened - 10:01:59 Document list closed 8.7. ! Missing or invalid document list This fatal error indicates that the document list could not be loaded, and is identical to the 'Cannot open document list' screen error message described in section 7.4. Log File Entries R-25 InfoMail/386 1.20 Reference Guide 8.8. ! No netmails to read This 'error' is written when the netmail directory is completely empty, and co-incides in occurrence and exact meaning with its associated screen message, described in section 7.20. 8.9. * Processing request from... This is written when a document request is recieved and processed. The log line includes the name and address of the remote user. 8.10. * Processing search from... This message is written when a document search message is encountered. It gives the name and address of the remote user who posted the search. 8.11. * Processing update from... This entry occurs when InfoMail receives a document update from a remote user, whose name and address are included in the entry. 8.12. + Sending document list to... This entry indicates that the document list is being sent to the remote user; this user should be the same user identified in the 'Processing ... from ...' entry immediately above in the log file. When you see this entry, you know that the user has requested (or attempted to update) a document which does not exist. If you want to see which document, you will have to look at the inbound request, assuming that you keep those requests. 8.13. + Sending document... This entry shows that a document has been sent to the user in response to a document request. The entry includes details of the user and the document, so you can keep track of which documents are being requested and who is requesting them. 8.14. + Sending file error to... This message, occurring after a '? Cannot open document file' error, shows that the user has been informed that the document file cannot be found. Log File Entries R-26 InfoMail/386 1.20 Reference Guide 8.15. + Sending inactive document error to... This log entry indicates that the user has been informed that the document they requested is inactive. The document details are not included here, you will have to look at inbound messages to see the document requested. Alternatively, check the document list editor for inactive documents if you don't think you should have any. 8.16. + Sending reject message to... When a document request or update is rejected, this log entry shows that the user has been sent the 'update/request rejected' standard message. 8.17. + Sending search results to... This log entry shows that the results of a user's search have been posted to them, and follows a 'Processing search from...' log entry. 8.18. + Sending update confirmation to... When a user successfully updates a document, they receive a confirmation message. This log entry shows that the confirmation message has been sent to them. 8.19. + Updated document... Coinciding with the log entry described in section 8.18, this entry shows that the updated document text has been written to the document file. Document details are provided here. Log File Entries R-27 InfoMail/386 1.20 Reference Guide 9. MISCELLANEOUS INFORMATION This section contains anything which is important enough to include for reference, but which isn't relevant to any of the other sections of this reference guide. 9.1. InfoMail Directory Contents This subsection describes all the files which should be present in the InfoMail directory, including all those from the original archive and others created by InfoMail. 9.1.1 INFOMAIL.EXE - The InfoMail Executable This is the main executable for InfoMail/386 1.20, including all of the program components. 9.1.2. CWSDPMI.EXE - The DPMI Server CWSDPMI is the DPMI server supplied with InfoMail/386 1.20. It was written by Charles Sandmann especially for DJGPP and programs written using that compiler. You can get the latest version of CWSDPMI on the Internet at www.delorie.com. InfoMail's author will attempt to keep up to date with the latest release of this DPMI server and keep a copy at Centurion for file request. At the time of writing, CSDPMI3B.ARJ is available for file request at 2:2502/666 (note no W in the archive name). If your operating system does not provide its own DPMI server for DOS sessions then you can use CWSDPMI instead. Simply move or copy CWSDPMI.EXE to somewhere on your DOS path and InfoMail will automatically find and load it each time you run INFOMAIL.EXE. 9.1.3. *.DOC - The Main Documentation The files CONTENTS.DOC, USER.DOC, REF.DOC, DEV.DOC and INDEX.DOC all form the main documentation. CONTENTS.DOC is the table of contents for all file .DOC files, and contains full information on all sections of them. USER.DOC is the user guide, intended as a starting place for first-time InfoMail users and those who want a 'how-to' answer to some common problems and features. You are reading REF.DOC. DEV.DOC is the developer's guide, intended for those who want to write programs to interface with InfoMail. INDEX.DOC is the full alphabetic index for all the other major document files. Miscellaneous Information R-28 InfoMail/386 1.20 Reference Guide 9.1.4. FILE_ID.DIZ/*.TXT - Minor Documentation Files These files include such things as the long file description, the quick start guide and the 'what's new' document. Filenames may vary; see the actual archive for a full list. 9.1.5. *.SAM - The Sample Files These files are samples created for your conveniece. Some of them are intended for use with the tutorial in the user guide, and others are for general use. DOCUMENT.SAM is the sample document file mentioned in the tutorial, and has no other use apart from a quick document for any testing you want to do. HEADER.SAM and FOOTER.SAM are the sample header and footer files. If these are to your taste, you can use these directly by specifying their names in the relevant fields of the configuration editor. DOCLIST.SAM is a sample document list file. It is identical to the internal document list sent as a default, so including its name directly in your configuration file won't appear to do much. It is included as a starting point for you to create your own customised document list. FILEERR.SAM is the sample 'file not found' error message template. It is identical to the internal message of the same purpose, but can be taken as a starting point for a customised version of this message. INACTIVE.SAM is the sample 'document inactive' message, identical in appearance to the internal version but usable as a starting point for customisation. ACCEPT.SAM and REJECT.SAM are the 'update accepted' and 'update or request rejected' templates. As with FILEERR.SAM and INACTIVE.SAM, these are identical to the default messages of that purpose but can be used to create customised messages more to your taste. RESULTS.SAM is the sample document results template. Again, this is identical to the internal version. It is recommended that document search results list the subject line of documents if the names aren't that descriptive. If you wish to follow this recommendation you can simply change the {W} in this text file to an {X} (see section 6 about macros), include the full path and filename of RESULTS.SAM in your configuration (in the 'Results' field), try out a document search and inspect the results. Miscellaneous Information R-29 InfoMail/386 1.20 Reference Guide 9.1.6. INFOMAIL.CFG - The Configuration File This is the file created by INFOMAIL CONFIG or INFOMAIL UPGRADE when you first install the package, and it is used (and required) by every other part of the program. 9.1.7. INFOMAIL.DAT/INFOMAIL.NDX - The Document List INFOMAIL.DAT is the document list file, containing all the details of all the documents. It is created by the document list editor or the upgrade utility, and is used by the netmail scan. INFOMAIL.NDX is the index file, used by the document list editor to ensure that the documents are in alphabetical order, and by the netmail scan to speed up location of individual documents and to keep document lists and searches in order. It is created by the upgrade utility or document list editor, and is mandatory for the running of the program. 9.1.8. INFOMAIL.CF$/INFOMAIL.DA$ - Upgrade Backups These files are created by the UPGRADE process, and are simply copies of your previous configuration files. These are useful if you need to revert to an earlier version of InfoMail for some reason, or if you make a mess of your configuration and need to re-import the original files. When you are satisfied that InfoMail is set up correctly you may delete these files. It is recommended that you let InfoMail run for a while beforehand, in case errors appear which are not initially apparent. 9.2. The INFOMAIL Environment Variable This is a convenient way of indicating to InfoMail where its data files are, it is the standard practice adopted by a large number of Fidonet applications and utilities. As an example, SET INFOMAIL=C:\INFOMAIL\ tells InfoMail that its data files are in C:\INFOMAIL. The trailing backslash is not necessary; InfoMail adds it internally if it is not present. The environment variable is overridden by the -PATH switch on the InfoMail command line; it is usual to use one or the other, but not both. 9.3. Defaults These are the default values of the fields in the configuration editor. They are used when setting up InfoMail for the first time. When upgrading, all the fields present in the earlier version of InfoMail retain their existing values. Miscellaneous Information R-30 InfoMail/386 1.20 Reference Guide Netmail .\ Log file <path>\INFOMAIL.LOG Active Yes Max Msg Size 16384 Kill Outbound Yes Requests InfoMail Updates InfoMail Update Searches InfoMail Search Kill Requests Yes Kill Updates Yes Kill Searches Yes Header <empty> Footer <empty> Doc list <empty> File err <empty> Inactive <empty> Accept <empty> Reject <empty> Results <empty> AKA List <empty> <path> is the path as specified in the INFOMAIL environment variable or the -PATH command line switch; if neither are used it defaults to '.\' and really ought to be changed. When adding a new document, the default values are as follows: Document <always entered by user> Active Yes Listed Yes Macros Yes <see below> Routing Standard Subject <empty> Status <empty> Request <empty> Update <empty> File <empty> 2nd File <empty> Accesses 0 When upgrading from a previous version of InfoMail, the fields present in that version retain their existing values. When upgrading from InfoMail 1.00, the Macros field in all documents is initially set to 'No' in order to make the new installation behave like the old one (there may be documents containing '{' and '}' which would cause confusion with Macros set to 'Yes). 9.4. Limits These are the limits placed on various fields and other parts of InfoMail (length of text fields is readily apparent from the screen display, so is not listed here) Miscellaneous Information R-31 InfoMail/386 1.20 Reference Guide Max Msg Size 65535 AKA List As many addresses as memory will hold Accesses 65535 (then resets to 0) Max Doc Size 64k after macro expansion Documents 2 billion Miscellaneous Information R-32